Implementing single sign-on in Elvis 6 using AD FS

Logging in to Elvis using single sign-on (SSO) using Active Directory Federation Services (AD FS) is one of the ways of logging in to Elvis using SSO.

This article describes how to implement AD FS in Elvis.

How it works

The process is as follows:

1. A user logs in on a machine that is connected to the same domain as the AD FS that is configured in Elvis.
2. Using Internet Explorer or Edge, the user accesses Elvis.
3. Elvis Server redirects the user to AD FS.
4. AD FS recognizes the user's Windows domain log-in.
5. AD FS automatically redirects the user back to Elvis.
6. The user is logged in to Elvis without ever seeing a log-in screen.

Note: Single sign-on without a password pop-up only works when on a system with Windows installed in combination with a Microsoft Web browser. For other Web browsers and operating systems, the user will be redirected to the AD FS login page once.

Supported clients

The following table shows for which Elvis clients single sign-on is supported:

Single sign-on behavior

How the single sign-on process behaves depends on one of the following scenarios:

Scenario 1: the user is not logged in to Active Directory

• When a user accesses the Pro client, Brand portal or Management console, the user logs in through Active Directory
• When a user accesses the InDesign client or the Admin pages, the user needs to log in directly to Elvis using the Elvis log in screen

Scenario 2: the user is already logged in to Active Directory (outside of Elvis)

• When a user accesses the Pro client, Brand portal or Management console, logging in is done automatically
• When a user accesses the InDesign client or the Admin pages, the user needs to log in directly to Elvis using the Elvis log in screen

Scenario 3: the user is logged in to Active Directory through the Pro client, Brand portal or Management console

• When a user accesses the Pro client, Brand portal, Management console or Admin pages, logging in is done automatically
• When a user accesses the InDesign client, the user needs to log in directly to Elvis using the Elvis log in screen

Requirements

Making this implementation work requires Microsoft AD FS (Active Directory Federation Services).

Implementation

Implementing the single sign-on process in Elvis Server 6 consists of the following steps:

1. Setting up HTTPS

2. Setting up LDAP

3. Creating a single sign-on keystore

4. Creating and importing a token-signing certificate

5. Configuring Elvis Server

6. Adding relying party trust

7. Configuring relying party trust

8. Testing the implementation

1. Setting up HTTPS

Make sure that a secure connection between Elvis and its clients exists by configuring Elvis Server to use HTTPS or by running Elvis Server behind a HTTPS terminating proxy or a load balancer.

2. Setting up LDAP

The single sign-on feature works by connection to Active Directory through LDAP. Make sure that Elvis Server is set up for connecting to LDAP by following the steps in section 'Connecting Elvis to LDAP' in Setting up users and user groups in Elvis 6.

3. Creating a single sign-on keystore

Authentication and authorization data is transferred using the Security Assertion Markup Language (SAML) format.

Elvis Server must sign the SAML requests made to the identity provider by using a keystore with a private key.

Create a keystore file by for example using the Java Keytool.

keytool -genkey -keystore "/srv/elvis-server/config/sso-keystore.jks" -storepass secret -keypass secret -alias elvis-signing -validity 1825 -dname 'CN=elvis,DC=contoso,DC=com' -keyalg RSA

Note: Make sure that the keystore password (storepass) and the key password (keypass) values are the same.

4. Creating and importing a token-signing certificate

A token-signing certificate is used to prevent attackers from altering or counterfeiting security tokens in an attempt to gain unauthorized access to federated resources. This certificate needs to be created and subsequently imported into the single sign-on keystore.

Generating the token-signing certificate

Step 1. Access Windows Server Manager, click Tools, and select AD FS Management.

Step 2. In the AD FS snap-in, under AD FS\Service\Certificates > Token-signing, right-click the certificate and click View Certificate.

The Certificate dialog box appears.

Step 3. Access the Details tab and click Copy to File.

The Certificate Export Wizard dialog box appears.

Step 4. Click Next.

The Export File Format page appears.

Step 5. Select the Base-64 encoded X.509 option and click Next.

The File to Export page appears.

Step 6. Click Browse to specify the export file, click Next, followed by clicking Finish.

Importing the file

Use the Java Keytool to import the ADFS token-signing certificate to the Elvis Server configured SSO keystore. Use the following command:

keytool -importcert -file token-signing-base64.cer -keystore "/srv/elvis-server/config/sso-keystore.jks" -alias adfs-token-signing

5. Configuring Elvis Server

Step 1. In the cluster-config.properties.txt file, configure the following settings:

• samlIdpMetadataUrl. The identity provider metadata URL.

Example: samlIdpMetadataUrl=https://fs.contoso.com/FederationMetadata/2007-06/FederationMetadata.xml

• samlSpEntityId. The unique identifier of the service provider.

Note: This does not need to be a valid URL although it is recommended to use one.

Example: samlSpEntityId=https://elvis.contoso.com

Step 2. In the node-config.properties.txt file, configure the following settings:

• samlKeyStore. File path pointing to the SAML keystore.

Example: samlKeyStore=${configDir}/sso-keystore.jks

• samlDefaultKey. Default key in the keystore.

Example: samlDefaultKey=elvis-signing

• samlKeyStorePassword. Password for the SAML keystore.

Example: samlKeyStorePassword=secret

Step 3. Make sure that the configuration property "serverUrl" in the node-config.properties.txt file has been set correctly.

Example: serverUrl=https://elvis.contoso.com.

Step 4. (Optional) Additional setting in the cluster-config.properties.txt file: 

• samlClientDefaultLogin. The default log in mode of the Pro client and other clients when SAML, single sign-on, or normal log in is configured.

Possible values: 

• true: The client by default proposes logging in using SAML or single sign-on
• false: The normal log in for LDAP users is provided

Example: samlClientDefaultLogin=false

Step 5. Restart Elvis Server.

6. Adding relying party trust

A relying party trust object consists of a variety of identifiers, names, and rules that identify this partner or Web application to the local Federation Service. (Source: microsoft.com Understanding Key AD FS Concepts.)

This relying party trust object needs to be added in Windows.

Note: It is assumed here that Windows 2012 R2 is used.

Step 1. From a running Elvis Server, get the SAML metadata by accessing the /saml/metadata endpoint with a Web browser and saving the file. (It will be used later in the process.)

Example: Accessing https://elvis.contoso.com/saml/metadata will result in the file 'spring_saml_metadata.xml'.

Step 1. Access Windows Server Manager, click Tools, and select AD FS Management.

Step 2. In the AD FS snap-in, under AD FS\Service\Certificates > Token-signing, right-click the certificate and click View Certificate.

Step 3. In the AD FS snap-in, under AD FS\Trust Relationships, right-click Relying Party Trusts, and click Add Relying Party Trust.

The Add Relying Party Trust Wizard is opened.

Step 4. On the Welcome page, click Start.

The Select Data Source page appears.

Step 5. Click Import data about the relying party from a file, click Browse to select the file generated in step 1, and click Next.

The Specify Display Name page appears.

Step 6. Type a name in the Display name field, under Notes type a description for this relying party trust, and click Next.

The Configure Multi-factor Authentication Now? page appears. In this example, this step is skipped; it can be configured later if desired.

Step 7. Click Next.

The Choose Issuance Authorization Rules page appears.

Step 8. Select either Permit all users to access this relying party or Deny all users access to this relying party, and click Next.

The Ready to Add Trust page appears.

Step 9. Review the settings and click Next to save your relying party trust information.

The Finish page appears.

Step 10. Click Close.

The Edit Claim Rules dialog box is displayed.

7. Configuring relying party trust

The Relying Party Trust in Windows needs to be configured to work correctly in Elvis. This is done by editing the Claim rules and changing some properties.

Editing the Claim Rules

Step 1. Access Windows Server Manager, click Tools, and select AD FS Management.

Step 2. In the AD FS snap-in, under AD FS\Trust Relationships\Relying Party Trusts, right-click the Elvis Party Trust and click Edit Claim Rules.

The Edit Claim Rules dialog box appears.

Step 3. Access the Issuance Transform Rules tab and click Add Rule to start the Transform Claim Rule Wizard.

The Choose Rule Type page appears.

Step 4. From the list, select Send LDAP Attributes as Claims and click Next.

The Configure Claim Rule page appears.

Step 5. Do the following:

• Under Claim rule name, type the display name for this rule.

• Under Attribute store, select Active Directory,

• Under Mapping of LDAP attributes to outgoing claim types, match the following LDAP attributes and Outgoing Claim Types:

Step 6. Click Finish followed by OK.

Changing properties

Step 1. In the AD FS snap-in, under AD FS\Trust Relationships\Relying Party Trusts, right-click the Elvis Party Trust and click Properties.

The Properties dialog box appears.

Step 2. Select the Encryption tab and click Remove to remove the Encryption certificate.

Step 3. Select the Advanced tab, make sure that SHA-256 is selected and click OK.

8. Testing the implementation

Test the implementation by trying out some or all of the scenarios described in Single sign-on behavior.