Autenticar e autorizar o acesso às APIs do Azure OpenAI utilizando o Azure API Management

2025-06-27

APLICA-SE A: Todos os níveis de Gestão de API

Neste artigo, aprenderá sobre maneiras de autenticar e autorizar endpoints da API do Azure OpenAI que são geridos usando a Gestão de API do Azure. Este artigo apresenta os seguintes métodos comuns:

Autenticação - Autentique-se em uma API Azure OpenAI usando políticas que autenticam através de uma chave API ou uma identidade gerida pelo Microsoft Entra ID.
Autorização - Para um controlo de acesso mais detalhado, pré-autorize pedidos que utilizem tokens OAuth 2.0 gerados por um fornecedor de identidade, como o Microsoft Entra ID.

Para obter informações de base, veja:

Pré-requisitos

Antes de seguir os passos neste artigo, deve ter:

Uma instância de Gestão de API. Para passos de exemplo, veja Criar uma instância do Azure API Management.
Um recurso e modelo de Azure OpenAI adicionado à sua instância de Gestão de API. Para passos de exemplo, consulte Import an Azure OpenAI API as a REST API.
Permissões para criar um registo de aplicação num fornecedor de identidade, como um inquilino Microsoft Entra associado à sua subscrição do Azure (para autorização OAuth 2.0).

Autenticar com chave de API

Uma maneira padrão de autenticar em uma API do Azure OpenAI é utilizando uma chave de API. Para esse tipo de autenticação, todos os pedidos de API devem incluir uma chave API válida no cabeçalho HTTP api-key.

A API Management pode gerir a chave da API de forma segura, utilizando um valor nomeado.
O valor nomeado pode então ser referenciado numa política de API para definir o cabeçalho api-key nos pedidos à API do Azure OpenAI. Fornecemos dois exemplos de como fazer isso: um utiliza a política set-backend-service, e o outro utiliza a política set-header.

Armazene a chave da API num valor nomeado

Obtenha uma chave API do recurso Azure OpenAI. No portal do Azure, encontre uma chave na página Chaves e Endpoint do recurso Azure OpenAI.
Vá para a sua instância de Gestão de API e selecione valores nomeados no menu à esquerda.
Selecione + Adicionar e adicione o valor como um segredo ou, opcionalmente, para maior segurança, use uma referência do cofre de chaves.

Passar a chave da API em pedidos de API - política de configuração de serviço de back-end

Crie um back-end que aponte para a API OpenAI do Azure.
1. No menu esquerdo da sua instância de Gerenciamento de API, selecione Backends.
2. Selecione + Adicionar e insira um nome descritivo para o back-end. Exemplo: openai-backend.
3. Sob Tipo, selecione Personalizado e insira o URL do ponto de extremidade do Azure OpenAI. Exemplo: https://contoso.openai.azure.com/openai.
4. Sob Credenciais de autorização, selecione Cabeçalhos, e insira api-key como o nome do cabeçalho e o valor nomeado como o valor.
5. Selecione Criar.
Adicione o seguinte trecho de política na seção de política para passar a chave de API nas solicitações para a API do Azure OpenAI.

Neste exemplo, o recurso backend é openai-backend.
```
<set-backend-service backend-id="openai-backend" />
```

Passe a chave da API nos pedidos da API - política de definição de cabeçalho

Alternativamente, adicione o seguinte trecho de política set-header na seção de política inbound para inserir a chave da API em pedidos para a API Azure OpenAI. Este trecho de política define o cabeçalho api-key com o valor nomeado que você configurou.

Neste exemplo, o valor nomeado na Gestão de API é openai-api-key.

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

Autenticar com identidade gerida

Uma maneira alternativa e recomendada de autenticar em uma API OpenAI do Azure é usando uma identidade gerenciada no Microsoft Entra ID. Para obter plano de fundo, consulte Como configurar o Serviço OpenAI do Azure com identidade gerenciada.

A seguir estão as etapas para configurar sua instância de Gerenciamento de API para usar uma identidade gerenciada para autenticar solicitações para uma API do Azure OpenAI.

Ativar uma identidade gerida atribuída pelo sistema ou pelo utilizador para a sua instância de Gestão de API. O seguinte exemplo assume que ativou a identidade gerida atribuída pelo sistema da instância.
Atribua à identidade gerida o papel de Cognitive Services OpenAI User, com o âmbito adequado ao recurso apropriado. Por exemplo, atribua à identidade gerida pelo sistema o papel de Cognitive Services OpenAI User no recurso Azure OpenAI. Para passos detalhados, consulte Controle de acesso baseado em funções para o serviço Azure OpenAI.
Adicione o seguinte trecho de política na secção de política inbound para autenticar pedidos à API Azure OpenAI usando a identidade gerida.

Neste exemplo:
- A política authentication-managed-identity obtém um token de acesso para a identidade gerida.
- A política set-header define o cabeçalho Authorization da solicitação com o token de acesso.
```
<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> 
```

Sugestão

Uma alternativa ao uso das políticas authentication-managed-identity e set-header mostradas neste exemplo é configurar um recurso backend que direciona solicitações de API para o ponto de extremidade do Serviço OpenAI do Azure. Na configuração de back-end, habilite a autenticação de identidade gerenciada para o Serviço OpenAI do Azure. O Gerenciamento de API do Azure automatiza essas etapas ao importar uma API diretamente do Serviço OpenAI do Azure. Para obter mais informações, consulte Importar API do Serviço OpenAI do Azure.

Autorização OAuth 2.0 usando um provedor de identidade

Para permitir um acesso mais detalhado às APIs OpenAPI por utilizadores ou clientes particulares, pode pré-autorizar o acesso à API do Azure OpenAI usando autorização OAuth 2.0 com o Microsoft Entra ID ou outro fornecedor de identidade. Para mais informações, consulte Proteger uma API no Azure API Management utilizando autorização OAuth 2.0 com Microsoft Entra ID.

Nota

Use a autorização OAuth 2.0 como parte de uma estratégia de defesa em profundidade. Não é um substituto para a autenticação por chave de API ou a autenticação de identidade gerida para uma API do Azure OpenAI.

A seguir, são apresentadas etapas de alto nível para restringir o acesso à API a utilizadores ou aplicações que estejam autorizados através de um fornecedor de identidade.

Crie uma aplicação no seu fornecedor de identidade para representar a OpenAI API no Azure API Management. Se estiver a utilizar o Microsoft Entra ID, registe uma aplicação no seu inquilino do Microsoft Entra ID. Registe detalhes como o ID da aplicação e o URI do público.

Conforme necessário, configure a aplicação para ter funções ou escopos que representem as permissões detalhadas necessárias para aceder à API Azure OpenAI.

Adicione um trecho de política na sua instância de Gestão de API para validar pedidos que apresentem um token da web JSON (JWT) no cabeçalho. Coloque este trecho antes de outras inbound políticas que definir para autenticar na API Azure OpenAI.

Nota

Os exemplos a seguir mostram a estrutura geral das políticas para validar um JWT. Personalize-os de acordo com seu provedor de identidade e os requisitos de seu aplicativo e API.

validate-azure-ad-token - Se usar o Microsoft Entra ID, configure a política validate-azure-ad-token para validar o público e as declarações no JWT. Para mais detalhes, consulte a referência da política.

<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 - Se utilizar outro fornecedor de identidade, configure a política validate-jwt para validar a audiência e as reivindicações no JWT. Para mais detalhes, consulte a referência da política.

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

Saiba mais sobre Microsoft Entra ID e OAuth2.0.
Autenticar pedidos para serviços de IA do Azure

Partilhar via