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.

Although the OAuth 2.0 client credentials grant flow is not currently directly supported by the Azure AD B2C authentication service, you can set up client credential flow using Azure AD and the Microsoft identity platform /token endpoint for an application in your Azure AD B2C tenant. An Azure AD B2C tenant shares some functionality with Azure AD enterprise tenants.

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.

  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 AD B2C.
  4. Select App registrations, and then select New registration.
  5. Enter a Name for the application. For example, managementapp1.
  6. Select Accounts in this organizational directory only.
  7. Under Permissions, clear the Grant admin consent to openid and offline_access permissions check box.
  8. Select Register.
  9. Record the Application (client) ID that appears on the application 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. Under Manage, select API permissions.
  2. Under Configured permissions, select Add a permission.
  3. Select the Microsoft APIs tab, then select Microsoft Graph.
  4. Select Application permissions.
  5. Expand the appropriate permission group and select the check box of the permission to grant to your management application. For example:
    • AuditLog > AuditLog.Read.All: For reading the directory's audit logs.
    • Directory > Directory.ReadWrite.All: For user migration or user management scenarios.
    • Policy > Policy.ReadWrite.TrustFramework: For continuous integration/continuous delivery (CI/CD) scenarios. For example, custom policy deployment with Azure Pipelines.
  6. Select Add permissions. As directed, wait a few minutes before proceeding to the next step.
  7. Select Grant admin consent for (your tenant name).
  8. If you are not currently signed-in with Global Administrator account, sign in with an account in your Azure AD B2C tenant that's been assigned at least the Cloud application administrator role and then select Grant admin consent for (your tenant name).
  9. Select Refresh, and then verify that "Granted for ..." appears under Status. It might take a few minutes for the permissions to propagate.

Create client secret

  1. Under Manage, select Certificates & secrets.
  2. Select New client secret.
  3. Enter a description for the client secret in the Description box. For example, clientsecret1.
  4. Under Expires, select a duration for which the secret is valid, and then select Add.
  5. Record the secret'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.