OAuth2 Setup

Accurids allows the use of OAuth2 together with OpenID Connect (OIDC) for managing user access. For interactive user logins, Accurids uses the Authorization Code Flow. For machine-to-machine (M2M) access, Accurids supports the Client Credentials Flow.

By default, Accurids uses its built-in user management (see Platform Administration), unless OAuth2 is explicitly configured (see below).

There are several identity providers which support OAuth2, for example:

Microsoft Entra ID (formerly Azure AD)
Ping Identity
Google
Okta
... and many others

To enable OAuth2 authentication, both Accurids and the identity provider must be configured. The sections below describe the required settings. The exact steps in the identity provider's UI may vary; refer to its documentation for details.

Configuration of the Identity Provider

For the examples below, we assume that Accurids is reachable at https://accurids.your-company.com. Replace this URL with the actual URL of your installation.

Choose an identifier (a few lowercase letters) for your OAuth2 registration, for example youridp. Replace youridp in all examples below with your chosen identifier.

Create an application in the identity provider, typically of type "web application" with OIDC support.
Add a redirect URI. The preferred value is {baseUrl}/login/oauth2/code/{registrationId}. The placeholders {baseUrl} and {registrationId} are automatically replaced by the system URL and the registration identifier respectively. This requires that Accurids has access to the original request URL (e.g. via X-Forwarded-* headers from a reverse proxy or Kubernetes ingress).

If the original request URL is not available, use a fixed redirect URI instead: https://accurids.your-company.com/login/oauth2/code/youridp (replace youridp with your identifier). Note that this restricts Accurids to a single domain name.

Grant scopes profile and openid.
Configure claim mappings so that the authentication token contains the following information:

Information Default claim name

Given name given_name

Family name family_name

Email user_email

Organization organization

Roles roles

Accurids allows changing the expected claim names (see the claims configuration table below).
Configure application roles. Create three roles with the following values:

Role Value

User USER

Contributor CONTRIBUTOR

Admin ADMIN

If your identity provider uses different role values, you can override them with the security.role.* properties.

Configuration of Accurids

Set security=oauth2 and activate the oauth2 Spring profile. Then provide the following configuration values (replace youridp with your chosen registration identifier):

Core Settings

Parameter	Description	Example
`security`	Set to `oauth2` to enable OAuth2 support	`oauth2`
`accurids.security.registration`	The registration identifier	`youridp`

Spring OAuth2 Client

Parameter	Description	Example
`spring.security.oauth2.client.registration.youridp.client-id`	Client ID from the identity provider
`spring.security.oauth2.client.registration.youridp.client-secret`	Client secret from the identity provider
`spring.security.oauth2.client.registration.youridp.redirect-uri`	Redirect URI (see above)	`{baseUrl}/login/oauth2/code/{registrationId}`
`spring.security.oauth2.client.registration.youridp.scope`	Scopes needed to access user profile and roles	`profile,openid`
`spring.security.oauth2.client.registration.youridp.authorization-grant-type`	Always `authorization_code`	`authorization_code`
`spring.security.oauth2.client.provider.youridp.authorization-uri`	Authorization endpoint URL
`spring.security.oauth2.client.provider.youridp.token-uri`	Token endpoint URL
`spring.security.oauth2.client.provider.youridp.jwk-set-uri`	JWKS endpoint URL
`spring.security.oauth2.client.provider.youridp.user-name-attribute`	Claim that uniquely identifies the user	`user_email`

Claim Mapping (optional)

If your identity provider uses non-default claim names, override them with the following properties:

Parameter	Default	Description
`accurids.security.claims.firstName`	`given_name`	Claim containing the first name
`accurids.security.claims.lastName`	`family_name`	Claim containing the last name
`accurids.security.claims.email`	`user_email`, `preferred_username`	Claim containing the email
`accurids.security.claims.organization`	`organization`, `companyname`	Claim containing the organization
`accurids.security.claims.roles`	`roles`	Claim containing the assigned roles

Role Mapping (optional)

Parameter	Default	Description
`security.role.admin`	`ACCURIDS_ADMIN`	Role value that maps to Admin
`security.role.contributor`	`ACCURIDS_CONTRIBUTOR`	Role value that maps to Contributor
`security.role.user`	`ACCURIDS_USER`	Role value that maps to User

Microsoft Entra ID (Azure AD) Example

Accurids ships with a pre-configured Spring profile azuread that contains all Azure-specific OAuth2 endpoint URLs and claim mappings. To use it, activate the azuread profile instead of the generic oauth2 profile:

spring.profiles.active=azuread

You only need to provide tenant-specific values:

Parameter	Description
`accurids.security.tenant-id`	Your Entra ID (Azure AD) tenant ID
`spring.security.oauth2.client.registration.azure.client-id`	The Application (client) ID from the App Registration
`spring.security.oauth2.client.registration.azure.client-secret`	A client secret generated in the App Registration

App Registration in Entra ID

In the Azure Portal, go to Microsoft Entra ID > App registrations > New registration.
Enter a name (e.g. "Accurids") and select Single tenant for supported account types.
Under Authentication, add a Web platform with redirect URI: https://accurids.your-company.com/login/oauth2/code/azure (or use {baseUrl}/login/oauth2/code/{registrationId} if the original request URL is preserved).
Under API permissions, ensure Microsoft Graph > User.Read is granted. Click Grant admin consent (requires directory admin rights).

Define Application Roles

Under App roles, create three roles:

Display name	Value	Allowed member types
User	`USER`	Users/Groups
Contributor	`CONTRIBUTOR`	Users/Groups
Admin	`ADMIN`	Users/Groups

Assign Users and Groups

In Enterprise applications, find the Accurids application. Under Users and groups, add users or groups and assign them one of the three roles.

Optional Token Claims

Under Token configuration, add the following optional claims to the ID token to ensure Accurids receives the user's profile information:

email
family_name
given_name

Machine-to-Machine (M2M) Access

(Please note: This feature is available since Accurids 2.16.2.)

Accurids supports the OAuth2 Client Credentials Flow, allowing applications to access the API without a user context. Applications authenticate with their own credentials and are represented as service accounts in Accurids.

How It Works

An application obtains an access token from the identity provider using its client ID and client secret.
The application sends API requests to Accurids with the access token in the Authorization: Bearer <token> header.
Accurids validates the token and automatically provisions a service account for the application.

Service accounts are visible in the User Management section of the admin interface and are marked with a "Service Account" flag.

Identity Provider Setup

In the identity provider, create a separate client application (not the same as the Accurids web application registration) with permission to request tokens via the client credentials flow:

Create a new App Registration for the client application.
Add a client secret under Certificates & secrets.
Grant API permissions: Under API permissions, add a permission for the Accurids API app registration. The permission type should be Application (not Delegated).
Assign a role to the client application. In the Accurids API app registration, go to App roles and ensure the roles allow Applications as member type (in addition to Users/Groups). Then, in the client application's API permissions, assign the desired role.

For Entra ID, the app roles in the Accurids API app manifest should include "Application" in allowedMemberTypes:

{
    "allowedMemberTypes": ["User", "Application"],
    "displayName": "Admin",
    "value": "ADMIN",
    ...
}

Accurids Configuration

The client credentials flow requires Accurids to be configured as an OAuth2 Resource Server. The azuread profile already includes this configuration. For the generic oauth2 profile, add the following:

Parameter	Description	Example
`spring.security.oauth2.resourceserver.jwt.issuer-uri`	The token issuer URI	`https://sts.windows.net/{tenant-id}/`
`spring.security.oauth2.resourceserver.jwt.jwk-set-uri`	JWK Set URI (optional; auto-discovered from issuer if omitted)
`spring.security.oauth2.resourceserver.jwt.audiences`	The expected `aud` claim value (required)	`api://<client-id>`

If issuer-uri is not set, the resource server (and thus M2M support) is disabled.

Note

For Entra ID, access tokens are issued with a v1.0 issuer (https://sts.windows.net/{tenant-id}/) by default, even when using v2.0 endpoints. The azuread profile is pre-configured for this. If you set accessTokenAcceptedVersion: 2 in the app manifest, change the issuer URI to https://login.microsoftonline.com/{tenant-id}/v2.0.

Optional: Default Service Account Role

By default, client applications must have an explicit role assigned in the identity provider. If you want to allow applications without an explicit role to connect with a fallback role, set:

accurids.security.defaultServiceAccountRole=USER

When not set (the default), applications without an assigned role are rejected.

Optional: Service Account Email Domain

Service accounts are assigned a synthetic email address derived from the token's sub claim. The domain can be customized:

accurids.security.serviceAccount.emailDomain=@client.accurids

Obtaining a Token

To obtain an access token for testing, use the following curl command (Entra ID example):

curl -s -X POST \
  "https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token" \
  -d "client_id={client-app-id}" \
  -d "client_secret={client-secret}" \
  -d "scope=api://{api-app-id}/.default" \
  -d "grant_type=client_credentials"

Replace {tenant-id}, {client-app-id}, {client-secret}, and {api-app-id} with your actual values. The response contains an access_token field.

Calling the API

Use the obtained access token in the Authorization header (the example below just returns the ID of the authenticated user):

curl -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -X POST https://accurids.your-company.com/graphql \
  -d '{"query": "query { authenticatedUser {id} }"}'

Information	Default claim name
Given name	`given_name`
Family name	`family_name`
Email	`user_email`
Organization	`organization`
Roles	`roles`