OpenID Connect

This feature is only available in Enterprise Edition.

Starting with version 1.11.0, Arkindex Enterprise Edition supports authentication with single sign-on through OpenID Connect (OIDC). This allows for Arkindex user accounts to be externally managed through directory services such as Keycloak and Microsoft Entra ID.

Using OpenID Connect

On an instance with OpenID Connect enabled, the login page of the Arkindex frontend and of the administration interface both include a link to Login with OpenID Connect. This link redirects you to the OpenID provider’s own authentication interface.

OpenID Connect login button

After a successful login through the provider, you will be redirected to Arkindex. If you already had an account on Arkindex, you will be logged in. If you did not have one already, a new account will be created for you.

If the provider did not report that your email address was verified, you will receive a warning

In case you were already signed-on on the OpenID provider, clicking this button will redirect you to Arkindex after a few seconds and log you in immediately.

Password authentication

After authenticating with OpenID Connect, you will no longer be able to update your password, request a password reset, or log in using a password. You will need to log in exclusively using OpenID Connect.

Instance administrators can disconnect a user account from OpenID Connect to turn it back into a regular Arkindex account, which restores password authentication.

Setting up OpenID Connect

OIDC support is disabled by default, as it requires additional configuration. To enable OIDC on an instance, system administrators must obtain values for the oidc section of the configuration from the OIDC provider.

Using Keycloak

  1. Create an OpenID Connect client on the Keycloak instance.

  2. Under Settings  Access settings, configure the following:

    Root URL

    URL to the Arkindex instance.

    Home URL

    URL to the Arkindex instance.

    Valid redirect URIs

    URL to the Arkindex instance, followed by * to allow any URL within this instance. For example, https://arkindex.example.org/*.

    Valid post logout redirect URIs

    URL to the Arkindex instance, followed by * to allow any URL within this instance. For example, https://arkindex.example.org/*.

    Web origins

    A single plus sign (+). This will cause Keycloak to use the same value as Valid redirect URIs.

  3. Under Settings  Capability config, enable Client authentication and the Standard Flow.

  4. Under Credentials, select Client ID and secret as the Client authenticator and click Save, then copy the Client secret.

  5. Update the Arkindex backend configuration:

    oidc:
  provider: keycloak
  provider_discovery_uri: https://YOUR_KEYCLOAK_INSTANCE/realms/YOUR_REALM_NAME
  client_id: YOUR_CLIENT_ID
  client_secret: YOUR_CLIENT_SECRET

    You may also need to set up caching, as OpenID Connect support requires a cache.

Using Microsoft Entra ID

  1. Register a new application on Entra ID.

  2. Enable implicit ID tokens on this application.

    As the redirect URI for the new Web platform, use the /oidc/sso-callback on your Arkindex instance. For example, https://arkindex.example.org/oidc/sso-callback.

  3. Create a client secret on this application and copy its value.

  4. Update the Arkindex backend configuration:

    oidc:
  provider: default
  # This URI can be found under the `Endpoints` tab of the application overview
  provider_discovery_uri: https://login.microsoftonline.com/.../v2.0
  # This can be copied from the `Essentials` section of the application overview
  client_id: YOUR_CLIENT_ID
  # This can only be copied immediately after creating the client secret
  client_secret: YOUR_CLIENT_SECRET

    You may also need to set up caching, as OpenID Connect support requires a cache.

Disabling OpenID Connect

System administrators can disable OpenID Connect on an entire instance by commenting or removing the oidc section of the configuration and restarting their instance.

This will cause Arkindex to treat all accounts as local accounts, restoring password authentication:

  • Accounts that were created locally and later connected to OpenID Connect can be used again immediately using their previous password.

  • Accounts that did not exist locally, then were created automatically after logging in through OpenID Connect, do not have any password set. Users will need to request a password reset using the Forgot your password? link on the login page.

Disconnecting individual users

Through the administration interface, instance administrators can disconnect an account from OpenID Connect by editing users individually and erasing the OpenID Connect subject claim value.

Disabling OIDC on an account will restore password authentication. A new password may then need to be set, either through the administration interface or by letting the user click on the Forgot your password? link on the login page.

Technical information

This section contains information that may be helpful to system administrators attempting to diagnose issues with their OIDC configuration.

Token claim retrieval

After a successful authentication, Arkindex will look for various claims in the JSON Web Token to login or register a user. Arkindex will look for the first occurrence of a claim in the following sections, in order:

  1. info_token_claims

  2. id_token_claims

  3. auth_token_claims

Authentication process

Because Arkindex uses email addresses to uniquely identify users, it requires both the sub (subject) and email claims to be present. An HTTP 500 error will occur if these claims are missing.

When an account already exists with this OIDC subject claim, then the login process ends here and the user is authenticated.

When no account exists with this OIDC subject claim, but an account exists with this email instead

  • If it was already using OIDC, but with a different subject claim, a SuspiciousOperation error occurs. System administrators may need to disconnect the existing account from OIDC.

  • If it was not already using OIDC, its display name may be updated from the token claims. It may also be marked as having a verified email.

When there is no existing account, a new one gets created, with its email, display name and email verification defined from the token claims.

Display names

If any of the following claims are present, they will be set as the user’s display name:

  1. preferred_username

  2. username

  3. name

When creating a new account, if none of the above claims are present, Arkindex falls back to the email. On existing accounts, the display name remains unchanged.

Email verification

When the non-standard email_verified claim is set to true, the user will be marked as having a verified email. This claim is known to be provided by Keycloak. When this claim does not exist, it is also assumed to be true.

When the authentication process creates an account with a verified email, or when it causes an existing account to have a verified email when it did not before, the same actions run as after a successful email verification using the VerifyEmail API endpoint.

When the authentication process creates an account without a verified email, a verification email is automatically sent like it would with a local user registration.

The authentication process cannot cause an account with an already verified email to lose this status.