Authentication: SSO with OpenID Connect

Linkurious Enterprise supports any OpenID Connect compatible provider as external authentication providers.

What is OpenID Connect?

OpenID Connect (OIDC) is an identity layer on top of the OAuth2 protocol. It allows applications (like Linkurious Enterprise) to verify the identity of user based on the authentication performed by a server, as well as to obtain basic profile information about the user (username, email) in an interoperable manner.

Configuration

To set up Linkurious Enterprise authentication with an OpenID Connect provider, you need to obtain the following parameters from the provider:

• authorizationURL, e.g. https://accounts.google.com/o/oauth2/v2/auth
• tokenURL, e.g. https://www.googleapis.com/oauth2/v4/token
• clientID, e.g. 1718xxxxxx-xxxxxxxxxxxxxxxx.apps.googleusercontent.com
• clientSecret, e.g. E09dQxxxxxxxxxxxxxxxxSN

Example access.oauth2 configuration with any OpenID Connect provider:

"access": {
  // [...]
  "oauth2": {
    "enabled": true,
    "provider": "openidconnect",
    "authorizationURL": "https://accounts.google.com/o/oauth2/v2/auth",
    "tokenURL": "https://www.googleapis.com/oauth2/v4/token",
    "clientID": "XXXXXXXXXX-XXXXXXXXXXXXXXXX.apps.googleusercontent.com",
    "clientSecret": "XXXXXXXXXXXXXXXXXXXXXXX"
  }
}

OAuth2 redirect URL

The OAuth2 redirect URL of Linkurious Enterprise is the following: http(s)://HOST:PORT/api/auth/sso/return.

Scopes and Claims

A claim is a pieces of information that are returned by the authentication server for a given user (e.g. the e-mail address of a user is usually in a claim called "email").

A scope is groups of claims that can be requested from the authentication server (e.g. asking for the scope "profile" will usually return several claims called "name", "family_name", etc.)

When setting up Linkurious Enterprise with OIDC:

• providing a valid e-mail for each user is mandatory
• providing a username is recommended. When missing, the e-mail will be used as username.
• providing groups is only required when group mapping is enabled.

To do so, the following configuration options are available:

• access.oauth2.openidconnect.scope (default: "openid profile email"): The scopes that will be requested from the OIDC server (Note: the openid scope will always be requested, regardless of this setting).
• access.oauth2.openidconnect.emailClaim (default: "email"): The claim that will be used to read the user's e-mail (Note: if the value cannot be found, authentication will fail).
• access.oauth2.openidconnect.userClaim (default: "name"): The claim that will be used to read the user's name (Note: if the value cannot be found, the email will be used as username).
• access.oauth2.openidconnect.groupClaim (default: null, required when group mapping is enabled): The claim that will be used to read the user's list of groups.
• access.oauth2.openidconnect.userinfoURL (default: null, required when groupClaim is set): The URL of the UserInfo endpoint of the OIDC server, used to fetch groups.

Group mapping in OIDC

To set up group mapping in OpenID Connect is necessary to specify additional configuration keys:

• openidconnect.userinfoURL, e.g. https://XXXXXXXXXX.oktapreview.com/oauth2/v1/userinfo
• openidconnect.scope, e.g. openid profile email groups
• openidconnect.groupClaim, e.g. groups

For example if you want to set up OIDC with Okta:

"access": {
  // [...]
  "oauth2": {
    "enabled": true,
    "provider": "openidconnect",
    "authorizationURL": "https://XXXXXXXXXX.oktapreview.com/oauth2/v1/authorize",
    "tokenURL": "https://XXXXXXXXXX.oktapreview.com/oauth2/v1/token",
    "clientID": "XXXXXXXXXXXXXXXXXXXXXXX",
    "clientSecret": "XXXXXXXXXXXXXXXXXXXXXXX",
    "openidconnect": {
      "userinfoURL": "https://XXXXXXXXXX.oktapreview.com/oauth2/v1/userinfo",
      "scope": "openid profile email groups",
      "groupClaim": "groups"
    }
}