SAMLv2 authentication

Last modified by Aurelie Bertrand on 2026/01/12 16:46

Appendix

This document describes the implementation of a SAMLv2 authentication valve for DigDash Enterprise.

The use of SSO/SAML2 is not recommended when integrating a dashboard into a web page (via iframe).

Prerequisites

The acronyms used below are listed in the glossary at the end of this document.
Have configured the server with an SSL/TLS (HTTPS) connector (this authentication method requires secure exchanges).
Have the <Install DD>/add-ons/valve_saml2 folder containing all the files needed to set up the SAMLv2 authentication valve in the Tomcat server. The placement of these files is described in this document.
- The apache-tomcat folder: transposed to /etc/tomcat9/ under Linux and C:\Program Files\Apache Software Foundation\Tomcat 9.0\conf under Windows
  - The lib sub-folder: libraries and log configuration file to be placed in:
    - Under Linux: /usr/share/tomcat9/lib/
    - Under Windows : C:\Program Files\Apache Software Foundation\Tomcat 9.0\lib
  - The sub-folder webapps : ACS in a .war to be placed in :
    - Under Linux: /home/digdash/webapps/default
    - Under Windows: E:/digdash/webapps/default
- The resources_samples folder: examples of IdP metadata XML files and security parameter .properties files to be edited and placed in the desired location.
- The sp_metadata folder: The SP DigDash metadata XML file.

For the moment, only SP-initiated disconnection (SP-Initiated SLO) is supported.
The following operations must be carried out with the DigDash server stopped.
The user to be authenticated must exist in both the IdP and the LDAP.
If a reverse proxy is used, check header transmission: the reverse proxy used must allow X-Forwarded-Proto and X-Forwarded-Host headers to communicate.

It is advisable to have at least one user with the right to add users to the LDAP before installing the SAMLv2 valve, in order to avoid SSO authentication failures on the first connections due to the absence of such a user in the 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 make it possible to know their respective entry points and the details of secure exchanges.

Configuring the DigDash server

Copying libraries

Copy the libraries and the log configuration file from the <install DD>/add-ons/valve_saml2/apache-tomcat/lib folder to the :

under Linux: /usr/share/tomcat9/lib/
under Windows : C:\Program Files\Apache Software Foundation\Tomcat 9.0\lib

Files to copy :

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

Adding the SAMLv2 authentication valve

Activate the SAMLv2 authentication valve in the server.xml file located in the :

under Linux: /etc/tomcat9/
under Windows : C:\Program Files\Apache Software Foundation\Tomcat 9.0\conf

To do this, look for the <Host ...> element in the file, uncomment or add the <Valve ...> element below:

The value of the className attribute is invariant.

The values of the other attributes (allowAddr, idPMetadataPath, ...) are variable depending on the installation.

Attribute	Description
className	Name of the Java class implementing the org.apache.catalina.Valve interface, to be used as Valve here. This attribute is mandatory, as it is used to select the Valve to be used. There are in fact several implementations provided by Tomcat.
allowAddr	IP address of the server.
fallbackAuth	The fallback authentication method
idPMetadataPath	The absolute path of the XML file containing the IdP's metadata
securitySettingsPath	The absolute path to the .properties file with the security settings
uid	One of the attributes returned by the IdP in the SAMLv2 response to identify the authenticating user. If this attribute is not mentioned, the nameId from the SAMLv2 response is used to identify the user.
sharedPasswd	The password shared and verified at authentication. A hash in SSHA512 format can be used to avoid writing the password in the plaintext file (a tool such as pwdhash can be used under Linux to generate this hash).
ldapForPaths	Optional, these are regular expressions for URLs whose resources are authorised to pass the valve, thereby switching to LDAP authentication mode. Example: "http://localhost:8080/.*"
excludedPaths	Optional, these are the regular expressions of the paths whose resources are authorised to pass the valve, thus switching to LDAP authentication mode. Example: "/.*"
cookieTimeOut	Optional, this is the time (in seconds) after which the SSO cookie will expire. Defaults to 1800 seconds (30 minutes). Otherwise, the cookie will expire after the specified number of seconds. A negative value means that the cookie will expire when the browser is closed. A value of 0 means that the cookie will be deleted directly (not recommended). Example: cookieTimeOut="3600" (1 hour)
print_debug	Optional, set to false by default, otherwise add print_debug="true" for more verbose traces.

Add the .war file corresponding to the Service Provider ACS

Add the ddacs.war archive from the <install DD>/add-ons/valve_saml2/apache-tomcat/webapps folder to the :

under Linux: /home/digdash/webapps/default
under Windows: E:/digdash/webapps/default

This is the ACS entry point for the SP accessed by the IdP.

Adding security constraints

Uncomment or add the security constraints to the web.xml file located in the :

under Linux: /etc/tomcat9/
under Windows: C:\Program Files\Apache Software Foundation\Tomcat 9.0\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>

Application configuration

To do this, modify the digdash.properties file in <install DD> or /etc/digdash (under Linux) or in the folder you have configured.

Server configuration (ddenterprise.war)

In the digdash.properties file:

In the ddenterpriseapi.war box, find and uncomment the following lines with the values shown:

ddenterpriseapi.authMethod=External

Dashboard configuration (digdash_dashboard.war)

In the digdash.properties file :

In the digdash_dashbord.war box, find and uncomment the following lines with the values shown:

digdash_dashboard.SERVERURL=http://localhost:8080
digdash_dashboard.DOMAIN=ddenterpriseapi
digdash_dashboard.FORCEDOMAIN=true
digdash_dashboard.FORCESERVERURL=true
digdash_dashboard.sharedPasswd=<la valeur de l'attribut sharedPasswd dans l'élément Valve>

The example value for the digdash_dashboard.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.9% of usage. Naturally, you will need to refer to the address of the external server if these two elements are located on different servers.

Studio configuration (studio.war)

In the digdash.properties file :

In the studio.war box, find and uncomment the following lines with the values shown:

studio.SERVERURL=http://localhost:8080
studio.DOMAIN=ddenterpriseapi
studio.FORCEDOMAIN=true
studio.FORCESERVERURL=true
studio.PUBLICSERVERURL=<votre adresse URL publique>
studio.sharedPasswd=<la valeur de l'attribut sharedPasswd dans l'élément Valve>

The parameter studio.PUBLICSERVERURLis optional when installing an SSO.

The example value for this parameter will almost always refer to localhost, when the Studio and the server are placed in the same Tomcat server, which represents almost 99.9% of usage. Naturally, reference will have to be made to the address of the external server if these two elements are placed on different servers.

Configuring the Identity Provider

The IdP will need to register DigDash as an SP in its list of SPs so that DigDash can take advantage of Single Sign-On.
The IdP will need to use the metadata file provided by the SP for its configuration. Among other things, this file mentions the DigDash SP entry points (ACS URLs).

Service Provider metadata

The SP metadata will either be supplied directly and physically (by email, USB key, etc.) or by generation via the SP. It will be accessible via the following URL once the valve has been set up:

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

Configuring the Service Provider

The SP must load the IdP metadata into its application.

Identity Provider metadata

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

The absolute path of this file must be known and must be entered as the value of the idPMetadataPath attribute of the Valve element in Tomcat.

If the .xml metadata file is not read by the IdP, the following parameters must be set as indicated below:

entity id: https://[serveur_url]/?spmetadata=display
reply: https://[serveur_url]/ddacs/acs

Configuring security parameters

Place the saml2.sec.properties file in the <Install DD>/add-ons/valve_saml2/resources_samples folder corresponding to the security parameters in the directory of your choice.

The absolute path of this file must be known and must be entered as the value of the securitySettingsPath attribute of the Valve element in Tomcat.

The following tables show the various properties for setting security parameters:

General properties

General property	Description	Possible values
onelogin.saml2.strict	If true, the SP is in strict mode and will reject all unencrypted or unsigned messages if the SP expects them to be.	true,false
onelogin.saml2.debug	If true, debug mode will be enabled.	true,false

Service Provider properties

The default values for these properties are automatically loaded. You can uncomment certain properties as required to make values more explicit.

Service Provider properties	Description	Possible values
onelogin.saml2.sp.entityid	the identifier of the Service Provider entity	?spmetadata=display
onelogin.saml2.sp.assertion_consumer_service.url	SP entry point. This is the URL to which the IdP's SAML <Response> will be returned.	ddacs/acs
onelogin.saml2.sp.assertion_consumer_service.binding	SAML protocol binding used when returning the <Response> message. Onelogin supports HTTP-POST binding only for this endpoint.	urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST
onelogin.saml2.sp.single_logout_service.url	Specifies where and how the <Logout Response> message should be returned to the requester, in this case the SP.	ddacs/slo
onelogin.saml2.sp.single_logout_service.binding	SAML protocol binding used when returning the <LogoutResponse> or sending the <LogoutRequest> message. Onelogin supports HTTP-Redirect binding only for this endpoint.	urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect
onelogin.saml2.sp.nameidformat	Specifies constraints on the NameID to be used to represent the user to be authenticated.	urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
onelogin.saml2.sp.x509cert	The Service Provider's public key (or certificate).	See documentation SAMLv2 Authentication - Configuration
onelogin.saml2.sp.privatekey	The Service Provider's private key.	See documentation SAMLv2 Authentication - Configuration

Security properties

Security properties	Description	Possible values
onelogin.saml2.security.nameid_encrypted	Specifies whether the nameID of the <samlp:logoutRequest> sent by the SP should be encrypted.	true,false
onelogin.saml2.security.authnrequest_signed	Indicates whether <samlp:AuthnRequest> messages sent by this SP are signed. The metadata indicates this information.	true,false
onelogin.saml2.security.logoutrequest_signed	Indicates whether <samlp:logoutRequest> messages sent by this SP are signed.	true,false
onelogin.saml2.security.logoutresponse_signed	Indicates whether <samlp:logoutResponse> messages sent by this SP are signed.	true,false
onelogin.saml2.security.want_messages_signed	Indicates whether responses should be signed.	true,false
onelogin.saml2.security.want_assertions_signed	Indicates whether <samlp:Response>, <samlp:LogoutRequest> and <samlp:LogoutResponse> messages received by this SP must be signed.	true,false
onelogin.saml2.security.sign_metadata	Indicates the requirement for this SP's metadata to be signed.	true,false
onelogin.saml2.security.want_assertions_encrypted	Indicates that the assertions received by this SP must be encrypted.	true,false
onelogin.saml2.security.want_nameid_encrypted	Indicates that the nameID received by the SP must be encrypted.	true,false
onelogin.saml2.security.requested_authncontext	Authentication context.	urn:oasis:names:tc:SAML:2.0:ac:classes:Password or empty string if you do not want any context to be sent in the request. Several possible values, separated by commas.
onelogin.saml2.security.requested_authncontextcomparison	Enable authentication context comparison	exact
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 are also true).	true,false
onelogin.saml2.security.signature_algorithm	Hash algorithm used for the 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

Configuring the SAML 2 valve logs

In the server.xml file (located in the /etc/tomcat9/ folder under Linux or C:\Program Files\Apache Software Foundation\Tomcat 9.0\conf under Windows), inside the host tag, add the following valve to obtain logs:

In the example above, the log files will start with "localhost_access_log_test_header". The prefix can be modified as required.
The logs will be located in the Tomcat folder.

Log level

You can customise the log level for the authentication valve.

By default, only errors are logged. However, if you want to have more details about the course of actions and exchanges between the various entities, you can assign the value 'DEBUG' instead of 'ERROR' in the log4j.properties file which has been imported into the Tomcat lib folder.

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

SAMLv2 and LDAP DigDash coexistence (optional)

It is possible to use direct authentication via the DigDash LDAP directory while the SAMLv2 method is in place on your DigDash server.

Prior configuration

In the digdash.properties file :

In the studio.war box, find and uncomment the following lines with the values shown:

studio.allowLoginForm=true

In the digdash_dashboard.war box, find and uncomment the following lines with the values shown:

digdash_dashboard.allowLoginForm=true

Enabling DigDash LDAP mode

To activate the DigDash LDAP authentication mode, simply add the loginForm parameter to the URL with the value true.

So, if you need to authenticate to the dashboard directly using your DigDash LDAP credentials when SAMLv2 is already installed, the URL to use will be in the form :

https://<host>:<port>/digdash_dashboard/index.html?loginForm=true

Please note : in general, the loginForm parameter and its value should be specified on each domain independently of the others (ddenterpriseapi for the server, digdash_dashboard for the dashboard, studio for the web studio) in order to authenticate via LDAP.
Activating the loginForm parameter on the dashboard (digdash_dashboard domain) will not automatically activate it on the web studio (studio domain), for example.

Re-enabling SAMLv2 mode

To deactivate the DigDash LDAP mode and return to a state where SAMLv2 SSO authentication is used, simply set the loginForm parameter to false.
If you need to authenticate to the dashboard via SAMLv2 when direct authentication via DigDash LDAP was previously used, the URL to use will be in the form :

https://<host>:<port>/digdash_dashboard/index.html?loginForm=false

The previous warning note should also be taken into account in this case.

Using a reverse proxy

When using a reverse proxy, the remote IP valve must be adapted.

Open the server.xml file located in the :

under Linux: /etc/tomcat9/
under Windows: C:\Program Files\Apache Software Foundation\Tomcat 9.0\conf

In this file, the remote IP valve is entered as follows:

<Valve className="org.apache.catalina.valves.RemoteIpValve" internalProxies="127\.0\.[0-1]\.1" remoteIpHeader="x-forwarded-for" requestAttributesEnabled="true" protocolHeader="x-forwarded-proto" protocolHeaderHttpsValue="https"/>

Replace the value of the internalProxies property with the value of the reverse proxy IP as shown below.

<Valve className="org.apache.catalina.valves.RemoteIpValve" internalProxies="<IP OF REVERSE PROXY>" remoteIpHeader="x-forwarded-for" requestAttributesEnabled="true" protocolHeader="x-forwarded-proto" protocolHeaderHttpsValue="https"/>

Glossary

In this document we will refer to :

ACS: Assertion Consumer Service
IdP: Identity Provider
SLO: Single LogOut
SP: Service Provider (DigDash)
SSO: Single Sign On; SAMLv2 is an SSO method

References

https://www.oasis-open.org

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

https://www.onelogin.com/

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