5.1.2.9. OAuth2 / OpenID Connect (OIDC) based Single Sign-On (SSO)

Instead of entrusting the dashboard server with your users’ SSO credentials (to pass them to an LDAP/Active Directory server), you may prefer to use an OIDC based authentication provider to verify those credentials and forward the authentication to the dashboard.

Login Mask with OIDC enabled

Login Mask with OIDC enabled

Note

OIDC has been supported since 7.8.0, currently with the limitations listed below. Aside from these, we consider the feature stable and safe for daily use. Mixed use of regular password-authenticated users and OIDC-authenticated users is supported.

Once the feature is configured, the Login Mask will show an alternative login option that redirects users to your authentication provider. The label text My OIDC Provider comes from the Provider Name field of the OIDC Provider configuration.

Note that the values for the Provider Name, Issuer Identifier, and Client Identifier fields must be chosen carefully, because they cannot be changed later for security reasons. The Provider Name will also be part of the Redirect URI that you need to configure within your OIDC provider. The URI is derived from the Dashboard URL, including its URL path prefix, and is shown in the Redirect URI field of the configuration mask. With the default path prefix /axivion, it is of the following form:

https://your-dashboard.example.com/axivion/api/oauth2/{providerName}/authenticate
OIDC configuration mask

OIDC configuration mask

This mask can be reached via the Add Configuration button on the Authentication > OIDC page of the settings and guides you through the steps of the OIDC configuration. Note that the Issuer or Known Configuration URL field also accepts the Known Configuration URL, which is defined as <Issuer URL>/.well-known/openid-configuration in the OpenID Connect specification. After you have filled in the initial configuration and pressed the Test Connection button, the dashboard will try to autodetect the remaining configuration options and will allow you to modify them before saving and activating the configuration. These options are explained in the UI itself. Typically, you only need to adjust the Group Claim Name and the Compatibility Mode. The Default compatibility is meant for providers that require manual configuration of claims like name and groups and send refresh tokens out of the box. Switch to profile+offline_access compatibility if your provider prefers these scopes for configuration. The Microsoft Entra, Okta, PingID, and authentik compatibility modes are meant for the respective providers; see the provider-specific hints below. Okta, PingID, and authentik request the same scopes as profile+offline_access; Okta additionally requests the groups scope. The groups claim is essential for being able to assign permissions to authenticated OIDC users.

Caution

OIDC users and groups are associated with a provider configuration, so deleting a provider configuration will also delete the associated users and groups from the Dashboard.

Groups and Permissions Configuration

The Group Claim Name is the name of the user property requested from the OIDC provider that is expected to contain the names of the groups the authenticated user belongs to. You will likely need to tweak the configuration of your OIDC provider to ensure meaningful data is sent, because sending group memberships or roles of a user is not standardized and OpenID Provider (OP) implementations do this differently by default. In general, the dashboard requires a list of simple group or role names, e.g., the information that the authenticated user is a member of the groups developers and team_1. These group names must be configured in the OP to be sent to the dashboard as plain group names rather than internal OP group IDs (while using IDs is also possible, they typically lack intrinsic meaning).

configuring permissions for OIDC groups

OIDC groups with global permissions

In the example, on the Global Permissions page of the dashboard permissions configuration, the OIDC group developers is assigned the Log in permission. On the Project Permissions page, you would then typically assign the permission to view the results of projects owned by Team 1 to the group team_1. OIDC groups are added with the Create federated group button on the permissions pages, which is disabled until you have successfully configured your OpenID Provider. Also be aware that the group names must exactly match the group names provided by the OP (case-sensitive).

It is difficult to know whether the OP is configured properly to send group information. To gain insight into what is being received by the dashboard, you can configure logging to the DEBUG level (requires a restart) and inspect the messages logged when someone tries to log in.

The relevant log messages would look similar to these:

2024-05-17 11:18:51 +02:00 DEBUG: Authenticated and merged OAuth2/OIDC id token using
    issuer 'My OpenID Provider':
com.axivion.dashboard.webservice.oidc.IdToken@5e9f23b4[
  iss=https://oidc.example.com/123/
  sub=2903582309823094
  groups=[8f9c0424-8f80-4b29-9d12-463b28aa42a6, 755981dd-0f48-44d4-9e20-15d8932eb31e]
  groupsClaimName=groups
  expWithSkew=2024-05-17T10:19:50Z
  iat=2024-05-17T09:13:50Z
  authTime=<null>
  cHash=<null>
  atHash=<null>
  preferredUsername=admin@example.com
  uniqueName=<null>
  name=<null>
  email=admin@example.com
  upn=<null>
]
2024-05-17 11:18:51 +02:00 DEBUG: Refreshed OIDC User Info:
    com.axivion.dashboard.webservice.oidc.OIDCUserInfo$UIRelevantInfo@1c2f5a7e[
  groups=[administrators, developers]
  name=<null>
  uniqueName=<null>
  preferredUsername=admin@example.com
  sub=2903582309823094
  email=admin@example.com
  upn=<null>
]

The first message shows the groups contained in the ID token. If the UserInfo endpoint of the OP also returns groups, they replace those in the ID token. The second message shows the resulting group names (in this case, administrators and developers) that can be used to assign permissions.

Logout / End Session Configuration

When you click Logout in the user menu of the navigation bar, the Axivion Dashboard Server also attempts to end the session at the OIDC provider. Once completed, the OP will redirect back to the Axivion Dashboard Server base URL. As all redirect URIs must be registered at the OP beforehand, please add the Axivion Dashboard Server base URL to the list of allowed post logout redirect URIs. If your OIDC provider does not have a separate section for post logout redirect URIs, please use the default Redirect URIs section.

Microsoft Entra / AzureAD specific hints

To properly receive groups from Microsoft Entra, some specific configuration is needed. You can configure Entra’s behavior per application, so there is no risk of affecting other applications.

Note that there may be several ways to configure this. Essentially, one of the claims sent by Entra to the Dashboard upon login must contain a list of the names of the groups to which the current user belongs.

This claim must then be configured via the Group Claim Name option. The screenshot shows how to configure Entra to use the roles claim for this purpose. In the screenshot, the red border highlights the button used to open the right pane, which allows you to include group information in the Token received by the Dashboard.

configuring entra to send group names instead of IDs

Configuring Entra to send group names instead of IDs

By default, the roles checkbox is unchecked. Depending on your Microsoft Entra configuration, groups may be sent as UIDs via the groups claim, which can be difficult to interpret.

We encourage the use of roles, as multiple Entra groups can be mapped to a single role, and roles are sent as plain strings.

To create roles, navigate to the App roles tab and link them to groups and users via Enterprise Applications > Axivion Application > Users and groups.

If you prefer to avoid the roles indirection, an alternative method is to specify the cloud_displayname property in the manifest tab. This replaces group UIDs with names; in this case, the Group Claim Name must remain set to groups. Refer also to Microsoft’s documentation regarding the groups claim.

configuring plain names for Entra groups

Configuring plain names for Entra groups

Currently, you will need to inspect the log files, as documented in the permissions section, to determine what is actually received by the Dashboard when users encounter an InsufficientPermissionException after logging in.

To create API tokens, OIDC (OpenID Connect) must be configured in Microsoft Entra mode. This requires switching the compatibility mode from Default to Microsoft Entra.

setting the entra hint for the axivion dashboard

Let the Axivion Dashboard know that you are using Microsoft Entra

Okta specific hints

Select Okta compatibility. Enable the refresh token grant so the dashboard server can maintain an ongoing session.

general settings

Enable refresh tokens

The option to rotate the refresh token can be safely enabled, as the Axivion Dashboard Server will always use the most recently provided refresh token.

Under Sign-in, configure the OpenID Connect ID Token setting to always send the groups claim. This claim is mandatory for permission management within the Axivion Dashboard Server.

setting the groups claim

Setup sharing groups with the Axivion Dashboard

Note

With Okta compatibility, the Axivion Dashboard Server does not redirect to Okta on logout to end the session there. This is currently a known limitation.

PingID specific hints

Select PingID compatibility. Using PingID as an OpenID Connect provider requires the configuration of additional scopes and claims.

Configuring Scopes

Configuring Scopes

The profile scope provides various name claims used to determine the display name in the Axivion Dashboard Server. The email scope provides the email claim, which is used for the display name when no other name claims are present. In the future, it will be used for email notifications; see limitations. The offline_access scope allows the Axivion Dashboard Server to extend an ongoing session, removing the need for users to re-authenticate every few minutes.

Configuring groups claim

Configuring Claims

The groups claim is mandatory for permission management within the Axivion Dashboard Server.

Configuring logout redirect uri

Configuring Logout Redirect URI

Upon logout, the Axivion Dashboard Server will redirect to PingID to end the session. After the session ends, PingID will redirect back to the Axivion Dashboard Server. For this to work, the Signoff URL in PingID must match the Axivion Dashboard Server base path.

goauthentik specific hints

Select authentik compatibility.

Keycloak specific hints

Select profile+offline_access compatibility. In Keycloak, navigate to Client Scopes, edit the profile scope, and add a predefined mapper groups.

Limitations

As mentioned above, the OIDC integration currently has some limitations.

VCS User Mapping

OIDC users currently cannot be mapped to VCS users. This means that when logged in as an OIDC user, the ME filter will not appear in the issue list, and other users with the View Issue Owners permission will not be able to see issue ownership by dashboard users (only by VCS users).

Email Notifications

OIDC users currently cannot be notified via email about newly added or removed issues.

Custom Named Filters and API Tokens in Dashboard API Python Wrapper

Managing custom named filters and API tokens for OIDC users in the Dashboard API Python wrapper is currently not possible.

User Management

OIDC users are listed as read-only in the user management table. Their group memberships are only known at login time and are not displayed there. Many OIDC user properties (e.g., email address, group memberships) must be provided by the OpenID provider; no additions or overrides can be defined in the Dashboard. Some of these limitations may be permanent.