Microsoft Entra setup

Frontdoor signs users in with Microsoft Entra ID through the OAuth 2.0 Authorization Code flow with PKCE, using MSAL. You need an app registration in your tenant.

Step 1: Create an app registration

1. In the Azure portal, go to Microsoft Entra ID > App registrations > New registration.
2. Name: Frontdoor, or any name you prefer.
3. Supported account types:
   • Single tenant: only users from your organization (most common).
   • Multitenant: users from any Microsoft Entra organization.
4. Redirect URI: select Web and enter:
   • production: https://frontdoor.contoso.com/api/auth/microsoft/callback
   • local development: http://localhost:3001/api/auth/microsoft/callback
5. Select Register.

Step 2: Note the identifiers

From the Overview page of the new app registration, copy:

• Application (client) ID → AZURE_CLIENT_ID
• Directory (tenant) ID → AZURE_TENANT_ID

Step 3: Create a client secret

1. Go to Certificates & secrets > Client secrets > New client secret.
2. Add a description (for example "Frontdoor production") and choose an expiration.
3. Copy the Value right away, because it is not shown again → AZURE_CLIENT_SECRET.

Rotate the secret periodically and never commit it to source control.

Step 4: Configure API permissions

Sign-in permissions

1. Go to API permissions > Add a permission > Microsoft Graph > Delegated permissions.
2. Add:
   • openid: sign users in
   • profile: read the user's display name
   • email: read the user's email address
   • User.Read: read the signed-in user's basic profile
3. Select Grant admin consent, or ask a tenant admin to do it.

Group sync and pre-onboarding permissions

To use Entra group sync (ENTRA_GROUP_SYNC=true) or the Sync groups action, also add these Microsoft Graph application permissions and grant admin consent:

Permission	Why
User.Read.All	Read each user's group memberships (/users/{id}/transitiveMemberOf)
GroupMember.Read.All	Read the members of imported groups (/groups/{id}/transitiveMembers)
Group.Read.All	Optional: broader reads of group objects (description, visibility and similar)

Both the sign-in flow and Sync groups call Microsoft Graph with an app-only token. Without these application permissions the group features return 403 errors, even for a global admin.

Pre-onboard users searches the tenant with the same app-only token and needs User.Read.All with admin consent, also when ENTRA_GROUP_SYNC is off.

Profile photos

To let the prewarm utility and the avatar refresh in Customize fetch Microsoft 365 photos for existing users, add the application permission ProfilePhoto.Read.All with admin consent.

Step 5: Set the environment variables

AZURE_CLIENT_ID=00000000-0000-0000-0000-000000000000
AZURE_CLIENT_SECRET=your-client-secret
AZURE_TENANT_ID=00000000-0000-0000-0000-000000000000
AZURE_REDIRECT_URI=https://frontdoor.contoso.com/api/auth/microsoft/callback

See Configuration reference for the other variables.

How group sync works

With ENTRA_GROUP_SYNC=true, at each sign-in Frontdoor:

1. fetches the user's group memberships through /users/{id}/transitiveMemberOf
2. refreshes the tenant-wide group catalog through /groups, at most once every ENTRA_TENANT_REFRESH_MINUTES
3. stores the groups in a discovery cache

Admins then import only the groups they want to use. Because Graph is called app-only, the user's sign-in consent stays on the minimal openid, profile, email and User.Read set. Sync groups uses the same app-only path to refresh the group catalog and every user's memberships at once.

The first time you enable ENTRA_GROUP_SYNC=true, add the application permissions, grant consent, then trigger a fresh sign-in or a Sync groups to fill the cache.

Discovery and import are separate. If you delete imported Entra groups from Frontdoor, they are not recreated on the next sign-in: they must be discovered again by a sign-in or a sync, then imported again. See Groups and access.

Pre-onboarded users are covered by the sync too, so their Entra groups can appear before they sign in.