Configure Identity Providers

You can set up WorkFusion User Management (Keycloak) to authenticate users based on identities from external providers.

WorkFusion User Management supports integration with identity providers (IdPs) using either of the protocols:

• SAML v2.0

• OpenID Connect v1.0

Integrate IdP based on SAML v2.0

To integrate with an IdP using the SAML protocol, follow the steps below:

1. Prepare the IdP client for integration with WorkFusion User Management.
2. Create and configure a SAML IdP provider in WorkFusion User Management.
3. Authenticate in Control Tower with IdP credentials.
4. Map client roles to IdP users.

Configure IdP client

The configuration flow is as follows:

1. Import the WF User Management IdP settings (the IdP entity descriptor) using either of the two methods:

   • Paste the following URL in your browser address line: https://{{keycloak_dns}}/auth/realms/{{workfusion_realm}}/protocol/saml/descriptor, where:

     • keycloak_dns is the DNS address of your User Management instance.

     • workfusion_realm is the name of the realm where you manage clients, roles, groups, users, and so on. Typically, it is WorkfusionRealm.

   • Go to Realm settings > General > Endpoints > SAML 2.0 Identity Provider Metadata.

     

   Regardless of the method you use, this brings you to XML containing the IdP metadata, including the certificates.

   

2. Use the IdP settings from Step 1 to configure the IdP client for integration with WorkFusion User Management.

3. Get the entity descriptor for your IdP client. Retrieve the IdP client data (Single Sign-On Service URL, Single Logout Service URL, certificates, and so on) essential for further configuration of the SAML IdP in WorkFusion User Management.

Create SAML IdP

Before creating a SAML IdP, enable username editing:

1. On the left menu, navigate to Realm settings.

2. Go to the Login tab.

3. Make sure the Edit username toggle is on. If it is off, turn it on.

   

Then, create a SAML IdP as instructed below:

1. On the left menu, select Identity Providers.

2. On the right, click the Add provider drop-down box and select SAML v2.0.

   

   The action brings you to the screen where you need to configure the IdP settings.

Configure SAML IdP

To integrate with the SAML IdP you created in the previous step, configure the settings as described below and switch the Enabled toggle on.

General settings

• The Redirect URI is generated automatically.

• Set Alias to saml.

Saml settings

Fill in the fields and switch toggles on or off as shown in the screenshot below. Then, click Save and proceed to setting the authentification flow.

Pay attention to the following recommendations:

• Service Provider Entity ID: the field is required, the specified ID is used for unique identification of the service provider.

• Identity Provider Entity ID: the field is optional, the specified ID is used to validate the issuer if received SAML assertions.

• Single Sign-On Service URL: the field is required, specifies the SAML endpoint to start the authentication process.

• Single Logout Service URL: the field is optional, specifies the SAML logout endpoint.

• Validating X509 Certificate: contains the public certificate to validate the signatures of SAML requests and responses from the configured IdP.

• Principal Type: the setting must match the Identity Provider configuration. If you are unsure which parameter is sent, you can use SAML troubleshooting tools for investigation, for example, SAML Chrome Panel.

note

The values for the configuration fields above are specified in the IdP entity descriptor mentioned in Configure IdP client.

Set authentication flow

To set an authentication flow for the configured IdP, follow the steps below:

1. On the left menu, select Authentication.

   

2. In the list on the Flows tab, click the browser flow.

3. Find the Identity Provider Redirector step and open its settings by clicking the cogwheel button.

   

4. Specify the SAML alias for the IdP you are matching to the authentication flow and click Save.

   

info

If you want to have the possibility to configure multiple IDPs, do not specify the Default Identity Provider parameter.

After you complete the authentication flow setup, user authentication in all clients (Control Tower, Workspace, Kibana) is based on the credentials stored in the IdP. Your next step is to sign in to Control Tower with the IdP credentials.

Authenticate in Control Tower

Authentication is essential for IdP users to appear as WorkFusion User Management entities. Follow the steps below:

1. Go to the Control Tower URL. From the URL, you are redirected to the following IdP login form.

   

2. To log in, enter the credentials for a valid IdP user. The following form appears on the screen:

   

   You can set the form to update automatically using an Identity Provider mapper. For instructions and a sample project, see the Create IdP mapper section.

3. Fill in the Username, Email, First name, and Last name fields (all fields are mandatory) and submit.

Two authentication outcomes are possible:

• If the username of the IdP user does not exist in WorkFusion User Management, it is created. However, the Control Tower authentication attempt fails. To make the authentication a success, configure a Control Tower role for the created user as described in the Map roles to IdP users section.

• If the username of the IdP user already exists in WorkFusion User Management, you see the following screen:

  

  • Clicking Review profile brings you back to the login page where you need to change the value in the Username field.

  • Clicking Add to existing account brings you to the below email verification page. The verification is essential for you to add the IdP credentials to an existing WorkFusion User Management user.

    

    To verify, sign in to the email assigned to the respective WF User Management user and click the email verification link.

info

If an existing WorkFusion User Management user doesn't have a wf-control-tower client role, you get an authentication error message. To proceed, configure Control Tower roles. For the configuration details, refer to the Map roles to IdP users section.

Create IdP mapper

To create an IdP mapper, do as follows:

1. Go to Identity Providers > SAML > Mappers and click Add mapper.

   

2. In the form that follows, select Mapper Type and fill in other fields.

   

Below is a sample of how you can create an IdP mapper:

1. Specify any name for the mapper.

2. Specify the sync mode override. Possible values include:

   • Legacy to keep the behavior as it was before you selected the option.
   • Import to only import the user once at their first login with the IdP credentials.
   • Force to constantly update the user after every login under the identity provider.
   • Inherit to use the sync mode defined in the identity provider for this mapper.

3. Select a mapper type based on the table below:

   Mapper type	Description
   Advanced Attribute to Role	If the set of attributes exists and can be matched, grant the user the specified realm- or client-level role.
   Username Template Importer	Format the username to import.
   Hardcoded User Session Attribute	When a user is imported from an IdP, hardcode the mapper value to a specific user session attribute.
   Attribute Importer	Import the declared SAML attribute, if it exists in the assertion, to a specified user property or attribute.
   Hardcoded Role	When a user is imported from an IdP, hardcode a role mapping for the user.
   Hardcoded Attribute	When a user is imported from an IdP, hardcode the mapper value to a specific user attribute.
   SAML Attribute to Role	If an attribute exists, grant the user the specified realm or application role.

   The rest of the parameters are specific to the mapper type you’ve chosen.

Map roles to IdP users

The user-to-role mapping is essential for users to access User Management clients. You have two mapping alternatives:

• Automatic
• Manual

Automatic role mapping

If the underlying organizational structure allows, you can configure an IdP provider to send user attributes in SAML assertions and WorkFusion User Management to map new users to specific roles based on those. For instance, the IdP can send the Department, Organization Unit, Job Title attributes, and the WF User Management maps users to specific client roles based on their values.

Below is an example of how a job title is mapped to the Control Tower Administrator role:

Alternatively, if you store users in LDAP and can't use the attribute-to-role mapping or if you need more fine-grained management of groups or roles, configure User Federation with your LDAP and then set group and role mappings. For details, refer to Configure LDAP.

Manual role mapping for IdP users

Manual role mapping becomes possible after IdP users are already on the Users list in the WF User Management system. To map manually, follow the steps below:

1. On the left menu, click Users and select a user by clicking its name in the list.

   

2. On the user's settings page, go to the Role mapping tab, click the Assign role button, and choose Client roles.

   

3. In the displayed window, select the checkboxes corresponding to the client roles to which you want the user to have access and click Assign.

   

In about 10 minutes (max), the new setup is synced with Control Tower or another client. This means users can log in to Control Tower or another client with their IdP credentials.

Sign and encrypt certificates

To generate certificates for signing and encrypting SAML assertions, complete the following steps:

1. In the WorkFusion realm, select Realm Settings > Keys > Add providers.

   

2. Click the Add provider button and select rsa-generated.

3. Fill in the following form with the desired keystore priority, length, and so on.

   

   Changing the priority for a provider does not cause the keys to be re-generated. If you want to change the Key size, you can edit the provider, which entails generating new keys.

4. Save the provider. The generated certificates appear in the WF User Management SAML entity descriptor mentioned in Configure IdP client.

It is also possible to use an existing keypair and certificates. For details, visit the Keycloak official documentation.

Migrate users with Link trusted provider flow

The Link trusted provider flow is designed to facilitate user migration from one version to another. The flow is applied at first login. It is only allowed for users with a trusted provider, the same provider you used before migrating to WorkFusion User Management.

To set up the flow, navigate to Identity providers and choose your identity provider. Then, on the provider's settings page, go to the Advanced settings section and, in the First login flow override drop-down box, select Link trusted provider.

The flow has significant differences as compared to the default first broker login one.

The first broker login flow requires the verification of external users against a local user in WorkFusion User Management in case of a collision. To verify, the following checks are essential:

• Email check, which is not always possible in customer environments.
• Asking users to prompt a local password or sign in as an admin and specify an OTP for a user, which adds manual work, especially when the number of users to be migrated is significant.

The Link trusted provider migration flow is designed to simplify the first login by performing the following sequence of actions:

1. It creates a user if it doesn't exist in WorkFusion User Management.
2. It links a migrated user to that in WorkFusion User Management if the latter exists with the same username.
3. It does not allow users to update mapped attributes (username, email) from Identity Providers.

Integrate multiple identity providers

The WorkFusion User Management allows you to set up multiple Identity Providers for user authentication. The feature can be particularly useful when an organization has multiple departments that require separate authentication flows.

If multiple IdPs are configured, users attempting to log in will see sign-in options. For example, if there are two IdPs configured, the following screen is displayed:

To add multiple IdPs, follow the steps below:

1. Go to Identity Providers and click Add provider.

   

2. In the drop-down list, choose the required provider.

3. Configure an additional provider:

   • For SAML IdPs, use the guide. When configuring, consider the following recommendations:

     • Specify a user-friendly Display name. Make it concise and clear as the names longer than 14 symbols are truncated by an ellipsis. In this way, users can easily identify IdPs on the login page.

     • To change the order of the IdP login buttons on the login page, assign a value to the Display order parameter of each IdP. For instance, if you have two IdPs, assign 1 and 2 to indicate their position in the display sequence.

       

   • For OpenID providers, refer to the official Keycloak documentation.

info

If you want to have the possibility to configure multiple IDPs, do not specify the Default Identity Provider parameter when setting the Browser authentication flow.

Disable automated user creation

By default, when a user authenticates using IdP credentials and there is no record for them in the internal WorkFusion User Management database, such a record is created. This saves you the trouble of creating users but may not be suitable for specific setups.

For instance, if you cannot completely trust an IdP, you may want to pre-create users in WorkFusion User Management and disable the automated user creation to provide an additional authentication layer with a separate set of credentials. In this case, even if the credentials you specified on the login screen pass the IdP's authentication, you will not sign in successfully to Work.AI.

info

Disabling automated user creation is only possible after completing the SSO configuration.

To disable the automated user creation, follow the steps below:

1. To create an authentication flow, click Authentication > Flows > Create flow.

   

2. Set any alias name for further usage and click Create.

   

3. Click Add execution to define the execution type for the created flow.

   

4. In the displayed list, choose an execution type:

   

5. If needed, click Add sub-flow to add one or more sub-flows to the authentification flow.

   

6. On the Identity providers page, click a configured IdP in the list to open its setting page.

   

7. On the provider's setting page, find the Advanced settings section and, in the Post login flow drop-down box, select the flow created in Step 2 (in this example, Empty) and click Save.

   

8. Go to the Users page, click the user you want to link to the IdP, and navigate to the Identity provider links tab.

   

9. On the Identity provider links tab, find the IdP with which you want to link the user and click Link account.

10. In the displayed window, fill in the fields as described below and click the Link button.

    • User ID: specify SAM-Account-Name from the IdP.
    • Username: type in the IdP username from the WF User Management in lower case.

    

Integrate based on OpenID Connect v1.0

For the instructions to create and configure an OIDC IdP, refer to the Keycloak official documentation.