Tutorial: Register an application to enable sign-up and sign-in using Azure Active Directory B2C

This tutorial helps you create a Microsoft Azure Active Directory (Azure AD) B2C tenant and register an application with it in just a few minutes.

In this article, you learn how to:

  • Create an Azure AD B2C tenant
  • Link your tenant to your subscription
  • Register your application

If you don't have an Azure subscription, create a free account before you begin.

Log in to Azure

Log in to the Azure portal.

Create an Azure AD B2C tenant

B2C features can't be enabled in your existing tenants. You need to create an Azure AD B2C tenant.

Click the Create a resource button. In the Search the marketplace field, enter Azure Active Directory B2C.

Add button highlighted and the text Azure Active Directory B2C in the search the marketplace field

In the results list, select Azure Active Directory B2C.

Azure Active Directory B2C selected in the results list

Details about Azure Active Directory B2C are shown. To begin configuring your new Azure Active Directory B2C tenant, click the Create button.

Select Create a new Azure AD B2C Tenant. The settings specified in the following table use the company name Contoso as an example. You will need to provide your own organization name and a unique tenant name when creating your tenant.

Azure AD B2C create tenant with sample text in the available fields

Setting Sample value Description
Organization name Contoso Name of the organization.
Initial domain name ContosoB2CTenant Domain name for the B2C tenant. By default, the initial domain name includes .onmicrosoft.com. If you are creating a test tenant, choose a non-production name such as ContosoB2CTesting.
Country or region United States Choose the country or region for the directory. The directory will be created in this location and cannot be changed later.

Click the Create button to create your tenant. Creating the tenant may take a few minutes. You are alerted in your notifications when it is complete.

Congratulations, you have created an Azure Active Directory B2C tenant. You are a Global Administrator of the tenant. You can add other Global Administrators as required. To switch to your new tenant, click the manage your new tenant link.

Manage your new tenant link

Important

If you are planning to use a B2C tenant for a production app, read the article on production-scale vs. preview B2C tenants. There are known issues when you delete an existing B2C tenant and re-create it with the same domain name. You need to create a B2C tenant with a different domain name.

You need to link your Azure AD B2C tenant to your Azure subscription to enable all B2C functionality and pay for usage charges. To learn more, read this article. If you don't link your Azure AD B2C tenant to your Azure subscription, some functionality is blocked and, you see a warning message ("No Subscription linked to this B2C tenant or the Subscription needs your attention.") in the B2C settings. It is important that you take this step before you ship your apps into production.

To switch to your Azure AD B2C tenant, select the B2C directory in the top-right corner of the portal.

Switch to your Azure AD B2C tenant

Select Azure AD B2C from the services list in the Azure portal.

Select B2C service

If Azure AD B2C isn't in the services list, expand All services in the navigation bar at the top-left side of the portal. Search for Azure AD B2C and select Azure AD B2C in the result list. You can also select the star icon to add Azure AD B2C it your favorite services list.

Searching for Azure AD B2C service

You can also access the blade by entering Azure AD B2C in Search resources at the top of the portal. In the results list, select Azure AD B2C to access the B2C settings blade.

Register your application

To build an application that accepts consumer sign-up and sign-in, you first need to register the application with an Azure Active Directory B2C tenant. Get your own tenant by using the steps outlined in Create an Azure AD B2C tenant.

Applications created in the Azure portal must be managed from the same location. If you edit the Azure AD B2C applications using PowerShell or another portal, they become unsupported and do not work with Azure AD B2C. See details in the faulted apps section.

This article uses examples that will help you get started with our samples. You can learn more about these samples in the subsequent articles.

Log in to the Azure portal as the Global Administrator of the B2C tenant.

To switch to your Azure AD B2C tenant, select the B2C directory in the top-right corner of the portal.

Switch to your Azure AD B2C tenant

Select Azure AD B2C from the services list in the Azure portal.

Select B2C service

Choose next steps based on your application type

Register a web app

In the B2C settings, click Applications and then click + Add.

+ Add button in applications

To register your web application, use the settings specified in the table.

Example registration settings for new web app

Setting Sample value Description
Name Contoso B2C app Enter a Name for the application that describes your application to consumers.
Include web app / web API Yes Select Yes for a web application.
Allow implicit flow Yes Select Yes if your application uses OpenID Connect sign-in
Reply URL https://localhost:44316 Reply URLs are endpoints where Azure AD B2C returns any tokens that your application requests. Enter a proper Reply URL. In this example, your app is local and listening on port 44316.

Click Create to register your application.

Your newly registered application is displayed in the applications list for the B2C tenant. Select your web app from the list. The web application's property pane is displayed.

Web app properties

Make note of the globally unique Application Client ID. You use the ID in your application's code.

Create a web app client secret

If your web application calls a web API secured by Azure AD B2C, perform these steps:

  1. Create an application secret by going to the Keys blade and clicking the Generate Key button. Make note of the App key value. You use the value as the application secret in your application's code.
  2. Click API Access, click Add, and select your web API and scopes (permissions).

Note

An Application Secret is an important security credential, and should be secured appropriately.

Jump to next steps

Register a web API

In the B2C settings, click Applications and then click + Add.

+ Add button in applications

To register your web API, use the settings specified in the table.

Example registration settings for new web api

Setting Sample value Description
Name Contoso B2C API Enter a Name for the application that describes your API to consumers.
Include web app / web API Yes Select Yes for a web API.
Allow implicit flow Yes Select Yes if your application uses OpenID Connect sign-in
Reply URL https://localhost:44316/ Reply URLs are endpoints where Azure AD B2C returns any tokens that your application requests. Enter a proper Reply URL. In this example, your web API is local and listening on port 44316.
App ID URI api The App ID URI is the identifier used for your web API. The full identifier URI including the domain is generated for you.

Click Create to register your application.

Your newly registered application is displayed in the applications list for the B2C tenant. Select your web API from the list. The API's property pane is displayed.

Web API properties

Make note of the globally unique Application Client ID. You use the ID in your application's code.

Click Published scopes to add more scopes as necessary. By default, the "user_impersonation" scope is defined. The user_impersonation scope gives other applications the ability to access this api on behalf of the signed-in user. If you wish, the user_impersonation scope can be removed.

Jump to next steps

Register a mobile or native app

In the B2C settings, click Applications and then click + Add.

+ Add button in applications

To register your mobile or native application, use the settings specified in the table.

Example registration settings for new mobile or native application

Setting Sample value Description
Name Contoso B2C app Enter a Name for the application that describes your application to consumers.
Native client Yes Select Yes for a mobile or native application.
Custom Redirect URI com.onmicrosoft.contoso.appname://redirect/path Enter a redirect URI with a custom scheme. Make sure you choose a good redirect URI and do not include special characters such as underscores.

Click Create to register your application.

Your newly registered application is displayed in the applications list for the B2C tenant. Select your mobile or native app from the list. The application's property pane is displayed.

Application properties

Make note of the globally unique Application Client ID. You use the ID in your application's code.

If your native application calls a web API secured by Azure AD B2C, perform these steps:

  1. Create an application secret by going to the Keys blade and clicking the Generate Key button. Make note of the App key value. You use the value as the application secret in your application's code.
  2. Click API Access, click Add, and select your web API and scopes (permissions).

Note

An Application Secret is an important security credential, and should be secured appropriately.

Jump to next steps

Choosing a web app or api reply URL

Currently, apps that are registered with Azure AD B2C are restricted to a limited set of reply URL values. The reply URL for web apps and services must begin with the scheme https, and all reply URL values must share a single DNS domain. For example, you cannot register a web app that has one of these reply URLs:

https://login-east.contoso.com

https://login-west.contoso.com

The registration system compares the whole DNS name of the existing reply URL to the DNS name of the reply URL that you are adding. The request to add the DNS name fails if either of the following conditions is true:

  • The whole DNS name of the new reply URL does not match the DNS name of the existing reply URL.
  • The whole DNS name of the new reply URL is not a subdomain of the existing reply URL.

For example, if the app has this reply URL:

https://login.contoso.com

You can add to it, like this:

https://login.contoso.com/new

In this case, the DNS name matches exactly. Or, you can do this:

https://new.login.contoso.com

In this case, you're referring to a DNS subdomain of login.contoso.com. If you want to have an app that has login-east.contoso.com and login-west.contoso.com as reply URLs, you must add those reply URLs in this order:

https://contoso.com

https://login-east.contoso.com

https://login-west.contoso.com

You can add the latter two because they are subdomains of the first reply URL, contoso.com.

Choosing a native app redirect URI

There are two important considerations when choosing a redirect URI for mobile/native applications:

  • Unique: The scheme of the redirect URI should be unique for every application. In the example (com.onmicrosoft.contoso.appname://redirect/path), com.onmicrosoft.contoso.appname is the scheme. We recommend following this pattern. If two applications share the same scheme, the user sees a "choose app" dialog. If the user makes an incorrect choice, the login fails.
  • Complete: Redirect URI must have a scheme and a path. The path must contain at least one forward slash after the domain (for example, //contoso/ works and //contoso fails).

Ensure there are no special characters like underscores in the redirect uri.

Faulted apps

B2C applications should NOT be edited:

If you edit the Azure AD B2C application as described and try to edit it again in Azure AD B2C features on the Azure portal, it becomes a faulted app, and your application is no longer usable with Azure AD B2C. You need to delete the application and create it again.

To delete the app, go to the Application Registration Portal and delete the application there. In order for the application to be visible, you need to be the owner of the application (and not just an admin of the tenant).

Next steps

In this article, you learned how to:

  • Create an Azure AD B2C tenant
  • Link your tenant to your subscription
  • Register your application