Επεξεργασία

Κοινοποίηση μέσω

Authenticate and authorize access to LLM APIs by using Azure API Management

APPLIES TO: All API Management tiers

In this article, you learn how to authenticate and authorize access to AI API endpoints that Azure API Management manages. This article shows the following common methods:

  • Authentication - Authenticate to an AI API by using policies that use either an API key or a Microsoft Entra ID managed identity.

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

For background, see:

Prerequisites

To follow the examples in this article, you must have:

Authenticate by using API key

A default way to authenticate to an AI API is by using an API key. For this type of authentication, all API requests must include a valid API key in an HTTP header. The header name depends on the API. For example, Azure OpenAI in Microsoft Foundry APIs use the api-key header.

  • API Management can manage the API key in a secure way by using a named value.
  • You can reference the named value in an API policy to set the api-key header in requests to the API. The following two examples show how to do this: one uses the set-backend-service policy, and the other uses the set-header policy.

Store the API key in a named value

Here's an example of how to store an Azure OpenAI API key in a named value in API Management:

  1. Get an API key from the AI model deployment. For an Azure OpenAI model deployment, find this information on the Home page for your project in the Microsoft Foundry portal.
  2. Go to your API Management instance, and select Named values in the left menu.
  3. Select + Add, and add the value as a secret. For more security, optionally use a key vault reference.

Pass the API key in API requests - set-backend-service policy

  1. Create a backend that points to the Azure OpenAI API.

    1. In the left menu of your API Management instance, select Backends.
    2. Select + Add, and enter a descriptive name for the backend. Example: openai-backend.
    3. Under Type, select Custom, and enter the URL of the Azure OpenAI endpoint. Example: https://contoso.services.ai.azure.com/openai.
    4. Under Authorization credentials, select Headers, and enter api-key as the header name and the named value as the value.
    5. Select Create.

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

    In this example, the backend resource is openai-backend.

    <set-backend-service backend-id="openai-backend" />

Pass the API key in API requests - set-header policy

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.

In this example, the named value in API Management is openai-api-key.

<set-header name="api-key" exists-action="override">
    <value>{{openai-api-key}}</value>
</set-header>

Authenticate with managed identity

For Azure OpenAI and other model deployments in Microsoft Foundry, use a managed identity in Microsoft Entra ID to authenticate. For background, see How to configure Azure OpenAI in Microsoft Foundry Models with Microsoft Entra ID authentication.

Follow these steps to configure your API Management instance to use a managed identity for authentication.

  1. Enable a system-assigned or user-assigned managed identity for your API Management instance. The following example assumes that you enabled the instance's system-assigned managed identity.

  2. 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 Microsoft Foundry resource. For detailed steps, see Role-based access control for Azure OpenAI service.

  3. Add the following policy snippet in the inbound policy section to authenticate requests to the API by using the managed identity.

    In this example:

    <authentication-managed-identity resource="https://cognitiveservices.azure.com" output-token-variable-name="managed-id-access-token" ignore-error="false" /> 
<set-header name="Authorization" exists-action="override"> 
    <value>@("Bearer " + (string)context.Variables["managed-id-access-token"])</value> 
</set-header>

Tip

Instead of using the authentication-managed-identity and set-header policies shown in this example, you can configure a backend resource that directs API requests to the AI service endpoint. In the backend configuration, configure managed identity credentials to the https://cognitiveservices.azure.com/ resource. Azure API Management automates these steps when you import an API directly from Microsoft Foundry.

OAuth 2.0 authorization by using identity provider

To enable more fine-grained access to Azure OpenAPI or other LLM APIs by particular users or clients, preauthorize access to the API by 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.

Note

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.

The following steps show how to restrict API access to users or apps that are authorized by using an identity provider.

  1. Create an application in your identity provider to represent the AI API in Azure API Management. If you're using Microsoft Entra ID, register an application in your Microsoft Entra ID tenant. Record details such as the application ID and the audience URI.

    As needed, configure the application to have roles or scopes that represent the fine-grained permissions needed to access the AI API.

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

    Note

    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.

    • 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 tenant-id={{TENANT_ID}} header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">
    <client-application-ids>
            <application-id>{{CLIENT_APP_ID}}</application-id>
    </client-application-ids>
   <audiences>
        <audience>...</audience> 
    </audiences>
    <required-claims>
        <claim name=...>
            <value>...</value>
        </claim>
    </required-claims>
</validate-azure-ad-token>

    • 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 header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">
    <openid-config url={{OPENID_CONFIGURATION_URL}} />
    <issuers>
        <issuer>{{ISSUER_URL}}</issuer>
    </issuers>
    <audiences>
        <audience>...</audience> 
    </audiences>
    <required-claims>
        <claim name=...>
            <value>...</value>
        </claim>
    </required-claims>
</validate-jwt>

Related content

  • Last updated on