Configuring the SAML authentication

The SAML (Security Assertion Markup Language) authentication is an open standard that makes it possible to use a single authentication on an identification portal for various applications.

Within the SAML protocol, there are two distinct entities:

IdP (Identity Provider): The identities manager, that manages authentication and guarantees the authenticity of a person and of the information linked to that person. The following providers are among the most well-known: Microsoft ADFS (via Active Directory), Azure AD, Okta and Auth0.
SP (Service Provider): The service provider that delegates the authentication to the IdP. This is the Akuiteo server.

Note

The SAML protocol provides two types of operations: the Authentication and the Provisioning. The Provisioning, which is used to create and feed an unknown user, is not handled by Akuiteo.

Configuring the IdP: ADFS

Creating a relying party trust

The detailed process for creating a relying party trust is available in the Microsoft documentation. The process below describes the steps to set up SAML for Akuiteo specifically.

From the server manager, click on Tools > AD FS Management.

From the Actions section on the right, click on Add Relying Party Trust.

In the creation window, specify the following information:

On the Select Data Source page, select Enter data about the relying party manually.
On the Configure URL page, check the Enable support for the SAML 2.0 WebSSO protocol box and specify the relying party SAML 2.0 SSO service URL, that is to say the SAML URL of the Service Provider (Akuiteo), for example: https://XXXXX/akuiteo/saml/SSO.

Note

This URL must be secured and start with https://. It must also be accessible from an employee's computer (internal address of a local network or accessible from outside of the network).

On the Configure Identifiers page, fill in the Akuiteo server's URL, for example: https://akuiteo.myakuiteo.com/akuiteo.
On the Choose Access Control Policy page, select the following strategy: Permit everyone.

Complete the trust's creation.

Configuring claim rules

Now, you must create two claim rules:

The first rule is a mapping one to link the AD's email field to the SAML message's email field.
The second rule to transform the SAML message's email field into a NameID.

From the list of relying party trusts, right-click on the new trust > Edit Claim Issuance Policy....

From the Issuance Transform Rules tab, click on Add Rule... to create the first rule:

On the Choose Rule Type page, select the Send LDAP Attributes as Claims template.
On the Configure Claim Rule page, select the following information:
- Attribute store = Active Directory
- LDAP Attribute = E-Mail Addresses
- Outgoing Claim Type = E-Mail Address

Then, create the second rule:

On the Choose Rule Type page, select the Transform an Incoming Claim template.
On the Configure Claim Rule page, select the following information:
- Incoming claim type = Email
- Outgoing claim type = Name ID
- Outgoing name ID format = Email
- Pass through all claim values checked

Configuring the IdP: Azure AD

In a web browser, enter the following address https://portal.azure.com/ and log in as an administrator. In the home page, click on the View button in the Manage Azure Active Directory section.

Click on Enterprise applications from the left menu, then click on New application from the header of the application page.

Then, click on Create your own application.

Give an Input name to this new application (Akuiteo-Production for example) and leave the Integrate any other application you don't find in the gallery (Non-gallery) option checked. Then, click on Create.

On the new application's page, select the 2. Set up single sign on block then select the SAML block.

In the authentication configuration page, fill in the required fields:

Identifier (Entity ID) - URL of your Akuiteo server, for example: https://akuiteo.myakuiteo.com/akuiteo
Reply URL - URL for the SAML connection based on the previous URL (with the /saml/SSO suffix), for example: https://akuiteo.myakuiteo.com/akuiteo/saml/SSO

Configuring Akuiteo

Generating a private encryption key

Note

This step is not required for SaaS customers.

The Akuiteo server must have a certificate file in the .jks format in order to encrypt the exchanges with the IdP. To do this, we use Java Keytool to create a self-signed certificate.

On the Akuiteo server, run the following command line:

Copy

keytool -genkey -keyalg RSA -alias saml -keystore saml.jks -keysize 2048

Fill in the main information of the certificate and make sure to keep the file's password. The following is an example:

Copy

Quels sont vos nom et prénom ?
  [Unknown]:  Akuiteo
Quel est le nom de votre unité organisationnelle ?
  [Unknown]:  IT
Quel est le nom de votre entreprise ?
  [Unknown]:  Akuiteo
Quel est le nom de votre ville de résidence ?
  [Unknown]:  Lyon
Quel est le nom de votre état ou province ?
  [Unknown]:  Rhône
Quel est le code pays à deux lettres pour cette unité ?
  [Unknown]:  FR
Est-ce CN=Akuiteo, OU=IT, O=Akuiteo, L=Lyon, ST=Rhône, C=FR ?
  [non]:  oui
  
Entrez le mot de passe de la clé pour <saml>
        (appuyez sur Entrée s'il s'agit du mot de passe du fichier de clés) :
Ressaisissez le nouveau mot de passe :
  
Warning:
Le fichier de clés JKS utilise un format propriétaire. Il est recommandé de migrer vers PKCS12, qui est un format standard de l'industrie en utilisant "keytool -importkeystore -srckeystore saml.jks -destkeystore saml.jks -deststoretype pkcs12".

A saml.jks file is generated. This file will then be used for configuring Akuiteo.

Extracting the public certificate

On the Akuiteo server, run the following command line:

Copy

keytool -export -alias saml  -keystore "C:\Keys\saml.jks" -rfc -file C:\Keys\saml.cert

Where the path contains a reference to the Akuiteo server.

If needed, import the saml.cert file on ADFS.

Configuring the Administration console

On Akuiteo's side, the information to configure SAML is defined in the Administration console, from the Security > SAML menu.

From the SAML configurations screen, click on the New configuration button at the top right of the screen.

In the configuration window, fill in the following fields:

Field	Description
Code	Enter a code to identify the configuration. This code must be unique.
Active configuration	Check this box to activate the SAML authentication. If the box is not checked, the authentication will be based on another authentication method (if active) or on the database.
IDP	Fill in the IdP's identifier field, which is the Entity ID. You can find this ID in the metadata.xml field. If you use Active Directory, this is the Azure AD Identifier.
Audience	Fill in the application ID for the IdP and the public URL. If you use Active Directory, this is the Identifier (Entity ID).
MetaLocation	Fill in the location of the metadata file (URL or local file). If you use Active Directory, this is the URL of the federation metadata file.
KeyAlias	Fill in the alias of the certificate file (.jks).
KeyPwd	Fill in the password of the certificate file (.jks).
KeyLocation	Fill in the location of the certificate file (.jks).
userNameDomains	When the SAML authentication is active, any email login is redirected by default to the IdP in order to be authenticated. If you want to limit this authentication to specific email domains, add those domains in the userNameDomains field. That field allows you to specify: either a single domain, or a list of domains, separated by a comma (,). For example: akuiteo.com, myakuiteo.com
redirectDomainWhitelist	If the authentication domain is different from the domain used to access the Akuiteo application, the authentication domain must be authorized on Akuiteo's business server. In that case, specify the authentication domain to authorize. For example: exemple.authentification.com

Note

For the MetaLocation and KeyLocation files, the protocol must be specified in the header. If a file is stored locally, add file:/ at the beginning of the path.

Click on Save.

If the connection is made, the configuration is added to the Administration console. If the connection cannot be made, an error message is displayed.

Restart the server to take the configuration into account.

To modify a configuration, click on for the relevant line, make all necessary modifications then click on Update.

To delete a configuration, click on for the relevant line then confirm the deletion.

Configuring Tomcat

Removing the comment on the Manager tag

From the Tomcat installation directory of the Akuiteo server, go to conf.

Open the context.xml configuration file with a text editor.

Remove the comment on the <Manager ... /> tag as follows:

Copy

<Context>
    <!-- Default set of monitored resources -->
    <WatchedResource>WEB-INF/web.xml</WatchedResource>
 
    <!-- Uncomment this to disable session persistence across Tomcat restarts -->
    <Manager pathname="" />
 
    <!-- Uncomment this to enable Comet connection tacking (provides events
         on session expiration as well as webapp lifecycle) -->
    <!--
    <Valve className="org.apache.catalina.valves.CometConnectionManagerValve" />
    -->
</Context>

Specifying the external URL of the Akuiteo server

When there is a SAML connection ongoing, the Web Portal and Customer Portal redirect to the Akuiteo server in order to initiate the SAML connection. Therefore, the external / public address of the Akuiteo server must be known to the portals.

To do this, two solutions are available:

Add a configuration item to each portal.
In the context.xml configuration file, add:

Copy

<!-- SAML -->
<Environment name="t9gestion#t9gest.extrernal.server.url" type="java.lang.String" override="false" value="https://akuiteo.myakuiteo.com/akuiteo"/>

Configuring to be used with a reverse proxy

If a reverse proxy is used as front of Akuiteo's business server, you must add the following configuration to Tomcat's HTTP connector (server.xml or context.xml configuration file):

Copy

<Connector port="${http.port}"
    protocol="org.apache.coyote.http11.Http11NioProtocol"
    server="Akuiteo"
    proxyName="akuiteo.xxx.com"
    proxyPort="443"
    scheme="https"
/>

Where:

proxyName is the DN to access Akuiteo via a reverse proxy
proxyPort is the access port to Akuiteo via a reverse proxy (usually 443)
scheme is the access protocol to Akuiteo via a reverse proxy (usually https)

Aligning the JWT secret between the web portals and the Akuiteo server

If the Akuiteo server and the web portals are hosted on separate Tomcat instances, you must "align" the JWT secret, that is to say make sure this secret is the same between all the instances. This secret is used for encrypting employees' login between the various Akuiteo servers. A secret of 63 alphanumeric characters is needed only.

Tip

To generate the JWT secret, you can use a generator (for example https://www.grc.com/passwords.htm).

Specify the secret in the JVM parameters of each Tomcat by adding, for example:

Copy

-Djwt.secret=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX