Single-page application: App registration

To register a single-page application (SPA) in the Microsoft identity platform, complete the following steps. The registration steps differ between MSAL.js 1.0, which supports the implicit grant flow, and MSAL.js 2.0, which supports the authorization code flow with PKCE.

Create the app registration

Tip

Steps in this article might vary slightly based on the portal you start from.

For both MSAL.js 1.0- and 2.0-based applications, start by completing the following steps to create the initial app registration.

  1. Sign in to the Microsoft Entra admin center.
  2. If you have access to multiple tenants, use the Settings icon in the top menu to switch to the tenant in which you want to register the application from the Directories + subscriptions menu.
  3. Browse to Identity > Applications > App registrations, select New registration.
  4. Enter a Name for your application. Users of your app might see this name, and you can change it later.
  5. Choose the Supported account types for the application. Do NOT enter a Redirect URI. For a description of the different account types, see the Register an application.
  6. Select Register to create the app registration.

Next, configure the app registration with a Redirect URI to specify where the Microsoft identity platform should redirect the client along with any security tokens. Use the steps appropriate for the version of MSAL.js you're using in your application:

Redirect URI: MSAL.js 2.0 with auth code flow

Follow these steps to add a redirect URI for an app that uses MSAL.js 2.0 or later. MSAL.js 2.0+ supports the authorization code flow with PKCE and CORS in response to browser third party cookie restrictions. The implicit grant flow is not supported in MSAL.js 2.0+.

  1. In the Microsoft Entra admin center, select the app registration you created earlier in Create the app registration.
  2. Under Manage, select Authentication > Add a platform.
  3. Under Web applications, select the Single-page application tile.
  4. Under Redirect URIs, enter a redirect URI. Do NOT select either checkbox under Implicit grant and hybrid flows.
  5. Select Configure to finish adding the redirect URI.

You've now completed the registration of your single-page application (SPA) and configured a redirect URI to which the client will be redirected and any security tokens will be sent. By configuring your redirect URI using the Single-page application tile in the Add a platform pane, your application registration is configured to support the authorization code flow with PKCE and CORS.

Follow the tutorial for further guidance.

Redirect URI: MSAL.js 1.0 with implicit flow

Follow these steps to add a redirect URI for a single-page app that uses MSAL.js 1.3 or earlier and the implicit grant flow. Applications that use MSAL.js 1.3 or earlier do not support the auth code flow.

  1. In the Microsoft Entra admin center, select the app registration you created earlier in Create the app registration.
  2. Under Manage, select Authentication > Add a platform.
  3. Under Web applications, select Single-page application tile.
  4. Under Redirect URIs, enter a redirect URI.
  5. Enable the Implicit grant and hybrid flows:
    • If your application signs in users, select ID tokens.
    • If your application also needs to call a protected web API, select Access tokens. For more information about these token types, see ID tokens and Access tokens.
  6. Select Configure to finish adding the redirect URI.

You've now completed the registration of your single-page application (SPA) and configured a redirect URI to which the client will be redirected and any security tokens will be sent. By selecting one or both of ID tokens and Access tokens, you've enabled the implicit grant flow.

Note about authorization flows

By default, an app registration created by using single-page application platform configuration enables the authorization code flow. To take advantage of this flow, your application must use MSAL.js 2.0 or later.

As mentioned previously, single-page applications using MSAL.js 1.3 are restricted to the implicit grant flow. Current OAuth 2.0 best practices recommend using the authorization code flow rather than the implicit flow for SPAs. Having limited-lifetime refresh tokens also helps your application adapt to modern browser cookie privacy limitations, like Safari ITP.

When all your production single-page applications represented by an app registration are using MSAL.js 2.0 and the authorization code flow, uncheck the implicit grant settings on the app registration's Authentication pane in the Microsoft Entra admin center. Applications using MSAL.js 1.x and the implicit flow can continue to function, however, if you leave the implicit flow enabled (checked).

Next steps

Configure your app's code to use the app registration you created in the previous steps: App's code configuration.