As solicitações de aplicativo para a maioria dos serviços do Azure devem ser autenticadas com chaves ou conexões sem senha. Os desenvolvedores devem ser diligentes para nunca expor as chaves em um local não seguro. Qualquer pessoa que obtenha acesso à chave pode autenticar-se no serviço. A autenticação sem chave oferece benefícios aprimorados de gerenciamento e segurança em relação à chave da conta, pois não há nenhuma chave (ou cadeia de conexão) para armazenar.
As conexões sem chave são habilitadas com as seguintes etapas:
- Configure sua autenticação.
- Defina variáveis de ambiente, conforme necessário.
- Use um tipo de credencial de biblioteca de Identidade do Azure para criar um objeto de cliente do Azure OpenAI.
Autenticação
A autenticação para o Microsoft Entra ID é necessária para usar as bibliotecas de cliente do Azure.
A autenticação difere com base no ambiente em que o aplicativo está sendo executado:
Bloco de construção sem chave do Azure OpenAI
Use o link a seguir para explorar o modelo Azure OpenAI Keyless Building Block AI. Este modelo provisiona uma conta do Azure OpenAI com sua permissão de função RBAC da conta de usuário para autenticação sem chave (Microsoft Entra) para acessar os SDKs da API OpenAI.
Nota
Este artigo usa um ou mais modelos de aplicativo de IA como base para os exemplos e orientações no artigo. Os modelos de aplicativos de IA fornecem implementações de referência bem mantidas e fáceis de implantar que ajudam a garantir um ponto de partida de alta qualidade para seus aplicativos de IA.
Explore o modelo .NET End to end do Azure OpenAI Keyless Authentication Building Block AI.
Explore o modelo Go End to end do Azure OpenAI Keyless Authentication Building Block AI.
Explore o modelo Java End to end do Azure OpenAI Keyless Authentication Building Block AI.
Explore o modelo JavaScript End to end do Azure OpenAI Keyless Authentication Building Block AI.
Explore o modelo Python End to end do Azure OpenAI Keyless Authentication Building Block AI.
Autenticar para desenvolvimento local
Autenticar para ambientes hospedados no Azure
Encontre a função para seu uso do Azure OpenAI. Dependendo de como você pretende definir essa função, você precisa do nome ou da ID.
| Nome da função |
ID da função |
| Para a CLI do Azure ou o Azure PowerShell, você pode usar o nome da função. |
Para o Bicep, você precisa do ID da função. |
Use a tabela a seguir para selecionar uma função e um ID.
| Caso de utilização |
Nome da função |
ID da função |
| Assistants |
Cognitive Services OpenAI Contributor |
a001fd3d-188f-4b5d-821b-7da978bf7442 |
| Conclusão do chat |
Cognitive Services OpenAI User |
5e0bd9bd-7b93-4f28-af87-19fc36ad61bd |
Selecione um tipo de identidade a ser usado.
-
Identidade pessoal: sua identidade pessoal vinculada ao seu logon no Azure.
-
Identidade gerenciada: uma identidade gerenciada e criada para uso no Azure. Para identidade gerenciada, crie uma identidade gerenciada atribuída pelo usuário. Ao criar a identidade gerenciada, você precisa do
Client ID, também conhecido como app ID.
Para encontrar sua identidade pessoal, use um dos seguintes comandos. Use o ID como o <identity-id> na próxima etapa.
Para o desenvolvimento local, para obter seu próprio ID de identidade, use o seguinte comando. Você precisa entrar com az login antes de usar este comando.
az ad signed-in-user show \
--query id -o tsv
Para o desenvolvimento local, para obter seu próprio ID de identidade, use o seguinte comando. Você precisa entrar com Connect-AzAccount antes de usar este comando.
(Get-AzContext).Account.ExtendedProperties.HomeAccountId.Split('.')[0]
A identidade da pessoa ou serviço que executa a implantação é definida como o parâmetro ao usar o principalIdBicep implantado com a CLI do Desenvolvedor do Azure.
A variável a seguir main.parameters.json é definida como a identidade que executa o processo.
"principalId": {
"value": "${AZURE_PRINCIPAL_ID}"
},
Para uso no Azure, especifique uma identidade gerenciada atribuída pelo usuário como parte do processo de implantação do Bicep. Crie uma identidade gerenciada atribuída pelo usuário separada da identidade que executa o processo.
resource userAssignedManagedIdentity 'Microsoft.ManagedIdentity/userAssignedIdentities@2018-11-30' = {
name: managedIdentityName
location: location
}
Use as etapas encontradas aqui: localize a ID do objeto de usuário no portal do Azure.
Atribua a função RBAC (controle de acesso baseado em função) à identidade do grupo de recursos.
Para conceder suas permissões de identidade ao seu recurso por meio do RBAC, atribua uma função usando o comando az role assignment create da CLI do Azure.
az role assignment create \
--role "Cognitive Services OpenAI User" \
--assignee "<identity-id>" \
--scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>"
Para conceder permissões ao seu aplicativo para seu recurso do Azure OpenAI por meio do RBAC, atribua uma função usando o cmdlet New-AzRoleAssignment do Azure PowerShell.
New-AzRoleAssignment -ObjectId "<identity-id>" -RoleDefinitionName "Cognitive Services OpenAI User" -Scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>"
Use o seguinte modelo do Azure OpenAI Bicep para criar o recurso e definir a autenticação para o identityId. O bíceps requer o ID da função. O name mostrado neste trecho do Bicep não é a função do Azure, é específica para a implantação do Bicep.
// main.bicep
param environment string = 'production'
// USER ROLES
module openAiRoleUser 'core/security/role.bicep' = {
scope: openAiResourceGroup
name: 'openai-role-user'
params: {
principalId: (environment == 'development') ? principalId : userAssignedManagedIdentity
principalType: (environment == 'development') ? 'User' : 'ServicePrincipal'
roleDefinitionId: '5e0bd9bd-7b93-4f28-af87-19fc36ad61bd'
}
}
O seguinte Bíceps genérico é chamado a main.bicep partir do para criar qualquer função.
// core/security/role.bicep
metadata description = 'Creates a role assignment for an identity.'
param principalId string // passed in from main.bicep identityId
@allowed([
'Device'
'ForeignGroup'
'Group'
'ServicePrincipal'
'User'
])
param principalType string = 'ServicePrincipal'
param roleDefinitionId string
resource role 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
name: guid(subscription().id, resourceGroup().id, principalId, roleDefinitionId)
properties: {
principalId: principalId
principalType: principalType
roleDefinitionId: resourceId('Microsoft.Authorization/roleDefinitions', roleDefinitionId)
}
}
Use as etapas encontradas em abrir a página Adicionar atribuição de função no portal do Azure.
Quando aplicável, substitua <identity-id>, <subscription-id>e <resource-group-name> pelos seus valores reais.
Para se conectar ao Azure OpenAI, seu código precisa conhecer seu ponto de extremidade de recurso e pode precisar de outras variáveis de ambiente.
Crie uma variável de ambiente para seu ponto de extremidade do Azure OpenAI.
-
AZURE_OPENAI_ENDPOINT: Esta URL é o ponto de acesso para o seu recurso Azure OpenAI.
Crie variáveis de ambiente com base no local em que seu aplicativo é executado:
| Location |
Identidade |
Description |
| Local |
Pessoal |
Para tempos de execução locais com sua identidade pessoal, entre para criar sua credencial com uma ferramenta. |
| Cloud do Azure |
Identidade gerida atribuída pelo utilizador |
Crie uma AZURE_CLIENT_ID variável de ambiente contendo a ID do cliente da identidade gerenciada atribuída pelo usuário para autenticar como. |
Instalar a biblioteca de cliente do Azure Identity
Use o link a seguir para instalar a biblioteca de cliente do Azure Identity.
Instale a biblioteca de cliente Go Azure Identity:
go get -u github.com/Azure/azure-sdk-for-go/sdk/azidentity
Instale a biblioteca de cliente Java Azure Identity com o seguinte arquivo POM:
<dependencyManagement>
<dependencies>
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-identity</artifactId>
<version>1.10.0</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
Usar DefaultAzureCredential
A biblioteca de Identidade do DefaultAzureCredential Azure permite que o cliente execute o mesmo código no ambiente de desenvolvimento local e na Nuvem do Azure.
Para obter mais informações sobre o DefaultAzureCredential para .NET, consulte a visão geral do DefaultAzureCredential.
Execute uma das seguintes abordagens para definir o ID do cliente da identidade gerenciada atribuída pelo usuário:
Definir variável de ambiente AZURE_CLIENT_ID. O construtor sem parâmetros de DefaultAzureCredential usa o valor dessa variável de ambiente, se presente.
using Azure;
using Azure.AI.OpenAI;
using Azure.Identity;
using System;
using static System.Environment;
string endpoint = GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT");
OpenAIClient client = new(new Uri(endpoint), new DefaultAzureCredential());
Configure a propriedade ManagedIdentityClientId em DefaultAzureCredentialOptions:
using Azure;
using Azure.AI.OpenAI;
using Azure.Identity;
using System;
using static System.Environment;
string endpoint = GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT");
var credential = new DefaultAzureCredential(
new DefaultAzureCredentialOptions
{
ManagedIdentityClientId = "<user_assigned_client_id>"
});
OpenAIClient client = new(new Uri(endpoint), credential);
Para obter mais informações sobre o DefaultAzureCredential para Go, consulte a visão geral do DefaultAzureCredential.
import (
"log"
"github.com/Azure/azure-sdk-for-go/sdk/ai/azopenai"
"github.com/Azure/azure-sdk-for-go/sdk/azidentity"
)
func main() {
dac, err := azidentity.NewDefaultAzureCredential(nil)
if err != nil {
log.Fatalf("ERROR: %s", err)
}
client, err := azopenai.NewClient(os.Getenv("AZURE_OPENAI_ENDPOINT"), dac, nil)
if err != nil {
log.Fatalf("ERROR: %s", err)
}
_ = client
}
Para obter mais informações sobre DefaultAzureCredential para Java, consulte a visão geral DefaultAzureCredential.
Execute uma das seguintes abordagens para definir o ID do cliente da identidade gerenciada atribuída pelo usuário:
Definir variável de ambiente AZURE_CLIENT_ID. O construtor sem parâmetros de DefaultAzureCredential usa o valor dessa variável de ambiente, se presente.
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.azure.ai.openai.OpenAIClient;
import com.azure.ai.openai.OpenAIClientBuilder;
String endpoint = System.getenv("AZURE_OPENAI_ENDPOINT");
DefaultAzureCredential credential = new DefaultAzureCredentialBuilder().build();
OpenAIClient client = new OpenAIClientBuilder()
.credential(credential)
.endpoint(endpoint)
.buildClient();
Atribua uma identidade gerenciada atribuída ao usuário específica com DefaultAzureCredential usando o DefaultAzureCredentialBuilder para configurá-la com uma ID de cliente:
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.azure.ai.openai.OpenAIClient;
import com.azure.ai.openai.OpenAIClientBuilder;
String endpoint = System.getenv("AZURE_OPENAI_ENDPOINT");
String userAssignedClientId = "<your managed identity client ID>";
TokenCredential dacWithUserAssignedManagedIdentity
= new DefaultAzureCredentialBuilder().managedIdentityClientId(userAssignedClientId).build();
OpenAIClient client = new OpenAIClientBuilder()
.credential(dacWithUserAssignedManagedIdentity)
.endpoint(endpoint)
.buildClient();
Para obter mais informações sobre DefaultAzureCredential para JavaScript, consulte a visão geral do DefaultAzureCredential.
Execute uma das seguintes abordagens para definir o ID do cliente da identidade gerenciada atribuída pelo usuário:
Definir variável de ambiente AZURE_CLIENT_ID. O construtor sem parâmetros de DefaultAzureCredential usa o valor dessa variável de ambiente, se presente.
import { DefaultAzureCredential, getBearerTokenProvider } from "@azure/identity";
import { AzureOpenAI } from "openai";
const credential = new DefaultAzureCredential();
const scope = "https://cognitiveservices.azure.com/.default";
const azureADTokenProvider = getBearerTokenProvider(credential, scope);
const endpoint = process.env["AZURE_OPENAI_ENDPOINT"] || "<endpoint>";
const deployment = "<your Azure OpenAI deployment name>";
const apiVersion = "2024-05-01-preview";
const options = { azureADTokenProvider, deployment, apiVersion, endpoint }
const client = new AzureOpenAI(options);
Atribua uma identidade gerenciada atribuída ao usuário específica com DefaultAzureCredential usando o parâmetro managedIdentityClientId para configurá-la com uma ID de cliente:
import { DefaultAzureCredential, getBearerTokenProvider } from "@azure/identity";
import { AzureOpenAI } from "openai";
const managedIdentityClientId = "<your managed identity client ID>";
const credential = new DefaultAzureCredential({
managedIdentityClientId: managedIdentityClientId,
});
const scope = "https://cognitiveservices.azure.com/.default";
const azureADTokenProvider = getBearerTokenProvider(credential, scope);
const endpoint = process.env["AZURE_OPENAI_ENDPOINT"] || "<endpoint>";
const deployment = "<your Azure OpenAI deployment name>";
const apiVersion = "2024-05-01-preview";
const options = { azureADTokenProvider, deployment, apiVersion, endpoint }
const client = new AzureOpenAI(options);
Para obter mais informações sobre DefaultAzureCredential para Python, consulte a visão geral do DefaultAzureCredential.
Execute uma das seguintes abordagens para definir o ID do cliente da identidade gerenciada atribuída pelo usuário:
Definir variável de ambiente AZURE_CLIENT_ID. O construtor sem parâmetros de DefaultAzureCredential usa o valor dessa variável de ambiente, se presente.
import openai
from azure.identity import DefaultAzureCredential, get_bearer_token_provider
token_provider = get_bearer_token_provider(DefaultAzureCredential(), "https://cognitiveservices.azure.com/.default")
openai_client = openai.AzureOpenAI(
api_version=os.getenv("AZURE_OPENAI_VERSION"),
azure_endpoint=os.getenv("AZURE_OPENAI_ENDPOINT"),
azure_ad_token_provider=token_provider
)
Atribua uma identidade gerenciada atribuída ao usuário específica com DefaultAzureCredential usando o parâmetro managed_identity_client_id para configurá-la com uma ID de cliente:
import openai
from azure.identity import DefaultAzureCredential, get_bearer_token_provider
user_assigned_client_id = "<your managed identity client ID>"
credential = DefaultAzureCredential(
managed_identity_client_id=user_assigned_client_id
)
token_provider = get_bearer_token_provider(credential, "https://cognitiveservices.azure.com/.default")
openai_client = openai.AzureOpenAI(
api_version=os.getenv("AZURE_OPENAI_VERSION"),
azure_endpoint=os.getenv("AZURE_OPENAI_ENDPOINT"),
azure_ad_token_provider=token_provider
)
Recursos