Skip to content

Commit ac48011

Browse files
Stacyrch140Stacyrch140
authored
Merge pull request #265898 from dlepow/aoai
[APIM] Auth to Azure OpenAI API
2 parents 8c0a55c + 360b736 commit ac48011

File tree

3 files changed

+232
-0
lines changed

3 files changed

+232
-0
lines changed

‎articles/api-management/TOC.yml

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -209,6 +209,10 @@
209209
href: grpc-api.md
210210
- name: Azure OpenAI
211211
items:
212+
- name: Import Azure OpenAI API as REST API
213+
href: azure-openai-api-from-specification.md
214+
- name: Authenticate and authorize to Azure OpenAI
215+
href: api-management-authenticate-authorize-azure-openai.md
212216
- name: Protect Azure OpenAI keys
213217
href: /semantic-kernel/deploy/use-ai-apis-with-api-management?toc=%2Fazure%2Fapi-management%2Ftoc.json&bc=/azure/api-management/breadcrumb/toc.json
214218
- name: Configure API for SSE

‎articles/api-management/api-management-authenticate-authorize-azure-openai.md

Lines changed: 161 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
---
2+
title: Authenticate to Azure OpenAI API - Azure API Management
3+
titleSuffix: Azure API Management
4+
description: Options to authenticate and authorize to Azure OpenAI APIs using Azure API Management. Includes API key, managed identity, and OAuth 2.0 authorization.
5+
author: dlepow
6+
ms.service: api-management
7+
ms.topic: article
8+
ms.date: 02/20/2024
9+
ms.author: danlep
10+
---
11+
12+
# Authenticate and authorize access to Azure OpenAI APIs using Azure API Management
13+
14+
In this article, you learn about ways to authenticate and authorize to Azure OpenAI API endpoints that are managed using Azure API Management. This article shows the following common methods:
15+
16+
* **Authentication** - Authenticate to an Azure OpenAI API using policies that authenticate using either an API key or a Microsoft Entra ID managed identity.
17+
18+
* **Authorization** - For more fine-grained access control, preauthorize requests that pass OAuth 2.0 tokens generated by an identity provider such as Microsoft Entra ID.
19+
20+
For background, see:
21+
22+
* [Azure OpenAI Service REST API reference](/azure/ai-services/openai/reference)
23+
24+
* [Authentication and authorization to APIs in API Management](authentication-authorization-overview.md).
25+
26+
## Prerequisites
27+
28+
Before following the steps in this article, you must have:
29+
30+
- An API Management instance. For example steps, see [Create an Azure API Management instance](get-started-create-service-instance.md).
31+
- An Azure OpenAI resource and model added to your API Management instance. For example steps, see [Import an Azure OpenAI API as a REST API](azure-openai-api-from-specification.md).
32+
- Permissions to create an app registration in an identity provider such as a Microsoft Entra tenant associated with your Azure subscription (for OAuth 2.0 authorization).
33+
34+
## Authenticate with API key
35+
36+
A default way to authenticate to an Azure OpenAI API is by using an API key. For this type of authentication, all API requests must include a valid API key in the `api-key` HTTP header.
37+
38+
* API Management can manage the API key in a secure way, by using a [named value](api-management-howto-properties.md).
39+
* The named value can then be referenced in an API policy to set the `api-key` header in requests to the Azure OpenAI API. We provide two examples of how to do this: one uses the [`set-backend-service`](set-backend-service-policy.md) policy, and the other uses the [`set-header`](set-header-policy.md) policy.
40+
41+
### Store the API key in a named value
42+
43+
1. Obtain an API key from the Azure OpenAI resource. In the Azure portal, find a key on the **Keys and Endpoint** page of the Azure OpenAI resource.
44+
1. Go to your API Management instance, and select **Named values** in the left menu.
45+
1. Select **+ Add**, and add the value as a secret, or optionally for more security, use a [key vault reference](api-management-howto-properties.md#key-vault-secrets).
46+
47+
### Pass the API key in API requests - set-backend-service policy
48+
49+
1. Create a [backend](backends.md) that points to the Azure OpenAI API.
50+
1. In the left menu of your API Management instance, select **Backends**.
51+
1. Select **+ Add**, and enter a descriptive name for the backend. Example: *openai-backend*.
52+
1. Under **Type**, select **Custom**, and enter the URL of the Azure OpenAI endpoint. Example: `https://contoso.openai.azure.com/openai`.
53+
1. Under **Authorization credentials**, select **Headers**, and enter *api-key* as the header name and the named value as the value.
54+
1. Select **Create**.
55+
1. Add the following `set-backend-service` policy snippet in the `inbound` policy section to pass the API key in requests to the Azure OpenAI API.
56+
57+
In this example, the backend resource is *openai-backend*.
58+
59+
```xml
60+
<set-backend-service backend-id="openai-backend" />
61+
```
62+
63+
### Pass the API key in API requests - set-header policy
64+
65+
Alternatively, add the following `set-header` policy snippet in the `inbound` policy section to pass the API key in requests to the Azure OpenAI API. This policy snippet sets the `api-key` header with the named value that you set up.
66+
67+
In this example, the named value in API Management is *openai-api-key*.
68+
69+
```xml
70+
<set-header name="api-key" exists-action="override">
71+
<value>{{openai-api-key}}</value>
72+
</set-header>
73+
```
74+
75+
76+
## Authenticate with managed identity
77+
78+
An alternative way to authenticate to an Azure OpenAI API by using a managed identity in Microsoft Entra ID. For background, see
79+
[How to configure Azure OpenAI Service with managed identity](../ai-services/openai/how-to/managed-identity.md).
80+
81+
Following are steps to configure your API Management instance to use a managed identity to authenticate requests to an Azure OpenAI API.
82+
83+
1. [Enable](api-management-howto-use-managed-service-identity.md) a system-assigned or user-assigned managed identity for your API Management instance. The following example assumes that you've enabled the instance's system-assigned managed identity.
84+
85+
1. Assign the managed identity the **Cognitive Services OpenAI User** role, scoped to the appropriate resource. For example, assign the system-assigned managed identity the **Cognitive Services OpenAI User** role on the Azure OpenAI resource. For detailed steps, see [Role-based access control for Azure OpenAI service](../ai-services/openai/how-to/role-based-access-control.md).
86+
87+
1. Add the following policy snippet in the `inbound` policy section to authenticate requests to the Azure OpenAI API using the managed identity.
88+
89+
In this example:
90+
91+
* The [`authentication-managed-identity`](authentication-managed-identity-policy.md) policy obtains an access token for the managed identity.
92+
* The [`set-header`](set-header-policy.md) policy sets the `Authorization` header of the request with the access token.
93+
94+
```xml
95+
<authentication-managed-identity resource="https://cognitiveservices.azure.com" output-token-variable-name="managed-id-access-token" ignore-error="false" />
96+
<set-header name="Authorization" exists-action="override">
97+
<value>@("Bearer " + (string)context.Variables["managed-id-access-token"])</value>
98+
</set-header>
99+
```
100+
101+
## OAuth 2.0 authorization using identity provider
102+
103+
To enable more fine-grained access to OpenAPI APIs by particular users or clients, you can preauthorize access to the Azure OpenAI API using OAuth 2.0 authorization with Microsoft Entra ID or another identity provider. For background, see [Protect an API in Azure API Management using OAuth 2.0 authorization with Microsoft Entra ID](api-management-howto-protect-backend-with-aad.md).
104+
105+
> [!NOTE]
106+
> Use OAuth 2.0 authorization as part of a defense-in-depth strategy. It's not a replacement for API key authentication or managed identity authentication to an Azure OpenAI API.
107+
108+
Following are high level steps to restrict API access to users or apps that are authorized using an identity provider.
109+
110+
1. Create an application in your identity provider to represent the OpenAI API in Azure API Management. If you're using Microsoft Entra ID, [register](api-management-howto-protect-backend-with-aad.md#register-an-application-in-microsoft-entra-id-to-represent-the-api) an application in your Microsoft Entra ID tenant. Record details such as the application ID and the audience URI.
111+
112+
As needed, configure the application to have roles or scopes that represent the fine-grained permissions needed to access the Azure OpenAI API.
113+
114+
1. Add an `inbound` policy snippet in your API Management instance to validate requests that present a JSON web token (JWT) in the `Authorization` header. Place this snippet *before* other `inbound` policies that you set to authenticate to the Azure OpenAI API.
115+
116+
> [!NOTE]
117+
> The following examples show the general structure of the policies to validate a JWT. Customize them to your identity provider and the requirements of your application and API.
118+
119+
* **validate-azure-ad-token** - If you use Microsoft Entra ID, configure the `validate-azure-ad-token` policy to validate the audience and claims in the JWT. For details, see the [policy reference](validate-azure-ad-token-policy.md).
120+
121+
```xml
122+
<validate-azure-ad-token tenant-id={{TENANT_ID}} header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">
123+
<client-application-ids>
124+
<application-id>{{CLIENT_APP_ID}}</application-id>
125+
</client-application-ids>
126+
<audiences>
127+
<audience>...</audience>
128+
</audiences>
129+
<required-claims>
130+
<claim name=...>
131+
<value>...</value>
132+
</claim>
133+
</required-claims>
134+
</validate-azure-ad-token>
135+
```
136+
137+
138+
* **validate-jwt** - If you use another identity provider, configure the `validate-jwt` policy to validate the audience and claims in the JWT. For details, see the [policy reference](validate-jwt-policy.md).
139+
140+
```xml
141+
<validate-jwt header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">
142+
<openid-config url={{OPENID_CONFIGURATION_URL}} />
143+
<issuers>
144+
<issuer>{{ISSUER_URL}}</issuer>
145+
</issuers>
146+
<audiences>
147+
<audience>...</audience>
148+
</audiences>
149+
<required-claims>
150+
<claim name=...>
151+
<value>...</value>
152+
</claim>
153+
</required-claims>
154+
</validate-jwt>
155+
```
156+
157+
## Related content
158+
159+
* Learn more about [Microsoft Entra ID and OAuth2.0](../active-directory/develop/authentication-vs-authorization.md).
160+
* [Authenticate requests to Azure AI services](../ai-services/authentication.md)
161+
* [Protect Azure OpenAI keys with API Management](/semantic-kernel/deploy/use-ai-apis-with-api-management?toc=%2Fazure%2Fapi-management%2Ftoc.json&bc=/azure/api-management/breadcrumb/toc.json)

‎articles/api-management/azure-openai-api-from-specification.md

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
---
2+
title: Import an Azure OpenAI API as REST API - Azure API Management
3+
description: How to import an Azure OpenAI API as a REST API from its OpenAPI specification.
4+
ms.service: api-management
5+
author: dlepow
6+
ms.author: danlep
7+
ms.topic: how-to
8+
ms.date: 02/22/2024
9+
ms.custom: template-how-to
10+
---
11+
12+
# Import an Azure OpenAI API as a REST API
13+
14+
This article shows how to import an [Azure OpenAI](/azure/ai-services/openai/overview) API into an Azure API Management instance from its OpenAPI specification. After importing the API as a REST API, you can manage and secure it, and publish it to developers.
15+
16+
## Prerequisites
17+
18+
- An existing API Management instance. [Create one if you haven't already](get-started-create-service-instance.md).
19+
- Access granted to Azure OpenAI in the desired Azure subscription.
20+
You can apply for access to Azure OpenAI by completing the form at https://aka.ms/oai/access. Open an issue on this repo to contact us if you have an issue.
21+
- An Azure OpenAI resource with a model deployed. For more information about model deployment, see the [resource deployment guide](../ai-services/openai/how-to/create-resource.md).
22+
23+
Make a note of the deployment ID (name). You'll need it when you test the imported API in API Management.
24+
25+
## Download the OpenAPI specification
26+
27+
Download the OpenAPI specification for an endpoint that your model supports. For example, download the OpenAPI specification for the [chat completion endpoint](https://github.com/Azure/azure-rest-api-specs/blob/main/specification/cognitiveservices/data-plane/AzureOpenAI/inference/stable/2023-05-15/inference.json) of the GPT-35-Turbo and GPT-4 models.
28+
29+
1. In a text editor, open the specification file that you downloaded.
30+
1. In the `servers` element in the specification, substitute the name of your Azure OpenAI resource endpoint for the placeholder values in the specification. The following example `servers` element is updated with the `contoso.openai.azure.com` resource endpoint.
31+
```json
32+
[...]
33+
"servers": [
34+
{
35+
"url": "https://contoso.openai.azure.com/openai",
36+
"variables": {
37+
"endpoint": {
38+
"default": "contoso.openai.azure.com"
39+
}
40+
}
41+
}
42+
],
43+
[...]
44+
```
45+
1. Make a note of the value of the API `version` in the specification. You'll need it to test the API. Example: `2023-05-15`.
46+
47+
## Add OpenAPI specification to API Management
48+
49+
50+
1. In the [Azure portal](https://portal.azure.com), navigate to your API Management instance.
51+
1. In the left menu, select **APIs** > **+ Add API**.
52+
1. Under **Define a new API**, select **OpenAPI**. Enter a **Display name** and **Name** for the API and enter an **API URL suffix**.
53+
1. Select **Create**.
54+
55+
The API is imported and displays operations from the OpenAPI specification.
56+
57+
[!INCLUDE [api-management-test-api-portal](../../includes/api-management-test-api-portal.md)]
58+
59+
> [!IMPORTANT]
60+
> Authentication to the OpenAI API requires an API key or a managed identity. To configure authentication using API Management policies, see [Authenticate and authorize to Azure OpenAI API](api-management-authenticate-authorize-azure-openai.md).
61+
62+
[!INCLUDE [api-management-define-api-topics.md](../../includes/api-management-define-api-topics.md)]
63+
64+
## Related content
65+
66+
* [Azure OpenAI Service as a central capability with Azure API Management](/samples/azure/enterprise-azureai/enterprise-azureai/)
67+
* [Azure API Management - Azure OpenAI sample](https://github.com/galiniliev/apim-azure-openai-sample)

0 commit comments

Comments
 (0)