Implementing single sign-on in Assets Server using AD FS

Info: Performing some of the steps described in this article requires direct server access. Depending upon how your system is hosted and the level of access you have to that system, coordination may be required with your Partner or WoodWing Support team. For a full overview of the steps that need to be done by WoodWing and how to request them, see WoodWing Cloud - Change management.

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

This article describes how to implement AD FS in Assets Server.

Note: AD FS cannot be used when running Assets Server on our WoodWing Cloud platform.

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 Assets Server.
2. Using Internet Explorer or Edge, the user accesses Assets Server.
3. Assets 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 Assets Server.
6. The user is logged in to Assets Server 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 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 Assets, Brand portal, or Management console, the user logs in through Active Directory
• When a user accesses Assets for InDesign or the Admin pages, the user needs to log in directly to Assets Server using the Assets Server log in screen

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

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

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

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

Requirements

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

Implementation

Implementing the single sign-on process in Assets Server 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 Assets 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 Assets Server and its clients exists by configuring Assets Server to use HTTPS or by running Assets 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 Assets Server is set up for connecting to LDAP by following the steps in section 'Connecting Assets Server to LDAP' in Setting up users and user groups in Assets Server.

3. Creating a single sign-on keystore

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

Assets 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 Assets Server configured SSO keystore. Use the following command:

Copy the command

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

5. Configuring Assets 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://assets.server.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://assets.server.contoso.com.

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

• samlClientDefaultLogin. The default log in mode of Assets 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 Assets 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 Assets 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://assets.server.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 Assets Server. 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 Assets Server 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 Assets Server 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.