Connect with an OAuth client

With OAuth client, the gateway requests a token from your identity provider with the OAuth 2.0 client credentials grant and sends it on every call. Use it when your API verifies tokens issued by Microsoft Entra ID, Auth0, Okta, Keycloak, Amazon Cognito or another provider with a token endpoint.

Before you begin

Register a client for Faustine at your identity provider and grant it the scope or audience of your API. Each provider has its own page:

How the gateway gets the token

On the first call through a connection, the gateway sends a form-encoded POST to the token URL with grant_type=client_credentials, the scopes and the audience set on the API, and the connection's client ID and secret. It reads access_token from the response and adds Authorization: Bearer <access_token> to the call.

The gateway keeps the token and renews it 30 seconds before the expires_in the provider returned. When the response has no expires_in, it uses the exp claim of the token. It also requests a new token when a call answers 401.

Set the strategy on the API

To describe the token endpoint:

In the portal, go to APIs and select your API.
Select the Authentication tab, then Edit.
In Sign-in method, select OAuth client.
In Token provider, select your provider and fill in the fields it shows. The token URL appears under the field as you type.
Fill in Client secret sent, Scopes and Audience.
Select Save changes.

Token provider	Fields	Token URL
Microsoft Entra ID	Tenant ID	`https://login.microsoftonline.com/<TENANT>/oauth2/v2.0/token`
Auth0	Domain	`https://<DOMAIN>/oauth/token`
Keycloak	Server URL, Realm	`<SERVER_URL>/realms/<REALM>/protocol/openid-connect/token`
Okta	Domain, Authorization server	`https://<DOMAIN>/oauth2/<SERVER>/v1/token`
Amazon Cognito	User pool domain	`https://<DOMAIN>/oauth2/token`
Custom	Token URL	The URL as you enter it.

Field	Description
Scopes	Space-separated. Sent as `scope`.
Audience	Sent as `audience`. Required for Auth0. Leave it empty when the provider does not use one.
Client secret sent	In the body sends `client_id` and `client_secret` as form fields. HTTP Basic sends them in the `Authorization` header of the token request. Selecting Microsoft Entra ID sets In the body, and selecting Amazon Cognito sets HTTP Basic.

Add the client to a connection

To store the client's credentials for one deployment, add a connection and enter the Client ID and Client secret of the client you registered in the Credentials step.

The test requests a token and then calls the operation, so Reached the endpoint with a 2xx status confirms the client, the scopes and the audience.

Troubleshooting

Symptom	Cause	Fix
`Identity provider refused the client credentials`, with `invalid_client`	The client ID or secret is wrong, or the provider expects the secret the other way.	Correct the values in the connection, or change Client secret sent.
`Identity provider refused the client credentials`, with `invalid_scope`	The client is not granted the scope.	Grant the scope at the provider, or correct Scopes.
`Auth0 needs the API identifier as the audience.`	Audience is empty for an Auth0 token URL.	Enter the identifier of the API as registered in Auth0.
The token request succeeds and calls answer `401`	Your API does not accept the token's audience or scopes.	Compare the token's claims with what your API verifies.

Next steps

Authentication: token exchange, for an API that swaps the provider's token for its own.
Write a custom sign-in script: for a token request the form does not cover.
Add an API to a gateway: serve the API through the connection.