Edit

Integrate ADFS Identity Provider

The document describes the integration of ADFS/SSO with WorkFusion services.

Prerequisites

IA Cloud Enterprise version 10.2 is installed.

Configure Keycloak

1. Log in to the Keycloak master admin console https://<user-management-domain>/auth/admin/master/console/ with the superuser credentials.

2. Select WorkfusionRealm.

   

3. On the Identity Providers page, create the new SAML v2.0 IDP provider.

   

   In the saml group, on the Settings tab, set the parameters:

   • Alias: saml
   • Display name: any meaningful name, for example, saml
   • Enabled: true
   • Store tokens: true
   • Trust email: true
   • First login flow: depending on type of installation, select:
     • first broker login for migration from version of IA Cloud that didn't have Keycloak
     • Link trusted provider to skip user verification step

4. Navigate to the Import External IDP Config group. In the Import From URL box, paste the URL of the federation metadata config: https://<your_domain>/FederationMetadata/2007-06/FederationMetadata.xml (for example, https://fs.wflab.io/FederationMetadata/2007-06/FederationMetadata.xml) and click Import.

   

5. In the SAML config group, configure SAML assertion signature:

   • Want AuthnRequests Signed: enabled
   • Want Assertions Signed: enabled
   • Want Assertions Encrypted: enabled
   • Signature Algorithm: RSA_SHA256
   • SAML Signature Key Name: CERT_SUBJECT
   • Force Authentication: enabled
   • Validate Signature: enabled

   

6. Save IDP configuration.

7. Go to the Mappers tab and click Create.

   

   In the Identity Provider Mapper section, add the mappers with the following parameters:

   Field	Username mapper	First name mapper	Last name mapper
   Name	username	First Name	Last Name
   Mapper Type	Attribute importer	Attribute importer	Attribute importer
   Friendly Name	uid	firstName	lastName
   User Attribute Name	username	firstName	lastName

   

   If needed, add other mappers, for example, attribute to role. Alternatively, you can configure User Federation with your Active Directory and set up group or role mapping here. For details, refer to Configure LDAP.

8. Configure group or role mapping for users.

   You need to configure proper roles and groups for logged-in users to use the IA Cloud services. Otherwise, users face a FORBIDDEN error after login, and you need to assign appropriate roles and groups manually for each of them.

   You can configure groups and roles mapping in several ways, depending on users' existing attributes and hierarchy in Active Directory. Suppose it's possible to map some LDAP attributes to user roles (for example, map specific values of Department, Organization Unit, or Job Title to IA Cloud roles). In that case, you can configure it on the Mappers tab of the IDP provider.

   Here is an example of a job title mapping to a Control Tower Administrator role. The users with an Administrator value in the Job Title get the Administrator role.

   

   To receive Job Title as title attribute in SAML assertion, set it in the ADFS configuration:

   

   For more information on adding the configuration on the ADFS side, refer to Create claim rules.

   If you need more fine-grained management of groups and roles, you can configure User Federation with your Active Directory and set groups and roles mapping here.

   For the details, refer to Configure LDAP.

   In this case, users are fetched into Keycloak from AD on the User Federation configuration step and linked to ADFS on user login. With this setup, on the Settings tab, in the First login flow dropdown, select Link trusted provider (see step 3 of the Configure Keycloak guide). With selected Link trusted provider, the username applied for the ADFS login is linked automatically.

9. Go to the Export tab and click Download.

   

10. Go to Authentication > Browser > Identity Provider Redirector > Actions > Configure.

11. Create authenticator configuration with created IDP provider as a default authenticator:

    • Alias: saml
    • Default Identity Provider: saml

    

Configure ADFS

Add new relying party trust

To add a new relying party trust:

1. Log in to the Windows server where ADFS is installed (for example, via remote desktop connection or any other applicable way).

2. Launch the AD FS Management application by clicking Start > Administrative Tools > AD FS Management, and then select Trust Relationships > the Relying Party Trusts node.

   

3. In the Actions sidebar, click Add Relying Party Trust.

   

4. In the Add Relying Party Trust wizard, click Start.

   

5. On the Select Data Source screen, click Import data about the relying party from a file and select All files in the file browser. Keycloak exports its metadata with the default TXT extension.

   

   In the file browser, select the metadata file downloaded on the Go to export tab > download step, and click Next.

   

6. In the Add Relying Party Trust wizard, provide information for each screen:

   1. On the Specify Display Name screen, enter a Display name and any notes and click Next.
   2. Click Next to skip the Choose Access Control Policy screen.

7. On the Ready to Add Trust screen, review your settings and click Next.

8. Click Finish.

Create claim rules

After creating the relying party trust, add the claim rules:

1. In the Relying Party Trusts list, right-click the relying party object you created, click Edit Claim Insurance Policy.

   

2. Click Add Rule.

   

3. In the Claim Rule Template list, select the Send LDAP Attributes as Claims template and click Next.

4. Create the following rule:

   1. Claim rule name: descriptive rule name
   2. Attribute store: active directory
   3. Add the following mapping (LDAP Attribute-Outgoing Claim Type):
      • User-Principal-Name: UPN
      • E-Mail-Addresses: email
      • SAM-Account-Name: uid
      • Given-Name: firstName
      • Surname: lastName

   

5. Click OK.

6. Create another rule by clicking Add Rule and select Transform an Incoming Claim as a template.

7. On the next screen, create the following rule:

   • Claim rule name: descriptive rule name
   • Incoming claim type: UPN
   • Outgoing claim type: Name ID
   • Outgoing name ID format: Email
   • Pass through all claim values—default value

   

8. Click OK to create the claim rule, and then click OK again to finish creating rules.

Troubleshoot

Check ADFS logs

To view the issues that may arise on the ADFS side, check the ADFS logs:

1. On the ADFS server, navigate to Control Panel > Administrative Tools > Event Viewer.

   

2. In Event Viewer in the left panel, navigate to Applications and Services Logs > ADFS > Admin and view ADFS logs.

   

For more details, see How to check ADFS logs for SAML logins.

Troubleshoot through debugging

For troubleshooting an issue, enable the debug mode in Keycloak:

1. Connect via SSH to the MASTER server, where Keycloak is running.

2. On the MASTER server, stop the supervisord service.

   systemctl stop supervisord
   

3. In /opt/workfusion/keycloak/bin/standalone.sh, set DEBUG_MODE to true.

   DEBUG\_MODE="${DEBUG:-true}"
   DEBUG\_PORT="${DEBUG\_PORT:-8787}"
   

   You can also edit /opt/workfusion/supervisord/apps/keycloak.ini and add --debug to the startup line.

   command = bash -c '
       source /opt/workfusion/environment.sh;
       /opt/workfusion/keycloak/bin/standalone.sh --debug \\
       --server-config=standalone-ha.xml \\
       --properties=/opt/workfusion/keycloak/keycloak.properties \\
   '
   

4. Start the supervisord service again.

   systemctl start supervisord
   

After Keycloak starts, you can debug it remotely on a specified port.

Possible errors after debugging

Error type 1

You can face the following error after ADFS sends assertions back to Keycloak after login:

Keycloak logs contain the following error:

{"timestamp":"2021-02-03T14:06:43.462Z","sequence":156,"loggerClassName":"org.jboss.logging.Logger","loggerName":"org.keycloak.broker.saml.SAMLEndpoint","level":"ERROR","message":"no principal in assertion; expected: FRIENDLY_ATTRIBUTE(uid)","threadName":"default task-1","threadId":127,"mdc":{},"ndc":"","hostName":"sso-mish-wfaw-10014-master1.WORKFUSION-LB-HOSTNAME","processName":"jboss-modules.jar","processId":535}

To fix the errors, go to the SAML Config section > Identity Providers and change the Keycloak Principal Type config from Attribute [Friendly Name] to Attribute [Name].

Error type 2

You can also face the following error after ADFS sends assertions back to Keycloak after login:

Keycloak logs contain the following error:

{"timestamp":"2021-02-05T11:51:57.483Z","sequence":405,"loggerClassName":"org.jboss.logging.Logger","loggerName":"org.keycloak.events","level":"WARN","message":"type=IDENTITY_PROVIDER_RESPONSE_ERROR, realmId=WorkfusionRealm, clientId=null, userId=null, ipAddress=172.20.243.193, error=invalid_saml_response","threadName":"default task-37","threadId":445,"mdc":{},"ndc":"","hostName":"ip-172-20-51-15.ec2.internal","processName":"jboss-modules.jar","processId":2021}

An invalid relying party trust identifier could cause these errors. Thus, ensure that the identifier does not contain a trailing slash. The identifier should be <keycloak_host>/auth/realms/WorkfusionRealm, (for example, https://sso-mish-wfaw-10014-auth-lb1.WORKFUSION-LB-HOSTNAME/auth/realms/WorkfusionRealm).

Error type 3

You can also face the following issue during the connection to Control Tower or WorkSpace using ADFS SSO:

"The authentication statement is too old to be used with value XXXX."

For security reasons, the system limits the time enabling processing of SAML messages and assertions. You can customize the time parameters with the following settings.

The system allows users to perform single sign-on for up to 7,200 seconds (120 minutes) since their initial authentication with the IDP, based on the AuthInstance value of the Authentication statement. Some IDPs allow users to stay authenticated for longer periods than this, and you might need to change the default value by setting maxAuthenticationAge of the WebSSOProfileConsumerImpl bean.

Based on the default parameters from Advanced configuration, search by maxAuthenticationAge.

To fix the issue:

1. Use one of the solutions below:

   • On the ADFS server, change the Web SSO lifetime(minutes) value from 480 to 120.

     

     

   • In the /opt/workfusion/workfusion/webapps/workfusion/WEB-INF/classes/spring/saml-security.xml file, add the following parameter with the value of 28,800 seconds (480 minutes, which is the default for ADFS).

     before:

     <bean id="webSSOprofileConsumer" class="org.springframework.security.saml.websso.WebSSOProfileConsumerImpl">
         <property name="responseSkew" value="#{samlProperties.responseSkew}"/>
     </bean>
     

     after:

     <bean id="webSSOprofileConsumer" class="org.springframework.security.saml.websso.WebSSOProfileConsumerImpl">
         <property name="responseSkew" value="#{samlProperties.responseSkew}"/>
         <property name="maxAuthenticationAge" value="28800"/>
     </bean>
     

2. Restart the WorkFusion service.

   wfmanager restart workfusion