Skip to main content
Version: 14.0

Set Up OIDC Authentication

OpenID connect (OIDC) is an authentication layer on top of the OAuth 2.0 authorization framework that can be used to securely sign in a user to ADONIS. Authentication and authorization is performed using the Authorization Code Flow.

To configure this authentication mechanism, you need to complete the following steps:

When you have completed these steps, you can:

caution

To configure this authentication mechanism, you need experience with JSON. If you need help, contact your ADONIS consultant.

Prerequisites

Before you configure ADONIS to use OpenID connect for authentication, you will need an account with an OpenID Connect provider (OP) such as Microsoft Azure AD or Google to verify the identity of your users. Register ADONIS with the OP and obtain the following details:

  • Client ID

  • Client secret

  • Authorization endpoint

  • Token endpoint

  • Issuer

Adapt Authentication Configuration of the Web Application

This authentication mechanism needs to be configured on the Admin Page:

  • Open the Admin Page. On the toolbar at the top of the screen, click More  , and then click Authentication.

The necessary settings are described below.

Create OIDC Connector

On the Authentication page, under Connectors, all authentication mechanisms (= connectors) of the ADONIS web client are listed. Your first task is to add a new OIDC connector here:

  • Click the button to add a new connector, and then click the button to edit your new connector.

The new connector will already include a number of properties. Replace the content with the following JSON snippet, and then click Save:

{

"enabled": true,

"id": "OIDC Login",

"index": 0,

"ldap": {

"domains": [],

"enabled": false,

"properties": []

},

"properties": {

"auth_server_client_id": {

"value": "<client ID>"

},

"auth_server_client_secret": {

"value": "<client secret>"

},

"auth_server_issuer": {

"value": "<issuer URL>"

},

"auth_server_url_authorize": {

"value": "<authorize URL>"

},

"auth_server_url_token": {

"value": "<token URL>"

},

"scopes": {

"value": "profile"

},

"store_login_hint": {

"value": "true"

},

"claims": {

"value": "claim_login,claim_firstname,claim_lastname"

},

"claim_login": {

"value": "sub"

},

"claim_firstname": {

"value": "given_name"

},

"claim_lastname": {

"value": "family_name"

}

},

"type": "OIDC",

"user-mapping": {}

}

Here is an explanation of the configuration above:

  • OIDC authentication is now activated ("enabled": true,) and will be used as the default connector ("index": 0,).

  • If you want, you can change the name for the connector ("id": "OIDC Login",).

  • LDAP coupling is disabled ("ldap": {},).

  • A number of properties ("properties": {},) still have placeholders, we will configure those in the next step.

  • A basic set of OIDC claims that contain information about the user is provided ("claims": {). We will customize those later.

  • This connector is an OIDC connector ("type": "OIDC",).

  • The user mapping ("user-mapping": {}) is still empty, we will also configure it later.

Edit Authorization Server Configuration

Next, you need to edit the authorization server configuration of the OIDC connector:

  • Click the OpenID symbol on the right of the OIDC Connector.

The Authorization Server Configuration (OIDC) form appears. You can enter and edit the following data:

  • Authorization endpoint

    The authorization endpoint at the OP.

  • Token endpoint

    The token endpoint at the OP.

  • Issuer

    The issuer identifier of the OP.

  • Client ID

    The public identifier for ADONIS as registered with the OP.

  • Client secret

    The secret password for ADONIS as registered with the OP.

  • Remember user

    Enable this check box to store the last used user ID and pass it for future authentication processes, so this user account will be automatically selected (can be useful when operating multiple user accounts).

Define Claims

Next, you need to define the claims that the OP should supply. Claims are used to transport information about the user such as their email address, first name and last name:

  • Click the button on the right of the OIDC Connector.

Adapt the following parameters:

  • scopes

    OAuth 2.0 scopes for use with your OP. Set to "profile" by default, which signifies a request for viewing information about the user to the OP.

  • claims

    Set this property to register claims which should be evaluated, e.g. "value": "claim_login,claim_firstname,claim_lastname". Enter a descriptive name for every claim you want to synchronize. Separate the claims with a comma.

  • claim_login

    The name of the claim holding the username to be used.

  • claim_firstname

    The name of the claim holding the given name to be used.

  • claim_lastname

    The name of the claim holding the family name to be used.

note

You can create and register additional claims (e.g. claim_email) as needed.

Provide User Mapping

Next, you will need to provide a user mapping. The user mapping contains instructions on how to deal with a user during the authentication process, e.g. if a user should be created when it doesn't exist yet or which system roles or user groups to assign to the user. Additionally, the user mapping contains instructions on how to map the claims supplied by the OP to ADONIS user attributes:

  • Replace the section "user-mapping": {} of the OIDC Connector with the following JSON snippet:

"user-mapping": {

"autoCreateUser": true,

"auto_sync_user": {

"auto_sync_attributes": true,

"auto_sync_groups": true,

"auto_sync_roles": true,

"enabled": true

},

"default_groups": [

"Default group"

],

"default_roles": [

{

"name": "Common"

}

],

"properties": [

{

"attr": "NAME",

"name": "claim_login"

},

{

"attr": "FORENAME",

"name": "claim_firstname"

},

{

"attr": "SURNAME",

"name": "claim_lastname"

}

],

"repositories": [],

"roles": [],

"user_deletion_handling": {

"deleteNotFoundUsers": true,

"moveUndeletableUsersToGroup": false

}

}

Here is an explanation of the configuration above:

  • Users are automatically created on login ("autoCreateUser": true,) and user data will updated every time a user logs in ("auto_sync_user": {...},).

  • Every user will be assigned the user group "Default group" and the system role "Design & Document" (unique name Common).

  • The previously registered claims are mapped to ADONIS user attributes ("attr": "...", "name": "...")

  • Users who are not found during synchronization should be deleted ("user_deletion_handling": { "deleteNotFoundUsers": true, ...}).

note

You can adapt the user mapping as needed. For more information, check the Help file which you can download from the Admin Page and the User Mapping section.

Start Authenticating Users

Save your changes on the Admin Page. Once the changes are saved, they take effect immediately. A restart is not required.

All users that can log in to the configured OP should also be able to log in to the ADONIS web client. Furthermore, if a user does not yet exist in the database, it is created and also assigned to the corresponding user groups/system roles according to the mapping definition within the configuration.

(Optional) Tracking Errors

Logging output is written to the files <Tomcat installation>/logs/ADONIS14_0.log” and <ADONIS installation/*_aworker.log>.