Connect an API that uses Microsoft Entra ID

If your API verifies tokens issued by Microsoft Entra ID, Faustine signs in as an application of its own, with the client credentials grant. You register that application in your directory and enter its values in Faustine.

Before you begin

Your API is registered in Entra ID and exposes an application ID URI, such as api://<APP_ID>.
You can register applications and grant admin consent in the directory.

Register a client in Entra ID

In Entra ID, create the following. For the screens, see Register an application and the client credentials flow in the Microsoft documentation.

An app registration for Faustine.
A client secret for it. Copy the secret's value when it is created.
Application permissions (app roles) on your API, granted to the new application with admin consent. The client credentials grant has no user, so delegated permissions do not apply.

Note three values: the directory ID (the value for Tenant ID), the application (client) ID and the client secret.

Set the token endpoint on the API

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 Microsoft Entra ID.
In Tenant ID, enter the directory's GUID or a verified domain, such as contoso.onmicrosoft.com.
In Scopes, enter the .default scope of your API: api://<APP_ID>/.default.
Leave Audience empty and Client secret sent on In the body.
Select Save changes.

The token URL appears under Tenant ID:

https://login.microsoftonline.com/<TENANT>/oauth2/v2.0/token

With the client credentials grant, Entra ID accepts only the .default scope of a resource. The token carries the application permissions you granted.

Add the client to a connection

Value from Entra ID	Field in the connection
Application (client) ID	Client ID
Client secret value	Client secret

Select the Connections tab, then New connection, or select an existing connection.
In Credentials, enter the Client ID and Client secret.
In the Test step, select a read operation and select Test connection.

Reached the endpoint with a 2xx status confirms that Entra ID issued a token and your API accepted it.

Troubleshooting

Symptom	Cause	Fix
`Identity provider refused the client credentials`, with `invalid_client`	The client secret is wrong or expired, or the secret's ID was entered instead of its value.	Create a new secret and enter its value in the connection.
`Identity provider refused the client credentials`, with `invalid_scope`	Scopes is not the `.default` scope of a resource.	Enter `api://<APP_ID>/.default`.
The test reaches the API and it answers `401` or `403`	The token has no `roles` claim your API accepts.	Grant the application permission with admin consent.

Next steps

Connect with an OAuth client: every field of the strategy and how the token is renewed.
Add a connection: the full wizard.
Authentication: token exchange, when your API swaps the Entra ID token for its own.