Get Started!

˂ Return to FAQ

XTAM and Azure (Office 365) SSO SAML Integration

A cloud-hosted Azure Active Directory is a service provided by Microsoft that can provide a single sign-on using your Active Directory credentials. XTAM supports integration with single sign-on (SSO) logins through a SAML 2.0 identity provider (IDP) like those of Azure AD (AAD) to provide authentication services.
 

Requirements

Before you begin to integrate XTAM with your AAD using SAML, 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. This Active Directory integration provides the security for users and groups in XTAM after they are authenticated via AAD.
  • Access to your existing XTAM host server. You will need to update a configuration file, certificates and restart services.
  • The required Azure subscription plan and an account with access to create and configure Non-gallery applications in Azure Active Directory.

 

Step 1: Create and Configure your Azure AD Enterprise Application

This step describes the process required to create and begin the configuration of your Azure Enterprise Application.

1

Login to your Azure Management Portal and navigate to Azure Active Directory > Enterprise Applications and click on the New application button.

2

On the Add an application blade, select the Non-gallery application tile.

XTAM Azure SSO SAML Integration - Add a Non-gallery Application

3

Enter a new for your application and then click the Add button.

4

Once your app is created, navigate to its Single sign-on menu and click the SAML tile.

XTAM Azure SSO SAML Integration - Single Sign-on SAML Method

5

Now we will begin the first part of this app’s SAML configuration. In the Basic SAML Configuration section, click the Edit button (pencil icon) and populate the following parameters:

5a

Identifier (Entity ID) (Required) – Enter your XTAM host name like https://xtam.company.com

5b

Reply URL (Assertion Consumer Service URL) (Required) – Enter your XTAM host name plus /cas/login?client_name=AzureSSO. For example, https://xtam.company.com/cas/login?client_name=AzureSSO

5c

Sign On URL (Optional) – Enter your XTAM login page like https://xtam.company.com/xtam

5d

Relay State (Optional) – Enter your XTAM login page like https://xtam.company.com/xtam

5e

Logout URL (Optional) – leave empty

XTAM Azure SSO SAML Integration - Basic SAML Configuration

Please do not logout of your Azure Management Portal yet. We will return to this Enterprise Application later to complete the required configuration.

 

Step 2: Begin Configuration of XTAM

This step describes the process required to modify XTAM configuration in order to identify your Azure Enterprise Application.

1

Logon to the XTAM server and open the file $XTAM_HOME/web/conf/catalina.properties in a text editor.

2

Locate the section labeled # CAS and add or update the following lines replacing {cas.managed.path} with your XTAM host server like https://xtam.company.com:

cas.managed.path={cas.managed.path} 
cas.server.name={cas.managed.path}
cas.server.prefix={cas.managed.path}/cas
3

Below this # CAS section, create a new section with the following lines:

# Azure SSO SAML 
cas.authn.pac4j.saml[0].clientName=AzureSSO
cas.authn.pac4j.saml[0].keystorePassword=somePassword
cas.authn.pac4j.saml[0].privateKeyPassword=somePassword 
cas.authn.pac4j.saml[0].serviceProviderEntityId=your Azure Enterprise Application’s Identifier (Entity ID)
cas.authn.pac4j.saml[0].serviceProviderMetadataPath=C:/xtam/content/keys/azuresso.xml
cas.authn.pac4j.saml[0].keystorePath=C:/xtam/content/keys/samlKeystoreAzureSSO.jks
cas.authn.pac4j.saml[0].identityProviderMetadataPath=https://login.microsoftonline.com/yourAzureDirectoryID/federationmetadata/2007-06/federationmetadata.xml?appid=yourAzureEnterpriseApplicationID
cas.authn.pac4j.saml[0].maximumAuthenticationLifetime=2073600
3a

cas.authn.pac4j.saml[0].clientName: This parameter will define the button name on the XTAM login page for this SAML authentication. We recommend not including spaces in this value.

3b

cas.authn.pac4j.saml[0].keystorePassword: Define an alpha-numeric password.

3c

cas.authn.pac4j.saml[0].privateKeyPassword: Define the same alpha-numeric password as the keystorePassword.

3d

cas.authn.pac4j.saml[0].serviceProviderEntityId: Enter the exact value from your Azure Enterprise Application’s Identifier (Entity ID) as configured in step 1.

3e

cas.authn.pac4j.saml[0].serviceProviderMetadataPath: Define an XTAM path and name that will be used for the Federated Metadata xml file. We recommend storing this file in the /content/keys like c:/xtam/content/keys/azuresso.xml (Windows) or /var/opt/xtam/content/keys/azuresso.xml (Linux).

3f

cas.authn.pac4j.saml[0].keystorePath Define an XTAM path and name for the XTAM keystore file (.jks). We recommend storing this file in the /content/keys directory like c:/xtam/content/keys/samlKeystoreAzureSSO.jks (Windows) or /var/opt/xtam/content/keys/samlKeystoreAzureSSO.jks (Linux).

3g

cas.authn.pac4j.saml[0].identityProviderMetadataPath: Enter the entire URL from your Auzre Enterprise Application’s App Federation Metadata URL. The URL should resemble this format: https://login.microsoftonline.com/yourAzureDirectoryID/federationmetadata/2007-06/federationmetadata.xml?appid=yourAzureEnterpriseApplicationID

3h

cas.authn.pac4j.saml[0].maximumAuthenticationLifetime=2073600: This value defines a 24 day period (value in seconds) in which a user has generated a last authentication event in Azure Active Directory. This parameter helps if users begin experiencing login issues due to old Azure authentication events.

XTAM Azure SSO SAML Integration - XTAM Configuration File

Please note, if XTAM is configured to accept sAMAccountName logins as opposed to UserPrincipalName (UPN), then you will need to also add this line to this configuration file: xtam.saml.upn.adjust=true. Otherwise, when XTAM is configured for UPN, you do not have to include this line or if you do, set it to false.

If you want to force a login every time for your users, you can add the following line to this configuration file: cas.authn.pac4j.saml[0].forceAuth=true

4

Save and close this catalina.properties file.

5

Restart the PamManagement service (Windows) or pammanager service (Linux) and wait 2-5 minutes for the service to come back online.

6

To check your work thus far, open your web browser and navigate to the XTAM login page. If you see a red button labelled AzureSSO at the bottom right, please proceed to the next step. If you do not, please double check your configuration in the previous steps and restart the XTAM service once more.

XTAM Azure SSO SAML Integration - XTAM Login Page

 

Step 3: Convert the XTAM Keystore

This step describes the process required to convert the XTAM keystore file (.jks) to a .pfx certificate so it can be uploaded to your Azure Enterprise Application.

1

Now that the XTAM service is fully restarted, the keystore file should now be present in the location defined in the parameter cas.authn.pac4j.saml[0].keystorePath from the step 2. Check that this file exists and is greater than 0 kb in size.

2

To convert this .jks file to the required .pfx format, open a command prompt (you may need to run it with elevated or administrative privileges), change directory to your $XTAM_HOME and execute the following. Replace the values highlighted in red with the exact ones from your configuration in step 2.

bin\Pamkeytool -importkeystore -srckeystore C:\xtam\content\keys\samlKeystoreAzureSSO.jks -srcstoretype JKS -srcstorepass somePassword -destkeystore C:\xtam\content\keys\samlKeystoreAzureSSO.pfx -deststoretype PKCS12 -deststorepass somePassword

XTAM Azure SSO SAML Integration - XTAM Certificate Conversion Command

This command should execute successfully. If you receive any errors, warning or cancellations, resolve these before continuing.

 

Step 4: Complete the Azure Enterprise Application Configuration

This step describes the process required to complete the configuration of your Azure Enterprise Application.

1

Return to your Azure Enterprise Application configuration in your Azure Portal and click the Edit button (pencil icon) for the SAML Signing Certificate section.

2

Click the Import Certificate button, select your .pfx file that was converted in step 3, enter your -deststorepass somePassword from the executed command in step 3 and finally click the Add button.

XTAM Azure SSO SAML Integration - Import XTAM Certificate

3

When this certificate is added, you should now see 2 certificates listed for this Enterprise Application. For the certificate that was just imported, open its context menu and select the option Make certificate active. After it’s status changes to Active, close this blade.

XTAM Azure SSO SAML Integration - SAML Signing Certificate

4

Navigate to the application’s Users and groups menu and add a list of users, or at least your test account for now.

 

Step 5: Complete the XTAM Configuration

This step describes the process required to complete the configuration of XTAM.

1

Return to the XTAM host server, navigate to the directory where the federated metadata xml file was created in step 2 (cas.authn.pac4j.saml[0].serviceProviderMetadataPath) and delete this .xml file.

2

Restart the PamManagement service (Windows) or pammanager service (Linux) again and wait 2-5 minutes for the service to come back online.

3

When the service comes back online, a new xml file should have been downloaded from the Azure Enterprise Application and saved to this location with the defined file name.

XTAM Azure SSO SAML Integration - Federated Metadata XML File

If the file is not automatically downloaded after this service restart, then you can manually download the xml file from the SAML Signing Certificate section by clicking the Federation Metadata XML Download link. Once downloaded, copy the file to this location and rename it to the expected file name as defined in the XTAM configuration. Lastly, restart the XTAM service again to complete this manual process. XTAM Azure SSO SAML Integration - Federated Metadata XML Download Link

 

Step 6: Test the Integration

This final step is used to test the integration between XTAM and your Azure Active Directory Enterprise Application.

1

Open a new browser session (private or incognito) and navigate to the XTAM login page.

2

Located on the bottom right of this login page, you should see a new red button labeled AzureSSO or whatever value you entered for the client name earlier.

XTAM Azure SSO SAML Integration - XTAM Login Page

3

To test the integration, the following is expected:

  • When you click this red AzureSSO button, you will be redirected to the the Microsoft Login page
  • You will enter your Azure Active Directory username that has been giving access to the Enterprise Application earlier and click Next.XTAM Azure SSO SAML Integration - Microsoft Online User Prompt
  • You will enter the password for this user account and click Sign in.XTAM Azure SSO SAML Integration - Microsoft Online Password Prompt
  • After the account is authenticated against Azure Active Directory, you will be redirected to the XTAM homepage (All Records view) and your account should be displayed as logged in.XTAM Azure SSO SAML Integration - Login Successful

If you receive any errors during this test procedure, then recheck all configuration that was entered in the previous steps and restart the XTAM service again.

 
 

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