Edit

Share via

Register a Microsoft Graph application

  • Article

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.

Azure AD B2C authentication service directly supports OAuth 2.0 client credentials grant flow (currently in public preview), but you can't use it to manage your Azure AD B2C resources via Microsoft Graph API. However, you can set up client credential flow using Microsoft Entra ID and the Microsoft identity platform /token endpoint for an application in your Azure AD B2C tenant.

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. 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. 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

For your application to access data in Microsoft Graph, grant the registered application the relevant application permissions. The effective permissions of your application are the full level of privileges implied by the permission. For example, to create, read, update, and delete every user in your Azure AD B2C tenant, add the User.ReadWrite.All permission.

Note

The User.ReadWrite.All permission does not include the ability update user account passwords. If your application needs to update user account passwords, grant user administrator role. When granting user administrator role, the User.ReadWrite.All is not required. The user administrator role includes everything needed to manage users.

You can grant your application multiple application permissions. For example, if your application also needs to manage groups in your Azure AD B2C tenant, add the Group.ReadWrite.All permission as well.

App registrations

  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:
    • User > User.ReadWrite.All: For user migration or user management scenarios.
    • Group > Group.ReadWrite.All: For creating groups, read and update group memberships, and delete groups.
    • AuditLog > AuditLog.Read.All: For reading the directory's audit logs.
    • 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. Sign in with an account in your Azure AD B2C tenant that has the Cloud Application Administrator role assigned to it, then select Grant admin consent for (your tenant name).
  9. Select Refresh, then verify that "Granted for ..." appears under Status. It might take a few minutes for the permissions to propagate.

[Optional] Grant user administrator role

If your application or script needs to update users' passwords, you need to assign the User administrator role to your application. The User administrator role has a fixed set of permissions you grant to your application.

To add the User administrator role, follow these 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. Search for and select Azure AD B2C.
  4. Under Manage, select Roles and administrators.
  5. Select the User administrator role.
  6. Select Add assignments.
  7. In the Select text box, enter the name or the ID of the application you registered earlier, for example, managementapp1. When it appears in the search results, select your application.
  8. Select Add. It might take a few minutes to for the permissions to fully propagate.

Create client secret

Your application needs a client secret to prove its identity when requesting a token. To add the client secret, follow these steps:

  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.

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.