Skip to content

Consume internal API on behalf of an employee

This how-to guides you through the steps required to consume an API secured with Entra ID on behalf of an employee. This is also known as the on-behalf-of (OBO) flow.

Prerequisites

Configure your application

Depending on how you communicate with the API you're consuming, configure the appropriate outbound access policies.

Exchange token

Now you can exchange the employee's subject token for a new token, targeting the API that you want to consume.

Send a HTTP POST request to the endpoint found in the NAIS_TOKEN_EXCHANGE_ENDPOINT environment variable. The request must have a Content-Type header set to either:

  • application/json or
  • application/x-www-form-urlencoded

The body of the request should contain the following parameters:

Parameter Example Value Description
identity_provider azuread Always azuread.
target api://<cluster>.<namespace>.<other-api-app-name>/.default The intended audience (target API or recipient) of the new token.
user_token eyJra... The user's access token from the inbound request. Token that should be exchanged.
Token request
POST ${NAIS_TOKEN_EXCHANGE_ENDPOINT} HTTP/1.1
Content-Type: application/json

{
    "identity_provider": "azuread",
    "target": "api://<cluster>.<namespace>.<other-api-app-name>/.default",
    "user_token": "eyJra..."
}
Token request
POST ${NAIS_TOKEN_EXCHANGE_ENDPOINT} HTTP/1.1
Content-Type: application/x-www-form-urlencoded

identity_provider=azuread&
target=api://<cluster>.<namespace>.<other-api-app-name>/.default&
user_token=eyJra...
Successful response
{
    "access_token": "eyJra...",
    "expires_in": 3599,
    "token_type": "Bearer"
}

Your application does not need to validate this token.

Tokens are automatically cached by default

The endpoint will always return a cached token, if available. The endpoint will never return an expired token.

To forcibly get a new token, set the skip_cache property to true in the request. This is only necessary if the token is denied by the target API, for example if permissions have changed since the token was issued.

Consume API

Once you have acquired a new token, you can finally consume the target API by using the token as a Bearer token:

GET /resource HTTP/1.1

Host: api.example.com
Authorization: Bearer eyJraWQ...

📚 Entra ID reference