Runtime API Security

The Runtime API does not allow anonymous access and is secured by an OAuth access token issued either by the Management UI host or an external token service.

Requesting a Token

The Management UI host provides an OAuth 2 (RFC 6749) compliant token endpoint to request access tokens. You create a client ID and secret for Runtime API clients when you set up the configuration for the Management UI host. Your client application will use this shared client ID and secret to request access tokens for the Runtime API.

To request an access token, send a POST to the /connect/token (or your token service of choice) endpoint:

POST /connect/token HTTP/1.1
Host: policyserver.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&
client_id=<insert id here>&
client_secret=<insert secret here>

Note

Technically, this is using so-called OAuth 2.0 Client Credentials Grant. Client ID and secret can be sent either via an authorization header or the POST body. For more information, see the OAuth 2.0 spec

The response will contain an access token and a lifetime:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
    "access_token":"2YotnFZFEjr1zCsicMWpAA",
    "expires_in":3600,
}

Using your own Token Service

If you already have an OAuth 2.0 authorization server, you can use this server to issue access tokens for PolicyServer. By default, the tokens you issue must contain an audience of value policyserver.runtime for the runtime API and/or policyserver.management for the management API. But these values can be changed in configuration.

You establish trust with your authorization server by setting the base-address in configuration, e.g. in JSON:

"PolicyServer": {

    "host": {
        "identity": {

            "externalTokenIssuer": {

                "authority": "https://demo.identityserver.io"

                "runtimeApiAudience" : "policyserver.runtime",
                "managementApiAudience" : "policyserver.management"
            }
        }
    }
}

Note

The authorization server must support OpenID Connect discovery.

Warning

If the access token contains a sub claim the call will be unauthorized if the caller is not an authorized PolicyServer administrator.

Using the Access Token

To use the access token, send it on the authorization header to the Runtime API:

POST /runtime/policy/EmergencyRoom
Host: policyserver.example.com
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA

...