Skip to main content

How to Register a Single-Page Application in Microsoft Entra ID

· 11 min read
Jagdish Kumawat
Founder @ Dewiride

A browser app that signs people in with Microsoft Entra ID, such as a React or Next.js front end using MSAL, needs an app registration of its own. What makes it a single-page application registration is one setting: the type of its redirect URI. This guide registers one in the Microsoft Entra admin center, then with the Azure CLI.

What Makes a Single-Page App Different​

A single-page app runs in the visitor's browser, where anyone can read its code. It can't keep a secret, so its registration has none. Instead, it signs people in with the authorization code flow with PKCE: each sign-in uses a one-time value the app makes up on the spot, so a sign-in code intercepted on its way back is useless without it. MSAL, Microsoft's sign-in library, does all of this for you.

Two things in the registration make that work:

SettingWhy
Redirect URIThe address Microsoft sends the sign-in response to. Microsoft sends responses only to addresses listed in the registration, and the address must match exactly — including path, protocol and port, as MSAL's documentation puts it
Platform: Single-page applicationLets the browser exchange the sign-in code for tokens. Microsoft's documentation says a SPA redirect URI is what supports the auth code flow with PKCE and cross-origin requests from the browser

The examples on this page register a chat app called Dewiride Service Desk Chat that runs on http://localhost:3000 and receives sign-in responses at /redirect, the redirect bridge page MSAL Browser 5 needs (How to Add the MSAL Redirect Bridge Page to a Next.js App). Use your own app's name and address.

Prerequisites​

  • Permission to register applications in your Microsoft Entra tenant. By default every member of a tenant has it. If your organization has set Users can register applications to No, you need the Application Developer role (Restrict who can create applications).
  • For the Azure CLI route: the Azure CLI signed in to that tenant (az login).

Step 1: Start a New Registration​

  1. Open the Microsoft Entra admin center and sign in with your work account.
  2. If you can reach more than one tenant, select the Settings icon in the top menu and switch to the right one under Directories + subscriptions.
  3. Browse to Entra ID > App registrations and select New registration.

Step 2: Fill In the Form​

FieldValueWhy
NameDewiride Service Desk ChatThe name people see, on Microsoft's consent screen for example
Supported account typesSingle tenant onlyOnly people from your organization can sign in
Redirect URI — platformSingle-page application (SPA)Makes it a single-page app registration
Redirect URI — addresshttp://localhost:3000/redirectWhere your app receives sign-in responses while you develop it

The Register an application form with the name Dewiride Service Desk Chat, Supported account types set to Single tenant only, the Single-page application platform selected with the redirect URI http://localhost:3000/redirect, and the Register button highlighted

http:// is fine for localhost. When the app goes live, add its real address, starting with https://, as another redirect URI of the same registration.

Select Register. On the registration's Overview page, copy two values, as for any registration (How to Register a Web API in Microsoft Entra ID shows the page):

ValueWhere your app uses it
Application (client) IDMSAL's clientId. On this page it's shown as 33333333-…
Directory (tenant) IDMSAL's authority: https://login.microsoftonline.com/<tenant ID>

Neither is a secret: the browser needs both to sign anyone in.

Step 3: Check the Default Permission​

Every registration made in the admin center starts with one permission: Microsoft Graph > User.Read, which lets the app read the signed-in person's profile through Microsoft Graph. Microsoft's registration guide mentions it: Once you register your application, it gets assigned the User.Read permission.

Keep it if your app calls Microsoft Graph for the profile. If it doesn't, remove it, so the app asks for nothing it doesn't use: signing in alone doesn't need it (How to Add an API Permission to an App Registration in Microsoft Entra ID removes it and adds the permission for your own API).

That's the whole registration. There is no client secret to create, and there must never be one in a browser app: Microsoft's documentation says the platform prevents the use of client credentials in all flows in the presence of an Origin header, to ensure that secrets aren't used from within the browser.

Do It with the Azure CLI​

The Azure CLI creates the registration with az ad app create, but has no option for single-page app redirect URIs, so that part goes to Microsoft Graph with az rest. The examples register an app called My Single-Page App. First, create it; the command is the same in every shell:

Terminal
az ad app create --display-name "My Single-Page App" --sign-in-audience AzureADMyOrg --query "{appId:appId, id:id}"
Output
{
"appId": "55555555-5555-5555-5555-555555555555",
"id": "56565656-5656-5656-5656-565656565656"
}

AzureADMyOrg is Single tenant only; appId is the client ID. Keep the client ID in a variable and create the app's service principal, the object the admin center creates for you automatically:

Terminal
SPA_APP_ID=$(az ad app list --display-name "My Single-Page App" --query "[0].appId" --output tsv)
az ad sp create --id $SPA_APP_ID --query "{appId:appId, displayName:displayName, id:id}"
Output
{
"appId": "55555555-5555-5555-5555-555555555555",
"displayName": "My Single-Page App",
"id": "57575757-5757-5757-5757-575757575757"
}

Now add the redirect URI as a single-page application address. The file spa.json holds the list of the app's SPA redirect URIs:

Terminal
cat > spa.json <<'EOF'
{
"spa": {
"redirectUris": ["http://localhost:3000/redirect"]
}
}
EOF
az rest --method PATCH --uri "https://graph.microsoft.com/v1.0/applications(appId='$SPA_APP_ID')" --body @spa.json

az rest prints nothing when the update works. Check where the address landed:

Terminal
az ad app show --id $SPA_APP_ID --query "{spa:spa.redirectUris, web:web.redirectUris, publicClient:publicClient.redirectUris}"
Output
{
"publicClient": [],
"spa": [
"http://localhost:3000/redirect"
],
"web": []
}

A registration has three lists of redirect URIs, one per platform, and the address is in the spa list only. az ad app create has --web-redirect-uris and --public-client-redirect-uris options, but they fill the other two lists, which are for web apps with a server and for desktop and mobile apps.

One difference from the admin center: a registration made with az ad app create starts with no permissions. az ad app permission list --id returned [] for it, where the admin center would have added User.Read.

Common Mistakes​

MistakeWhat happensDo this instead
Choosing the Web platform for a browser appExchanging the sign-in code from the browser fails; Microsoft's documentation shows a CORS error in the consoleChoose Single-page application (SPA)
A redirect URI that differs from the app's by a slash, a port or http/httpsMicrosoft refuses to send the response thereRegister the exact address MSAL's redirectUri resolves to
Creating a client secret for the appA secret in a browser app isn't secret, and the platform refuses client credentials from the browser anywayNever give a single-page app a secret
Keeping User.Read without calling Microsoft GraphThe registration asks for more than the app usesRemove it, or keep it only if the app reads the profile from Graph
Adding the SPA address with --web-redirect-urisIt lands in the web list, not the spa listSet spa.redirectUris with az rest

Troubleshooting​

SymptomLikely causeFix
A CORS error for login.microsoftonline.com/…/token in the browser consoleThe redirect URI is registered under Web, not Single-page applicationRegister it as a single-page application address
Microsoft's sign-in page says the redirect URI doesn't matchThe address your app sends isn't in the SPA list exactlyCompare it character by character with the registration
A consent screen at the first sign-inThe person is asked to agree to the permissions the app requestsExpected once per person; for your own API's scope, the API can pre-authorize the app

FAQ​

Can one registration serve both localhost and production?​

Yes. The SPA list holds several addresses: add the production address next to the localhost one. Many teams use separate registrations per environment instead, so a test app can never sign anyone in to production.

Is the client ID a secret?​

No. It's in every sign-in request your app sends from the browser, and anyone can see it. It identifies the app; it doesn't prove anything.

Does a single-page app need the Microsoft Graph permission to sign people in?​

No. Signing in works with the standard sign-in permissions MSAL asks for itself. Microsoft Graph's permission reference says: You don't need to specify the User.Read permission to return an ID token with the v2.0 endpoint.

Conclusion​

A single-page app's registration is a normal registration with one special setting: its redirect URI is of the Single-page application type. Register it as Single tenant only with your app's exact /redirect address, copy the client and tenant IDs for MSAL, create no secret, and keep User.Read only if the app calls Microsoft Graph. With the Azure CLI, az ad app create and az ad sp create create it, and az rest sets spa.redirectUris.

Additional Resources​