OpenID Connect authentication
- Prerequisites
- Configuring the DigDash server
- Application configuration
- Configuring the OpenID Provider
- Log Level
- OpenID Connect and LDAP DigDash coexistence (optional)
- Glossary
- References
This document describes how to set up an OpenID Connect authentication valve for DigDash.
Prerequisites
- The acronyms used below are listed in the glossary at the end of this document.
- Have configured the DigDash server with an SSL/TLS (HTTPS) connector (this authentication method requires secure exchanges).
- Have the <Install DD>/add-ons/valve_openidconnect folder containing all the files needed to set up the OpenID Connect authentication valve in the DigDash 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 logs 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 webapps sub-folder : the DigDash entry point (endpoint) in a .war to be placed in:
- under Linux: /home/digdash/webapps/default
- under Windows: E:/digdash/webapps/default
- The lib sub-folder: libraries and logs configuration file to be placed in :
- The apache-tomcat folder: transposed to /etc/tomcat9/ under Linux and C:\Program Files\Apache Software Foundation\Tomcat 9.0\conf under Windows
- The following operations must be carried out with the DigDash server stopped.
- The user to be authenticated must exist both at the PO and in the DigDash LDAP.
Configuring the DigDash server
Copy the libraries
Copy the libraries and the log configuration file from the <install DD>/add-ons/valve_openidconnect/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 :
| oidc-valve.jar | log4j-api-2.19.0.jar |
| slf4j-api-2.0.6.jar | log4j-1.2-api-2.19.0.jar |
| log4j-slf4j-impl-2.19.0.jar | log4j2.properties |
| log4j-core-2.19.0.jar |
Adding the OpenID Connect authentication valve
Activate the OpenID Connect authentication valve in the server.xml file located in the :
- on 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:
className="org.bsworks.catalina.authenticator.oidc.OpenIDConnectSSOValve"
allowAddr="localhost,127.0.0.*,0:0:0:0:0:0:0:1"
fallbackAuth="ldap"
sharedPasswd="secret"
redirect_url="https://localhost:8443/digdash_oidc_endpoint/oidcendpoint"
providers="[
{
name: OpenID Provider name,
issuer: issuer,
clientId: clientId,
clientSecret: clientSecret
}
]"
usernameClaim="email"
additionalScopes="email"
cookieTimeOut="-1"
></Valve>
The value of the className attribute is invariant.
The values of the allowAddr, sharedPasswd, redirect_url, providers, usernameClaim, additionalScopes attributes are variable depending on the installation.
| Attributes | Description |
| className (required ) | 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 several implementations provided by Tomcat. |
| allowAddr (required ) | IP address of the server. |
| fallbackAuth (required) | The fallback authentication method. |
| sharedPasswd (required ) | The password shared and verified during authentication (see point II.5). |
| redirect_url (required ) | This is the application path to which users will be redirected after authenticating with the OP. For DigDash, the URL will be https://<DigDash address>:<port>/digdash_oidc_endpoint/oidcendpoint or |
| cookieTimeOut (optional ) | Optional, this is the time (in seconds) after which the SSO cookie will expire. Defaults to 1800 seconds (30 minutes). A negative value means that the cookie will expire when the browser is closed. Example: cookieTimeOut="3600" (1 hour) |
| print_debug (optional ) | Optional, set to false by default, otherwise add print_debug="true" for more verbose traces. |
| providers (required ) | JSON object array value. Each element corresponds to an OpenID Provider used by the application. The syntax differs from the standard JSON format in that double quotes are not used for the names of properties and their values (to make the format more XML-like). A value can be surrounded by single quotes if it contains separators such as commas, braces or spaces. Each object representing a PO has the following properties: - issuer (mandatory) : This is a unique URL to identify the PO. - name (optional) : A name associated with the PO; otherwise the issuer by default. - clientId (required): The client ID associated with the application at the PO. - clientSecret (optional) : The Secret client. Note that most POs require a Secret client, particularly for calls to the PO's entry points. However, some OPs support public clients, hence the absence of a Secret client. - usernameClaim (optional): The user Identifier attribute requested by the RP and returned by the PO to identify the authenticating user. - additionalScopes (optional) : Additional scopes to the 'openid' scope separated by spaces. |
| usernameClaim (optional ) | The default user identifier used by all OPs that do not specify one in the OP's own properties. |
| additionalScopes(optional ) | The default additional scopes used by all OPs that do not specify one in the OP's own properties. |
| httpConnectTimeout (optional ) | Timeout in milliseconds for establishing the connection to the OP. 5000 ms (5 seconds) by default. |
| ldapForPaths (optional ) | These are the regular expressions of the URLs whose resources are authorised to pass the valve, thereby switching to LDAP authentication mode. Example: "https://localhost:8443/digdash_dashboard/.*" |
| 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: "/.*" |
Add the .war corresponding to the Relying Party entry point
Add the digdash_oidc_endpoint.war archive from the <install DD>/add-ons/valve_openidconnect/apache-tomcat/webapps folder to the :
- under Linux: /home/digdash/webapps/default
- under Windows: E:/digdash/webapps/default
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
...
<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:
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.DOMAIN=ddenterpriseapi
digdash_dashboard.FORCEDOMAIN=true
digdash_dashboard.FORCESERVERURL=true
digdash_dashboard.sharedPasswd=<la valeur de l'attribut sharedPasswd dans l'élément Valve>
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.DOMAIN=ddenterpriseapi
studio.FORCEDOMAIN=true
studio.FORCESERVERURL=true
studio.PUBLICSERVERURL=<votre adresse URL publique en HTTPS>
studio.sharedPasswd=<la valeur de l'attribut sharedPasswd dans l'élément Valve>
Configuring the OpenID Provider
The PO must register DigDash as an RP in its list of RPs so that DigDash can take advantage of Single Sign-On.
The PO will also need to fill in the callback URL to identify the entry point to the DigDash application. The URL will be in the form
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 actions and exchanges between the various entities, you can set the value to 'DEBUG' instead of 'ERROR' in the log4j.properties file that has been imported into the Tomcat lib folder.
log4j.logger.org.bsworks=ERROR, stdout
becomes
log4j.logger.org.bsworks=DEBUG, stdout
OpenID Connect and LDAP DigDash coexistence (optional)
It is possible to combine direct authentication via the DigDash LDAP directory with the OpenID Connect method 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:
In the digdash_dashbord.war box, find and uncomment the following lines with the values shown:
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 OpenIDConnect is already installed, the URL to use will be in the form :
https://<host>:<port>/digdash_dashboard/index.html?loginForm=true
Re-enabling OpenID Connect mode
To deactivate the DigDash LDAP mode and return to a state where OpenID Connect SSO authentication is used, simply set the loginForm parameter to false.
If you need to authenticate to the dashboard via OpenID Connect 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.
Glossary
In this document we will refer to :
- Endpoint : Point of entry
- OP : OpenID Provider or Identity Provider
- RP : Relying Party or Service Provider (DigDash)
- SSO : Single Sign On; OpenIDConnect is an SSO method.
References
DigDash uses the tomcat8-oidcauth OpenSource library from Boyle Software, Inc. to support the OpenID Connect authentication method.