Authentication using SAML

This documentation explains SAML2 authentication to configure Wedia to connect via a provider of SAML2 identities.

Terms used in this documentation:

Service Provider : SAML Authentication Client : Wedia
Identity Provider : External system used to authenticate a user.

SAML Authentication flow in Wedia

A login with SAML follows this typical scenario :

A user open the Login page provided by Wedia
The user clicks on a SSO SAML2 provider listed in the login page,
This user is directed on the connection page of the identity provider SAML2,
This user logs in on this page,
The users is redirected to Wedia,
Wedia searches for a user corresponding to the SAML2 user, according to a matching rule configured in Wedia,
If the user does not exist, it is created automatically with a combination of attributes retrieved from the SAML2 authentication assertion, or default values,
The user is logged in, and can use Wedia (It is also possible to set up an additional accreditation step)

Collecting attributes from SAML assertion to map to the local user

Before setting up the SAML connection, it is important to list which attributes coming from the SAML authentication server will be replicated into the Wedia user.

Please note that any user attributes such as email, phone, first name, last name, etc. will fall under GDPR regulations, and should be declared in the GDPR processing documents.

A single attribute is required for the connection to work "Name-ID." It should generally correspond to a local attribute allowing to uniquely identify a user (e.g. : login) but it will be possible to choose another attribute for that like email.

Since 11.1.0 : It is possible to specify URLs managed by a supplier SAML2. Simply select them from URLs Managed. By default, the URLs available are:

The one configured in the variables
Those extracted from the sites present in the application.

The only URL enabled is the one configured in the administration variable. It is possible to add some by entering the URL in the input field located under the site selector.

Before 11.1.0: Configuring the external site access address correctly configuring the application variables in /admin/ebnAdministration.ebn. Indeed, the SAML2 protocol is based on a strong identification of the different parties (Service provider, Identity provider). This identification goes through fixed and often secure access URLs. It is therefore not recommended to integrate SAML2 on a preprod.monappli.com machine when the production environment must be called prod.monappli.com because this will no longer work and it will be necessary to reconfigure the authentication.

Configuring a SAML2 connection

Follow these steps to set up a SAML2 connection :

Login to the /admin configuration screen
Click Authentication service on the Server Configuration tab
Click the Identity Provider tab

Create a new identity provider :

Click Add New Identity Server.
Choose SAML2 as the supplier type.
Give this supplier a name. This name will appear on the login screen presented to the user.

Export the service provider’s metadata

In the Service Provider column, enter the service identifier and the size of the encryption and encryption keys for SAML2 envelopes as in the example below.

To export the metadata that will be sent to your identity provider, click on Export metadata.

The service identifier is the name of this service provider at of an identity provider. The format is free and must not be modified after the implementation of SAML2 authentication. Encryption and encryption key sizes can be adapted to suit the following requirements the level of encryption based on the provider’s capabilities identification and legislation in force for installed servers.

Metadata import from identity provider or manual information

The configuration is done in the right column as in the screenshot below.

There are two ways to configure the identity provider. The easiest consists in importing the metadata file of the identity provider that the latter’s administrator sent you. Just click on Import metadata and select the corresponding file. The configuration fields will be automatically updated with the information extracted from this file.

Otherwise, you must manually enter the login/disconnect URLs as follows that the identity provider’s encryption and/or signature certificates in X.509 format.

Mapping the SAML2 / local attributes.

This part consists of:

Must → define the local object with the user’s info. By default, this object is user.

Obligatory →fill in the SAML2 attributes and local "pivots" allowing you to find a local user corresponding to the user identified by the identity provider.

Optional →add additional matches that will allow you to import SAML2 attributes into local user attributes when importing SAML2 attributes into local user attributes of a user’s first login.

Pivot attributes

For the mapping of pivotal attributes, good configurations are:

Name-ID (SAML2) → login (local).
Email (SAML2) → email (Local)

The rules for selecting these fields are as follows:

SAML and local pivot fields must be capable of identifying in such a way that a single user.
The SAML pivot field must be persistent (important in the case of Name-ID). In other words, a user must always obtain the same value for these fields.

Additional attributes

The additional attribute mapping is optional: it has no effect on the proper functioning of SAML authentication. However, it is interesting to be able to retrieve information from the user to create the local user. Typically, the name, the first name, and email are information we’ll want to get back.

In the same way, it can be interesting to initialize the new user with default WXM attributes: role, active / inactive status, language, etc The configuration screen allows you to configure both types of attributes:

SAML attribute mapping or static value.
The previous screenshot shows a typical example of usage.

The configuration of the initialization values is quite limited in this screen. For more advanced treatments, it is best to create a trigger in beforeInsert on the object to initialize (in this case: user).

ADFS configuration

On the ADFS side, a good claim configuration is:

SAM-Account-Name ⇒ NameID
User-Principal-Name ⇒ E-Mail Address
Display-Name ⇒ Name

Wedia side:

Name-Id ⇒ login
Email ⇒ email
Name ⇒ name

Setting up a development server for testing a SAML connection

As a software integrator, it can be interesting to run a local SAML connection for testing.

The procedure is as follows:

Deploy your webapp with the same context as the target machine: traditionally ROOT.
Edit your hosts file to point the URL of the target server at your development environment by adding a line of the type: 127.0.0.0.1 monserverdeprod
Access the login URL as if you were going to the production server (remember to switch to https if necessary). E.g.: https://monserveurdeprod/wcm.jspz
Remember to delete the modification of the hosts file at the end of your tests to access the production server again.

SAML2 authentication via Shibboleth Identity Provider

This article is not intended to explain the installation of the application Shibboleth Identity Provider but to present the key points to enable authentication via this identity provider from a WEDIA application.

Prerequisites

Install a JDK 1.7
Install Tomcat 7
Retrieve the shibboleth distribution here: http://shibboleth.net/downloads/identity-provider/2.4.3/
Install shibboleth via the script install. sh, we will install here application in /opt/shibboleth
The hostname of our idP server is idp2.wedia.fr (adapted in the configuration examples given below).
To function properly SSL must be enabled on the idP Tomcat and on the application server hosting the WEDIA application. SAML2 only works via SSL.

If you have any questions, please do not hesitate to refer to the WIKI of installation / Shibboleth configuration: https://wiki.shibboleth.net/confluence/display/SHIB2/IdPConfiguration

This parameter setting documentation has been tested on Shibboleth Identity Provider versions 2.4.0,2.4.1 and 2.4.3. It does not cover documentation for 1. x versions depreciated since 2010 or future 3. x versions.
Logging if necessary

WIKI: https://wiki.shibboleth.net/confluence/display/SHIB2/IdPLogging

Passing the edu. internet2. middleware. shibboleth logger in DEBUG
Pass the edu. vt. middleware. ldap logger to DEBUG
Discomment the logger PROTOCOL_MESSAGE and pass it to DEBUG

Meta-data Shibboleth

Retrieve the file /opt/shibboleth-idp/metadata/idp-metadata. xml from your computer, this is the file that will be imported later in the WEDIA configuration.

Configuration of relying-party. xml

WIKI: https://wiki.shibboleth.net/confluence/display/SHIB2/IdPRelyingParty WIKI: https://wiki.shibboleth.net/confluence/display/SHIB2/IdPMetadataProvider

Add a new RelayingParty AFTER the DefaultRelyingParty element that will represent the WEDIA application for which we wish to offer the SAML2 identification functionalities (this is the SAML service ID) in the WEDIA configuration).

<rp: RelyingParty id="wediaidP"
    provider="https://idp2.wedia.fr/idp/shibboleth"
    defaultSigningCredentialRef="IdPCredential".
    defaultAuthenticationMethod="urn: oasis: names: tc: SAML: 2.0: ac: classes: PasswordProtectedTransport" >
        <rp: ProfileConfiguration xsi: type="saml: SAML2SSOProfile" encryptAssertions="never" includeAttributeStatement="true" encryptNameIds="never" />
        <rp: ProfileConfiguration xsi: type="saml: SAML2LogoutRequestProfile" signResponses="conditional"/>
</rp: RelyingParty>

defaultAuthenticationMethod="urn: oasis: names: tc: SAML: 2.0: ac: classes: PasswordProtectedTransport" indicates you want to authenticate the user via login/password, we will define the method later in the handler.xml file.

Add WEDIA metadata declaration for relaying party (we will export wedia-metadata.xml later in this how-to via screens
WEDIA Board of Directors).
<metadata: MetadataProvider id="wediaSPMD".
        xsi: type="FilesystemMetadataProvider".
        xmlns="urn: mace: shibboleth: 2.0: metadata"
        metadataFile="/opt/shibboleth-idp/metadata/wedia-metadata. xml" maintainExpiredMetadata="true" />

attribute-resolver. xml configuration

WIKI: https://wiki.shibboleth.net/confluence/display/SHIB2/IdPAddAttribute

This file is used to define how to retrieve attributes from the data source, here LDAP.

In the <resolver node: AttributeResolver… add the declaration of LDAP attributes to be recovered, for example:

<resolver: AttributeDefinition xsi: type="ad: Simple" id="userprincipalname" sourceAttributeID="userprincipalname"> >
    <resolver: Dependency ref="myLDAP" />
    <resolver: AttributeEncoder xsi: type="enc: SAML2String" name="urn: oid: 0.9.2342.19200300.100.1.1" friendlyName="userprincipalname" />
</resolver: AttributeDefinition>>
<resolver: AttributeDefinition xsi: type="ad: Simple" id="displayname" sourceAttributeID="displayname">
    <resolver: Dependency ref="myLDAP" />
    <resolver: AttributeEncoder xsi: type="enc: SAML2String" name="urn: oid: 0.9.2342.19200300.100.1.2" friendlyName="displayname" />
</resolver: AttributeDefinition>>
<resolver: AttributeDefinition xsi: type="ad: Simple" id="givenname" sourceAttributeID="givenname">
    <resolver: Dependency ref="myLDAP" />
    <resolver: AttributeEncoder xsi: type="enc: SAML2String" name="urn: oid: 0.9.2342.19200300.100.1.3" friendlyName="givenname" />
</resolver: AttributeDefinition>>

Here we will retrieve the attributes LDAP userPrincipalName, displayName and givenName.

Note that id and sourceAttributeID must be lower case!

Add DataConnector for LDAP that will allow to find the user in LDAP to retrieve its attributes.

attribute-filter configuration

WIKI: https://wiki.shibboleth.net/confluence/display/SHIB2/IdPAddAttribute

This file describes which attributes will be exposed to suppliers of services.

In the AttributeFilterPolicyGroup node add the attributes you want to add send to the service provider (the WEDIA application). Here we want to send the three attributes declared in attribute-resolver.

Configuration of handler.xml

WIKI: https://wiki.shibboleth.net/confluence/display/SHIB2/IdPAuthUserPass

This file allows you to define the methods that will be used to identify a user

Activate the handler Username/password login handler

login.config configuration

WIKI: https://wiki.shibboleth.net/confluence/display/SHIB2/IdPAuthUserPass

Describes the method for authenticating the user to LDAP by connecting to the LDAP server.

Add the following code to ShibUserPassAuth (replacing MONSERVEURLDAP) by the address of the LDAP server passing the correct information databaseDn/bindDn/bindCredential that depend on the LDAP server used.
Contact your administrator for more information.

Configuration of SAML connectors in WEDIA

Create a new SAML connection, the name of this new connection is free.

The service identifier must be the same as the ID given to the element.
RelyingParty in the relyingparty.xml file, here: wediaidP

Click the Apply Changes button.

Click on the button Export metadata and save the file on the idP server in /opt/shibboleth/metadata/wedia-metadata.xml

Click on the button Import metadata and upload the file idp-metadata. xml downloaded above (during the Metadatas step of Shibboleth Identity Provider).

Click Apply Changes (if the button appears).

At this stage it is possible to test the configuration of the idP via the client aacli. sh of shibboleth of the kind:

by replacing USERNAME with the login of a known user in the system, SAML2 attributes will be displayed in the console. If no attribute is returned, there is a problem in the configuration. Check the error messages and other logs in /opt/shibboleth/logs (think of activating the shibboleth logs to find the source of the anomalies).

Start the tomcat server of the idP

Click on the Test SAML2 Connection button and log in with a known user on LDAP, the configuration will reload.

Then configure LDAP properties to the user properties:

Object name "user" local = user
Local user pivot property name = email
Name of pivot attribute SAML = urn: oid: 0.9.2342.19200300.100.1.1
Add necessary correspondence, for example:
- status = 6 (static value)
- activated = 1 (static value)
- Type = 1 (static value)
- role = 4 (static value)
- name = urn: oid: 0.9.2342.19200300.100.1.2 (SAML attribute)

These correspondences will make it possible to create at each connection of a new one user a new user if necessary or will search for a user by in relation to the pivot attribute SAML.

Here all users will be created as developers. So beware of make connections that make sense on your application.

For example, we might want to create users but not to allow them to log in to the application and send an email to a administrator to validate the account. This could be done by placing use it in a particular status, by setting activated=2 and sending the email in the afterInsert trigger of the object to use so that someone will validate the user.

Click the Apply Changes button.

The configuration of SAML2 is complete, your users will be able to connect to the WEDIA application by clicking on the button provided for this purpose on the WEDIA application login page.