Autenticação e autorização no Microsoft Foundry

A autenticação e a autorização no Microsoft Foundry controlam como usuários ou sistemas autenticam sua identidade e obtêm permissão para executar operações. A Foundry divide as operações em plano de controle (gerenciamento de recursos) e plano de dados (uso em tempo de execução), cada uma com sua própria autenticação e superfície de controle de acesso baseado em função.

A Foundry dá suporte a dois métodos de autenticação: Microsoft Entra ID e chaves de API. Microsoft Entra ID permite acesso condicional, identidades gerenciadas e RBAC granular. As chaves de API permanecem disponíveis para criação rápida, mas não têm rastreabilidade por usuário. Este artigo compara esses métodos, mapeia identidades para funções e descreve cenários de privilégios mínimos comuns.

Pré-requisitos

• Uma assinatura Azure. Se você não tiver uma, crie uma conta gratuita.
• Um recurso Microsoft Foundry com um subdomínio custom configurado.
• Compreensão dos conceitos do Azure RBAC.
• Para atribuir funções, você precisa da função Proprietário ou da função administrador de acesso do usuário no escopo apropriado.
• (Opcional) O CLI do Azure ou SDK do Azure para Python instalado para autenticação programática.
• (Opcional) pacotes do Python para exemplos de código: pip install azure-identity requests

Plano de controle e plano de dados

As operações do Azure se dividem em duas categorias: plano de controle e plano de dados. Azure separa o gerenciamento de recursos (plano de controle) do runtime operacional (plano de dados). Portanto, você usa o plano de controle para gerenciar recursos em sua assinatura e usa o plano de dados para aproveitar as funcionalidades expostas pela instância de um tipo de recurso. Para saber mais sobre o plano de controle e o plano de dados, consulte Azure plano de controle e plano de dados. Na Foundry, há uma clara distinção entre operações de plano de controle versus operações de plano de dados. A tabela a seguir explica a diferença entre os dois, o escopo no Foundry, as operações típicas de um usuário, as ferramentas de exemplo e as funcionalidades, e a superfície de autorização para uso de cada um.

Para todos os exemplos de Bicep, Terraform e SDK, consulte o repositório foundry-samples no GitHub for Foundry.

As listas e o diagrama a seguir ilustram a separação entre as ações do plano de controle e do plano de dados em detalhes. As ações do plano de controle no Foundry incluem:

• Criação de recursos de fundição
• Criação de projeto de fundimento
• Criação do Host de Funcionalidade da Conta
• criação do host de funcionalidades do Project
• Implementação de modelo
• Criação de conexão de conta e projeto

As ações do plano de dados no Foundry incluem:

• Compilando agentes
• Executando uma avaliação
• Rastreamento e monitoramento
• Ajuste fino

O diagrama a seguir ilustra a separação entre o plano de controle e o plano de dados na Foundry, juntamente com as atribuições de RBAC (controle de acesso baseado em função) e quais acessos um usuário pode ter, seja no plano de controle, no plano de dados ou em ambos. Conforme visto no diagrama, as "ações" do RBAC são associadas ao plano de controle, enquanto as "dataActions" do RBAC estão associadas ao plano de dados.

Métodos de autenticação

A Foundry dá suporte a Microsoft Entra ID (baseada em token, sem chave) e chaves de API.

Microsoft Entra ID

Microsoft Entra ID usa tokens de portador OAuth 2.0 com escopo para https://ai.azure.com/.default.

Use Microsoft Entra ID para:

• Cargas de trabalho de produção.
• Acesso condicional, MFA (autenticação multifator) e acesso just-in-time.
• Integração de RBAC com privilégio mínimo e identidade gerenciada.

Vantagens: atribuições de função detalhadas, auditoria por usuário, vida útil do token controlável, manutenção automática de segredos e identidades gerenciadas para serviços.

Limitações: maior complexidade de configuração inicial. Requer compreensão do RBAC (controle de acesso baseado em função). Para obter mais informações sobre o RBAC no Foundry, consulte Controle de acesso baseado em função para Microsoft Foundry.

Chaves de API

As chaves de API são segredos estáticos no escopo de um recurso Foundry.

Use chaves de API para:

• Prototipagem rápida.
• Ambientes de teste isolados em que a rotação de segredo único é aceitável.

Vantagens: simples, independente de linguagem e não requer aquisição de token.

Limitações: não é possível expressar a identidade do usuário, é difícil de definir o escopo granularmente e é mais difícil de auditar. Geralmente não é aceito pelas cargas de trabalho de produção da empresa e não é recomendado por Microsoft.

Para obter mais informações sobre como habilitar a autenticação sem chave, consulte Configure key-less authentication with Microsoft Entra ID.

Autenticar com Microsoft Entra ID (Python)

O exemplo a seguir mostra como autenticar com o Microsoft Entra ID usando a biblioteca azure-identity e fazer uma solicitação para um ponto de extremidade Foundry.

from azure.identity import DefaultAzureCredential
import requests

# Create a credential object using DefaultAzureCredential
# This automatically uses environment variables, managed identity, or Azure CLI credentials
credential = DefaultAzureCredential()

# Get an access token for the Cognitive Services scope
token = credential.get_token("https://ai.azure.com/.default")

# Use the token in your API request
headers = {
    "Authorization": f"Bearer {token.token}",
    "Content-Type": "application/json"
}

# Replace with your Foundry endpoint
endpoint = "https://<your-resource-name>.cognitiveservices.azure.com"

# Example: List deployments (adjust the path for your specific API)
response = requests.get(f"{endpoint}/openai/deployments?api-version=2024-10-21", headers=headers)
print(response.json())

Saída esperada: uma resposta JSON listando suas implantações de modelo ou um erro de autenticação se as credenciais estiverem ausentes ou a atribuição de função não estiver configurada.

Referência:Biblioteca de identidade do Azure |

Autenticar com uma chave de API (Python)

O exemplo a seguir mostra como autenticar usando uma chave de API. Use essa abordagem somente para protótipos rápidos; Microsoft Entra ID é recomendado para produção.

import requests

# Replace with your actual API key and endpoint
api_key = "<your-api-key>"
endpoint = "https://<your-resource-name>.cognitiveservices.azure.com"

headers = {
    "api-key": api_key,
    "Content-Type": "application/json"
}

# Example: List deployments
response = requests.get(f"{endpoint}/openai/deployments?api-version=2024-10-21", headers=headers)
print(response.json())

Saída esperada: uma resposta JSON listando suas implantações de modelo ou um erro 401 se a chave de API for inválida.

Referência: Alternar chaves de acesso à API

Matriz de suporte a recursos

Consulte a matriz a seguir para entender quais capacidades no Foundry suportam a chave de API versus o Microsoft Entra ID.

Tipos de identidade

Azure recursos e aplicativos se autenticam usando diferentes tipos de identidade, cada um projetado para cenários específicos. Principais de usuário representam usuários humanos, principais de serviço representam aplicativos ou processos automatizados, e identidades gerenciadas fornecem uma maneira segura e livre de credenciais para que recursos do Azure acessem outros serviços. Entender essas distinções ajuda você a escolher a identidade certa para entradas interativas, comunicação entre aplicativos ou automação de carga de trabalho.

Azure dá suporte aos seguintes tipos de identidade.

Visão geral das funções integradas

No Foundry, use as funções integradas para separar as ações permitidas para um usuário. A maioria das empresas deseja uma separação de ações de controle e plano de dados para suas funções internas. Outros esperam que uma função de plano de controle e dados combinados minimize o número de atribuições de função necessárias. A tabela a seguir lista os cenários e as funções internas do Foundry correspondentes que adequam-se melhor a cada cenário.

Para entender a divisão de funções internas e as ações de controle e plano de dados, examine o diagrama a seguir.

Configurar Microsoft Entra ID

Para obter orientações de alto nível sobre como configurar a autenticação Entra ID na Foundry, consulte Configuração sem chave.

1. Verifique se o recurso Microsoft Foundry tem um subdomínio personalizado configurado. Consulte subdomínios personalizados. Um subdomínio personalizado é necessário para autenticação baseada em token.

2. Atribua a função interna ou personalizada necessária a cada principal. Você precisa da função proprietário ou administrador de acesso de usuário no escopo de destino para atribuir funções. Atribuições de função comuns:

   • Usuário de Azure AI: para desenvolvedores que precisam desenvolver e testar com modelos pré-implantados.
   • Azure AI Project Manager: para líderes de equipe que precisam criar projetos e gerenciar implantações.
   • Azure Proprietário da Conta de IA: para administradores que precisam de gerenciamento completo de recursos e podem atribuir condicionalmente Azure usuário de IA para acesso ao plano de dados.
   • Azure Proprietário de IA: para usuários que precisam de gerenciamento completo de recursos e acesso ao plano de dados. Exemplo de comando da CLI para atribuir a função de usuário de IA Azure:

   az role assignment create \
     --assignee <principal-id> \
     --role "Azure AI User" \
     --scope /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<resource-name>
   

   Para verificar a atribuição de função, execute az role assignment list --assignee <principal-id> --scope <resource-scope> e confirme se a função aparece na saída.

3. (Opcional) Para uma entidade de serviço, crie um registro de aplicativo, adicione um segredo ou certificado do cliente e anote a ID do locatário, a ID do cliente e o segredo ou certificado.

4. (Opcional) Para uma identidade gerenciada, habilite a identidade atribuída pelo sistema no serviço de chamada ou anexe uma identidade atribuída pelo usuário e atribua uma função a ela no recurso Foundry.

5. Remova a autenticação baseada em chave depois que todos os chamadores usarem a autenticação de token. Opcionalmente, desabilite a autenticação local em modelos de implantação.

Referência: Atribuir funções do Azure | Controle de acesso baseado em função para Foundry

Solucionar problemas de erros comuns de autenticação

Conteúdo relacionado

• Controle de acesso baseado em função para o Foundry
• Configure a autenticação sem chave com o Microsoft Entra ID
• Rotacionar chaves de acesso à API
• Azure funções internas (IA + machine learning)
• Autenticação vs. autorização (Microsoft Entra ID)
• Conceitos básicos de identidade