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 ADOIT. 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:
To configure this authentication mechanism, you need experience with JSON. If you need help, contact your ADOIT consultant.
Prerequisites
Before you configure ADOIT 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 ADOIT 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 ADOIT 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 ADOIT as registered with the OP.
Client secret
The secret password for ADOIT 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.
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 ADOIT 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": "Architect"
}
],
"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 "Enterprise Architect" (unique name
"Architect".The previously registered claims are mapped to ADOIT user attributes (
"attr": "...", "name": "...")Users who are not found during synchronization should be deleted (
"user_deletion_handling": { "deleteNotFoundUsers": true, ...}).
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 ADOIT 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/ADOIT16_0.log” and ”<ADOIT installation/*_aworker.log>”.