SAMLv2 authentication

Last modified by Aurelie Bertrand on 2021/10/11 15:41

Configuration

Installation of a SAMLv2 authentication valve for DigDash

Summary: 

Prerequisites

  • The acronyms used later are referenced in the glossary at the end of this document.
  • Having configured the DigDash server with an SSL / TLS (HTTPS) connector (this authentication method requires secure exchanges)
  • Have the <digdash_installation> / add-ons / valve_saml2 folder containing all the files necessary for setting up the SAMLv2 authentication valve in the DigDash Tomcat server. The placement of these files is described in this document.
    • The apache-tomcat folder: transposed to <digdash_install> / apache-tomcat
      • The lib sub-folder: libraries and log configuration file to be placed in <digdash_install> / apache-tomcat / lib
      • The webapps: acs sub-folder in a .war file to be placed in <digdash_install> / apache-tomcat / webapps
    • The resources_samples folder: examples of XML files of IdP metadata and .properties file of security parameters to edit and place in the location of your choice.
    • The sp_metadata folder: The SP DigDash metadata XML file.
  • For the moment, DigDash only supports the disconnection initiated by the SP (SP-Initiated SLO).
  • The following operations are to be performed on the stopped DigDash server .
  • The user to be authenticated must exist both at the IdP and in the LDAP DigDash.
    • It is therefore advisable to have at least one user having the rights to add DigDash users in the LDAP DigDash before installing the SAMLv2 valve, this in order to avoid SSO authentication failures from the first connections due to absence of such user in LDAP.

Mutual exchange of SP and IdP metadata

The two parties (Identity Provider and Service Provider) must first exchange their respective metadata in the form of XML files. This metadata will in particular make it possible to know their respective entry point and the details of secure exchanges.

 Configuration of the DigDash server

 Copy of libraries

Add the libraries and the log configuration file from the apache-tomcat / lib folder to the folder

<digdash_installation> / apache / lib :

saml2-valve.jarslf4j-api-1.7.12.jar
commons-codec-1.10.jarlog4j-1.2.15.jar
commons-lang3-3.4.jarslf4j-log4j12-1.7.7.jar
commons-logging-1.2.jarxmlsec-2.0.7.jar
joda-time-2.9.4.jarlog4j.properties

Libraries of the apache-tomcat / lib folder

Addition of the SAMLv2 authentication valve

Add the SAMLv2 authentication valve in the server.xml file located in the folder

<digdash_installation> / apache-tomcat / conf

To do this, add the following Valve element in the Host element .

<Server ... >
  ...
     <Host ... >
         <Valve className = "com.onelogin.saml2.SAML2SSOValve"
                allowAddr = "localhost, 127.0.0. *, 0: 0: 0: 0: 0: 0 : 0: 1 "
                idPMetadataPath = " C: \ idp_md.xml "
                securitySettingsPath = " C: \ saml2.sec.properties "
                uid = " email "
                sharedPasswd = " sharedPassword " />
                 ...
     </Host>
  ...
< / Server>

Ex extract from the server.xml file

Invariable value (className) 

Variable value depending on the installation (allowAddr, idPMetadataPath, ...)

AttributeDescription
classNameName of the Java class, implementing the org.apache.catalina.Valve interface, to use as Valve here. This attribute is mandatory because it allows you to select the Valve to use. There are indeed several implementations provided by Tomcat.
allowAddrServer IP address.
idPMetadataPathThe absolute path of the XML file with IdP metadata
securitySettingsPathThe absolute path of the .properties file with security settings
uidOne of the attributes returned by the IdP in the SAMLv2 response to identify the user who authenticates. If this attribute is not mentioned, the nameId of the SAMLv2 response is used to identify the user.
sharedPasswdThe shared password and verified at authentication (see point II.5)
allowedCtxPathOptional , is "/ adminconsole" by default; it is the path of the context whose resources are authorized to pass the valve, useful when the adminconsole is named differently. Example: allowedCtxPath = "/ customadminconsole"
ldapForPathsOptional , these are regular expressions of URLs whose resources are authorized to pass the valve, thus going into LDAP authentication mode. Example: "http: // localhost: 8080 /.*"
cookieTimeOut

Optional , this is the time (in seconds) after which the SSO cookie will expire. Worth 1800 seconds (30 minutes) by default.
 Otherwise, the cookie will expire after the number of seconds mentioned.

Example: cookieTimeOut = "3600" (1 hour)

print_ debugOptional , is false by default, otherwise add print_debug = "true" for more verbose traces.

Table describing the attributes of the Valve element

Addition of the .war corresponding to the ACS of the Service Provider

Add the ddacs.war archive from the apache-tomcat / webapps folder to the folder

<digdash_installation> / apache-tomcat / webapps .

It is the ACS entry point of the SP accessed by the IdP.

Addition of security constraints

Add the security constraints to the web.xml file located in the folder

<digdash_installation> / apache-tomcat / conf .

<web-app ... >
  ...
     <security-role>
         <role-name> CUSTOM </role-name>
     </security-role>

     <security-constraint>
         <display-name> CUSTOM Security Constraint </ display-name>
         <web-resource-collection>
             <web-resource-name> Protected Area </web-resource-name>
             <url-pattern> / * </url-pattern>
         </web-resource-collection>
         <auth-constraint>
             <role-name> CUSTOM </role-name>
         </auth-constraint>
     </security-constraint>

     <security-constraint>
         <web-resource-collection>
             <web-resource-name> Non-Protected Area</web-resource-name>
             <url-pattern> / vjdbc </url-pattern>
         </web-resource-collection>
     </security-constraint>
  ...
</web-app>

Extract from web.xml file

Server URL and domain for the Dashboard

It may be necessary, and it is advisable to specify on which server / domain the Dashboard will rely.

To do this, modify in the web.xml file in

<digdash_installation> / apache-tomcat / webapps / digdash_dashboard / WEB-INF.

To force the domain, change the value of the FORCEDOMAIN parameter to true .
 Mention the domain name by changing the DOMAIN parameter .

To force the server address, change the value of the  FORCESERVERURL  parameter to true .  Mention the server address by changing the SERVERURL parameter .

<web-app ... >
  ...
     <servlet>
         <servlet-name> dashServlet </servlet-name>
         <servlet-class> com.digdash.server.DigdashServiceImpl </servlet-class>
          ...
         <init-param>
             <param-name> DOMAIN </param-name>
             <param-value> ddenterpriseapi </param-value>
         </init-param>
         <init-param>
             <param-name> FORCEDOMAIN </param-name>
             <param-value> true </param-value>
         </init-param>
         <init-param>
             <param-name> SERVERURL </ param-name>
             <param-value> http: // localhost: 8080</param-value>
         </init-param>
         <init-param>
             <param-name> FORCESERVERURL </param-name>
             <param-value> true </param-value>
         </init-param>
          ...
     </servlet>
  ...
</web-app>

Extract from web.xml file

Variable value depending on the installation

config_auth_saml2_fr_test_html_829eaa34e529ef0c.png
 		The example value for the SERVERURL parameter will almost always refer to localhost, when the dashboard and the server are placed in the same Tomcat server, which represents almost 99% of usage. It will naturally be necessary to refer to the address of the external server if these two elements are placed on different servers.
config_auth_saml2_fr_test_html_829eaa34e529ef0c.png
 

This parameter can be edited via the web.xml file as indicated above. This file is specific to each installation of DigDash. You can enter this parameter more generally in the file

<user> / Application Data / Enterprise Server / dashboard_system.xml

For more information, you can refer to the DigDash documentation “guide_avance_systeme_fr.pdf”.

Changing the value of the sharedPasswd parameter

Change the value of the sharedPasswd parameter (secret value below to change) in the web.xml file of Dashboard in the folder

<digdash_installation> / apache-tomcat / webapps / digdash_dashboard / WEB-INF .

The value must correspond to that mentioned in the sharedPasswd attribute in the valve of the file

<digdash_installation> /apache-tomcat/conf/server.xml (see part II.2).

<web-app ... >
  ...
     <servlet>
         <servlet-name> dashServlet </servlet-name>
         <servlet-class> com.digdash.server.DigdashServiceImpl </servlet-class>
          ...

        <init-param>
            <param-name> sharedPasswd </param-name>
            <param-value> secret </param-value>
        </init-param>
         ...
     </servlet>
  ...
 </web-app>

Variable value depending on the installation

Extract from the server.xml file

Modification of the authentication method

Modify the authentication method (LDAP is the default method) in the web.xml file located in the folder

<digdash_installation> / apache-tomcat / webapps / ddenterpriseapi / WEB-INF .

"External" means that safety is managed by the valve configured above.

<web-app ... >
  ...
     <servlet>
  ...
     </servlet>
  ...
     <servlet>
         <description> </description>
         <display-name> DDEnterpriseAuthServlet </display-name>
         <servlet-name > DDEnterpriseAuthServlet </servlet-name>
         <servlet-class> com.digdash.server.DDEnterpriseAuthServlet </servlet-class>

         <init-param>
             <param-name> authMethod </param-name>
             <param-value> External </param-value>
         </init-param>
          ...
     </servlet>
  ...
 </web-app>

Extract from web.xml file

Identity Provider Configuration

The IdP will need to register DigDash as an SP in its SP list before DigDash can take advantage of Single Sign-On.

The IdP must in particular use the metadata file provided by the SP for its configuration. This mentions among other things the entry points of the SP DigDash (URL ACS).

Service Provider metadata

The SP metadata will either be provided directly and physically (by email, by USB key, etc.) or by generation via the SP. Indeed, they will be accessible via the following URL once the valve is in place:

https: // <DigDash server address>: <port> /? spmetadata = display

Service Provider Configuration

The SP must load the IdP metadata into its application.

Identity Provider metadata

Place the file in XML format provided by the IdP corresponding to the IdP metadata in the directory of your choice.

NB  : The absolute path of this file will be known and will be entered as the value of the idPMetadataPath attribute of the SAMLv2 valve.

Configuration of security parameters

Place the file in .properties format corresponding to the security parameters in the directory of your choice.

NB1  : The absolute path of this file will be known and will be entered as the value of the securitySettingsPath attribute of the SAMLv2 valve.

The following table presents the different possible properties for setting security:

PropertiesDescription

onelogin.saml2.sp.entityid

onelogin.saml2.sp.assertion_consumer_service.url

onelogin.saml2.sp.assertion_consumer_service.binding

onelogin.saml2.sp.single_logout_service.url

onelogin.saml2.sp.single_logout_service.binding

onelogin.saml2.sp.nameidformat

onelogin.saml2.sp.x509cert

onelogin.saml2.sp.privatekey

Properties relating to the Service Provider.

The default values ​​of these properties are automatically loaded on the SP side.

If necessary, it is possible to override these properties by mentioning them in the properties file.

The more detailed description of these parameters as well as the values ​​used can be directly consulted in the security file resources_samples \ saml2.sec.properties provided.

onelogin.saml2.strictIndicates whether the SP rejects all unencrypted or unsigned messages if the SP expects them to be.

true

false

onelogin.saml2.security.nameid_encryptedIndicates if the nameID of the <samlp: logoutRequest> sent by the SP must be encrypted

true

false

onelogin.saml2.security.authnrequest_signedIndicates whether <samlp: AuthnRequest> messages sent by this SP are signed. Metadata indicates this information.

true

false

onelogin.saml2.security.logoutrequest_signedIndicates whether the <samlp: logoutRequest> messages sent by this SP are signed.

true

false

onelogin.saml2.security.logoutresponse_signedIndicates whether the <samlp: logoutResponse> messages sent by this SP are signed.

true

false

onelogin.saml2.security.want_messages_signedIndicates if responses should be signed

true Message is required to be signed

false Message is not required to be signed

onelogin.saml2.security.want_assertions_signedIndicates the obligation of the <samlp: Response>, <samlp: LogoutRequest> and <samlp: LogoutResponse> messages received by this SP to be signed.

true

false

onelogin.saml2.security.sign_metadataIndicates the obligation of the metadata of this SP to be signed.

true requires signature of metadata

false default

onelogin.saml2.security.want_assertions_encryptedIndicates the obligation of assertions received by this SP to be encrypted.

true

false

onelogin.saml2.security.want_nameid_encryptedIndicates the obligation of the nameID received by the SP to be encrypted.

true

false

onelogin.saml2.security.requested_authncontextAuthentication context

Empty if you don't want any context to be sent in the AuthnRequest request

Multiple values ​​separated by commas otherwise.

onelogin.saml2.security.onelogin.saml2.security.requested_authncontextcomparisonEnables authentication context comparison
'exact' by default
onelogin.saml2.security.want_xml_validationIndicates whether the SP validates all XML responses received. (If true, validation is only effective if this property and the 'onelogin.saml2.strict' property is also true.

true

false

onelogin.saml2.security.signature_algorithmHash algorithm used for signature.

http://www.w3.org/2000/09/xmldsig#rsa-sha1

http://www.w3.org/2000/09/xmldsig#dsa-sha1

http://www.w3.org/2001/04/xmldsig-more#rsa-sha256

http://www.w3.org/2001/04/xmldsig-more#rsa-sha384

http://www.w3.org/2001/04/xmldsig-more#rsa-sha512

Table describing possible security settings

config_auth_saml2_fr_test_html_cfd0582386f81fc1.png
 		The shaded fields are fields offered by the onelogin library but which are not yet implemented for the SAMLv2 valve from DigDash, therefore not taken into account.

VI. Configuring the Java environment

The Java Cryptography Extension (JCE) is required. You can download the jce-6, jce-7 or jce-8 version, and unzip it in the folder

$ {java.home} / jre / lib / security /

VersionsDownload links
jce-6http://www.oracle.com/technetwork/java/javase/downloads/jce-6-download-429243.html
jce-7http://www.oracle.com/technetwork/java/javase/downloads/jce-7-download-432124.html
jce-8http://www.oracle.com/technetwork/java/javase/downloads/jce8-download-2133166.html

Log level

You can customize the log level for the authentication valve.

By default, only errors are logged. If however you want to have more details on the course of actions and exchanges between the different entities, you can assign the value 'DEBUG' instead of 'ERROR' in the log4j.properties file which was imported into the lib folder of Tomcat .

log4j.logger.com.onelogin.saml2 = ERROR , stdout

log4j.logger.com.onelogin.saml2 = DEBUG , stdout

SAML2 authentication on the Enterprise Studio side

To authenticate with SAMLv2 on the Enterprise Studio side, please ensure that you have performed the following actions:

Server and domain definitions in the .jnlp file

You can, like the Dashboard, define the server and the domain on which DigDash will rely.

To do this, modify the end of the digdash.jnlp file in the DigDash installation folder <digdash_installation> / apache-tomcat / webapps / adminconsole

<jnlp ...>
  ...
      <application-desc main-class = "commandline.CommandLineMain">

      <argument> https: // localhost: 8443 </argument> (1)
      <argument> ddenterpriseapi </argument> (2 )
      <argument><%=lang%> </argument> (3)
      <argument><%=dashboard%> </argument> (4)
      <argument> -AuthMode = External </argument> (5)
      <argument> -SSLNoPathCheck </argument> (A)
  ...
      </application-desc>
</jnlp>

Extract from the digdash.jnlp file

Warning : the arguments noted (1), (2), (3), (4), (5) must not change order.

Argument (1): the address of the DigDash server; variable depending on your installation

Argument (2): the name of the DigDash domain; variable depending on your installation

Argument (5): The authentication method; External, mandatory

Argument (A): optional argument, sometimes necessary in the case of SSL, HTTPS connections.

Connection to DigDash Enterprise Studio

Download and run the .jnlp by going to the DigDash home page in the Enterprise Studio section.

config_auth_saml2_fr_test_html_27c2ab581e0d9d7e.png

 

An authentication window should appear with the IdP authentication target.

In this document, Salesforce is the IdP we have chosen to illustrate our examples.

config_auth_saml2_fr_test_html_dff5c9e389ba1c1d.png

 

Capture: target with Salesforce IdP authentication form

The user must enter his login data and if he has been authenticated with the IdP and that he corresponds to an existing user in the LDAP DigDash, the authentication will have succeeded and the window will attest to the success of authentication.

config_auth_saml2_fr_test_html_6230a5f637fd4c54.png

 

Capture: window of successful authentication

The window will close automatically, then Enterprise Studio will start loading to launch.

 Lexicon

We will call in this document:

SSO: Single Sign On or Single Authentication; SAMLv2 is an SSO method

SLO: Single LogOut or Single Logout

IdP: Identity Provider or Identity Provider

SP: the Service Provider or the Service Provider (DigDash)

ACS: Assertion Consumer Service

References

https://www.oasis-open.org

DigDash uses the OpenSource onelogin library from OneLogin Inc to support the SAMLv2 authentication method.

https://www.onelogin.com/

https://github.com/onelogin/java-saml