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

A autenticação e a autorização no Microsoft Foundry controlam como os principais provam a identidade e obtêm permissão para realizar operações. O Foundry divide as operações em plano de controlo (gestão de recursos) e plano de dados (utilização em tempo de execução), cada um com a sua própria superfície de autenticação e controlo de acesso baseado em funções (RBAC).

O Foundry suporta dois métodos de autenticação: Microsoft Entra ID e chaves API. O Microsoft Entra ID permite acesso condicional, identidades geridas e RBAC granular. As chaves API continuam disponíveis para prototipagem rápida, mas carecem de rastreabilidade por utilizador. Este artigo compara estes métodos, mapeia identidades a funções e descreve cenários usuais de mínima utilização de privilégios.

Pré-requisitos

• Uma subscrição do Azure. Se não tiveres uma, cria uma conta gratuita.
• Um recurso Microsoft Foundry com um subdomínio personalizado configurado.
• Compreensão dos conceitos Azure RBAC.
• Para atribuir funções, precisa do papel de Proprietário ou de Administrador de Acesso ao Utilizador no âmbito apropriado.
• (Opcional) O CLI do Azure ou SDK do Azure para Python instalado para autenticação programática.
• (Opcional) Pacotes Python para exemplos de código: pip install azure-identity requests

Plano de controlo e plano de dados

As operações do Azure dividem-se em duas categorias: plano de controlo e plano de dados. O Azure separa a gestão de recursos (plano de controlo) do runtime operacional (plano de dados). Assim, utiliza o plano de controlo para gerir os recursos na sua subscrição e o plano de dados para aceder às capacidades apresentadas pela sua instância de um tipo de recurso. Para saber mais sobre plano de controlo e plano de dados, consulte Azure plano de controlo e plano de dados. No Foundry, há uma distinção clara entre operações no plano de controlo e operações no plano de dados. A tabela seguinte explica a diferença entre os dois, o âmbito no Foundry, as operações típicas de um utilizador, ferramentas e funcionalidades de exemplo, e a superfície de autorização para usar cada uma.

Para todas as amostras Bicep, Terraform e SDK, consulte o repositório foundry-samples em GitHub para Foundry.

As listas e o diagrama seguintes ilustram em detalhe a separação entre as ações do plano de controlo e do plano de dados. As ações do plano de controlo dentro da Foundry incluem:

• Criação de recursos na fundição
• Criação de projetos de fundição
• Criação de Servidor de Capacidade de Conta
• Criação de Project Capability Host
• Implementação do modelo
• Criação de ligações à conta e ao projeto

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

• Agentes de construção
• Realização de uma avaliação
• Rastreamento e monitorização
• Afinação

O diagrama seguinte mostra a perspetiva da separação entre plano de controlo e plano de dados no Foundry, juntamente com as atribuições de controlo de acesso baseado em funções (RBAC), e que acesso um utilizador pode ter no plano de controlo, no plano de dados ou em ambos. Como se vê no diagrama, as "ações" do RBAC estão associadas ao plano de controlo, enquanto as "dataActions" do RBAC estão associadas ao plano de dados.

Métodos de autenticação

O Foundry suporta Microsoft Entra ID (baseado em token, sem chave) e chaves API.

Microsoft Entra ID

Microsoft Entra ID utiliza tokens portadores OAuth 2.0 direcionados para https://ai.azure.com/.default.

Use o Microsoft Entra ID para:

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

Vantagens: atribuições de funções detalhadas, auditoria por principal, tempo de vida controlável dos tokens, higiene secreta automática e identidades geridas para serviços.

Limitações: Maior complexidade inicial de configuração. Requer compreensão do controlo de acesso baseado em funções (RBAC). Para mais informações sobre RBAC no Foundry, veja Controlo de acesso baseado em funções para Microsoft Foundry.

Chaves API

As chaves API são segredos estáticos direcionados a um recurso da Foundry.

Utilize as chaves da API para:

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

Vantagens: Simples, independente da linguagem e não requer aquisição de tokens.

Limitações: Não é possível expressar a identidade do utilizador, é difícil de definir detalhadamente e é mais difícil de auditar. Geralmente não é aceite por cargas de trabalho de produção empresariais e não é recomendado pela Microsoft.

Para mais informações sobre como ativar a autenticação sem chave, veja Configure autenticação sem chave com Microsoft Entra ID.

Autenticar com Microsoft Entra ID (Python)

O exemplo seguinte mostra como autenticar com Microsoft Entra ID usando a biblioteca azure-identity e fazer um pedido a um endpoint 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())

Resultado esperado: Uma resposta JSON a listar as implementações dos seus modelos, ou um erro de autenticação se faltarem credenciais ou se a atribuição de funções não estiver configurada.

Referência: DefaultAzureCredential | azure-identity library

Autenticar com uma chave API (Python)

O exemplo seguinte mostra como autenticar usando uma chave API. Use esta abordagem apenas para prototipagem rápida; Recomenda-se o Microsoft Entra ID 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 a listar as implementações dos seus modelos, ou um erro 401 se a chave API for inválida.

Referência: Alternar chaves de acesso API

Matriz de suporte a funcionalidades

Consulte a seguinte matriz para perceber que capacidades do Foundry suportam a chave API em comparação com o Microsoft Entra ID.

Tipos de identidade

Os recursos e aplicações do Azure autenticam-se utilizando diferentes tipos de identidade, cada um desenhado para cenários específicos. Os principais utilizadores representam utilizadores humanos, os principais de serviço representam aplicações ou processos automatizados, e as identidades geridas fornecem uma forma segura e livre de credenciais para os recursos do Azure acedirem a outros serviços. Compreender estas distinções ajuda-o a escolher a identidade certa para logins interativos, comunicação app a app ou automação de cargas de trabalho.

O Azure suporta os seguintes tipos de identidade.

Visão geral das funções incorporadas

No Foundry, use os papéis incorporados para separar as ações permitidas para um utilizador. A maioria das empresas quer uma separação entre as ações de controlo e plano de dados para as suas funções integradas. Outros esperam um papel combinado de plano de dados e de controlo para minimizar o número de atribuições de funções necessárias. A tabela seguinte lista os cenários e os papéis incorporados correspondentes na Foundry que melhor se ajustam a cada cenário.

Para compreender a divisão dos papéis incorporados e as ações do plano de controlo e de dados, consulte o diagrama seguinte.

Configurar o Microsoft Entra ID

Para orientações de alto nível sobre a configuração da autenticação Entra ID no Foundry, consulte Configurar autenticação sem chave.

1. Certifique-se de que o seu recurso Microsoft Foundry tem um subdomínio personalizado configurado. Ver Subdomínios personalizados. É necessário um subdomínio personalizado para autenticação baseada em tokens.

2. Atribua a função incorporada ou personalizada necessária a cada principal. É necessário o papel de Proprietário ou Administrador de Acesso ao Utilizador no âmbito alvo para atribuir funções. Atribuições comuns de funções:

   • Azure AI User: Para programadores que precisam de construir e testar com modelos pré-implementados.
   • Azure AI Project Manager: Para líderes de equipa que precisam de criar projetos e gerir implementações.
   • Azure Proprietário da Conta IA: Para administradores que precisam de gestão total de recursos e podem atribuir condicionalmente Azure Utilizador IA para acesso ao plano de dados.
   • Azure AI Owner: Para utilizadores que necessitam tanto de gestão total de recursos como de acesso ao plano de dados. Exemplo de comando CLI para atribuir o papel de Utilizador IA do 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ções, execute az role assignment list --assignee <principal-id> --scope <resource-scope> e confirme que a função aparece na saída.

3. (Opcional) Para um principal de serviço, crie um registo de aplicação, adicione um cliente secreto ou certificado, e indique o ID do inquilino, o ID do cliente e o segredo ou certificado.

4. (Opcional) Para uma identidade gerida, ativa a identidade atribuída ao sistema no serviço chamador ou anexa uma identidade atribuída pelo utilizador, depois atribui-lhe um papel no recurso Foundry.

5. Remover a autenticação baseada em chave depois de todos os chamadores usarem autenticação por token. Opcionalmente, desative a autenticação local nos templates de implementação.

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

Resolução de erros comuns de autenticação

Conteúdo relacionado

• Controlo de acesso baseado em funções para a Foundry
• Configurar autenticação sem chave com Microsoft Entra ID
• Alternar chaves de acesso API
• Azure funções incorporadas (IA + aprendizagem automática)
• Autenticação vs. autorização (Microsoft Entra ID)
• Fundamentos da identidade