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 ¶
- Your application receives requests with an employee subject token in the
Authorizationheader. The application is either: - The API you're consuming has granted access to your application and employees
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/jsonor -
application/x-www-form-urlencoded
The body of the request should contain the following parameters:
| Parameter | Example Value | Description |
|---|---|---|
identity_provider | entra_id | Always entra_id. |
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. |
POST ${NAIS_TOKEN_EXCHANGE_ENDPOINT} HTTP/1.1
Content-Type: application/json
{
"identity_provider": "entra_id",
"target": "api://<cluster>.<namespace>.<other-api-app-name>/.default",
"user_token": "eyJra..."
}POST ${NAIS_TOKEN_EXCHANGE_ENDPOINT} HTTP/1.1
Content-Type: application/x-www-form-urlencoded
identity_provider=entra_id&
target=api://<cluster>.<namespace>.<other-api-app-name>/.default&
user_token=eyJra...{
"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...