Authentication OpenID Connect

What is OpenID Connect

OpenID Connect is a simple identity layer on top of the OAuth 2.0 protocol. It enables DGLux to verify users based on authentication performed by a 3rd party Authorization Server and to obtain basic profile information about the user. See the official OpenID Connect Frequently Asked Questions for more information.

OpenID Provider

The first step to setting up OpenID Connect Authorization is to have an OpenID Connect Provider. This 3rd party authorization server is where DGLux will redirect the user to log in. Once they have logged in with the provider, the user is redirected back to a special end-point in DGLux.

Some example OpenID Providers (in no particular order) are Auth0, Okta, and KeyCloak. The setup of these, or other OpenID Connect Providers, is outside of the scope of this document. Currently DGLux does not support auto-discovery or dynamic-registration, however each OpenID Connect provider should have a similar process:

• Register a new application for the DGLux server within the OpenID Connect Provider. This process should generate a clientId and a secret which will need to stored for your DGLux configuration.
• Add (login) callback URL. Once the authentication provider has authorized a user, it will only permit callbacks to URLs that you specify with them. There, you must specify the DGLux Server address with an additional path of /sso/openId. Example: If your DGLux Server is running on localhost:8443 you must specify: https://localhost:8443/sso/openId in their allowed callbacks.
• (Optional) You may also specify a logout URL which will redirect back to the root address of the dglux installation for example: https://localhost:8443/

Finally, you must also make note of the issuer address for the OpenID Connect Provider. This is often the custom domain provided for the application by your OpenID Provider, Examples: https://dev-XXXXXX.okta.com/ or https://MyApp.auth0.com.

DGLux Configuration

The DGLux server configuration must be updated to direct login requests to the OpenID Connect provider. To do so, the server.json file must be modified. Within the file make the following adjustments:

• Change the "authType" value to `"openId"
• At the bottom of the server.json file, add the following section:

"openId": {
  "issuer": "<issuer URI from above>",
  "clientId": "<client_id from OpenID Connect Provider>",
  "secret": "<secret from the OpenID Connect Provider>"
}

The DGLux server will attempt to connect to the issuer address and locate the openid-configuration automatically. It will connect to <issuer_url>/.well-known/openid-configuration to try and retrieve the configuration. In the event that your OpenID Connect Provider requires additional components, such as a query string, it may be necessary to provide a link to the entire OpenID Configuration address in the "issuer" field above. Example:

"issuer": "https://somedomin.b2clogin.com/somedomain.onmicrosoft.com/v2.0/.well-known/openid-configuration?p=B2C_somedomain"

There are two optional configuration parameters for the OpenID Connect configuration. The first is "usernameKey". OpenID Connect Providers may be inconsistent with the value passed to represent a preferred username, by default DGLux Server will try to use the value found in the "preferred_username" key returned by the Provider, and will fall back to "sub" (which is often a less desirable unique indicator). The "usernameKey" configuration value allows you to specify which key from the Provider should be used as the username. Example:

"usernameKey": "email"

The second optional parameter is to specify the scopes sent for the OpenID Connect request. By default the DGLux server will request 3 scopes. The first is "openid" which is required for all OpenID Connect requests. This will always be added by the DGLux server and should never be included manually. The additional two scopes are "email" and "profile". In the event you wish to specify additional scopes, you can use the "scopes" configuration parameter. This parameter is a list of strings. Note: If you provide additional scopes it will replace the email and profile scopes. So if you wish to add the "nickname" scope, but also receive profile and email, then you must specify all three as the scope configuration parameter. Example:

"scope": ["nickname", "profile", "email"]

An example of a fully configured OpenID Connect block within the server.json file:

"openId": {
  "issuer": "https://my.issuer.com",
  "clientId": "myAppClientId",
  "secret": "longSecretValuexew8ewe230sda83232sdd",
  "usernameKey": "email",
  "scope": ["nickname", "profile", "email"]
}

We convert the following symbols to underscores "_" when importing username from the OpenID Connect provider. So jane.doe@example.com becomes jane_doe_example_com

"@", "=", "_", "+", "-", "!", ".", "|"