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

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

Neste artigo, você aprenderá a autenticar e autorizar o acesso aos pontos de extremidade da API de IA gerenciados pelo Gerenciamento de API do Azure. Este artigo apresenta os seguintes métodos comuns:

• Autenticação – autenticar em uma API de IA utilizando políticas que empregam 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:

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

Pré-requisitos

Para seguir os exemplos 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.
• Uma implantação de modelo de IA foi adicionada à instância de API Management como uma IA. Para obter etapas de exemplo, consulte Importar uma API do Microsoft Foundry ou importar uma API de modelo de idioma.
• (Para autorização do OAuth 2.0) Permissões para criar um registro de aplicativo em um provedor de identidade, como um locatário do Microsoft Entra ID associado à sua assinatura do Azure.

Autenticar usando a chave de API

Uma maneira padrão de se autenticar em uma API de IA é 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 em um cabeçalho HTTP. O nome do cabeçalho depende da API. Por exemplo, o Azure OpenAI nas APIs do Microsoft Foundry usa o api-key cabeçalho.

• O Gerenciamento de API pode gerenciar a chave de API de forma segura usando um valor nomeado.
• Você pode referenciar o valor nomeado em uma política de API para definir o api-key cabeçalho em solicitações para a API. Os dois exemplos a seguir mostram como fazer isso: um usa a set-backend-service política e o outro usa a set-header política.

Armazenar a chave de API em um valor nomeado

Aqui está um exemplo de como armazenar uma chave de API openai do Azure em um valor nomeado no Gerenciamento de API:

1. Obtenha uma chave de API da implantação do modelo de IA. Para uma implantação de modelo do Azure OpenAI, encontre essas informações na home page do seu projeto no portal do Microsoft Foundry.
2. Acesse a instância de Gerenciamento de API e selecione Valores nomeados no menu à esquerda.
3. Selecione + Adicionar e adicione o valor como um segredo. Para obter mais segurança, opcionalmente, 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.services.ai.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

Para o Azure OpenAI e outras implantações de modelo no Microsoft Foundry, use uma identidade gerenciada na ID do Microsoft Entra para autenticar. Para obter mais informações, consulte Como configurar a OpenAI do Azure nos Modelos de Microsoft Foundry com a autenticação do Microsoft Entra ID.

Siga estas etapas para configurar sua instância de Gerenciamento de API para usar uma identidade gerenciada para autenticação.

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ê habilitou 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 a função de Usuário do OpenAI de Serviços Cognitivos à identidade gerenciada pelo sistema no recurso Microsoft Foundry. Para obter etapas detalhadas, consulte Controle de acesso baseado em função para o serviço OpenAI do Azure.

3. Adicione o seguinte snippet de política na seção de políticas inbound para autenticar solicitações à API 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 habilitar o acesso mais refinado ao Azure OpenAPI ou a outras APIs LLM por usuários ou clientes específicos, pré-autorize o acesso à API usando a autorização do OAuth 2.0 com a ID do Microsoft Entra 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.

As etapas a seguir mostram como 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 de IA 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 necessário, configure o aplicativo para ter funções ou escopos que representem as permissões refinadas necessárias para acessar a API de IA.

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 ferramentas do Foundry