Configure OneSpan User Websites as an external authentication method for Microsoft Entra ID

  • Updated on Nov 7, 2025
  • Published on Jul 7, 2025
  • 7 minute(s) read
Prev Next

You can set up OneSpan User Websites as proxy to use OneSpan Authentication Server as an external authentication method for identity management platforms that support OpenID Connect (OIDC), such as Microsoft Entra ID. This allows users to select DIGIPASS authenticators as an additional authentication method to meet multi-factor authentication requirements.

Microsoft Entra ID supports external authentication methods on top of OpenID Connect (OIDC), an authentication protocol based on the OAuth 2.0 framework. In this context, Microsoft Entra ID is the so-called relying party, and OneSpan Authentication Server (via OneSpan User Websites) is a so-called OpenID provider.

Note that OneSpan User Websites does not support multi-tenancy when used as external authentication method for Microsoft Entra ID.

Before you begin

Ensure you have the following:

  • You have deployed and successfully set up OneSpan User Websites with the OpenID Connect web application (see Installation).

  • A Microsoft Entra ID setup with at least a P1 subscription option

  • A Microsoft Entra ID administrative service account, i.e., with at least the Global Administrator or Privileged Role Administrator role.

Set up for Microsoft Entra ID

Setting up OneSpan User Websites as an external authentication method for Microsoft Entra ID includes the following tasks:

At the time of writing, Microsoft Entra ID is still marked as Preview. Functionality, availability, and user experience are likely to change in future updates without prior notice and may affect references to UI elements used in this guide.

Task 1: Set up the OpenID Connect endpoints

As OneSpan User Websites acts as an OpenID provider, it needs to provide the following three endpoints:

  • OIDC discovery endpoint. This endpoint is used by the relying party to retrieve the OIDC configuration and provider metadata.

    Default value: https://userwebsites_address/oidc/.well-known/openid-configuration

  • OIDC authorization endpoint. This is the endpoint users are redirected to by the relying party to perform the additional authentication.

    Default value: https://userwebsites_address/oidc/web

  • OIDC public certificates endpoint. This endpoint is used by the relying party to retrieve the public keys required to verify signatures issued by your instance. The OneSpan User Websites web application automatically generates new keys and the respective certificates on each service start and periodically generates new ones after a specified key expiration time, by default, 1 hour.

    Default value: https://userwebsites_address/oidc/keys

If you deploy OneSpan User Websites from the provided installation packages, these endpoints are set up by default. userwebsites_address is determined by the setup. All endpoints must be publicly reachable via the internet. If you need to adapt this, you can change the configuration manually.

The OIDC discovery endpoint returns a JSON-formatted OIDC metadata document. Basically, it needs to contain at least the following:

{
  "authorization_endpoint": "https://<userwebsites_address>:<userwebsites_port>/oidc/web",
  "issuer": "https://<userwebsites_address>/oidc",
  "jwks_uri": "https://<userwebsites_address>/keys",
  "id_token_signing_alg_values_supported": [
    "RS256"
  ],
  "response_types_supported": [
    "id_token"
  ],
  "subject_types_supported": [
    "public"
  ]
}

For more information, refer to OpenID Provider Metadata.

Task 2: Register OneSpan User Websites as an application in Microsoft Entra ID

  1. Sign in to the Microsoft Entra ID administration center, at https://entra.microsoft.com/.

  2. Navigate to Identity > Applications > App registrations.

  3. Click New registration.

  4. Configure the new application:

    1. Name: A display name for the application.

    2. Supported account types: Accounts in this organizational directory only

    3. Platform: Web

    4. Redirect URI: The authorization endpoint URL provided by your OneSpan User Websites instance (see Set up the OpenID Connect endpoints).

    5. Click Register.

      When the application was successfully registered in Microsoft Entra ID, the Overview page will display the registration summary. Note the value for Application (client) ID, as you will need it in the subsequent tasks.

Task 3: Create an external authentication method in Microsoft Entra ID

  1. Sign in to the Microsoft Entra ID administration center, at https://entra.microsoft.com/.

  2. Navigate to Protection > Authentication methods.

  3. Click Add external method (Preview).

  4. Configure the authentication method:

    1. Name: A descriptive display name that is shown to end users when they need to select the authentication method. Note that you cannot change this name afterward and that it needs to be unique for all external authentication methods in your Microsoft Entra ID tenant.

    2. Client ID: A unique client ID to identify the external authentication method in your Microsoft Entra ID tenant, for example, an UUID.

    3. Discovery Endpoint: The OIDC discovery endpoint URL provided by your OneSpan User Websites instance (see Set up the OpenID Connect endpoints).

    4. App ID: The application (client) ID that was generated during application registration.

    5. Click Request Permission and consent.

    6. Set Enable to On.

    7. Click Save.

Task 4: Create a policy in Microsoft Entra ID

  1. Sign in to the Microsoft Entra ID administration center, at https://entra.microsoft.com/.

  2. Navigate to Protection > Conditional Access > Policies.

  3. Click New policy.

  4. Configure the new policy:

    1. Name: A descriptive display name for the policy, for example, OneSpan MFA.

    2. Users: Add the users or user groups for which you want to require multi-factor authentication via OneSpan User Websites.

      We recommend to not assign this policy to all users (including tenant administrators) to avoid blocking administrative access inadvertently.

    3. Target resources: Select the resources and apps that you want to protect.

    4. Grant: Enable Grant access and select Require multifactor authentication.

Task 5: Configure the external authentication method in OneSpan User Websites

Open the OneSpan User Websites OIDC configuration file, i.e. webapps_folder\oidc\WEB-INF\classes\oidc.conf, where webapps_folder is the web application folder of your web server. If you deployed OneSpan User Websites from the provided installation packages, this is usually %ProgramFiles%\OneSpan\User Websites\tomcat\webapps.

Configure the following settings:

# The OIDC primary and backup servers. Only the names "primary" and "backup" are allowed.
com.onespan.userwebsites.oidc.SOAP.Servers.primary.URL = <primary_oas_instance>
com.onespan.userwebsites.oidc.SOAP.Servers.backup.URL = <backup_oas_instance>

# Metadata configuration
com.onespan.userwebsites.oidc.issuer = <oidc_discovery_endpoint>
com.onespan.userwebsites.oidc.auth.endpoint = <oidc_authorization_endpoint>
com.onespan.userwebsites.oidc.keys.endpoint = <oidc_keys_endpoint>

# Keys and token expiration
com.onespan.userwebsites.oidc.keys.expirationTime = 604800
com.onespan.userwebsites.oidc.keys.expirationTimeLeeway = 3600
com.onespan.userwebsites.oidc.token.expirationTime = 300

# Identity provider (IdP) configuration
com.onespan.userwebsites.oidc.idp.app.clientId = <app_id>
com.onespan.userwebsites.oidc.idp.eam.clientId = <client_id>
com.onespan.userwebsites.oidc.idp.issuer = <idp_issuer>
com.onespan.userwebsites.oidc.idp.keys.endpoint = https://login.microsoftonline.com/organizations/discovery/v2.0/keys
com.onespan.userwebsites.oidc.idp.tenantId = <entra_tenant_id>
com.onespan.userwebsites.oidc.idp.userIdClaim = preferred_username

Replace the following:

  • primary_oas_instance. The IP address including the SOAP port of the main OneSpan Authentication Server instance in URL format, e.g., https://10.2.2.15:8888. Any value specified in the global OneSpan User Webseites configuration file admintool.properties (set using the OneSpan Web Configuration Tool) takes precedence over the value specified in this file.

  • backup_oas_instance. The IP address including the SOAP port of the backup OneSpan Authentication Server instance in URL format, e.g.. https://10.2.2.16:8888. Any value specified in the global OneSpan User Webseites configuration file admintool.properties (set using the OneSpan Web Configuration Tool) takes precedence over the value specified in this file.

  • oidc_discovery_endpoint. The URL of the OpenID Connect discovery endpoint of your OneSpan User Websites instance, e.g., https://10.2.2.17/oidc. This has to be the same value as set for Discovery Endpoint when you created the external authentication method in Microsoft Entra ID (see Create an external authentication method in Microsoft EntraID), as well as set in the OIDC metadata (see Set up the OpenID Connect endpoints). It must be publicly reachable from the internet. Microsoft Entra ID uses this endpoint to retrieve the OpenID Connect configuration.

  • oidc_keys_endpoint. The URL of the OpenID Connect public key endpoint of your OneSpan User Websites instance, e.g., https://10.2.2.17/oidc/keys. This has to be the same value as set in the OIDC metadata (see Set up the OpenID Connect endpoints). It must be publicly reachable from the internet. Microsoft Entra ID uses this endpoint to retrieve the public keys required to verify signatures issued by your instance.

  • oidc_authorization_endpoint. The URL of the authorization endpoint of your OneSpan User Websites instance, e.g., https://10.2.2.17:9443/oidc/web. This has to be the same value as set for Reply URI when you registered the app in Microsoft Entra ID (see Register OneSpan User Websites as an application in Microsoft EntraID), as well as set in the OIDC metadata (see Set up the OpenID Connect endpoints). It must be publicly reachable from the internet. Microsoft Entra ID redirects the users to this endpoint to perform the multi-factor authentication.

  • client_id. The client ID that you set when creating the external authentication method in Microsoft Entra ID (see Create an external authentication method in Microsoft EntraID).

  • app_id. The application (client) ID that was generated when you registered the app in Microsoft Entra ID (see Register OneSpan User Websites as an application in Microsoft EntraID).

  • idp_issuer. The URL of the Microsoft Entra ID issuer endpoint, i.e., https://login.microsoftonline.com/entra_tenant_id/v2.0.

  • entra_tenant_id. The tenant Id in Microsoft Entra ID.

Additional configuration settings:

  • com.onespan.userwebsites.oidc.idp.keys.endpoint specifies the URL of the Microsoft Entra ID key endpoint. By default, this is set to https://login.microsoftonline.com/organizations/discovery/v2.0/keys.

  • com.onespan.userwebsites.oidc.idp.userIdClaim specifies the payload claim in the ID token sent by Microsoft Entra ID that OneSpan User Websites should use as the user Id when sending the authentication request to OneSpan Authentication Server. By default, this is set to preferred_username, which in Microsoft Entra ID can be configured as an email address, phone number, or a generic username without a specified format.

  • com.onespan.userwebsites.oidc.keys.expirationTime specifies the time span in seconds after which the OneSpan User Websites web application should automatically generate new keys and the respective certificates. Note that new keys are always generated when the OneSpan User Websites service is restarted. By default, this is set to 604800 (1 week).

  • com.onespan.userwebsites.oidc.keys.expirationTimeLeeway specifies the key leeway time, that is an overlap time with the old key to allow for minor time shifts. By default, this is set to 3600 (1 hour).

  • com.onespan.userwebsites.oidc.token.expirationTime specifies how long in seconds an OpenID Connect token is considered as valid. By default, this is set to 300 (5 minutes).