> Markdown version of https://docs.laavat.io/getting-started/onboarding/aad/ from the LAAVAT PKI and Signing Platform documentation. All pages: https://docs.laavat.io/llms.txt

# Microsoft Entra ID Integration

Microsoft Entra ID is used to authorize users based on group membership.

The authorization is done based on the object identifier in the authorization token.

LAAVAT PKI and Signing Platform uses OAuth2 Implicit grant flow to fetch data from the MS Graph API. Client credentials are used first to get an access token, and then user data is fetched using the access token.

Once application credentials and [initial groups](https://docs.laavat.io/getting-started/onboarding/initialgroups/) are created, follow instructions on the chapter: [Identity Provider Setup](https://docs.laavat.io/getting-started/onboarding/identity-provider-setup/) to complete the onboarding.

## Creating application

In the Microsoft Entra ID tab of the Azure portal, create a new app registration.

Name the new application appropriately. In the `'Who can use this application or access this API?'` dialog, select the single-tenant option. (Only accounts from this organization can access the application). Redirect URL is added in the form of `https://app.laavat.io/<CustomerName>/api/v1/auth/callback` and `https://app.laavat.io/<CustomerName>/gui/callbackgui`. When adding the Redirect URL, the platform type must be **Web**.

After creating the app, note the `Application (client) ID` and `Directory (tenant) ID` — you will enter both in the [setup wizard](https://docs.laavat.io/getting-started/onboarding/identity-provider-setup/). See [setup wizard fields](https://docs.laavat.io/appendixes/registration/) for the full list of values it asks for.

In the Certificates & Secrets tab of the application, create a new `client secret`.
Choose a preferred expiration time for the secret.

## Token configuration

The OID (Object Identifier) claim is included in the token by default and is used as the user identifier. No additional token configuration is required.

> **Warning: Deprecation Notice**
> UPN (User Principal Name) was previously used as the user identifier and required adding an optional claim. UPN is now deprecated and replaced by OID (Object Identifier).
>
> **Migration steps:**
>
> 1. First, migrate all clients to use `oid:<object-id>` instead of `upn:<email>` (see [Client Guide](https://docs.laavat.io/usage/clientguide/clients/))
> 2. Only after all clients have been migrated, remove the UPN optional claim from your Entra ID application token configuration
>
> **Do not remove the UPN optional claim before completing step 1** — existing clients that still reference UPN will stop working.

## API permissions

The application uses Microsoft Graph API endpoint `user: checkMemberGroups` [See documentation](https://learn.microsoft.com/en-us/graph/api/directoryobject-checkmembergroups?view=graph-rest-1.0&tabs=http).

To access this API, the application needs the following API permissions. All permissions must be `application` type (not delegated). An admin consent is required to activate these permissions.

- `User.Read.All`
- `GroupMember.Read.All`
- `Directory.Read.All`

## Expose an API

To enable the Azure CLI to request tokens for the service, an API must be exposed.

Click a Add a scope link.
Click save and continue to accept proposed Application ID URI.

On Add a scope blade type in following information.
You can modify names and description fields, if needed.

Scope name: Signing.Access
Who can consent: Admins only
Admin consent display name: Signing
Admin consent description: Access to LAAVAT PKI and Signing Platform

Click Add scope-button.

In the `Authorized Client Applications`, add Azure cli which has an ID of `04b07795-8ddb-461a-bbee-02f9e1bf7b46` for this scope.

## Support of cloud-native Service Principals

Cloud-native Service Principals can be used to access the LAAVAT PKI and Signing Platform API without interactive login.
One use case is creating a Service Principal for a Jenkins instance.