Merge pull request #228428 from MicrosoftDocs/release-ga-apim-authorizations

[APIM] Authorizations GA release content

Author: huypub

.openpublishing.redirection.api-management.json

@@ -149,6 +149,16 @@
         "source_path_from_root": "/articles/api-management/validation-policies.md",
         "redirect_url": "/azure/api-management/api-management-policies#validation-policies",
         "redirect_document_id": false
+    },
+    {
+        "source_path_from_root": "/articles/api-management/authorizations-how-to.md",
+        "redirect_url": "/azure/api-management/authorizations-how-to-github",
+        "redirect_document_id": false
+    },
+    {
+        "source_path_from_root": "/articles/api-management/authorizations-reference.md",
+        "redirect_url": "/azure/api-management/authorizations-configure-common-providers",
+        "redirect_document_id": false
     }
   ]
 }

articles/api-management/TOC.yml

@@ -83,8 +83,11 @@
               href: ./security-controls-policy.md
             - name: Security baseline
               href: /security/benchmark/azure/baselines/api-management-security-baseline?toc=/azure/api-management/&bc=/azure/api-management/breadcrumb/toc.json
-            - name: Authentication and authorization
+            - name: Authentication and authorization options
               href: authentication-authorization-overview.md
+      - name: API authorizations
+        href: authorizations-overview.md
+        displayName: OAuth
       - name: Observability
         href: observability.md
         displayName: monitoring
@@ -289,12 +292,16 @@
             - name: Mitigate OWASP API threats
               href: mitigate-owasp-api-threats.md
               displayName: OWASP top 10, vulnerability, vulnerabilities
-          - name: Manage API authorizations
+          - name: Configure API authorizations for OAuth 2.0 backends
             items:
-            - name: Authorizations overview
-              href: authorizations-overview.md
-            - name: Configure and use authorization
-              href: authorizations-how-to.md
+            - name: Configure common authorization providers
+              href: authorizations-configure-common-providers.md
+            - name: Configure and use authorization - Azure AD
+              href: authorizations-how-to-azure-ad.md
+            - name: Configure and use authorization - GitHub
+              href: authorizations-how-to-github.md
+            - name: Configure multiple authorization connections
+              href: configure-authorization-connection.md
           - name: Set up backend authentication
             items:
             - name: Mutual certificate authentication
@@ -530,8 +537,6 @@
               href: xml-to-json-policy.md
             - name: xsl-transform
               href: xsl-transform-policy.md
-      - name: Authorizations - identity providers
-        href: authorizations-reference.md
       - name: Azure Policy built-ins
         displayName: samples, policies, definitions
         href: ./policy-reference.md

articles/api-management/api-management-gateways-overview.md

@@ -106,7 +106,7 @@ Managed and self-hosted gateways support all available [policies](api-management
 | Policy | Managed (Dedicated)  | Managed (Consumption) | Self-hosted<sup>1</sup>  |
 | --- | ----- | ----- | ---------- |
 | [Dapr integration](api-management-policies.md#dapr-integration-policies) |  ❌ | ❌ | ✔️ |
-| [Get authorization context](get-authorization-context-policy.md) |  ✔️ |  ❌ | ❌ |
+| [Get authorization context](get-authorization-context-policy.md) |  ✔️ |  ✔️ | ❌ |
 | [Quota and rate limit](api-management-policies.md#access-restriction-policies) |  ✔️ |  ✔️<sup>2</sup> | ✔️<sup>3</sup>
 | [Set GraphQL resolver](set-graphql-resolver-policy.md) |  ✔️ |  ❌ | ❌ |
 

articles/api-management/authentication-authorization-overview.md

@@ -85,9 +85,9 @@ There are different reasons for wanting to do this. For example:
 
 ### Token management by API Management
 
-API Management also supports acquisition and secure storage of OAuth 2.0 tokens for certain downstream services using the [authorizations](authorizations-overview.md) (preview) feature, including through use of custom policies and caching.
+API Management also supports acquisition and secure storage of OAuth 2.0 tokens for certain downstream services using the [authorizations](authorizations-overview.md) feature, including through use of custom policies and caching.
 
-With authorizations, API Management manages the tokens for access to OAuth 2.0 backends, simplifying the development of client apps that access APIs.
+With authorizations, API Management manages the tokens for access to OAuth 2.0 backends, allowing you to delegate authentication to your API Management instance to simplify access by client apps to a given backend service or SaaS platform.
 
 ### Other options
 

articles/api-management/authorizations-configure-common-providers.md

@@ -0,0 +1,80 @@
+---
+title: Configure authorization providers - Azure API Management | Microsoft Docs
+description: Learn how to configure common identity providers for authorizations in Azure API Management. Example providers are Azure Active Directory and a generic OAuth 2.0 provider. An authorization manages authorization tokens to an OAuth 2.0 backend service. 
+services: api-management
+author: dlepow
+ms.service: api-management
+ms.topic: how-to
+ms.date: 02/07/2023
+ms.author: danlep
+---
+
+# Configure identity providers for API authorizations
+
+In this article, you learn about configuring identity providers for [authorizations](authorizations-overview.md) in your API Management instance. Settings for the following common providers are shown:
+
+* Azure AD provider
+* Generic OAuth 2.0 provider
+
+You add identity provider settings when configuring an authorization in your API Management instance. For a step-by-step example of configuring an Azure AD provider and authorization, see:
+
+* [Create an authorization with the Microsoft Graph API](authorizations-how-to-azure-ad.md)
+
+## Prerequisites
+
+To configure any of the supported providers in API Management, first configure an OAuth 2.0 app in the identity provider that will be used to authorize API access. For configuration details, see the provider's developer documentation.
+
+* If you're creating an authorization that uses the authorization code grant type, configure a **Redirect URL** (sometimes called Authorization Callback URL or a similar name) in the app. For the value, enter `https://authorization-manager.consent.azure-apim.net/redirect/apim/<YOUR-APIM-SERVICENAME>`.
+
+* Depending on your scenario, configure app settings such as scopes (API permissions).
+    
+* Minimally, retrieve the following app credentials that will be configured in API Management: the app's **client id** and **client secret**.
+
+* Depending on the provider and your scenario, you might need to retrieve other settings such as authorization endpoint URLs or scopes.
+
+## Azure AD provider
+
+Authorizations support the Azure AD identity provider, which is the identity service in Microsoft Azure that provides identity management and access control capabilities. It allows users to securely sign in using industry-standard protocols.
+
+* **Supported grant types**: authorization code, client credentials
+
+> [!NOTE]
+>  Currently, the Azure AD authorization provider supports only the Azure AD v1.0 endpoints.
+ 
+
+### Azure AD provider settings
+    
+[!INCLUDE [api-management-authorization-azure-ad-provider](../../includes/api-management-authorization-azure-ad-provider.md)]
+
+
+## Generic OAuth 2.0 providers
+
+Authorizations support two generic providers:
+* Generic OAuth 2.0
+* Generic OAuth 2.0 with PKCE 
+
+A generic provider allows you to use your own OAuth 2.0 identity provider based on your specific needs. 
+
+> [!NOTE]
+> We recommend using the generic OAuth 2.0 with PKCE provider for improved security if your identity provider supports it. [Learn more](https://oauth.net/2/pkce/)
+
+* **Supported grant types**: authorization code, client credentials
+
+### Generic authorization provider settings
+
+[!INCLUDE [api-management-authorization-generic-provider](../../includes/api-management-authorization-generic-provider.md)]
+
+## Other identity providers
+
+API Management supports several providers for popular SaaS offerings, such as GitHub. You can select from a list of these providers in the Azure portal when you create an authorization.
+
+:::image type="content" source="media/authorizations-configure-common-providers/saas-providers.png" alt-text="Screenshot of identity providers listed in the portal.":::
+
+**Supported grant types**: authorization code, client credentials (depends on provider)
+
+Required settings for these providers differ from provider to provider but are similar to those for the [generic OAuth 2.0 providers](#generic-oauth-20-providers). Consult the developer documentation for each provider.
+
+## Next steps
+
+* Learn more about [authorizations](authorizations-overview.md) in API Management.
+* Create an authorization for [Azure AD](authorizations-how-to-azure-ad.md) or [GitHub](authorizations-how-to-github.md).

articles/api-management/authorizations-how-to-azure-ad.md

@@ -0,0 +1,168 @@
+---
+title: Create authorization with Microsoft Graph API - Azure API Management | Microsoft Docs
+description: Learn how to create and use an authorization to the Microsoft Graph API in Azure API Management. An authorization manages authorization tokens to an OAuth 2.0 backend service. 
+services: api-management
+author: dlepow
+ms.service: api-management
+ms.topic: how-to
+ms.date: 04/10/2023
+ms.author: danlep
+---
+
+# Create an authorization with the Microsoft Graph API
+
+This article guides you through the steps required to create an [authorization](authorizations-overview.md) with the Microsoft Graph API within Azure API Management. The authorization code grant type is used in this example.
+
+You learn how to:
+
+> [!div class="checklist"]
+> * 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](../active-directory/roles/delegate-app-roles.md#restrict-who-can-create-applications)
+
+    If you want to create your own developer tenant, you can sign up for the [Microsoft 365 Developer Program](https://developer.microsoft.com/microsoft-365/dev-program).
+- A running API Management instance. If you need to, [create an Azure API Management instance](get-started-create-service-instance.md).
+- Enable a [system-assigned managed identity](api-management-howto-use-managed-service-identity.md) 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 into the [Azure portal](https://portal.azure.com/) with an account with sufficient permissions in the tenant.
+1. Under **Azure Services**, search for **Azure Active Directory**.
+1. On the left menu, select **App registrations**, and then select **+ New registration**. 
+    :::image type="content" source="media/authorizations-how-to-azure-ad/create-registration.png" alt-text="Screenshot of creating an Azure AD app registration in the portal.":::
+    
+1. 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*.
+    1. In **Supported account types**, select an option that suits your scenario, for example, **Accounts in this organizational directory only (Single tenant)**.
+    1. 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.
+    1. Select **Register**.
+1. On the left menu, select **API permissions**, and then select **+ Add a permission**.
+    :::image type="content" source="./media/authorizations-how-to-azure-ad/add-permission.png" alt-text="Screenshot of adding an API permission in the portal.":::
+
+    1. Select **Microsoft Graph**, and then select **Delegated permissions**.
+        > [!NOTE]
+        > Make sure the permission **User.Read** with the type **Delegated** has already been added.
+    1. Type **Team**, expand the **Team** options, and then select **Team.ReadBasic.All**. Select **Add permissions**.
+    1. Next, select **Grant admin consent for Default Directory**. The status of the permissions will change to **Granted for Default Directory**.
+1. On the left menu, select **Overview**. On the **Overview** page, find the **Application (client) ID** value and record it for use in Step 2.
+1. On the left menu, select **Certificates & secrets**, and then select **+ New client secret**.    
+    :::image type="content" source="media/authorizations-how-to-azure-ad/create-secret.png" alt-text="Screenshot of creating an app secret in the portal.":::
+    
+    1. Enter a **Description**.
+    1. Select any option for **Expires**.
+    1. Select **Add**.
+    1. 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](https://portal.azure.com) and go to your API Management instance.
+1. On the left menu, select **Authorizations**, and then select **+ Create**.    
+    :::image type="content" source="media/authorizations-how-to-azure-ad/create-authorization.png" alt-text="Screenshot of creating an API authorization in the portal.":::    
+1. 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*        |
+  
+1. 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.
+    :::image type="content" source="media/authorizations-how-to-azure-ad/login-azure-ad.png" alt-text="Screenshot of login with Azure AD in the portal.":::
+
+1. When prompted, sign in to your organizational account.
+1. On the confirmation page, select **Allow access**.
+1. After successful authorization, the browser is redirected to API Management and the window is closed. In API Management, select **Next**.
+1. 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](api-management-howto-use-managed-service-identity.md#create-a-system-assigned-managed-identity).
+1. For this example, select **API Management service `<service name>`**.
+
+    :::image type="content" source="media/authorizations-how-to-azure-ad/create-access-policy.png" alt-text="Screenshot of selecting a managed identity to use the authorization."::: 
+ 
+1. 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](https://portal.azure.com) and go to your API Management instance.
+1. On the left menu, select **APIs > + Add API**.
+1. 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*       |
+
+1. 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 |
+
+1. Follow the preceding steps to add another operation with the following settings.
+
+    |Setting  |Value  |
+    |---------|---------|
+    |**Display name**     | *getJoinedTeams*        |
+    |**URL** for GET    |  /me/joinedTeams |
+
+1. Select **All operations**. In the **Inbound processing** section, select the (**</>**) (code editor) icon.
+1. 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**. 
+
+    ```xml
+    <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](get-authorization-context-policy.md) policy fetches an authorization token by referencing the authorization provider and authorization that were created earlier. 
+* The [set-header](set-header-policy.md) 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.
+1. Select **Send**. 
+    
+    :::image type="content" source="media/authorizations-how-to-azure-ad/graph-api-response.png" alt-text="Screenshot of testing the Graph API in the portal.":::
+
+    A successful response returns user data from the Microsoft Graph.
+
+## Next steps
+
+* Learn more about [access restriction policies](api-management-access-restriction-policies.md)
+* Learn more about [scopes and permissions](../active-directory/develop/scopes-oidc.md) in Azure AD.