Microsoft Entra app registration

One app registration, in your own Microsoft Entra tenant, serves every customer organization. It’s used for Teams single sign-on, Sign in with Microsoft in the browser (MSAL), customer admin consent, and the API’s on-behalf-of access to Microsoft Graph.

In the steps below, app.example.com stands for the host name in your APP_URL.

1. Register the app. In the Microsoft Entra admin center, open App registrations → New registration. Give it a name, and under Supported account types choose Accounts in any organizational directory (Any Microsoft Entra ID tenant – Multitenant). Leave the redirect URI empty for now and register.

   Copy the Application (client) ID: it’s ENTRA_CLIENT_ID.

2. Expose an API.

   • Set the Application ID URI to api://app.example.com/<client id>. This is ENTRA_APP_ID_URI. Teams requires this exact form: the app’s domain followed by the client ID.

   • Add a scope named access_as_user. Allow admins and users to consent, and fill in the display names and descriptions (for example “Use the app as you”).

   • Under Authorized client applications, add these two Microsoft Teams clients and tick the access_as_user scope for each, so Teams can get a token without prompting:

     Client ID	Microsoft Teams client
     1fec8e78-bce4-4aaf-ab1b-5451cc387264	Teams desktop and mobile apps
     5e3ce6c0-2b1f-4285-8d4b-75ee78787346	Teams web client

3. Add redirect URIs under Authentication → Add a platform:

   Platform	Redirect URI	Used for
   Single-page application	https://app.example.com/auth-redirect.html	The MSAL sign-in popup in the browser
   Web	https://app.example.com/api/tenant/microsoft/callback	Returning from customer admin consent

   For local development, add http://localhost:5173/auth-redirect.html (SPA) and http://localhost:5173/api/tenant/microsoft/callback (Web) too, or use a separate development registration.

4. Create a client secret under Certificates & secrets → New client secret. Copy the Value (not the ID): it’s ENTRA_CLIENT_SECRET. Note the expiry date and rotate it before then; Microsoft sign-in and every OneDrive, Teams and mail feature stop working when it expires.

5. Add Microsoft Graph permissions under API permissions → Add a permission → Microsoft Graph → Delegated permissions (see the table below).

6. Configure the API with ENTRA_CLIENT_ID, ENTRA_CLIENT_SECRET and ENTRA_APP_ID_URI, and restart it.

Microsoft Graph permissions

All permissions are delegated: the API acts only as the signed-in user, within what that user can already do. It requests no application permissions.

Permission	Used for
openid, profile, offline_access	Sign-in
User.Read	Signing in and reading the user’s own profile
Files.ReadWrite.All	Browsing, opening and saving files in the user’s OneDrive and in the SharePoint folders of their Teams channels
Team.ReadBasic.All	Listing the teams the user belongs to
Channel.ReadBasic.All	Listing a team’s channels
Mail.Send	Sending signing invitations and reminders from the user’s own mailbox
User.ReadBasic.All	Searching the directory for colleagues (adding users, choosing signers)

When a customer’s administrator chooses Approve as Microsoft 365 admin, Microsoft’s admin-consent page grants all of the permissions configured on the registration (it requests https://graph.microsoft.com/.default). If you add or remove permissions later, customers need to consent again.

Tokens the API accepts

The API validates tokens against Microsoft’s published signing keys, requires the audience to be your Application ID URI or client ID, accepts both v1.0 and v2.0 issuers for the token’s tenant, and requires the access_as_user scope. You don’t need to change accessTokenAcceptedVersion in the app manifest.

Publisher verification

Many organizations only let users consent to multi-tenant apps from verified publishers, and require admin consent otherwise. Consider completing Microsoft’s publisher verification for the registration.

Troubleshooting

Symptom	Likely cause
Microsoft sign-in isn’t configured on this server	ENTRA_CLIENT_ID or ENTRA_CLIENT_SECRET is missing.
Invalid Microsoft token	ENTRA_APP_ID_URI doesn’t match the registration’s Application ID URI, or the token was issued for another app.
Token is missing the access_as_user scope	The scope isn’t named access_as_user, or the client asked for a different scope.
Teams shows a sign-in error	The Teams client IDs aren’t authorized for the scope, or the Teams package was built with a different client ID or resource.
Your organization hasn’t granted this app access to Microsoft 365 yet	The customer hasn’t consented to the Graph permissions. Their owner should use Approve as Microsoft 365 admin.
MSAL popup fails with a redirect URI error	https://<app>/auth-redirect.html isn’t registered as a Single-page application redirect URI.
Admin consent fails with a redirect URI error	https://<app>/api/tenant/microsoft/callback isn’t registered under the Web platform, or APP_URL doesn’t match the public URL.