Use SAML and PingFederate to Authenticate Users

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 Core Platform. 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 to Enable SAML Authentication with PingFederate

To enable SAML authentication with PingFederate, follow these steps:

  1. 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
  2. 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\.

  3. 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 sign-in details and can access the Dashboard by clicking SIGN IN.

    If you want to sign in 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.