Skip to content

Commit 031007f

Browse files
JillGrant615JillGrant615
authored
Merge pull request #298754 from dlepow/apicaccess
[APIC] Authorization to APIs
2 parents f228319 + 21b1982 commit 031007f

12 files changed

+251
-4
lines changed

‎articles/api-center/TOC.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,8 @@
6464
href: enable-managed-api-analysis-linting.md
6565
- name: API analysis - self-managed
6666
href: enable-api-analysis-linting.md
67+
- name: Authorize access to APIs
68+
href: authorize-api-access.md
6769
- name: Discover shadow APIs with Dev Proxy
6870
href: discover-shadow-apis-dev-proxy.md
6971
- name: Find nonproduction API requests with Dev Proxy

‎articles/api-center/authorize-api-access.md

Lines changed: 198 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,198 @@
1+
---
2+
title: Configure API access in Azure API Center
3+
description: Learn how to configure access to APIs in the Azure API Center inventory using API keys or OAuth 2.0 authorization. Users authorized for access can test APIs in the API Center portal.
4+
author: dlepow
5+
ms.service: azure-api-center
6+
ms.topic: how-to
7+
ms.date: 04/30/2025
8+
ms.author: danlep
9+
ms.custom:
10+
# Customer intent: As an API program manager, I want to store API authorization information in my API center and enable authorized users to test APIs in the API Center portal.
11+
---
12+
13+
# Authorize access to APIs in your API center
14+
15+
You can configure settings to authorize access to APIs in your [API center](overview.md). These settings:
16+
17+
* Enable API authentication using either API keys or OAuth 2.0 authorization
18+
* Associate specific authentication methods with specific API versions in your inventory
19+
* Manage authentication to API versions by designated users or groups through access policies
20+
* Enable authorized users to test APIs directly in the [API Center portal](set-up-api-center-portal.md)
21+
22+
> [!NOTE]
23+
> This feature is currently in preview.
24+
25+
## Prerequisites
26+
27+
* An API center in your Azure subscription. If you haven't created one already, see [Quickstart: Create your API center](set-up-api-center.md).
28+
29+
* Register at least one API in your API center. For more information, see [Tutorial: Register APIs in your API inventory](register-apis.md).
30+
31+
* Configure an environment and a deployment for the API. For more information, see [Tutorial: Add environments and deployments for APIs](configure-environments-deployments.md).
32+
33+
* Set up the API Center portal. For more information, see [Set up API Center portal](set-up-api-center-portal.md).
34+
35+
* An Azure key vault to store API keys or OAuth 2.0 client secrets. For steps to create a key vault, see [Create a Key Vault](/azure/key-vault/general/quick-create-portal). The key vault should use the Azure role-based access control (RBAC) permission model.
36+
37+
* (For OAuth 2.0 authorization using Microsoft Entra ID) Permissions to create an app registration in a Microsoft Entra tenant associated with your Azure subscription.
38+
39+
40+
## Option 1: Configure settings for API key authentication
41+
42+
For an API that supports API key authentication, follow these steps to configure settings in your API center.
43+
44+
### 1. Store API key in Azure Key Vault
45+
46+
To manage the API key securely, store it in Azure Key Vault, and access the key vault using your API center's managed identity.
47+
48+
[!INCLUDE [store-secret-key-vault](includes/store-secret-key-vault.md)]
49+
50+
51+
### 2. Add API key configuration in your API center
52+
53+
1. In the [portal](https://azure.microsoft.com), navigate to your API center.
54+
1. In the left menu, under **Governance**, select **Authorization (preview)** > **+ Add configuration**.
55+
1. In the **Add configuration** page, set the values as follows:
56+
:::image type="content" source="media/authorize-api-access/configure-api-key.png" alt-text="Screenshot of configuring an API key in the portal.":::
57+
58+
| **Setting** | **Description** |
59+
|-------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------|
60+
| **Title** | A name for the authorization. |
61+
| **Description** | Optional description for the authorization. |
62+
| **Security scheme** | Select **API Key**. |
63+
|**API key location** | How the key is presented in API requests. Available values are **Header** (request header) and **Query** (query parameter). |
64+
| **API key parameter name** | Name of the HTTP header or query parameter that contains the API key. Example: `x-api-key` |
65+
| **API key Key Vault secret reference** | Secret identifier of the API key in Azure Key Vault. Example: `https://<key-vault-name>.vault.azure.net/secrets/<secret-name>/<version>` |
66+
67+
1. Select **Create**.
68+
69+
## Option 2: Configure settings for OAuth 2.0 authorization
70+
71+
For an API that supports OAuth 2.0 authorization, follow these steps to configure authentication settings in your API center. You can configure settings for one or both of the following OAuth 2.0 authorization flows:
72+
73+
* **Authorization code flow with PKCE (Proof Key for Code Exchange)** - This flow is recommended for authenticating users in the browser, such as in the API Center portal.
74+
* **Client credentials flow** - This flow is recommended for applications that don't require a specific user's permissions to access data.
75+
76+
77+
### 1. Create an OAuth 2.0 app
78+
79+
For OAuth 2.0 authorization, create an app registration in an identity provider, such as the Microsoft Entra tenant associated with your Azure subscription. The exact creation steps depend on the identity provider you use.
80+
81+
The following example shows how to create an app registration in Microsoft Entra ID.
82+
83+
1. Sign in to the [Azure portal](https://portal.azure.com) with an account with sufficient permissions in the tenant.
84+
1. Navigate to **Microsoft Entra ID** > **+ New registration**.
85+
1. In the **Register an application** page, enter your application registration settings:
86+
1. In **Name**, enter a meaningful name for the app.
87+
1. In **Supported account types**, select an option that suits your scenario, for example, **Accounts in this organizational directory only (Single tenant)**.
88+
1. (For authorization code flow) In **Redirect URI**, select **Single-page application (SPA)** and set the URI. Enter the URI of your API Center portal deployment, in the following form: `https://<service-name>.portal.<location>.azure-api-center.ms.` Replace `<service name>` and `<location>` with the name of your API center and the location where it's deployed, Example: `https://myapicenter.portal.eastus.azure-api-center.ms`
89+
1. Select **Register**.
90+
1. In the left menu, under **Manage**, select **Certificates & secrets**, and then select **+ New client secret**.
91+
1. Enter a **Description**.
92+
1. Select an option for **Expires**.
93+
1. Select **Add**.
94+
1. Copy the client secret's **Value** before leaving the page. You will need it in the following section.
95+
1. Optionally, add API scopes in your app registration. For more information, see [Configure an application to expose a web API](/entra/identity-platform/quickstart-configure-app-expose-web-apis#add-a-scope).
96+
97+
When you configure OAuth 2.0 authorization in your API center, you will need the following values from the app registration:
98+
99+
* The **Application (client) ID** from the app registration's **Overview** page, and the **Client secret** you copied previously.
100+
* The following endpoint URLs on the app registration's **Overview** > **Endpoints** page:
101+
* **OAuth2.0 authorization endpoint (v2)** - the authorization endpoint for Microsoft Entra ID
102+
* **OAuth 2.0 token endpoint (v2)** - the token endpoint and token refresh endpoint for Microsoft Entra ID
103+
* Any API scopes configured in the app registration.
104+
105+
### 2. Store client secret in Azure Key Vault
106+
107+
To manage the secret securely, store it in Azure Key Vault, and access the key vault using your API center's managed identity.
108+
109+
[!INCLUDE [store-secret-key-vault](includes/store-secret-key-vault.md)]
110+
111+
### 3. Add OAuth 2.0 authorization in your API center
112+
113+
1. In the [portal](https://azure.microsoft.com), navigate to your API center.
114+
1. In the left menu, under **Governance**, select **Authorization (preview)** > **+ Add configuration**.
115+
1. In the **Add configuration** page, set the values as follows:
116+
117+
:::image type="content" source="media/authorize-api-access/configure-oauth.png" alt-text="Screenshot of configuring OAuth 2.0 in the portal.":::
118+
119+
120+
> [!NOTE]
121+
> Configure settings based on the app registration you created previously in your identity provider. If you're using Microsoft Entra ID, find the **Client ID** on the **Overview** page of the app registration, and find the URL endpoints on the **Overview** > **Endpoints** page.
122+
123+
| **Setting** | **Description** |
124+
|-------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------|
125+
| **Title** | A name for the authorization. |
126+
| **Description** | Optional description for the authorization. |
127+
| **Security scheme** | Select **OAuth2**. |
128+
| **Client ID** | Client ID (GUID) of the app that you created in your identity provider. |
129+
| **Client secret** | Secret identifier of the client secret in Azure Key Vault.<br/><br/>Example: `https://<key-vault-name>.vault.azure.net/secrets/<secret-name>/<version>` |
130+
| **Authorization URL** | OAuth 2.0 authorization endpoint for the identity provider.<br/><br/>Example for Microsoft Entra ID: `https://login.microsoftonline.com/<tenant>/oauth2/v2.0/authorize` |
131+
| **Token URL** | OAuth 2.0 token endpoint for the identity provider.<br/><br/>Example for Microsoft Entra ID: `https://login.microsoftonline.com/<tenant>/oauth2/v2.0/token` |
132+
| **Refresh URL** | OAuth 2.0 token refresh endpoint for the identity provider. For most providers, same as the **Token URL**<br/><br/>Example for Microsoft Entra ID: `https://login.microsoftonline.com/<tenant>/oauth2/v2.0/token` |
133+
| **OAuth2 flow** | One or both of the OAuth 2.0 flows that you want to use. Available values are **Authorization code (PKCE)** and **Client credentials**. |
134+
| **Scopes** | One or more API scopes configured for your API, separated by spaces. If no scopes are configured, enter `.default`. |
135+
136+
1. Select **Create** to save the configuration.
137+
138+
## Add authentication configuration to an API version
139+
140+
After configuring settings for an API key or an OAuth 2.0 flow, add the API key or OAuth 2.0 configuration to an API version in your API center.
141+
142+
1. In the [portal](https://azure.microsoft.com), navigate to your API center.
143+
1. In the left menu, under **Assets**, select **APIs**.
144+
1. Select an API that you want to associate the authorization configuration with.
145+
1. In the left menu, under **Details**, select **Versions**.
146+
1. Select the API version that you want to add the authentication configuration to.
147+
1. In the left menu, under **Details**, select **Manage Access (preview)** > **+ Add authentication**.
148+
1. In the **Add authentication** page, select an available **Authentication configuration** that you want to associate.
149+
1. Select **Create**.
150+
151+
> [!NOTE]
152+
> You can add multiple authentication configurations to an API version. For example, you can add both API key and OAuth 2.0 configurations to the same API version, if supported by the API. Similarly, you can add the same configurations to multiple API versions.
153+
154+
## Manage access by specific users or groups
155+
156+
You can manage access by specific users or groups in your organization to an API version's authentication configuration. You do this by configuring an access policy that assigns users or groups the **API Center Credential Access Reader** role, scoped to specific authentication configurations in the API version. This is useful, for example, if you want to allow only specific users to test an API in the API Center portal using an API key or OAuth 2.0 flow.
157+
158+
1. In the [portal](https://azure.microsoft.com), navigate to your API center.
159+
1. Navigate to an API version to which you've added an authentication configuration (see previous section).
160+
1. In the left menu, under **Details**, select **Manage Access (preview)**.
161+
1. Select the **Edit access policies** dropdown at the end of the row for the authentication configuration whose access you want to manage.
162+
:::image type="content" source="media/authorize-api-access/edit-access-policies.png" alt-text="Screenshot of adding an access policy in the portal.":::
163+
164+
1. In the **Manage access** page, select **+ Add > Users** or **+ Add > Groups**.
165+
1. Search for and select the users (or groups) that you want to add. You can select multiple items.
166+
1. Click **Select**.
167+
168+
> [!TIP]
169+
> You can also remove users or groups from the access policy. In the **Manage access** page, select **Delete** in the context (...) menu for the user or group.
170+
171+
## Test API in API Center portal
172+
173+
174+
You can use the API Center portal to test an API that you configured for authentication and user access.
175+
176+
> [!TIP]
177+
> In addition to enabling specific users to test specific APIs in the API Center portal, you can configure [visibility settings](set-up-api-center-portal.md#api-visibility) for APIs. Visibility settings in the portal control the APIs that appear for all signed-in users.
178+
179+
1. In the [portal](https://azure.microsoft.com), navigate to your API center.
180+
1. In the left menu, under **API Center Portal**, select **Portal settings**.
181+
1. Select **View API Center portal**.
182+
1. In the API Center portal, select an API that you want to test.
183+
1. Select a version of the API that has an authentication method configured.
184+
1. Under **Options**, select **View documentation**.
185+
:::image type="content" source="media/authorize-api-access/view-api-documentation-small.png" lightbox="media/authorize-api-access/view-api-documentation.png" alt-text="Screenshot of API details in API Center portal.":::
186+
187+
1. Select an operation in the API, and select **Try this API**.
188+
1. In the window that opens, review the authentication settings. If you have access to the API, select **Send** to try the API.
189+
:::image type="content" source="media/authorize-api-access/test-api-operation-small.png" lightbox="media/authorize-api-access/test-api-operation.png" alt-text="Screenshot of testing an API in the API Center portal's test console.":::
190+
191+
1. If the operation is successful, you see the `200 OK` response code and the response body. If the operation fails, you see an error message.
192+
193+
194+
## Related content
195+
196+
* [Set up API Center portal](set-up-api-center-portal.md)
197+
* [Enable the Azure API Center portal view in Visual Studio Code](enable-api-center-portal-vs-code-extension.md)
198+
* [Authentication and authorization to APIs in Azure API Management](../api-management/authentication-authorization-overview.md)

‎articles/api-center/includes/api-center-portal-compare-apim-dev-portal.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ While the two portals share some features, they also have distinct differences.
2929
| Integrate with Microsoft Entra ID | ✔️ | ✔️ |
3030
| Add custom widgets | ✔️ | ❌ |
3131
| Customize with WordPress | ✔️ | ❌ |
32-
| Test APIs in test console | ✔️ | ❌ |
32+
| Test APIs in test console | ✔️ | ✔️ |
3333
| Subscribe to APIs | ✔️ | ❌ |
3434
| View API usage analytics | ✔️ | ❌ |
3535

‎articles/api-center/includes/store-secret-key-vault.md

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
---
2+
title: Include file
3+
description: Include file
4+
services: api-center
5+
author: dlepow
6+
7+
ms.service: azure-api-center
8+
ms.topic: include
9+
ms.date: 04/28/2025
10+
ms.author: danlep
11+
ms.custom: Include file
12+
---
13+
14+
15+
To store the API key as a secret in the key vault, see [Set and retrieve secret in Key Vault](/azure/key-vault/secrets/quick-create-portal).
16+
17+
> [!NOTE]
18+
> The *secret identifier* of the secret appears on the secret's details page. This is a URI of the form `https://<key-vault-name>.vault.azure.net/secrets/<secret-name>/<version>`. You need this value when you configure the secret in your API center.
19+
20+
#### Enable a managed identity in your API center
21+
22+
For this scenario, your API center uses a [managed identity](/entra/identity/managed-identities-azure-resources/overview) to access the key vault. Depending on your needs, enable either a system-assigned or one or more user-assigned managed identities.
23+
24+
The following example shows how to enable a system-assigned managed identity by using the Azure portal. At a high level, configuration steps are similar for a user-assigned managed identity.
25+
26+
27+
1. In the [portal](https://azure.microsoft.com), navigate to your API center.
28+
1. In the left menu, under **Security**, select **Managed identities**.
29+
1. Select **System assigned**, and set the status to **On**.
30+
1. Select **Save**.
31+
32+
#### Assign the Key Vault Secrets User role to the managed identity
33+
34+
Assign your API center's managed identity the **Key Vault Secrets User** role in your key vault. The following steps use the Azure portal.
35+
36+
1. In the [portal](https://azure.microsoft.com), navigate to your key vault.
37+
1. In the left menu, select **Access control (IAM)**.
38+
1. Select **+ Add role assignment**.
39+
1. On the **Add role assignment** page, set the values as follows:
40+
1. On the **Role** tab, select **Key Vault Secrets User**.
41+
1. On the **Members** tab, in **Assign access to**, select **Managed identity** > **+ Select members**.
42+
1. On the **Select managed identities** page, select the system-assigned managed identity of your API center that you added in the previous section. Click **Select**.
43+
1. Select **Review + assign** twice.

‎articles/api-center/media/authorize-api-access/configure-api-key.png

131 KB
Loading

‎articles/api-center/media/authorize-api-access/configure-oauth.png

154 KB
Loading

‎articles/api-center/media/authorize-api-access/edit-access-policies.png

80.5 KB
Loading

‎articles/api-center/media/authorize-api-access/test-api-operation-small.png

125 KB
Loading

‎articles/api-center/media/authorize-api-access/test-api-operation.png

120 KB
Loading

‎articles/api-center/media/authorize-api-access/view-api-documentation-small.png

127 KB
Loading

0 commit comments

Comments
 (0)