Single sign-on with OpenID Connect

You can set up the Administration Web Interface to integrate with an OpenID Connect (OIDC) provider, such as Microsoft Entra ID, to use it as an external authentication method for single sign-on (SSO). This allows administrative users to authenticate and sign in to the Administration Web Interface via OIDC.

This topic gives a conceptual overview of the SSO process. For more information about setting up SSO for Administration Web Interface, see Setting up OpenID Connect as single sign-on (SSO) option.

The following main components are involved:

• Administration Web Interface

• OpenID Connect provider

• OneSpan Authentication Server

• Message Delivery Component (MDC)

The single sign-on process with OpenID Connect is as follows:

1. The user opens the Administration Web Interface in a web browser and selects the SSO option.

2. The Administration Web Interface initiates an authorization request to the OIDC provider with a call to the provider’s authorization endpoint.

3. The OIDC provider redirects the user to a web page to enter the user’s credentials on the provider side and to perform any additional authentication.

4. If the authentication is successful, the OIDC provider returns an authentication code and state information to the Administration Web Interface.

5. The Administration Web Interface validates the state information. If valid, it initiates an authentication request to OneSpan Authentication Server with the authentication code (returned by the OIDC provider) and a nonce value (generated by the Administration Web Interface).

6. OneSpan Authentication Server generates an ID token request and submits it to the OIDC provider’s token endpoint (via MDC).

7. The OIDC provider generates and returns an ID token.

8. If the signature key used to sign the ID token has not been previously retrieved and cached by OneSpan Authentication Server yet, it retrieves the respective key from the OIDC provider’s key endpoint (via MDC).

9. OneSpan Authentication Server verifies the signature, the nonce returned by the OIDC provider, and the issuer.

10. If the verification is successful, OneSpan Authentication Server verifies whether a user account for the user (as specified by the user ID claim returned by the OIDC provider) already exists. If no user account exists, OneSpan Authentication Server attempts to create one:

    1. It verifies if dynamic user registration (DUR) is enabled in the effective policy. If not, the SSO process fails.

    2. It verifies if the OIDC provider returned a role claim. If not, it uses the default role defined in the global settings. If neither is defined, the SSO process fails.

    3. It derives the user role template by evaluating the role template pattern and replacing the {role} placeholder. For example, if the role template pattern is ROLE_TEMPLATE_FOR_{role} and the returned role claim is guest, the derived user role template is ROLE_TEMPLATE_FOR_guest. This user role template must already exist as OneSpan Authentication Server user account. If not, the SSO process fails.

    4. It creates a new user account based on the user role template. The new user account uses the same settings as the user role template, except for the following:

       • User ID and domain are determined via user name translation based on the value returned by the OIDC provider.

       • Admin level is the value from the user role template minus 1.

11. OneSpan Authentication Server returns a success response to the Administration Web Interface. The user is signed in and redirected to the Administration Web Interface landing page.