Autenticar e autorizar o acesso às APIs do OpenAI do Azure usando o Gerenciamento de API do Azure

APLICA-SE A: todas as camadas do Gerenciamento de API

Neste artigo, você aprenderá sobre maneiras de autenticar e autorizar os pontos de extremidade da API do OpenAI do Azure que são gerenciados usando o Gerenciamento de API do Azure. Este artigo apresenta os seguintes métodos comuns:

• Autenticação – Autenticar em uma API do OpenAI do Azure usando políticas que se autenticam usando uma chave de API ou uma identidade gerenciada do Microsoft Entra ID.

• Autorização – Para se ter controle de acesso mais refinado, pré-autorize as solicitações que passam os tokens OAuth 2.0 gerados por um provedor de identidade, como o Microsoft Entra ID.

Para obter o plano de fundo, consulte:

• Referência de API REST do Serviço OpenAI do Azure

• Autenticação e autorização para APIs no Gerenciamento de API.

Pré-requisitos

Antes de seguir as etapas deste artigo, você deve ter:

• Uma instância de Gerenciamento de API. Para obter etapas de exemplo, consulte Criar uma instância de Gerenciamento de API do Azure.
• Um recurso e um modelo do OpenAI do Azure adicionados à instância de Gerenciamento de API. Por exemplo, consulte Importar uma API do OpenAI do Azure como uma API REST.
• Permissões para criar um registro de aplicativo em um provedor de identidade, como um locatário do Microsoft Entra associado à sua assinatura do Azure (para autorização do OAuth 2.0).

Autenticar com a chave de API

Uma maneira padrão de se autenticar em uma API do OpenAI do Azure é usar uma chave de API. Para esse tipo de autenticação, todas as solicitações de API devem incluir uma chave de API válida no cabeçalho HTTP api-key.

• O Gerenciamento de API pode gerenciar a chave de API de forma segura usando um valor nomeado.
• Em seguida, o valor nomeado pode ser referenciado em uma política de API para definir o cabeçalho api-key nas solicitações na API do OpenAI do Azure. Fornecemos dois exemplos de como fazer isso: um usa a política set-backend-service e o outro usa a política set-header.

Armazenar a chave de API em um valor nomeado

1. Obtenha uma chave de API do recurso OpenAI do Azure. No portal do Azure, localize uma chave na página Chaves e Ponto de Extremidade do recurso OpenAI do Azure.
2. Acesse a instância de Gerenciamento de API e selecione Valores nomeados no menu à esquerda.
3. Selecione + Adicionare adicione o valor como um segredo ou, opcionalmente, para obter mais segurança, use uma referência de cofre de chaves.

Passe a chave de API nas solicitações de API – política de set-backend-service

1. Crie um back-end que aponte para a API do OpenAI do Azure.

   1. No menu à esquerda da sua instância de Gerenciamento de API, selecione Back-ends.
   2. Selecione + Adicionare insira um nome descritivo para o back-end. Exemplo: openai-back-end.
   3. Em Tipo, selecione Personalizado e insira a URL do ponto de extremidade do OpenAI do Azure. Exemplo: https://contoso.openai.azure.com/openai.
   4. Em Credenciais de autorização, selecione Cabeçalhose insira api-key como o nome do cabeçalho e o valor nomeado como o valor.
   5. Selecione Criar.

2. Adicione o seguinte snippet de política set-backend-service na seção de política inbound para passar a chave de API nas solicitações para a API do OpenAI do Azure.

   Neste exemplo, o recurso de back-end é openai-back-end.

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

Passe a chave de API nas solicitações de API – política de set-header

Como alternativa, adicione o seguinte snippet de política set-header na seção de política inbound para passar a chave de API nas solicitações para a API do OpenAI do Azure. Esse snippet de política define o cabeçalho api-key com o valor nomeado que você configurou.

Neste exemplo, o valor nomeado no Gerenciamento de API é openai-api-key.

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

Autenticar com identidade gerenciada

Uma maneira alternativa de se autenticar em uma API do OpenAI do Azure usando uma identidade gerenciada no Microsoft Entra ID. Para obter informações em segundo plano, consulte Como configurar o Serviço OpenAI do Azure com a identidade gerenciada.

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

1. Habilitar uma identidade gerenciada atribuída pelo sistema ou pelo usuário para a sua instância do Gerenciamento de API. O exemplo a seguir pressupõe que você tenha ativado a identidade gerenciada atribuída pelo sistema da instância.

2. Atribua a identidade gerenciada à função de Usuário do OpenAI dos Serviços Cognitivos, com escopo para o recurso apropriado. Por exemplo, atribua à identidade gerenciada atribuída pelo sistema a função de Usuário do OpenAI dos Serviços Cognitivos no recurso OpenAI do Azure. Para obter etapas detalhadas, consulte Controle de acesso baseado em função para o serviço OpenAI do Azure.

3. Adicione o snippet de política a seguir na seção de política inbound para autenticar as solicitações na API do OpenAI do Azure usando a identidade gerenciada.

   Neste exemplo:

   • A política authentication-managed-identity obtém um token de acesso para a identidade gerenciada.
   • 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> 
   

Autorização do OAuth 2.0 usando o provedor de identidade

Para permitir um acesso mais refinado às APIs do OpenAPI por usuários ou clientes específicos, você pode pré-autorizar o acesso à API do OpenAI do Azure usando a autorização do OAuth 2.0 com o Microsoft Entra ID ou outro provedor de identidade. Para obter informações em segundo plano, consulte Proteger uma API no Gerenciamento de API do Azure usando a autorização do OAuth 2.0 com o Microsoft Entra ID.

Observação

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

Veja a seguir as etapas de alto nível para restringir o acesso à API a usuários ou aplicativos autorizados usando um provedor de identidade.

1. Crie um aplicativo no seu provedor de identidade para representar a API do OpenAI no Gerenciamento de API do Azure. Se você estiver usando o Microsoft Entra ID, registre um aplicativo no locatário do Microsoft Entra ID. Registre detalhes, como a ID do aplicativo e o URI do público-alvo.

   Conforme for necessário, configure o aplicativo para ter funções ou escopos que representem as permissões refinadas necessárias para acessar a API do OpenAI do Azure.

2. Adicione um snippet de política inbound na sua instância de Gerenciamento de API para validar as solicitações que apresentam um token Web JSON (JWT) no cabeçalho Authorization. Coloque esse snippet antes de outras políticas inbound que você definiu para autenticar na API do OpenAI do Azure.

   Observação

   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 com os requisitos do seu aplicativo e API.

   • validate-azure-ad-token - Se você usar o Microsoft Entra ID, configure a política validate-azure-ad-token para validar o público-alvo e as declarações no JWT. Para obter mais detalhes, consulte a referência de 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 você usar outro provedor de identidade, configure a política validate-jwt para validar o público-alvo e as declarações no JWT. Para obter mais detalhes, consulte a referência de 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>
     

Conteúdo relacionado

• Saiba mais sobre o Microsoft Entra ID e o OAuth2.0.
• Autenticar solicitações para os serviços de IA do Azure
• Proteger as chaves do OpenAI do Azure com o Gerenciamento de API