TABLE OF CONTENTS

• Connection of Labforward applications with SAMLtest server
  • Introduction
  • SAML Config
  • Upload keycloak configs
  • Mappers
  • Re-authentication
    • Sync Mode Options
  • Conclusion

Connection of Labforward applications with SAMLtest server

Introduction

This article describes how we connected our Labforward applications with an existing test server named SAMLtest - SAMLtest. In order to reproduce the configuration on your own server, the steps should be similar:

• Download and install the server metadata
• Configure the connection
• Upload Keycloak’s metadata to the IdP server to properly configure the handshake

We set up an environment connected to SAMLtest, which runs a Shibboleth server as both IDP and SP (service provider) for testing purposes.

Here are the steps described for this configuration to be repeated on the subsequent installations with Shibboleth or other SAML-based Identity Providers.

First, in the Admin Panel, make sure the active realm is Labforward. Then add a new identity provider as SAML v2.0.

SAML Config

For this configuration group, download the file from https://samltest.id/saml/idp and import it at the bottom of the section. For an actual IdP, the URL will be different.

This configuration file is going to prefill several configuration items. Scroll back to the SAML configuration section and check the changed attributes:

First Login Flow: iam-first-broker-login

The option “First login flow” is shown after saving the configuration. It appears under the “Advanced settings” section:

Service Provider Entity ID: https://account.test.labforward.app/realms/labforward

Identity Provider Entity ID: https://samltest.id/saml/idp

Single Sign-On Service URL: https://samltest.id/idp/profile/SAML2/POST/SSO

Single Logout Service URL: We don’t want to log out the user in Shibboleth, so leave this field empty. 

The Entity ID is the value that describes the IAM service as Service Provider. The other ones are related to the Shibboleth configuration. The customer's administrators should provide these values.

Save the configs.

Upload keycloak configs

For the SAMLTest server to work correctly, it’s necessary to upload the Service Provider configuration, so both applications trust each other.

1. Download the XML configuration from the Admin Panel, on General settings under the Settings tab: 

1. On the SAML configuration, follow the link “Endpoints” for the SP descriptor
2. 

2. Upload the XML file (don’t use the URL field) to SAMLTest:  https://samltest.id/upload.php (Again, the URL will be different for an actual IdP.)

3. Test the login from IAM.

In case the integration fails, you can check the logs of your IdP: https://samltest.id/logs/idp.log

Mappers

The mappers tab becomes visible after saving the SAML configuration the first time:

We need to map the fields from SAML IdP to Keycloak. Each Shibboleth instance might bring a different implementation for these attributes, but following the sample server, they are:

• givenName
• surname
• mail

For each of these fields, it is necessary to create a new mapper with the type “Attribute Importer”.

Sync Mode Override: import → this means we only ask the field for the first registration. This should be the option for all mappings from Shibboleth.

For the given attributes of this server, the mapping should be:

• givenName → firstName
• sn → lastName
• mail → email

Also, it is necessary to map a param with the type “Hardcoded User Session Attribute”:

Sync Mode Override: inherit → we should import this session attribute on every login

User Session Attribute: idp_user

User Session Value: true

Re-authentication

Shibboleth IDP integration supports forcing re-authentication before critical actions. In general, it depends on the implementation of the Identity Provider to support this feature. If the Shibboleth instance respects the Force Authentication flag sent from IAM, it will always force the user to authenticate before these critical actions.

The Force Authentication flag can be configured via the Admin Panel in the Shibboleth/SAML IDP configuration. When it’s ON, the user will be re-authenticated in Shibboleth every time. When it’s OFF,  the IDP decides whether to reauthenticate or immediately redirect back to IAM with success since the user is already authenticated.

Sync Mode Options

As the last option in the Advanced settings group, there is the synchronization mode for Shibboleth IdP.

When Sync Mode is set to Import, the user data (first and last names and email) will be imported only once from the Identity Provider into IAM.

In case it’s desired that the IAM profile is always in sync with the remote Identity Provider, this should be set to Force.

Conclusion

In this document, we used the SAMLTest server as an example of SAML integration. The configuration should be similar to other IdPs supporting SAML protocol, such as Shibboleth. However, based on the internal configuration of the IdP, some extra steps might be needed to configure it during the setup.