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

APLICA-SE A: Todas as camadas de gerenciamento de API

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

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

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

Para mais informações, consulte:

• Referência da API REST do Azure OpenAI Service

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

Pré-requisitos

Antes de seguir as etapas neste 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 Azure OpenAI adicionados à sua instância de Gerenciamento de API. Para obter etapas de exemplo, consulte Importar uma API 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 autenticar em uma API do Azure OpenAI é usando 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 api-key cabeçalho HTTP.

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

Armazenar a chave da 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 Azure OpenAI.
2. Vá para sua instância de Gerenciamento de API e selecione Valores nomeados no menu à esquerda.
3. 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 solicitações de API - política set-backend-service

1. 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. Em Tipo, selecione Personalizado e insira a URL do ponto de extremidade do Azure OpenAI. Exemplo: https://contoso.openai.azure.com/openai.
   4. Em 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.

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

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

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

Passar a chave da API em solicitações de API - política set-header

Como alternativa, adicione o seguinte set-header trecho de inbound política na seção de política para passar a chave de API em solicitações para a API OpenAI do Azure. Este trecho de política define o api-key cabeçalho 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 a identidade gerida

Uma maneira alternativa de autenticar em uma API do Azure OpenAI 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.

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

2. Atribua à identidade gerenciada a função Usuário OpenAI dos Serviços Cognitivos, com escopo para o recurso apropriado. Por exemplo, atribua à identidade gerenciada atribuída pelo sistema a função Usuário 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 Azure OpenAI.

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

   Neste exemplo:

   • A authentication-managed-identity política obtém um token de acesso para a identidade gerenciada.
   • A set-header política define o Authorization cabeçalho 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 habilitar um acesso mais refinado às APIs da OpenAPI por usuários ou clientes específicos, você pode pré-autorizar o acesso à API do Azure OpenAI usando a autorização OAuth 2.0 com a ID do Microsoft Entra ou outro provedor de identidade. Para obter plano de fundo, consulte Proteger uma API no Gerenciamento de API do Azure usando a autorização OAuth 2.0 com a ID do Microsoft Entra.

Nota

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

A seguir estão 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 em seu provedor de identidade para representar a API OpenAI no Gerenciamento de API do Azure. Se você estiver usando o Microsoft Entra ID, registre um aplicativo em seu locatário do Microsoft Entra ID. Registre detalhes como o ID do aplicativo e o URI da audiência.

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

2. Adicione um trecho de inbound política em sua instância de Gerenciamento de API para validar solicitações que apresentam um token da Web JSON (JWT) no Authorization cabeçalho. Coloque este trecho antes de outras inbound políticas definidas para autenticar na API do 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 você usar o ID do Microsoft Entra, configure a validate-azure-ad-token política para validar a audiência e as declarações no JWT. Para obter 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 você usar outro provedor de identidade, configure a validate-jwt política para validar a audiência e as declarações no JWT. Para obter 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>
     

Conteúdos relacionados

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