Skip to content

Commit f757b0a

Browse files
author
gitName
committed
review comments
1 parent 66f369a commit f757b0a

File tree

6 files changed

+102
-65
lines changed

6 files changed

+102
-65
lines changed

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

Lines changed: 52 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -4,20 +4,20 @@ description: Learn how to configure access to APIs in the Azure API Center inven
44
author: dlepow
55
ms.service: azure-api-center
66
ms.topic: how-to
7-
ms.date: 04/25/2025
7+
ms.date: 04/28/2025
88
ms.author: danlep
99
ms.custom:
1010
# 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.
1111
---
1212

1313
# Authorize access to APIs in your API center
1414

15-
You can configure settings to authorize access to APIs in your API center. These settings:
15+
You can configure settings to authorize access to APIs in your [API center](overview.md). These settings:
1616

17-
* Enable API authentication using API keys or OAuth 2.0 authorization
17+
* Enable API authentication using either API keys or OAuth 2.0 authorization
1818
* Associate specific authentication methods with specific API versions in your inventory
1919
* 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
20+
* Enable authorized users to test APIs directly in the [API Center portal](set-up-api-center-portal.md)
2121

2222
> [!NOTE]
2323
> This feature is currently in preview.
@@ -26,89 +26,64 @@ You can configure settings to authorize access to APIs in your API center. These
2626

2727
* 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).
2828

29-
* Register at least API in your API center. For more information, see [Tutorial: Register APIs in your API inventory](register-apis.md).
29+
* Register at least one API in your API center. For more information, see [Tutorial: Register APIs in your API inventory](register-apis.md).
3030

3131
* Configure an environment and a deployment for the API. For more information, see [Tutorial: Add environments and deployments for APIs](configure-environments-deployments.md).
3232

3333
* Set up the API Center portal. For more information, see [Set up API Center portal](set-up-api-center-portal.md).
3434

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+
3537
* (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.
3638

3739

3840
## Option 1: Configure settings for API key authentication
3941

40-
For an API that supports API key authentication, follow these steps to configure settings in your API center. The API key must be stored in Azure Key Vault, and access to the key vault is through your API center's managed identity.
41-
42-
### 1. Store secret in Azure Key Vault
43-
44-
To store the API key securely, use Azure Key Vault. You can create a new key vault or use an existing one, using the Azure portal, Azure tools, or Azure SDKs. Your key vault should use the Azure role-based access control (RBAC) permission model.
45-
46-
* For steps to create a key vault, see [Create a Key Vault](/azure/key-vault/general/quick-create-portal).
47-
48-
* 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).
42+
For an API that supports API key authentication, follow these steps to configure settings in your API center.
4943

50-
> [!NOTE]
51-
> 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 add the API key configuration in your API center.
44+
### 1. Store API key in Azure Key Vault
5245

53-
### 2. Enable a managed identity in your API center
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.
5447

55-
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.
48+
[!INCLUDE [store-secret-key-vault](includes/store-secret-key-vault.md)]
5649

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

59-
60-
1. In the [portal](https://azure.microsoft.com), navigate to your API center.
61-
1. In the left menu, under **Security**, select **Managed identities**.
62-
1. Select **System assigned**, and set the status to **On**.
63-
1. Select **Save**.
64-
65-
### 3. Assign the Key Vault Secrets User role to the managed identity
66-
67-
Assign your API center's managed identity the **Key Vault Secrets User** role in your key vault. The following steps use the Azure portal.
68-
69-
1. In the [portal](https://azure.microsoft.com), navigate to your key vault.
70-
1. In the left menu, select **Access control (IAM)**.
71-
1. Select **+ Add role assignment**.
72-
1. On the **Add role assignment** page, set the values as follows:
73-
1. On the **Role** tab, select **Key Vault Secrets User**.
74-
1. On the **Members** tab, in **Assign access to**, select **Managed identity** > **+ Select members**.
75-
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**.
76-
1. Select **Review + assign** twice.
77-
78-
79-
### 4. Add API key configuration in your API center
51+
### 2. Add API key configuration in your API center
8052

8153
1. In the [portal](https://azure.microsoft.com), navigate to your API center.
8254
1. In the left menu, under **Assets**, select **Authorization (preview)** > **+ Add configuration**.
83-
1. In the **Add authorization** page, set the values as follows:
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+
8458
1. Enter a **Title** (name) and optional **Description** for the configuration.
8559
1. In **Security scheme**, select **API Key**.
8660
1. In **API key location**, select how the key is presented in API requests. Available values are **Header** (request header) and **Query** (query parameter).
8761
1. In **API key parameter name**, enter the name of the HTTP header or query parameter that contains the API key. For example, `x-api-key`.
8862
1. In **API key Key Vault secret reference**, enter the URI of the secret in your key vault that contains the API key. This is a URI of the form `https://<key-vault-name>.vault.azure.net/secrets/<secret-name>/<version>`.
8963
1. Select **Create**.
9064

65+
:::image type="content" source="media/authorize-api-access/configure-api-key.png" alt-text="Screenshot of configuring an API key in the portal.":::
9166

9267
## Option 2: Configure settings for OAuth 2.0 authorization
9368

9469
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:
9570

96-
* **Authorization code flow with PKCE (Proof Key for Code Exchange)** - This flow is recommended for authenticating users in mobile and web applications such as the API Center portal.
97-
* **Client credentials flow** - This flow is recommended for machine-to-machine applications that don't require a specific user's permissions to access data, such as background services or daemons.
71+
* **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.
72+
* **Client credentials flow** - This flow is recommended for applications that don't require a specific user's permissions to access data.
9873

9974

10075
### 1. Create an OAuth 2.0 app
10176

102-
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 steps depend on the identity provider you use.
77+
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.
10378

10479
The following example shows how to create an app registration in Microsoft Entra ID.
10580

106-
10781
1. Sign in to the [Azure portal](https://portal.azure.com) with an account with sufficient permissions in the tenant.
10882
1. Navigate to **Microsoft Entra ID** > **+ New registration**.
10983
1. In the **Register an application** page, enter your application registration settings:
11084
1. In **Name**, enter a meaningful name for the app.
11185
1. In **Supported account types**, select an option that suits your scenario, for example, **Accounts in this organizational directory only (Single tenant)**.
86+
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`
11287
1. Select **Register**.
11388
1. In the left menu, under **Manage**, select **Certificates & secrets**, and then select **+ New client secret**.
11489
1. Enter a **Description**.
@@ -125,45 +100,59 @@ In the following section, you will need the following values from the app regist
125100
* **OAuth 2.0 token endpoint (v2)** - the token URL endpoint for Microsoft Entra ID
126101
* Any API scopes configured in the app registration.
127102

128-
### 2. Add OAuth 2.0 authorization in your API center
103+
### 2. Store client secret in Azure Key Vault
104+
105+
To manage the secret securely, store it in Azure Key Vault, and access the key vault using your API center's managed identity.
106+
107+
[!INCLUDE [store-secret-key-vault](includes/store-secret-key-vault.md)]
108+
109+
### 3. Add OAuth 2.0 authorization in your API center
129110

130111
1. In the [portal](https://azure.microsoft.com), navigate to your API center.
131112
1. In the left menu, under **Assets**, select **Authorization (preview)** > **+ Add configuration**.
132-
1. In the **Add authorization** page, set the values as follows:
133-
1. Enter a **Title** (name) and optional **Description** for the authorization.
134-
1. In **Security scheme**, select **OAuth2**.
135-
1. In **Client ID**, enter the client ID of the app that you created in the previous section.
136-
1. In **Client secret**, enter the client secret of the app that you created in the previous section.
137-
1. In **Authorization URL**, enter the OAuth 2.0 authorization endpoint for the identity provider.
138-
1. In **Token URL**, enter the OAuth 2.0 token endpoint for the identity provider.
139-
1. In **OAuth2 flow**, select one or both of the OAuth 2.0 flows that you want to use. Available values are **Authorization code (PKCE)** and **Client credentials**.
140-
1. In **Scopes**, optionally enter one or more API scopes that your API supports, separated by " ". Example: `User.Read`
141-
1. Select **Create**.
113+
1. In the **Add configuration** page, set the values as follows:
114+
115+
| **Setting** | **Description** |
116+
|-------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------|
117+
| **Title** | A name and optional description for the authorization. |
118+
| **Description** | Opitonal description for the authorization. |
119+
| **Security scheme** | Select **OAuth2**. |
120+
| **Client ID** | Client ID of the app that you created in the previous section. |
121+
| **Client secret** | Enter the . |
122+
| **Authorization URL** | OAuth 2.0 authorization endpoint for the identity provider. |
123+
| **Token URL** | OAuth 2.0 token endpoint for the identity provider. |
124+
| **Refresh URL** | OAuth 2.0 refresh token endpoint for the identity provider. For most providers, same as the Token URL. |
125+
| **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**. |
126+
| **Scopes** | One or more API scopes configured for your API, separated by spaces. If no scopes are configured, enter `.default`. |
127+
128+
1. Select **Create** to save the configuration. |
142129

143130
## Add authentication configuration to an API version
144131

145-
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 inventory.
132+
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.
146133

147134
1. In the [portal](https://azure.microsoft.com), navigate to your API center.
148135
1. In the left menu, under **Assets**, select **APIs**.
149-
1. Select an API that you want to associate the authorization with.
136+
1. Select an API that you want to associate the authorization configuration with.
150137
1. In the left menu, under **Details**, select **Versions**.
151138
1. Select the API version that you want to add the authentication configuration to.
152139
1. In the left menu, under **Details**, select **Manage Access (preview)** > **+ Add authentication**.
153-
1. In the **Add authentication** page, select an available **Authentication configuration** that you want to associate with the API version.
140+
1. In the **Add authentication** page, select an available **Authentication configuration** that you want to associate.
154141
1. Select **Create**.
155142

156143
> [!NOTE]
157-
> 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. Similarly, you can add the same configurations to multiple API versions.
144+
> 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.
158145
159146
## Manage access by specific users or groups
160147

161-
You can manage access to an API version's authentication configuration by specific users or groups in your organization. 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.
148+
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.
162149

163150
1. In the [portal](https://azure.microsoft.com), navigate to your API center.
164151
1. Navigate to an API version to which you've added an authentication configuration (see previous section).
165152
1. In the left menu, under **Details**, select **Manage Access (preview)**.
166153
1. Select the **Edit access policies** dropdown at the end of the row for the authentication configuration whose access you want to manage.
154+
:::image type="content" source="media/authorize-api-access/edit-access-policies.png" alt-text="Screenshot of adding an access policy in the portal.":::
155+
167156
1. In the **Manage access** page, select **+ Add > Users** or **+ Add > Groups**.
168157
1. Search for and select the users (or groups) that you want to add. You can select multiple items.
169158
1. Click **Select**.
@@ -194,4 +183,5 @@ You can use the API Center portal to test an API that you configured for authent
194183
## Related content
195184

196185
* [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)
186+
* [Enable the Azure API Center portal view in Visual Studio Code](enable-api-center-portal-vs-code-extension.md)
187+
* [Authentication and authorization to APIs in Azure API Management](../api-management/authentication-authorization-overview.md)

‎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

0 commit comments

Comments
 (0)