Edit

Share via

Single-page application: App registration

  • Article

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. If you are using MSAL.js 1.0, we recommend you migrate to MSAL.js 2.0 to take advantage of the authorization code flow with PKCE which is more secure.

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. Go 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:

Keep in mind that MSAL.js 2.0+ supports the authorization code flow with PKCE which is more secure than the implicit grant flow. If you're using MSAL.js 1.0, consider migrating to MSAL.js 2.0 to take advantage of the authorization code flow with PKCE.

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 Cross-Origin Resource Sharing (CORS) in response to browser third party cookie restrictions. The implicit grant flow isn't supported in MSAL.js 2.0+.

  1. In the Microsoft Entra admin center, select the app registration you created 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.

Your SPA is now registered with a redirect URI. By configuring your redirect URI using the Single-page application tile in the Add a platform pane, your application registration supports the authorization code flow with PKCE and CORS.

Redirect URI: MSAL.js 1.0 with implicit flow

Follow these steps to add a redirect URI for a SPA that uses MSAL.js 1.3 or earlier and the implicit grant flow. Applications that use MSAL.js 1.3 or earlier don't support the authorization code flow.

  1. In the Microsoft Entra admin center, select the app registration you created 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.

Your SPA is now registered with a redirect URI. By selecting one or both of ID tokens and Access tokens, your application registration supports the implicit grant flow.

Note about authorization flows

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

SPAs 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 SPAs 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. If you still have SPAs using MSAL.js 1.x, leave the implicit flow enabled (checked).

Next steps

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