Manage Azure AD B2C with Microsoft Graph

Microsoft Graph allows you to manage many of the resources within your Azure AD B2C tenant, including customer user accounts and custom policies. By writing scripts or applications that call the Microsoft Graph API, you can automate tenant management tasks like:

  • Migrate an existing user store to an Azure AD B2C tenant
  • Deploy custom policies with an Azure Pipeline in Azure DevOps, and manage custom policy keys
  • Host user registration on your own page, and create user accounts in your Azure AD B2C directory behind the scenes
  • Automate application registration
  • Obtain audit logs

The following sections help you prepare for using the Microsoft Graph API to automate the management of resources in your Azure AD B2C directory.

Microsoft Graph API interaction modes

There are two modes of communication you can use when working with the Microsoft Graph API to manage resources in your Azure AD B2C tenant:

  • Interactive - Appropriate for run-once tasks, you use an administrator account in the B2C tenant to perform the management tasks. This mode requires an administrator to sign in using their credentials before calling the Microsoft Graph API.

  • Automated - For scheduled or continuously run tasks, this method uses a service account that you configure with the permissions required to perform management tasks. You create the "service account" in Azure AD B2C by registering an application that your applications and scripts use for authenticating using its Application (Client) ID and the OAuth 2.0 client credentials grant. In this case, the application acts as itself to call the Microsoft Graph API, not the administrator user as in the previously described interactive method.

You enable the Automated interaction scenario by creating an application registration shown in the following sections.

Register management application

Before your scripts and applications can interact with the Microsoft Graph API to manage Azure AD B2C resources, you need to create an application registration in your Azure AD B2C tenant that grants the required API permissions.

To register an application in your Azure AD B2C tenant, you can use the current Applications experience, or our new unified App registrations (Preview) experience. Learn more about the new experience.

  1. Sign in to the Azure portal.
  2. Select the Directory + Subscription icon in the portal toolbar, and then select the directory that contains your Azure AD B2C tenant.
  3. In the Azure portal, search for and select Azure Active Directory.
  4. Under Manage, select App registrations (Legacy).
  5. Select New application registration.
  6. Enter a name for the application. For example, managementapp1.
  7. For Application type, select Web app / API.
  8. Enter any valid URL in Sign-on URL. For example, https://localhost. The endpoint doesn't need to be reachable, but must be a valid URL.
  9. Select Create.
  10. Record the Application ID that appears on the Registered app overview page. You use this value in a later step.

Grant API access

Next, grant the registered application permissions to manipulate tenant resources through calls to the Microsoft Graph API.

  1. On the Registered app overview page, select Settings.
  2. Under API Access, select Required permissions.
  3. Select Microsoft Graph.
  4. Under Application Permissions, select the check box of the permission to grant to your management application. For example:
    • Read all audit log data: Select this permission for reading the directory's audit logs.
    • Read and write directory data: Select this permission for user migration or user management scenarios.
    • Read and write your organization's trust framework policies: Select this permission for continuous integration/continuous delivery (CI/CD) scenarios. For example, custom policy deployment with Azure Pipelines.
  5. Select Save.
  6. Select Grant permissions, and then select Yes. It might take a few minutes to for the permissions to fully propagate.

Create client secret

  1. Under API ACCESS, select Keys.
  2. Enter a description for the key in the Key description box. For example, clientsecret1.
  3. Select a validity Duration and then select Save.
  4. Record the key's VALUE. You use this value for configuration in a later step.

You now have an application that has permission to create, read, update, and delete users in your Azure AD B2C tenant. Continue to the next section to add password update permissions.

Enable user delete and password update

The Read and write directory data permission does NOT include the ability delete users or update user account passwords.

If your application or script needs to delete users or update their passwords, assign the User administrator role to your application:

  1. Sign in to the Azure portal and use the Directory + Subscription filter to switch to your Azure AD B2C tenant.
  2. Search for and select Azure AD B2C.
  3. Under Manage, select Roles and administrators.
  4. Select the User administrator role.
  5. Select Add assignments.
  6. In the Select text box, enter the name of the application you registered earlier, for example, managementapp1. Select your application when it appears in the search results.
  7. Select Add. It might take a few minutes to for the permissions to fully propagate.

Next steps

Now that you've registered your management application and have granted it the required permissions, your applications and services (for example, Azure Pipelines) can use its credentials and permissions to interact with the Microsoft Graph API.