PingAccess

Configuring Azure AD as the common token provider when PingAccess is protecting an API application

Configure Microsoft Azure AD to mint access tokens that can be validated locally when PingAccess is protecting an API application.

Before you begin

Make sure that you’ve configured an application in Microsoft Azure AD. If you haven’t, see creating Azure AD Graph API applications.

About this task

If you’re using PingAccess to protect an API application and want to use Azure AD as the common token provider, you must complete this task. Because Microsoft Azure AD doesn’t have an introspection endpoint to validate access tokens remotely, you must use a key from the JSON Web Key Set (JWKS) endpoint to validate access tokens locally. This task prevents Azure AD from adding a nonce value to the access token after it’s been signed because adding the nonce value blocks PingAccess’s ability to validate the access token.

However, if you’re protecting a web application with PingAccess and want to configure Azure AD as the common token provider, see configuring token provider-specific options instead. You don’t need to complete this task when PingAccess is protecting a web application because the userinfo endpoint in Azure AD can use the nonce value that Azure AD inserts into the access token and validate the access token remotely.

To configure Azure AD to mint an access token that can be validated locally:

Steps

  1. In your Azure AD environment, create a scope for the API application that you want to protect:

    1. On the Overview page of your Azure AD application, go to the Essentials section and copy the Application (client) ID.

    2. Go to Manage → Expose an API and in the Scopes section, click Add a scope.

      Use the following format to create the scope for your API application:

      api://Application (client) ID/scope name

      Make sure to paste in the Application (client) ID that you copied in step 1a.

      This scope is what prevents Azure AD from minting an access token with a nonce value that’s only usable by the userinfo endpoint.

  2. In the PingAccess administrative console, set up Azure AD as a common token provider:

    1. Go to Settings → System → Token Provider and select Common Token Provider.

    2. Fill out the OpenID Connect tab according to the configuring PingAccess to use Azure AD as the token provider and configuring token provider-specific options procedures.

    3. Fill out the OAuth Authorization tab according to the configuring OAuth authorization servers procedure.

      Troubleshooting:

      If you’ve configured a remote token access validator on your PingAccess application and try to remove the Introspection Endpoint or save without configuring it on the OAuth Authorization Server tab, you get the following error message:

      Introspection endpoint is required as there are applications that use remote token validation.

      Remove the remote access token validator before filling out your configuration on the OAuth Authorization Server tab.

  3. In your PingAccess application, set up a JWKS endpoint validator to perform local validation in Azure AD:

    1. Go to Applications → Applications, click the Expand icon to view more details about the API application that you want to protect, then click the pencil icon ().

    2. In the Application Type section, click Create below the Access Validation list.

      Do not select the remote access token validator, Token Provider, in the Access Validation list. You must instead set up a local access token validator.

      If you try to use a remote access token validator on your PingAccess API application without first configuring the introspection endpoint on the OAuth Authorization Server tab of the Token Provider page, you get the following error message:

      Cannot use remote validation as authorization server does not have an Introspection endpoint.

    3. In the Name field, enter a name for the token validator.

    4. In the Type list, select JSON Web Key Set (JWKS) Endpoint.

    5. In your Azure AD application, go to the Endpoints tab on the Overview page and copy the full URL of the OIDC metadata document endpoint.

    6. Open the OpenID Connect (OIDC) metadata document URL in a new tab and copy the value of the jwks_uri property beginning after the https://login.microsoft.online.com segment.

      Example:

      Directory (tenant) ID/discovery/v2.0/keys

    7. In PingAccess, return to the New Access Token Validator page and paste the jwks_uri value that you copied into the Path field.

    8. Click Save.

  4. Add the scope that you set up in Azure AD to your PingAccess web session:

    1. In your Azure AD application, go to Manage → Expose an API and in the Scopes section, copy the full path of the scope that you set up in step 1b.

      In PingAccess, go to Access → Web Sessions, click the Expand icon to view more details about the web session associated with your API application, then click the pencil icon ().

    2. Click Show Advanced Settings, then in the Scopes field, paste the full path of the scope that you copied in step 4a.

    3. Click Save.

Result

You now have an access token that PingAccess can validate and have finished configuring your PingAccess application, web session, and access token validator to use Azure AD as the common token provider.