Azure Active Directory B2C: Register your application

This Quickstart helps you register an application in a Microsoft Azure Active Directory (Azure AD) B2C tenant in a few minutes. When you're finished, your application is registered for use in the Azure B2C tenant.

Prerequisites

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 from the Azure AD B2C blade in the Azure portal must be managed from the same location. If you edit the 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.

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 the application type you are registering:

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.

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

Limitations

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 our example (com.onmicrosoft.contoso.appname://redirect/path), we use com.onmicrosoft.contoso.appname as 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 B2C application as described above and try to edit it again in the Azure AD B2C features blade on the Azure portal, it becomes a faulted app, and your application is no longer usable with Azure AD B2C. You have 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

Now that you have an application registered with Azure AD B2C, you can complete one of our quick-start tutorials to get up and running.