Authentication using SAML

SAML2 authentication

Preamble

This documentation briefly explains SAML2 authentication to configure WXM to connect via a provider of SAML2 identities. It is not intended to be used as documentation on SAML2. Please refer to the official documentation.

Terms used in this documentation:

Service Provider

SAML Authentication Client (WXM)

Identity Provider

Site used to authenticate a user.

Authentication principle SAML2 in WXM

First of all, SAML2 authentication does not change the object model about users / groups in WXM but is grafted on top. This means that it is not necessary to integrate SAML2 authentication early in the life of a project. It can be grafted at the end of it.

The general principle is as follows:

1. A user appears on the WXM connection chart,

2. It clicks on a SSO SAML2 provider,

3. This user arrives on the connection chart of the identity provider SAML2,

4. This user logs in,

5. It is redirected to WXM,

6. It is searched whether there is a WXM user corresponding to the SAML2 user according to a matching rule configured in WXM,

7. If the user does not exist, it is created automatically with a combination of attributes retrieved from the SAML2 authentication or imposed upon creation,

8. The user can normally use WXM.

What to prepare before configuring SAML2

We must foresee the attributes that we want to be able to import into the database local (email, phone, first name, last name, etc.). Only one 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 very well choose another attribute for that like email.

Similarly, URLs that are not in https can be refused by the identity provider. This is the case with ADFS.

How to configure SAML2

1. Go to the configuration screen

2. Go to the Administration homepage: admin/ebnAdminTools.ebn.

3. Click Authentication service on the Server Configuration tab

4. Click the Identity Provider tab

Create a new identity provider

1. Click Add New Identity Server.

2. Choose SAML2 as the supplier type.

3. Give this supplier a name. Choose the good because it is the name that will appear on the WXM login page.

Export of 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.

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.

Warning

4096-bit encryption requires Java to be installed. Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files for the installed FMV. This extension is available on the Oracle website.

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

Importation of metadata 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 of 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.

Optionally

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.

Pivotal 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

WXM side:

• Name-Id ⇒ login

• Email ⇒ email

• Name ⇒ name

How to test SAML authentication outside the production server

It is sometimes desirable to test new developments on the creating or updating users via SAML without affecting servers of production. The SAML protocol makes it easy to carry out these tests on an development environment by making a few modifications on his workstation local.

The procedure is as follows:

1. Deploy your webapp with the same context as the target machine: traditionally ROOT.

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

3. 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

4. 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.

<resolver: DataConnector id="myLDAP" xsi: type="dc: LDAPDirectory": LDAPDirectory
    ldapURL="ldap: //MONSERVEURLDAP: 389"
    baseDN="cn=Users, dc=RD, dc=local".
    principal="cn=Administrator, cn=Users, dc=RD, dc=local".
    principalCredential="**********"
    lowercaseAttributeNames="true">
    <dc: FilterTemplate>> FilterTemplate
        <![CDATA[
          (sAMAccountName=$requestContext. principalName)
        ]]>
    </dc: FilterTemplate> FilterTemplate>
</resolver: DataConnector>> DataConnector

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.

<afp: AttributeFilterPolicy id="releaseLDAP">
    <afp: PolicyRequirementRule xsi: type="basic: ANY"/>
    <afp: AttributeRule attributeID="userprincipalname"> >
        <afp: PermitValueRule xsi: type="basic: ANY" />
    </afp: AttributeRule>
    <afp: AttributeRule attributeID="displayname">
        <afp: PermitValueRule xsi: type="basic: ANY" />
    </afp: AttributeRule>
    <afp: AttributeRule attributeID="givenname"> >
        <afp: PermitValueRule xsi: type="basic: ANY" />
    </afp: AttributeRule>
</afp: AttributeFilterPolicy> Attribute

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

<ph: LoginHandler xsi: type="ph: UsernamePassword" jaasConfigurationLocation="file: ///opt/shibboleth-idp/conf/login. config">
            <ph: AuthenticationMethod>urn: oasis: names: tc: SAML: 2.0: ac: classes: PasswordProtectedTransport</ph: AuthenticationMethod>
</ph: LoginHandler>

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.

edu. vt. middleware. ldap. jaas. LdapLoginModule required
      ldapUrl="ldap: //MONSERVEURLDAP: 389"
      baseDn="cn=Users, dc=RD, dc=local".
      bindDn="cn=Administrator, cn=Users, dc=RD, dc=local".
      bindCredential="**************************"
      ssl="false"
      tls="false".
      subtreeSearch="true"
      userFilter="(& (objectclass=person)(sAMAccountName={0}))";

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:

    /opt/shibboleth-idp/bin/aacli.sh --configDir=/opt/shibboleth-idp/conf --principal=$USERNAME

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.