Using SAML and PingFederate to Authenticate Users – Acrolinx

Platform	Version
Core Platform	5.1, 5.2, 5.3, 5.4, 5.5, 5.6, 2018.10

Security Assertion Markup Language (SAML) is an XML-based, open-standard data format for exchanging authentication and authorization data between parties. In particular, between an identity provider and a service provider. SAML is one of the most popular technologies used to implement single sign-on for web-based applications. To authenticate users with SAML, you need a federation server that supports this technology.

Currently, the Acrolinx SAML implementation works exclusively with the PingFederate® server from Ping Identity. You must have a PingFederate server installed and running before you configure the Acrolinx server. If you don't have a PingFederate server, we can work with our hosting provider Rackspace to set one up for you. Contact your Acrolinx project consultant for more details.

Your PingFederate server must also have a connection to an identity management service such as Centrify, Okta, or OneLogin.

How Enable SAML Authentication with PingFederate

To enable SAML authentication with PingFederate, follow these steps:

Open your overlay of the core server properties file.

You find the overlay for the core server properties file in the following location:

%ACROLINX_CONFIGURATION_ROOT%\server\bin\coreserver.properties

Add the following properties:

dashboard.loginMode=authToken
authentication.useExternal=true
authentication.external=pingfederate
authentication.external.pingfederate.serviceProviderUrl=<PINGFEDERATE_SERVER_ADDRESS>/sp/startSSO.ping?PartnerIdpId=<IDENTITY_SERVICE_URL>
authentication.external.pingfederate.agentConfigFile=<PATH_TO_PINGFEDERATE_AGENT_CONFIG_FILE>

The following example shows a connection to a PingFederate server that uses Okta SSO as the identity management service:

dashboard.loginMode=authToken
authentication.useExternal=true
authentication.external=pingfederate
authentication.external.pingfederate.serviceProviderUrl=https://pingfederate.demo-inc.com:9031/sp/startSSO.ping?PartnerIdpId=http://www.okta.com/exk8b0rw7wgVJEIwS0h7
authentication.external.pingfederate.agentConfigFile=C:\files\agent-config.txt

If you don't yet have an agent config file, you can download one by following the procedure to Configure the OpenToken SP Adapter. If you drop the property authentication.external.pingfederate.agentConfigFile, the server will look for the agent-config.txt file in the directory <INSTALL_DIR>\server\bin\.

Save your changes and restart the core server.
When you open the Acrolinx Dashboard in your browser, the browser is redirected first to PingFederate and then to your identity provider. You sign in to your identity provider with your single sign-on credentials. Once you sign in, your identity provider redirects you back to PingFederate, which in turn redirects you back to the Dashboard.

The Dashboard shows a minimal sign-in screen where you can select the interface language only. You don't have to enter any user credentials and can access the Dashboard by clicking SIGN IN.

If you want to log on to the Dashboard with an Acrolinx admin account, click ADMINISTRATIVE LOGIN. This takes you to the standard Dashboard sign-in form where you can enter your admin sign-in details.

Normalized Usernames

We generally normalize usernames, even with external authentication like PingFederate. This means that we keep every character that falls under the following unicode categories:

Pc (CONNECTOR_PUNCTUATION)
Mc (COMBINING_SPACING_MARK)
Mn (NON_SPACING_MARK)
Nd (DECIMAL_DIGIT_NUMBER)
Lu (UPPERCASE_LETTER)
Ll (LOWERCASE_LETTER)
Lt (TITLECASE_LETTER)
Lm (MODIFIER_LETTER)
Lo (OTHER_LETTER)
Nl (LETTER_NUMBER)
or is "@", ".", or "-"

All other characters get replaced by "_".

Note that identical normalized usernames could lead to losing or overwriting user settings.