Get Started!

˂ Return to FAQ

XTAM and ADFS SSO 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

XTAM ADFS - Download Federation Metadata XML File

 

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:

2a

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.

bin\PamKeytool.cmd -import -alias xtadfs -file PATH_TO_CERTIFICATE_FILE.cer -keystore jre\lib\security\cacerts
2b

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.

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 Self-Signed 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:

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}
3

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

3a

cas.server.name={managed_path} — Your XTAM host name. For example, https://xtam.company.com

3b

cas.server.prefix={managed_path}/cas — Your XTAM host name. For example, https://xtam.company.com

3b

cas.authn.pac4j.saml[0].serviceProviderEntityId={managed_path} — Your XTAM host name. For example, https://xtam.company.com

3e

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)

3f

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)

3c

cas.authn.pac4j.saml[0].keystorePassword={password} — Create an alphanumeric password. Any value you want to enter.

3d

cas.authn.pac4j.saml[0].privateKeyPassword={password} — Create an alphanumeric password. Any value you want to enter.

3g

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.

4

When finished, save and close this file.

5

Restart the PamManagement (Windows) or the pammanager (Linux) service.

6

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.

7

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:

1a

For Windows:

bin\PamKeytool.cmd -keystore content\keys\samlKeystore.jks -export -alias saml2clientconfiguration -file content\keys\adfsxtam.cer
1b

For Unix or Linux:

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 3c (cas.authn.pac4j.saml[0].keystorePassword={password}).

XTAM ADFS - Generate XTAM ADFS 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 - XTAM Certificate 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.

XTAM ADFS - Create RPT - Welcome Screen

3

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

XTAM ADFS - Create RPT - Select Data Source Step

4

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 - Create RPT - Specify Display Name Step

5

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

XTAM ADFS - Create RPT - Choose Profile Step

6

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

XTAM ADFS - Create RPT - Configure Certificate Step

7

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 - Create RPT - Configure URL Step

8

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 - Create RPT - Configure Identifiers Step

9

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 - Create RPT - MFA Configuration Step

10

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 - Create RPT - Permit All Users Step

11

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

XTAM ADFS - Create RPT - Ready to Add Step

12

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 - Create RPT - Finish Step

 

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.

XTAM ADFS - Create Claim Rule - Add Rule Step

2

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 - Create Claim Rule - Rule Template Step

3

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

4

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

5

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

6

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

XTAM ADFS - Create Claim Rule - Rule Type Step

7

Click the Finish button to continue.

8

When you return to the Edit Claims Rule dialog, click its OK button to complete the creation of your rules.

XTAM ADFS - Create Claim Rule - Finish Step

 

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.

XTAM ADFS - Add Signature to RPT

3

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

XTAM ADFS - Add Signature

4

Click the Add button to add your XTAM certificate.

5

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.

6

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

XTAM ADFS - Add Signature Certificate

 
 
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 SSO Login Page Button

XTAM ADFS SSO Login Page

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

 
 

Copyright © 2018 Xton Technologies, LLC. All rights reserved.