Oauth2 Setup

Accurids allows the use of Oauth2 together with OpenID Connect for managing user access. Accurids supports the use of the Authorization Code Flow.

By default, Accurids uses it's built-in user management (see Platform Administration), unless the use of Oauth2 is explicitly configured (see below).

There are several identity providers which support Oauth2, like:

• Microsoft Azure AD
• Ping Identity
• Google
• Facebook
• ... and many others

To make the Oauth2 authentication work, Accurids and the identity provider must be configured. For the identity provider, we show which settings must be adapted, but there might be differences between the providers where exactly these settings can be configured. We kindly refer to the identity provider's documentation.

Below we also show how to configure Azure AD.

Configuration of the Identity Provider

For the example, we assume that Accurids is reachable under the domain https://accurids.your-company.com. In the configuration steps below, replace this URL with the actual URL of your Accurids installation.

Choose an identifier (just a few lower case letters) for your configuration. E.g. in this example we use ping. Please replace ping with whatever you have chosen.

1) Create an application "Accurids" in the identity provider. The application is usually of type "web application" with OIDC.

2) You need to add a "redirection URL". This tells the identity which URL should be looked up after the login procedure has been completed.

The preferred value is the expression {baseUrl}/login/oauth2/code/{registrationId}. The parts {baseUrl} and {registrationId} are automatically replaced by the systems URL resp. the registration ID (e.g ping). To be able to use this, it must be guaranteed that Accurids has access to the original request URL. For example, a reverse proxy or Kubernetes ingress controller usually sends this information together with the request. This setting is neecessary in case Accurids provides its service for different host names, e.g. one for Accurids core web service and one for a redirection service.

In case Accurids has no access to the original request URL, set it to https://accurids.your-company.com/login/oauth2/code/ping. (Replace ping by your configuration identifier.) But in this case, Accurids cannot serve multiple domain names.

3) Grant access to the scope accesses profile and openid.

4) Configure a 'role mapping' or similar: Specify that the authentication token contains the following information: * Given name (claim / field name: given_name) * Family name (claim / field name: family_name) * Email (claim / field name: user_email) * Organization (claim / field name: organization) * Roles (claim / field name: roles) Accurids allows to change the name of the claims where it expects the information, see below in case you need other names as above.

5) Configure the roles a user of Accurids could be in. There should be three roles:

* User
* Contributor
* Admin

Each role has a value. Set them to USER, CONTRIBUTOR, ADMIN. If you choose other values,
you can adapt the configuration as shown below.

Configuration of Accurids

The following configuration values must be set (please note that ping should be replaced by the configuration identifier that you have chosen):

Parameter name	Description	Example
accurids.security.registration	The configuration identifier	ping
accurids.security.registration.claims.firstName	The token's claim containing the first name	given_name
accurids.security.registration.claims.lastName	The token's claim containing the last name	family_name
accurids.security.registration.claims.email	The token's claim containing the email	user_email
accurids.security.registration.claims.organization	The token's claim containing the organization	organization
accurids.security.registration.claims.roles	The token's claim containing the roles	roles
security	Set to oauth2 to enable oauth2 support	oauth2
security.role.admin	The name of the admin role	ADMIN
security.role.contributor	The name of the contributor role	CONTRIBUTOR
security.role.user	The name of the user role	USER
spring.security.oauth2.client.registration.ping.client-id	Take the client ID from your identity provider's settings
spring.security.oauth2.client.registration.ping.client-secret	Add or generate a client secret in your identity provider's settings
spring.security.oauth2.client.registration.ping.redirect-uri	Enter the redirect URL from above
spring.security.oauth2.client.registration.ping.scope	The scopes needed to access the names, email and roles of a user	profile,openid
spring.security.oauth2.client.provider.ping.authorization-uri	Take the authorization URL from your identity provider's settings
spring.security.oauth2.client.provider.ping.jwk-set-uri	Take the JWKS endpoint from your identity provider's settings
spring.security.oauth2.client.provider.ping.token-uri	Take the token endpoint from your identity provider's settings
spring.security.oauth2.client.provider.ping.user-name-attribute	The token's claim that contains the user's email, must be consistent with the email claim above	user_email
spring.security.oauth2.client.registration.ping.authorization-grant-type	Always authorization_code	authorization_code

Azure AD example

Register Accurids as Application in AAD

Open the Azure Portal and select "Azure Active Directory" from the sidebar. Then select "App Registrations" from the side menu. Click "New Registration" from the top menu. Give the application name as it will appear within AAD. For "Supported Account Types" select "Single Tennant". Do NOT enter a Redirect URI. Next, click "Register".

Further App Registration Settings

Open "Authentication" in the side menu and click "Add a platform". Under Web applications, select the Single-page application tile. Under Redirect URIs, enter a redirect URI where your Accurids installation will be accessible to the user and add /signin at the end, resulting in e.g. https://accurids.mycompany.com/signin. Do NOT select either checkbox under Implicit grant and hybrid flows.

Open "API Permissions" and select "User.Read" under "Microsoft Graph". Then, click "Grant admin consent for ..." to grant the app consent to read the user profile from the active directory upon user login. This process requires admin rights for the whole active directory.

Add Manifest

Click "Manifest" in the side menu and modify the manifest file. Replace the key appRoles with the following:

"appRoles": [
        {
            "allowedMemberTypes": [
                "User"
            ],
            "description": "contributor access",
            "displayName": "Contributor",
            "id": "xxx",
            "isEnabled": true,
            "lang": null,
            "origin": "Application",
            "value": "CONTRIBUTOR"
        },
        {
            "allowedMemberTypes": [
                "User"
            ],
            "description": "Normal user access",
            "displayName": "User",
            "id": "xxx",
            "isEnabled": true,
            "lang": null,
            "origin": "Application",
            "value": "USER"
        },
        {
            "allowedMemberTypes": [
                "User"
            ],
            "description": "Full admin access",
            "displayName": "Admin",
            "id": "xxx",
            "isEnabled": true,
            "lang": null,
            "origin": "Application",
            "value": "ADMIN"
        }
    ],

Replace the key requiredResourceAccess with the following:

"requiredResourceAccess": [
        {
            "resourceAppId": "00000002-0000-0000-c000-000000000000",
            "resourceAccess": [
                {
                    "id": "xxx",
                    "type": "Scope"
                },
                {
                    "id": "xxx",
                    "type": "Scope"
                }
            ]
        },
        {
            "resourceAppId": "00000003-0000-0000-c000-000000000000",
            "resourceAccess": [
                {
                    "id": "xxx",
                    "type": "Scope"
                }
            ]
        }
    ],

Click Save to apply the changes.

Manage User Roles

To allow users access to the application, users or groups of users have to be added to the application registration and roles have to be assigned.

Go back to the global active directory settings (select "Active Directory" in the top sidebar). Next, select "Enterprise applications" from the side menu and click the newly registered Accurids application in the list. Under "Users and groups" you can add users or whole groups and assign them one of the three roles provided by Accurids: - User - Contributor - Admin

Role names can differ from the mentioned example and can be specified as environment variables (see below).

Add Optional Claims for Token

Optional claims are used to configure additional information which is returned in one or more tokens. Add the following claims mentioned below: