Partilhar via

Autentique e autorize o acesso a APIs LLM utilizando o Azure API Management

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

Neste artigo, aprende como autenticar e autorizar o acesso a endpoints de API de IA que a Azure API Management gere. Este artigo apresenta os seguintes métodos comuns:

  • Autenticação - Autentifique numa API de IA utilizando políticas que utilizam uma chave API ou uma identidade gerida com ID Microsoft Entra.

  • 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

Para seguir os exemplos deste artigo, deve ter:

Autentifique usando a chave API

Uma forma padrão de autenticar numa API de IA é usando uma chave de API. Para este tipo de autenticação, todos os pedidos de API devem incluir uma chave API válida num cabeçalho HTTP. O nome do cabeçalho depende da API. Por exemplo, o Azure OpenAI nas APIs Microsoft Foundry usa o api-key cabeçalho.

  • A Gestão de APIs pode gerir a chave API de forma segura usando um valor nomeado.
  • Pode referenciar o valor nomeado numa política de API ao definir o api-key cabeçalho nas solicitações para a API. Os dois exemplos seguintes mostram como fazer isto: um usa a set-backend-service política e o outro usa a set-header política.

Armazene a chave da API num valor nomeado

Aqui está um exemplo de como armazenar uma chave API do Azure OpenAI num valor nomeado na API Management:

  1. Obtenha uma chave API da implementação do modelo de IA. Para a implementação de um modelo Azure OpenAI, encontre esta informação na página inicial do seu projeto no portal Microsoft Foundry.
  2. Vá para a sua instância de Gestão de API e selecione valores nomeados no menu à esquerda.
  3. Selecionar + Adicionar e adicionar o valor como segredo. Para mais segurança, use opcionalmente uma referência de cofre de chaves.

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

  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. Sob Tipo, selecione Personalizado e insira o URL do ponto de extremidade do Azure OpenAI. Exemplo: https://contoso.services.ai.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.

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

Para Azure OpenAI e outras implementações de modelos no Microsoft Foundry, use uma identidade gerida no Microsoft Entra ID para autenticar. Para contextualizar, veja Como configurar Azure OpenAI em Modelos Microsoft Foundry com autenticação Microsoft Entra ID.

Siga estes passos para configurar a sua instância de Gestão de API para usar uma identidade gerida para autenticação.

  1. Ativar uma identidade gerida atribuída pelo sistema ou pelo utilizador para a sua instância de Gestão de API. O exemplo seguinte assume que ativou a identidade gerida atribuída pelo sistema à instância.

  2. Atribua à identidade gerida o papel de Cognitive Services OpenAI User, com o âmbito adequado ao recurso apropriado. Por exemplo, atribuir à identidade gerida atribuída pelo sistema o papel de Utilizador OpenAI de Serviços Cognitivos no recurso Microsoft Foundry. Para passos detalhados, consulte Controle de acesso baseado em funções para o serviço Azure OpenAI.

  3. Adicione o seguinte excerto de política na inbound secção de políticas para autenticar pedidos na API usando a identidade gerida.

    Neste exemplo:

    <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

Em vez de usar as authentication-managed-identity políticas e set-header mostradas neste exemplo, pode configurar um recurso backend que encaminhe os pedidos de API para o endpoint do serviço de IA. Na configuração backend, configure credenciais de identidade gerida para o https://cognitiveservices.azure.com/ recurso. O Azure API Management automatiza estes passos quando importa uma API diretamente do Microsoft Foundry.

Autorização OAuth 2.0 usando o fornecedor de identidade

Para permitir um acesso mais detalhado ao Azure OpenAPI ou outras APIs LLM por utilizadores ou clientes específicos, pré-autorize o acesso à API usando autorização OAuth 2.0 com 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.

Observação

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.

Os passos seguintes mostram como restringir o acesso à API a utilizadores ou aplicações autorizadas por um fornecedor de identidade.

  1. Crie uma aplicação no seu fornecedor de identidade para representar a API de IA 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 papéis ou escopos que representem as permissões detalhadas necessárias para aceder à API de IA.

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

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

Conteúdo relacionado

  • Last updated on