Azure Entra ID as Token Issuer

Instead of using the PolicyServer built-in OAuth token issuer for the management and runtime API, you can use Entra ID.

This involves setting up resources representing PolicyServer in Entra ID, registering clients to access those resources and establishing trust in PolicyServer.

Entra ID Setup

The first step is to configure an application in Azure Entra ID that exposes endpoints that represent the PolicyServer runtime and/or management API. Please see the Microsoft documentation Quickstart: Configure an application to expose a web API for reference.

Note

The guidance below is for a quick reference, however, be advised that Microsoft documentation may change time to time and require adjustment to the configurations below. If the configuration does not work and you need further support, please contact us.

Use the Entra ID UI to assign an Application ID URI, e.g. api://policyserver.

Currently Entra ID does not have a UI to expose scopes (or application roles in Entra ID language) for machine clients. You need to modify the application manifest manually.

In the application manifest, create the following sections for the respective APIs:

"appRoles": [
    {
        "allowedMemberTypes": [
            "Application"
        ],
        "description": "PolicyServer Management API",
        "displayName": "PolicyServer Management API",
        "id": "<insert GUID here>",
        "isEnabled": true,
        "lang": null,
        "origin": "Application",
        "value": "policyserver.management"
    },
    {
        "allowedMemberTypes": [
            "Application"
        ],
        "description": "PolicyServer Runtime API",
        "displayName": "PolicyServer Runtime API",
        "id": "<insert GUID here>",
        "isEnabled": true,
        "lang": null,
        "origin": "Application",
        "value": "policyserver.runtime"
    }
]

Also make sure to set the accessTokenAcceptedVersion to 2.

Registering a Client

In Microsoft terms, you are adding a “daemon app” to Entra ID, see Daemon app that calls web APIs - app registration for reference. Once the client is created, set a client secret (see here).

The last step is to assign API permissions. Use the API Permissions setting in the Entra ID portal, select the API app that you just created, and select the app roles you want to grant access to. Make sure you select the Application permissions category.

Since there is no interactive appproval process for machine to machine communications, you need to pre-approve the resource access in the portal. Use the Grant admin consent feature for that.

After following those steps, you should have a client, that is authorized to access one or more PolicyServer endpoints via granting the relevant application role.

Setting up the Client

This example is using the PolicyServer runtime client, the same settings exist for the management client as well.

The following configuration snippet shows the required settings for the PolicyServer client to request a token via Entra ID:

{
    "PolicyServerRuntimeClient": {
        "PolicyServerUrl": "https://your_policy_server",
        "BasePolicy": "EmergencyRoom",

        "TokenClient": {
            "Authority": "https://login.microsoftonline.com/<your_tenant_id>/v2.0",

            "ClientId": "<your_client_id>",
            "ClientSecret": "<your_client_secret>",
            "Scope": "api://policyserver/.default",

            "AuthenticationMethod": "SharedSecret",

            "DiscoveryPolicy":
            {
                "ValidateIssuerName": false,
                "ValidateEndpoints": false
            }
        }
    }
}

Setting up Entra ID Trust

The last step is to configure PolicyServer to trust and process the Entra ID access token. This involves configuring the authority and expected values for scope and audience as well as some mappings from the Entra ID claim types, to the standard claim types:

{
    "PolicyServer": {
        "host": {
            "identity": {
                "externalTokenIssuer": {

                    "authority": "https://login.microsoftonline.com/<your_tenant_id>/v2.0",

                    "RuntimeApiAudience": "<your_api_app_id>",
                    "RuntimeApiScope": "policyserver.runtime",

                    "ManagementApiAudience": "<your_api_app_id>",
                    "ManagementApiScope": "policyserver.management",

                    "claimMappings": {
                        "ClientIdClaimTypes": [ "azp" ],
                        "SubClaimTypes": [ "azp" ],
                        "ScopeClaimTypes": [ "roles"]
                    }
                }
            }
        }
    }
}