XTAM and ADFS Integration

A self-hosted Active Directory Federation Services (ADFS) is a service provided by Microsoft that provides a web login using your existing Active Directory credentials. XTAM supports integration with single sign-on (SSO) logins through a SAML 2.0 identity provider (IDP) like those of ADFS to provide authentication services.

Requirements

Before you begin to integrate XTAM with your ADFS, be sure you met the following pre-requisities:

  • A working XTAM deployment with the Federated Sign-In experience. The XTAM Federated Sign-In module provides the required SAML 2.0 web login functionality.
  • A working XTAM deployment with Active Directory integration. The Active Directory integration provides the security for users and groups in XTAM after they are authenticated via ADFS.
  • Access to your existing XTAM host server. You will need to update a configuration file, certificates and restart services.
  • Access to your existing ADFS Management module for Active Directory. You will need to create a new Relying Party Trust.
  • Your ADFS certificate to sign the login experience.

Configuring and installing ADFS is beyond the scope of this article, so we will provide a link to this Microsoft KB article for detailed information.

Step 1: Download your ADFS Federation Metadata File to XTAM

  1. Login to your XTAM host server and open your browser.
  2. Download and Save your ADFS Metadata xml file to {XTAM_HOME}/content/keys. This file can be found in this example location: https://<ADFS_hostname>/FederationMetadata/2007-06/FederationMetadata.xml
  3. XTAM-Download-ADFS-Federation-Metadata-XML

    Step 2: Import your ADFS Self-Signed Certificate to XTAM

    If your ADFS deployment is using a self-signed certificate, then continue with this step. Otherwise, skip step 2 and proceed to step 3.

  1. Export your self-signed certificate, copy it to your XTAM host server and paste it to {XTAM_HOME}/content/keys.
  2. Open a command line and navigate to the folder where XTAM is installed {$XTAM_HOME} and issue the following command:
    1. For Windows, substitute PATH_TO_CERTIFICATE_FILE.cer with the location and name of the self-signed .cer certificate file to be imported and used by XTAM.

      Copy
      bin\PamKeytool.cmd -import -alias xtadfs -file PATH_TO_CERTIFICATE_FILE.cer -keystore jre\lib\security\cacerts
    2. For Unix or Linux, substitute PATH_TO_CERTIFICATE_FILE.cer with the location and name of the self-signed .cer certificate file to be imported and used by XTAM.

      Copy
      bin/PamKeytool.sh -import -alias xtadfs -file PATH_TO_CERTIFICATE_FILE.cer -keystore jre/lib/security/cacerts

     

  3. After the command is issued, you will be prompted for the keystore password. Enter the value changeit and press the Enter key to continue.

  4. When prompted Trust this certificate? enter y and press the Enter key. You will receive the message Certificate was added to keystore when it has imported successfully.

    XTAM-ADFS-Import-SelfSigned-Certificate

Step 3: XTAM Configuration

This step describes the process required to modify XTAM configuration in order to identify your ADFS provider.

 

  1. Open the following file in a text editor {XTAM_HOME}/web/conf/catalina.properties
  2. Locate the section labeled # CAS and add the following lines:
  3. Copy
    cas.server.name={managed_path}
    cas.server.prefix={managed_path}/cas
     
    cas.authn.pac4j.saml[0].clientName=ADFS
    cas.authn.pac4j.saml[0].serviceProviderEntityId={managed_path}
    cas.authn.pac4j.saml[0].serviceProviderMetadataPath={FederationMetadata.xml}
    cas.authn.pac4j.saml[0].keystorePath={samlKeystore.jks}
    cas.authn.pac4j.saml[0].keystorePassword={password}
    cas.authn.pac4j.saml[0].privateKeyPassword={password}
    cas.authn.pac4j.saml[0].identityProviderMetadataPath={path}

  4. In the lines above, the following {placeholders} need to be updated using your own values as explained here:

    1. cas.server.name={managed_path} — Your XTAM host name. For example, https://xtam.company.com
    2. cas.server.prefix={managed_path}/cas — Your XTAM host name. For example, https://xtam.company.com
    3. cas.authn.pac4j.saml[0].serviceProviderEntityId={managed_path} — Your XTAM host name. For example, https://xtam.company.com
    4. cas.authn.pac4j.saml[0].serviceProviderMetadataPath={FederationMetadata.xml} — The full path and file name of the FederationMetadata.xml file that was saved in step (1). For example, C:/xtam/content/keys/FederationMetadata.xml (use forward slashes not backslashes)
    5. cas.authn.pac4j.saml[0].keystorePath={samlKeystore.jks} — Define a path and name for the XTAM auto-generated key. For example, C:/xtam/content/keys/samlKeystore.jks (use forward slashes not backslashes)
    6. cas.authn.pac4j.saml[0].keystorePassword={password} — Create an alphanumeric password. Any value you want to enter.
    7. cas.authn.pac4j.saml[0].privateKeyPassword={password} — Create an alphanumeric password. Any value you want to enter.
    8. cas.authn.pac4j.saml[0].identityProviderMetadataPath={path} — Copy and paste the full URL from your Identity Provider Metadata used in step (1). For example, https://<ADFS_hostname>/FederationMetadata/2007-06/FederationMetadata.xml.
  5. When finished, save and close this file.
  6. Restart the PamManagement (Windows) or the pammanager (Linux) service.

  7. After the service restarts, open a browser and navigate to the XTAM login page. If the XTAM login page is already open, then simply refresh this page.

  8. Open your file explorer, navigate to {XTAM_HOME}/content/keys and ensure that the samlKeystore.jks file was created. If the file is not present, then login to XTAM using a non-ADFS

    account and check again.

    XTAM-ADFS-samlKeystore-File-Generated

Step 4: Generate an XTAM Certificate

This step will generate an XTAM certificate to be used later as the Signature in your ADFS Relying Partner Trust.

 

  1. On the XTAM host server, open a command line and navigate to the folder where XTAM is installed {$XTAM_HOME} and issue the following command:
    1. For Windows:

      Copy
      bin\PamKeytool.cmd -keystore content\keys\samlKeystore.jks -export -alias saml2clientconfiguration -file content\keys\adfsxtam.cer
    2. For Unix or Linux:

      Copy
      bin\PamKeytool.sh -keystore content/keys/samlKeystore.jks -export -alias saml2clientconfiguration -file content/keys/adfsxtam.cer
  2. When prompted for the keystore password, enter the password you supplied in Step 3 Bullet 3f (cas.authn.pac4j.saml[0].keystorePassword={password}).

    XTAM-ADFS-Generate-XTAM-Certificate

  3. The XTAM certificate will be generated and saved to {XTAM_HOME}/content/keys/adfsxtam.cer. Locate and then Copy this certificate file to your ADFS server.

    XTAM-ADFS-Certificate-File-Generated

Step 5: Create an ADFS Relying Party Trust for XTAM

This section will describe how to create a new Relying Party Trust for XTAM to use for the integration. The connection between ADFS and XTAM is defined using this Relying Party Trust (RPT).

 

  1. Login to your ADFS server.
  2. Open your ADFS Management snap-in and click the Add Relying Party Trust… link to open the wizard. On the wizard’s Welcome screen, click the Start button to begin.
  3. XTAM-ADFS-Add-RPT-Step1-Welcome

  4. On the Select Data Source screen, select the last option, Enter data about the relying party manually and thenclick Next.

    XTAM-ADFS-Add-RPT-Step2-Data-Source

  5. On the Specify Display Name screen, enter a Display name that you’ll recognize and optionally any Notes you wish to include and then click Next.

    XTAM-ADFS-Add-RPT-Step3-Display-Name

  6. On the Choose Profile screen, select the ADFS FS profile radio button and then click Next.

    XTAM-ADFS-Add-RPT-Step4-Profile

  7. On the Configure Certificate screen, leave the certificate settings at their defaults and then click Next.

    XTAM-ADFS-Add-RPT-Step5-Certificate

  8. On the Configure URL screen, check the box labeled Enable support for the SAML 2.0 WebSSO protocol. The relying party service URL will be your {managed path} defined previously plus /cas/login?client_name=ADFS. For example, https://xtam.company.com/cas/login?client_name=ADFS. Click Next to continue.

    XTAM-ADFS-Add-RPT-Step6-URL

  9. On the Configure Identifiers screen, enter your {managed path} URL and then click the Add button. For example, https://xtam.company.com. Note that this URL must match exactly to what was used previously. Click Next to continue.

    XTAM-ADFS-Add-RPT-Step7-Identifiers

  10. On the next screen, you may configure multi-factor authentication if desired, but for this article we will enable the I do not want to configure multi-factor authentication settings for this relying party trust at this time and then click Next to continue.XTAM-ADFS-Add-RPT-Step8-MFA

  11. On the Choose Issuance Authorization Rules screen, select the Permit all users to access this relying party radio button and then click Next.

    XTAM-ADFS-Add-RPT-Step9-Permit-All

  12. On the Ready to Add Trust screen, review your settings and then click Next to continue.

    XTAM-ADFS-Add-RPT-Step10-Ready

  13. On the Finish screen, ensure the Open the Edit Claims Rules dialog option is checked and then click the Close button to continue.

    XTAM-ADFS-Add-RPT-Step11-Finish

Step 6: Create your ADFS Relying Party Trust Claim Rules

The Edit Claims Rules for your new Relying Trust will open automatically. If it does not open automatically, select your RPT from the list and then click the Edit Claims Rules options in the Actions menu. We will now configure a rule to finalize the ADFS integration.

 

  1. On the Issuance Transform Rules tab, click on the Add Rule button.
  2. XTAM-ADFS-Add-Rules-Step1-Add-Rule

  3. In the Add Transform Claim Rule Wizard, on the Choose Rule Type page, select Send LDAP Attributes as Claims for the Claim rule template. Click Next to continue.

    XTAM-ADFS-Add-Rules-Step2-Rule-Template

  4. On the Configure Rule screen, enter Attributes from AD as the Claims rule name.

  5. On the Configure Rule screen, select Active Directory from the Attribute store dropdown.

  6. On the Configure Rule screen, from the LDAP Attribute column, select User-Principal-Name.

  7. On the Configure Rule screen, from the Outgoing Claim Type column, select Name ID.

    XTAM-ADFS-Add-Rules-Step3-Configure-Rule

  8. Click the Finish button to continue.

  9. When you return to the Edit Claims Rule dialog, click its OK button to complete the creation of your rules.
  10. XTAM-ADFS-Add-Rules-Step4-Finish

Step 7: Add the XTAM Certificate to your RPT

In this step, we will add the XTAM certificate that we previously generated to your new RPT.

 

  1. In the ADFS Management snap-in, navigate to the AD FS > Trust Relationships > Relying Party Trusts section in the menu.
  2. Select your newly created RPT from the list, then right click and choose Properties.
  3. XTAM-ADFS-Add-Signature-Step1

  4. When the Properties dialog appears, click on the Signature tab.

    XTAM-ADFS-Add-Signature-Step2

  5. Click the Add button to add your XTAM certificate.

  6. In the Select a Request Signature Verification Certificate dialog, locate and select your adfsxtam.cer file (the one we generated in step 4) and then click Open.

  7. Your certificate will now be listed in the Signature table. Click the OK button to complete this step.

    XTAM-ADFS-Add-Signature-Step3

And that is it. You should now have a working ADFS SSO implementation for your XTAM deployment. Return to your XTAM login page, refresh and then click on the new Login with ADFS option on the bottom right to test your integration.

 

XTAM-ADFS-Integration-ADFS-Login-Option-1024x655

 

XTAM-ADFS-Integration-ADFS-Login-Page-1024x655

 

For security reasons, after you logout of XTAM, exit or close your web browser to securely complete the operation.