Azure AD as Token Issuer

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

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

Azure AD Setup

The first step is to configure an application in AAD 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.

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

Currently Azure AD does not have a UI to expose scopes (or application roles in AAD 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 Azure AD, 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 AAD 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 AAD:

{
    "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 AAD Trust

The last step is to configure PolicyServer to trust and process the AAD access token. This involves configuring the authority and expected values for scope and audience as well as some mappings from the AAD 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"]
                    }
                }
            }
        }
    }
}