Create an authorization with the Microsoft Graph API

This article guides you through the steps required to create an authorization with the Microsoft Graph API within Azure API Management. The authorization code grant type is used in this example.

You learn how to:

• Create an Azure AD application
• Create and configure an authorization in API Management
• Configure an access policy
• Create a Microsoft Graph API in API Management and configure a policy
• Test your Microsoft Graph API in API Management

Prerequisites

• Access to an Azure Active Directory (Azure AD) tenant where you have permissions to create an app registration and to grant admin consent for the app's permissions. Learn more

  If you want to create your own developer tenant, you can sign up for the Microsoft 365 Developer Program.

• A running API Management instance. If you need to, create an Azure API Management instance.

• Enable a system-assigned managed identity for API Management in the API Management instance.

Step 1: Create an Azure AD application

Create an Azure AD application for the API and give it the appropriate permissions for the requests that you want to call.

1. Sign in to the Azure portal with an account with sufficient permissions in the tenant.

2. Under Azure Services, search for Azure Active Directory.

3. On the left menu, select App registrations, and then select + New registration.

4. On the Register an application page, enter your application registration settings:

   1. In Name, enter a meaningful name that will be displayed to users of the app, such as MicrosoftGraphAuth.
   2. In Supported account types, select an option that suits your scenario, for example, Accounts in this organizational directory only (Single tenant).
   3. Set the Redirect URI to Web, and enter https://authorization-manager.consent.azure-apim.net/redirect/apim/<YOUR-APIM-SERVICENAME>, substituting the name of the API Management service where you will configure the authorization provider.
   4. Select Register.

5. On the left menu, select API permissions, and then select + Add a permission.

   1. Select Microsoft Graph, and then select Delegated permissions.

      Note

      Make sure the permission User.Read with the type Delegated has already been added.

   2. Type Team, expand the Team options, and then select Team.ReadBasic.All. Select Add permissions.
   3. Next, select Grant admin consent for Default Directory. The status of the permissions will change to Granted for Default Directory.

6. On the left menu, select Overview. On the Overview page, find the Application (client) ID value and record it for use in Step 2.

7. On the left menu, select Certificates & secrets, and then select + New client secret.
   

   1. Enter a Description.
   2. Select any option for Expires.
   3. Select Add.
   4. Copy the client secret's Value before leaving the page. You will need it in Step 2.

Step 2: Configure an authorization in API Management

1. Sign into the portal and go to your API Management instance.

2. On the left menu, select Authorizations, and then select + Create.
   

3. On the Create authorization page, enter the following settings, and select Create:

   Settings	Value
   Provider name	A name of your choice, such as aad-01
   Identity provider	Select Azure Active Directory v1
   Grant type	Select Authorization code
   Client id	Paste the value you copied earlier from the app registration
   Client secret	Paste the value you copied earlier from the app registration
   Resource URL	https://graph.microsoft.com
   Tenant ID	Optional for Azure AD identity provider. Default is Common
   Scopes	Optional for Azure AD identity provider. Automatically configured from AD app's API permissions.
   Authorization name	A name of your choice, such as aad-auth-01

4. After the authorization provider and authorization are created, select Next.

Step 3: Authorize with Azure AD and configure an access policy

1. On the Login tab, select Login with Azure Active Directory. Before the authorization will work, it needs to be authorized.

2. When prompted, sign in to your organizational account.

3. On the confirmation page, select Allow access.

4. After successful authorization, the browser is redirected to API Management and the window is closed. In API Management, select Next.

5. On the Access policy page, create an access policy so that API Management has access to use the authorization. Ensure that a managed identity is configured for API Management. Learn more about managed identities in API Management.

6. For this example, select API Management service <service name>, and then click "+ Add members". You should see your access policy in the Members table below.

   

7. Select Complete.

Note

If you update your Microsoft Graph permissions after this step, you will have to repeat Steps 2 and 3.

Step 4: Create a Microsoft Graph API in API Management and configure a policy

1. Sign into the portal and go to your API Management instance.

2. On the left menu, select APIs > + Add API.

3. Select HTTP and enter the following settings. Then select Create.

   Setting	Value
   Display name	msgraph
   Web service URL	https://graph.microsoft.com/v1.0
   API URL suffix	msgraph

4. Navigate to the newly created API and select Add Operation. Enter the following settings and select Save.

   Setting	Value
   Display name	getprofile
   URL for GET	/me

5. Follow the preceding steps to add another operation with the following settings.

   Setting	Value
   Display name	getJoinedTeams
   URL for GET	/me/joinedTeams

6. Select All operations. In the Inbound processing section, select the (</>) (code editor) icon.

7. Copy the following, and paste in the policy editor. Make sure the provider-id and authorization-id correspond to the values you configured in Step 2. Select Save.

   <policies>
       <inbound>
           <base />
           <get-authorization-context provider-id="aad-01" authorization-id="aad-auth-01" context-variable-name="auth-context" identity-type="managed" ignore-error="false" />
          <set-header name="authorization" exists-action="override">
              <value>@("Bearer " + ((Authorization)context.Variables.GetValueOrDefault("auth-context"))?.AccessToken)</value>
          </set-header>
       </inbound>
       <backend>
           <base />
       </backend>
       <outbound>
           <base />
       </outbound>
       <on-error>
           <base />
       </on-error>
   </policies>
   

The preceding policy definition consists of two parts:

• The get-authorization-context policy fetches an authorization token by referencing the authorization provider and authorization that were created earlier.
• The set-header policy creates an HTTP header with the fetched authorization token.

Step 5: Test the API

1. On the Test tab, select one operation that you configured.

2. Select Send.

   

   A successful response returns user data from the Microsoft Graph.

Next steps

• Learn more about access restriction policies
• Learn more about scopes and permissions in Azure AD.