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¶
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¶
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).
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¶
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¶
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.
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.
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.
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¶
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 Claims¶
The groups claim is mandatory for permission management within the Axivion Dashboard Server.
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
MEfilter will not appear in the issue list, and other users with theView Issue Ownerspermission 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.