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:

Visual Studio

• Visual Studio 2022 17.0 or later, with the ASP.NET and web development workload
• .NET 6.0 SDK

Visual Studio Code

• Visual Studio Code
• C# for Visual Studio Code (latest version)
• .NET 6.0 SDK

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. Repeat the steps to create three separate user flows as follows:

• A combined Sign in and sign up user flow, such as susi. This user flow also supports the Forgot your password experience.
• A Profile editing user flow, such as edit_profile.
• A Password reset user flow, such as reset_password.

Azure AD B2C prepends B2C_1_ to the user flow name. For example, susi becomes B2C_1_susi.

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.

To create the web app registration, use the following steps:

1. Sign in to the Azure portal.

2. If you have access to multiple tenants, select the Settings icon in the top menu to switch to your Azure AD B2C tenant from the Directories + subscriptions menu.

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

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

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

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

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

8. Under Manage, select the Authentication, go to Implicit grant and hybrid flows, select the ID tokens (used for implicit and hybrid flows) checkbox.

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.

    

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 App Application (client) 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:44316.

3. Select Sign Up/In.

   

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.

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

• Learn more about the code sample.
• Learn how to Enable authentication in your own web app by using Azure AD B2C.