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

A autenticação e a autorização no Microsoft Foundry controlam como as entidades comprovam sua identidade e obtêm permissão para executar operações. O Foundry divide as operações em plano de controle (gerenciamento de recursos) e plano de dados (uso de runtime), cada um com sua própria autenticação e superfície de RBAC (controle de acesso baseado em função).

A Foundry dá suporte a dois métodos de autenticação: ID do Microsoft Entra e chaves de API. A ID do Microsoft Entra 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 do Azure. Se você não tiver uma, crie uma conta gratuita.
• Um recurso do Microsoft Foundry com um subdomínio personalizado configurado.
• Noções básicas sobre os conceitos do RBAC do Azure.
• 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) A CLI do Azure ou o 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. O 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 o plano de controle e o plano de dados do Azure. 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 para o 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 de host do Project Capability
• Implementação de modelo
• Criação de conexão de conta e projeto

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

• Agentes de construção
• 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 à ID do Microsoft Entra (baseada em token, sem chave) e chaves de API.

Microsoft Entra ID

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

Use o ID do Microsoft Entra para:

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

Vantagens: atribuições de funções refinadas, auditoria por entidade de segurança, tempos de vida de token controláveis, higiene de segredos automática 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 o controle de acesso baseado em função para o 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 são aceitas por cargas de trabalho de produção corporativa e não são recomendadas pela Microsoft.

Para obter mais informações sobre como habilitar a autenticação sem chave, consulte Configurar autenticação sem chave com a ID do Microsoft Entra.

Autenticar com a ID do Microsoft Entra (Python)

O exemplo a seguir mostra como autenticar com Microsoft Entra ID usando a biblioteca azure-identity e fazer uma solicitação para um endpoint do 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; A ID do Microsoft Entra é recomendada 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 funcionalidades no Foundry suportam a chave de API em comparação com a ID do Microsoft Entra.

Tipos de identidade

Os recursos e os aplicativos do Azure são autenticados usando diferentes tipos de identidade, cada um projetado para cenários específicos. As principais de usuário representam usuários humanos, as principais de serviço representam aplicativos ou processos automatizados e as identidades gerenciadas fornecem uma maneira segura e sem credenciais para que os 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.

O Azure dá suporte aos seguintes tipos de identidade.

Visão geral das funções integradas

No Foundry, use as funções internas 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 uma função combinada de plano de dados e controle para minimizar 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 a ID do Microsoft Entra

Para obter orientações de alto nível sobre como configurar a autenticação de ID do Entra no Foundry, consulte Configurar autenticaçã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 integrada ou personalizada necessária a cada entidade 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 do Foundry: para desenvolvedores que precisam criar e testar com modelos pré-implantados.
   • Foundry Project Manager: Para líderes de equipe que precisam criar projetos e gerenciar implantações.
   • Proprietário da conta do Foundry: para administradores que precisam do gerenciamento completo de recursos e podem atribuir condicionalmente o Usuário do Foundry para acesso ao plano de dados.
   • Proprietário do Foundry: 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 do Foundry:

   az role assignment create \
     --assignee <principal-id> \
     --role "53ca6127-db72-4b80-b1b0-d745d6d5456d" \
     --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.

1. (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.
2. (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.
3. 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 o Foundry

Solucionar problemas de erros comuns de autenticação

Conteúdo relacionado

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