SAMLv2 authentication
Configuration
Installation of a SAMLv2 authentication valve for DigDash
Summary:
- Prerequisites
- Configuration of the DigDash server
- Identity Provider Configuration
- Service Provider Configuration
- Configuration of security parameters
- VI. Configuring the Java environment
- Log level
- SAML2 authentication on the Enterprise Studio side
- Lexicon
- References
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.
- The apache-tomcat folder: transposed to <digdash_install> / apache-tomcat
- 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.jar | slf4j-api-1.7.12.jar |
| commons-codec-1.10.jar | log4j-1.2.15.jar |
| commons-lang3-3.4.jar | slf4j-log4j12-1.7.7.jar |
| commons-logging-1.2.jar | xmlsec-2.0.7.jar |
| joda-time-2.9.4.jar | log4j.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 .
...
<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, ...)
| Attribute | Description |
| className | Name 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. |
| allowAddr | Server IP address. |
| idPMetadataPath | The absolute path of the XML file with IdP metadata |
| securitySettingsPath | The absolute path of the .properties file with security settings |
| uid | One 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. |
| sharedPasswd | The shared password and verified at authentication (see point II.5) |
| allowedCtxPath | Optional , 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" |
| ldapForPaths | Optional , 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. Example: cookieTimeOut = "3600" (1 hour) |
| print_ debug | Optional , 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 .
...
<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 .
...
<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
 | 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. |
| 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).
...
<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.
...
<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:
| Properties | Description |
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.strict | Indicates whether the SP rejects all unencrypted or unsigned messages if the SP expects them to be. |
true false | |
| onelogin.saml2.security.nameid_encrypted | Indicates if the nameID of the <samlp: logoutRequest> sent by the SP must be encrypted |
true false | |
| onelogin.saml2.security.authnrequest_signed | Indicates whether <samlp: AuthnRequest> messages sent by this SP are signed. Metadata indicates this information. |
true false | |
| onelogin.saml2.security.logoutrequest_signed | Indicates whether the <samlp: logoutRequest> messages sent by this SP are signed. |
true false | |
| onelogin.saml2.security.logoutresponse_signed | Indicates whether the <samlp: logoutResponse> messages sent by this SP are signed. |
true false | |
| onelogin.saml2.security.want_messages_signed | Indicates 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_signed | Indicates 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_metadata | Indicates the obligation of the metadata of this SP to be signed. |
true requires signature of metadata false default | |
| onelogin.saml2.security.want_assertions_encrypted | Indicates the obligation of assertions received by this SP to be encrypted. |
true false | |
| onelogin.saml2.security.want_nameid_encrypted | Indicates the obligation of the nameID received by the SP to be encrypted. |
true false | |
| onelogin.saml2.security.requested_authncontext | Authentication 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_authncontextcomparison | Enables authentication context comparison |
| 'exact' by default | |
| onelogin.saml2.security.want_xml_validation | Indicates 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_algorithm | Hash 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
 | 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 /
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
...
<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.
An authentication window should appear with the IdP authentication target.
In this document, Salesforce is the IdP we have chosen to illustrate our examples.
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.
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