Configure and use an authorization

In this article, you learn how to create an authorization (preview) in API Management and call a GitHub API that requires an authorization token. The authorization code grant type will be used.

Four steps are needed to set up an authorization with the authorization code grant type:

1. Register an application in the identity provider (in this case, GitHub).
2. Configure an authorization in API Management.
3. Authorize with GitHub and configure access policies.
4. Create an API in API Management and configure a policy.

Prerequisites

• A GitHub account is required.
• Complete the following quickstart: Create an Azure API Management instance.
• Enable a managed identity for API Management in the API Management instance.

Step 1: Register an application in GitHub

1. Sign in to GitHub.

2. In your account profile, go to Settings > Developer Settings > OAuth Apps > Register a new application.

   

   1. Enter an Application name and Homepage URL for the application.
   2. Optionally, add an Application description.
   3. In Authorization callback URL (the redirect URL), enter https://authorization-manager.consent.azure-apim.net/redirect/apim/<YOUR-APIM-SERVICENAME>, substituting the API Management service name that is used.

3. Select Register application.

4. In the General page, copy the Client ID, which you'll use in a later step.

5. Select Generate a new client secret. Copy the secret, which won't be displayed again, and which you'll use in a later step.

   

Step 2: Configure an authorization in API Management

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

2. In the left menu, select Authorizations > + Create.

   

3. In the Create authorization window, enter the following settings, and select Create:

   Settings	Value
   Provider name	A name of your choice, such as github-01
   Identity provider	Select GitHub
   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
   Scope	Set the scope to User
   Authorization name	A name of your choice, such as auth-01

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

5. On the Login tab, select Login with GitHub. Before the authorization will work, it needs to be authorized at GitHub.

   

Step 3: Authorize with GitHub and configure access policies

1. Sign in to your GitHub account if you're prompted to do so.

2. Select Authorize so that the application can access the signed-in user’s account.

   

   After authorization, the browser is redirected to API Management and the window is closed. If prompted during redirection, select Allow access. In API Management, select Next.

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

4. Select Managed identity + Add members and then select your subscription.

5. In Managed identity, select API Management service, and then select the API Management instance that is used. Click Select and then Complete.

   

Step 4: Create an API in API Management and configure a policy

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

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

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

   Setting	Value
   Display name	github
   Web service URL	https://api.github.com/users
   API URL suffix	github

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

   Setting	Value
   Display name	getdata
   URL	/data

   

5. In the Inbound processing section, select the (</>) (code editor) icon.

6. Copy the following, and paste in the policy editor. Make sure the provider-id and authorization-id correspond to the names in step 2.3. Select Save.

   <policies>
       <inbound>
           <base />
           <get-authorization-context provider-id="github-01" authorization-id="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>
           <rewrite-uri template="@(context.Request.Url.Query.GetValueOrDefault("username",""))" copy-unmatched-params="false" />
           <set-header name="User-Agent" exists-action="override">
               <value>API Management</value>
           </set-header>
       </inbound>
       <backend>
           <base />
       </backend>
       <outbound>
           <base />
       </outbound>
       <on-error>
           <base />
       </on-error>
   </policies>
   

   The policy to be used consists of four parts.

   • Fetch an authorization token.

   • Create an HTTP header with the fetched authorization token.

   • Create an HTTP header with a User-Agent header (GitHub requirement). Learn more

   • Because the incoming request to API Management will consist of a query parameter called username, add the username to the backend call.

     Note

     The get-authorization-context policy references the authorization provider and authorization that were created earlier. Learn more about how to configure this policy.

     

7. Test the API.

   1. On the Test tab, enter a query parameter with the name username.
   2. As value, enter the username that was used to sign into GitHub, or another valid GitHub username.
   3. Select Send.

   A successful response returns user data from the GitHub API.

Next steps

Learn more about access restriction policies.