Skip to content

Latest commit

 

History

History
142 lines (96 loc) · 8.53 KB

working-with-b2c.md

File metadata and controls

142 lines (96 loc) · 8.53 KB
Raw

Working with MSAL.js and Azure AD B2C

⚠️ Before you start here, make sure you understand how to initialize an app object and working with resources and scopes. We also recommend general familiarity with Azure AD B2C. See the B2C documentation for more.

MSAL.js supports authentication with social (Microsoft, Google, Facebook etc.), enterprise (ADFS, Salesforce etc.) and local (stored in the Azure AD B2C directory) identities using Azure AD B2C (B2C for short). When developing B2C apps with MSAL.js, there are a few important details to keep in mind.

Quick Facts

With B2C:

  • Users can authenticate with their social identities.
  • Users can be authorized to access B2C protected resources (but not AAD protected resources).
  • Users cannot obtain tokens for Microsoft APIs (e.g. MS Graph API) using delegated permissions.
  • Applications can obtain tokens for Microsoft APIs using application permissions (user management scenarios).

B2C App Configuration

The following is a B2C app configuration example:

const msalConfig = {
  auth: {
    clientId: "<your-clientID>",
    authority: "https://<your-tenant>.b2clogin.com/<your-tenant>.onmicrosoft.com/<your-policyID>",
    knownAuthorities: ["<your-tenant>.b2clogin.com"] // array of URIs that are known to be valid
  }
}

const apiConfig = {
  b2cScopes: ["https://<your-tenant>.onmicrosoft.com/<your-api>/<your-scope>"],
  webApiUri: "<your-api-uri>" // e.g. "https://fabrikamb2chello.azurewebsites.net/hello"
};

const loginRequest = {
  scopes: [ "openid", "offline_access" ]
}

const tokenRequest = {
  scopes: apiConfig.b2cScopes // e.g. "https://<your-tenant>.onmicrosoft.com/<your-api>/<your-scope>"
}

AAD vs B2C Endpoints

A major difference between Azure AD (AAD for short) vs. B2C tenants are with respect to their endpoints.

An AAD tenant:

  • Contains only AAD endpoints (login.microsoftonline.com/*).
  • Exposes a single token endpoint (login.microsoftonline.com/.../token).
  • AAD endpoints allow you to obtain tokens for:
    • Your applications protected by AAD.
    • Microsoft APIs, such as MS Graph API.

A B2C tenant:

  • Contains AAD and B2C endpoints (login.microsoftonline.com/* and <your-domain>.b2clogin.com/*).
  • Exposes separate token endpoints for each (login.microsoftonline.com/.../token, <your-domain>.b2clogin.com/.../token).
  • B2C endpoints allow you to obtain tokens for:
    • Your applications protected by B2C.

B2C and Delegated Permissions

Delegated permissions specify scope-based access using interactive authorization from the signed-in user. These permissions are presented to the resource (e.g. your web API, MS Graph API etc.) at run-time as scp claims in the client's Access Token.

A user's B2C authentication cannot be used to authorize to AAD protected apps, or Microsoft APIs (which are also protected by AAD). As such, when you use MSAL.js, you cannot use the <your-tenant>.b2clogin.com/.../token endpoint to obtain a token for MS Graph API.

OpenID Connect Permissions

The exception to the rule above comes from a special set of scopes known as OpenID Connect (OIDC) permissions, which includes openid and profile. Another special permission is the offline_access, which gives your app access to a resources on behalf of the user for an extended time (using a Refresh Token). MSAL.js will supply openid, profile and offline_access by default during loginPopup() and loginRedirect() requests.

AAD Authentication against a B2C Tenant

When you use login.microsoftonline.com endpoint without providing any policyID parameters against a B2C tenant, you hit the AAD endpoints of the B2C tenant. Only in this case you can get tokens for MS Graph API resources, using the signed-in user's context.

B2C and Application Permissions

Application permissions specify role-based access using the client application's credentials/identity. These permissions are presented to the resource at run-time as roles claims in the client's Access Token.

User Management Scenarios

The login.microsoftonline.com endpoints can still be used for any behind the scenes, non-interactive work on managing users and attributes, even if they are specific to B2C. When creating an application registration for an app that'll use client credentials grant to manage B2C resources using MS Graph API, you need to select the Graph API scopes that your management app needs to get permission for (see the documentation for more). Things to keep in mind:

  • To obtain application permissions, you'll need perform application authentication (using the client credentials grant).
  • To obtain delegated permissions, you'll need to perform user authentication with an admin account.
  • Management apps are typically registered as audience type 1 or type 2 (see below).

Other Topics

B2C and Account/Audience Types

During application registration, you are prompted to select an audience. The audience type you select indicates what type of authentication that you are targeting for.

Audience Type Description Authentication Type
#1 Accounts in this organizational directory only (single tenant) AAD Authentication
#2 Accounts in any organizational directory (multi-tenant). AAD Authentication
#3 Accounts in any organizational directory or any identity provider B2C Authentication

Acquiring an access token for your own API

There are 2 ways to acquire an access token for your own API:

  1. Request your clientId as a scope:
msal.loginRedirect({
    scopes: ["client_Id"]
});

Read more here

  1. Expose your own custom scope on your app registration and request this scope:
msal.loginRedirect({
    scopes: ["api://clientId/customScope.Read"]
});

B2C and Sign-out Experience

The sign-out clears the user's single sign-on state with Azure AD B2C, but it might not sign the user out of their social identity provider session. If the user selects the same identity provider during a subsequent sign-in, they might re-authenticate without entering their credentials. Here the assumption is that, if a user wants to sign out of the application, it doesn't necessarily mean they want to sign out of their social account (e.g. Facebook) itself.

B2C and Invite Flow

MSAL.js will only process tokens which it originally requested. If your flow requires that you send a user a link they can use to sign up, you will need to ensure that the link points to your app, not the B2C service directly. An example invite flow is as follows:

  1. User clicks link to your app
  2. App calls msal.loginRedirect and includes the id_token_hint in the extraQueryParameters
    msal.loginRedirect({
        scopes: ["example_scope"],
        extraQueryParameters: {'id_token_hint': your_id_token_hint}
    });
  1. App is redirected to B2C service where the user enters credentials/signs up
  2. B2C service redirects back to your app which calls await msal.handleRedirectPromise() to process the response and save the tokens

B2C and iframe usage

Azure AD B2C offers an embedded sign-in experience, which allows rendering a custom login UI in an iframe. Since MSAL prevents redirect in iframes by default, you'll need to set the allowRedirectInIframe configuration option to true in order to make use of this feature. For other considerations when using iframes, please refer to: Using MSAL in iframed apps