Configure authentication in a sample web app by using Azure AD B2C

This article uses a sample ASP.NET web application to illustrate how to add Azure Active Directory B2C (Azure AD B2C) authentication to your web applications.

Important

The sample ASP.NET web app that's referenced in this article can't be used to call a REST API, because it returns an ID token and not an access token. For a web app that can call a REST API, see Secure a Web API that's built with ASP.NET Core by using Azure AD B2C.

Overview

OpenID Connect (OIDC) is an authentication protocol that's built on OAuth 2.0. You can use OIDC to securely sign users in to an application. This web app sample uses Microsoft Identity Web. Microsoft Identity Web is a set of ASP.NET Core libraries that simplify adding authentication and authorization support to web apps.

The sign-in flow involves the following steps:

  1. Users go to the web app and select Sign-in.
  2. The app initiates an authentication request and redirects users to Azure AD B2C.
  3. Users sign up or sign in and reset the password. Alternatively, they can sign in with a social account.
  4. After users sign in successfully, Azure AD B2C returns an ID token to the app.
  5. The app validates the ID token, reads the claims, and returns a secure page to users.

When the ID token is expired or the app session is invalidated, the app initiates a new authentication request and redirects users to Azure AD B2C. If the Azure AD B2C SSO session is active, Azure AD B2C issues an access token without prompting users to sign in again. If the Azure AD B2C session expires or becomes invalid, users are prompted to sign in again.

Sign-out

The sign-out flow involves the following steps:

  1. From the app, users sign out.
  2. The app clears its session objects, and the authentication library clears its token cache.
  3. The app takes users to the Azure AD B2C sign-out endpoint to terminate the Azure AD B2C session.
  4. Users are redirected back to the app.

Prerequisites

A computer that's running either of the following:

Step 1: Configure your user flow

When users try to sign in to your app, the app starts an authentication request to the authorization endpoint via a user flow. The user flow defines and controls the user experience. After users complete the user flow, Azure AD B2C generates a token and then redirects users back to your application.

If you haven't done so already, create a user flow or a custom policy.

Step 2: Register a web application

To enable your application to sign in with Azure AD B2C, register your app in the Azure AD B2C directory. Registering your app establishes a trust relationship between the app and Azure AD B2C.

During app registration, you'll specify the redirect URI. The redirect URI is the endpoint to which users are redirected by Azure AD B2C after they authenticate with Azure AD B2C. The app registration process generates an application ID, also known as the client ID, that uniquely identifies your app. After your app is registered, Azure AD B2C uses both the application ID and the redirect URI to create authentication requests.

Step 2.1: Register the app

To create the web app registration, do the following:

  1. Sign in to the Azure portal.

  2. Make sure you're using the directory that contains your Azure AD B2C tenant. Select the Directories + subscriptions icon in the portal toolbar.

  3. On the Portal settings | Directories + subscriptions page, find your Azure AD B2C directory in the Directory name list, and then select Switch.

  4. In the Azure portal, search for and select Azure AD B2C.

  5. Select App registrations, and then select New registration.

  6. Under Name, enter a name for the application (for example, webapp1).

  7. Under Supported account types, select Accounts in any identity provider or organizational directory (for authenticating users with user flows).

  8. Under Redirect URI, select Web and then, in the URL box, enter https://localhost:5001/signin-oidc.

  9. Under Permissions, select the Grant admin consent to openid and offline access permissions checkbox.

  10. Select Register.

  11. Select Overview.

  12. Record the Application (client) ID for later use, when you configure the web application.

    Screenshot of the web app Overview page for recording your web application ID.

Step 2.2: Enable ID tokens

For web apps that request an ID token directly from Azure AD B2C, enable the implicit grant flow in the app registration.

  1. On the left pane, under Manage, select Authentication.
  2. Under Implicit grant, select the ID tokens (used for implicit and hybrid flows) and Access tokens (used for implicit flows) checkboxes.
  3. Select Save.

Step 3: Get the web app sample

Download the zip file, or clone the sample web application from GitHub.

git clone https://github.com/Azure-Samples/active-directory-aspnetcore-webapp-openidconnect-v2

Extract the sample file to a folder where the total length of the path is 260 or fewer characters.

Step 4: Configure the sample web app

In the sample folder, under the 1-WebApp-OIDC/1-5-B2C/ folder, open the WebApp-OpenIDConnect-DotNet.csproj project with Visual Studio or Visual Studio Code.

Under the project root folder, open the appsettings.json file. This file contains information about your Azure AD B2C identity provider. Update the following app settings properties:

Section Key Value
AzureAdB2C Instance The first part of your Azure AD B2C tenant name (for example, https://contoso.b2clogin.com).
AzureAdB2C Domain Your Azure AD B2C tenant full tenant name (for example, contoso.onmicrosoft.com).
AzureAdB2C ClientId The web API application ID from step 2.
AzureAdB2C SignUpSignInPolicyId The user flows or custom policy you created in step 1.

Your final configuration file should look like the following JSON:

"AzureAdB2C": {
  "Instance": "https://contoso.b2clogin.com",
  "Domain": "contoso.onmicrosoft.com",
  "ClientId": "<web-app-application-id>",
  "SignedOutCallbackPath": "/signout/<your-sign-up-in-policy>",
  "SignUpSignInPolicyId": "<your-sign-up-in-policy>"
}

Step 5: Run the sample web app

  1. Build and run the project.

  2. Go to https://localhost:5001.

  3. Select Sign Up/In.

    Screenshot of the "Sign Up/In" button on the project Welcome page.

  4. Complete the sign-up or sign-in process.

After successful authentication, you'll see your display name on the navigation bar. To view the claims that the Azure AD B2C token returns to your app, select Claims.

Screenshot of the web app token claims.

Deploy your application

In a production application, the app registration redirect URI is ordinarily a publicly accessible endpoint where your app is running, such as https://contoso.com/signin-oidc.

You can add and modify redirect URIs in your registered applications at any time. The following restrictions apply to redirect URIs:

  • The reply URL must begin with the scheme https.
  • The reply URL is case-sensitive. Its case must match the case of the URL path of your running application.

Next steps