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 será capaz de se autenticar no serviço. A autenticação sem chave oferece vantagens de segurança e gerenciamento aprimorados com relação à chave de conta porque não há nenhuma chave (nem cadeia de conexão) para armazenar.
As conexões sem chave estão habilitadas com as seguintes etapas:
- Configure sua autenticação.
- Defina as variáveis de ambiente, conforme necessário.
- Use um tipo de credencial de biblioteca de identidade do Azure para criar um objeto de cliente OpenAI do Azure.
Autenticação
A autenticação na ID do Microsoft Entra é 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 OpenAI do Azure
Use o link a seguir para explorar o modelo de IA do Building Block Keyless do OpenAI do Azure. Este modelo provisiona uma conta OpenAI do Azure com sua permissão de função RBAC de conta de usuário para autenticação sem chave (Microsoft Entra) para acessar os SDKs da API OpenAI.
Observação
Este artigo usa um ou mais modelos de aplicativo de IA como base para os exemplos e as diretrizes no artigo. Os modelos de aplicativo de IA fornecem implementações de referência regulares e fáceis de implantar que ajudam a garantir um ponto de partida de alta qualidade para os aplicativos de IA.
Autenticar para o desenvolvimento local
Autenticar para ambientes hospedados no Azure
Localize a função para o 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 de Função |
Para a CLI do Azure ou o Azure PowerShell, você pode usar o nome da função. |
Para o Bicep, você precisa da ID da função. |
Use a tabela a seguir para selecionar uma função e um ID.
Caso de uso |
Nome da função |
ID de Função |
Assistentes |
Cognitive Services OpenAI Contributor |
a001fd3d-188f-4b5d-821b-7da978bf7442 |
Preenchimentos de chat |
Cognitive Services OpenAI User |
5e0bd9bd-7b93-4f28-af87-19fc36ad61bd |
Selecione um tipo identidade para utilizar.
- Identidade pessoal: essa é sua identidade pessoal vinculada à sua entrada no Azure.
- Identidade gerenciada: essa é 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 desenvolvimento local, para obter sua própria ID de identidade, use o comando a seguir. Você precisa entrar com az login
antes de usar este comando.
az ad signed-in-user show \
--query id -o tsv
Para desenvolvimento local, para obter sua própria ID de identidade, use o comando a seguir. Você precisa entrar com Connect-AzAccount
antes de usar este comando.
(Get-AzContext).Account.ExtendedProperties.HomeAccountId.Split('.')[0]
Ao usar o Bicep implantado com a CLI do Desenvolvedor do Azure, a identidade da pessoa ou do serviço que executa a implantação é definida como o parâmetro principalId
.
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
}
Atribua a função de controle de acesso baseado em função (RBAC) à identidade para o grupo de recursos.
Para conceder suas permissões de identidade ao recurso por meio do RBAC, atribua uma função usando o comando da CLI do Azure az role assignment create.
az role assignment create \
--role "Cognitive Services OpenAI User" \
--assignee "<identity-id>" \
--scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>"
Para conceder permissões de aplicativo ao recurso OpenAI do Azure 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 OpenAI Bicep do Azure para criar o recurso e definir a autenticação para o identityId
. O Bicep requer a ID da função. O name
mostrado nesse snippet do Bicep não é a função do Azure; é específico 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 Bicep genérico a seguir é chamado do main.bicep
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)
}
}
Quando aplicável, substitua <identity-id>
, <subscription-id>
e <resource-group-name>
por seus valores reais.
Para se conectar ao OpenAI do Azure, seu código precisa conhecer o ponto de extremidade do recurso e pode precisar de outras variáveis de ambiente.
Crie uma variável de ambiente para o ponto de extremidade OpenAI do Azure.
AZURE_OPENAI_ENDPOINT
: essa URL é o ponto de acesso para o recurso OpenAI do Azure.
Crie variáveis de ambiente com base no local em que seu aplicativo é executado:
Location |
Identidade |
Descrição |
Local |
Pessoal |
Para tempos de execução locais com sua identidade pessoal, faça login para criar sua credencial com uma ferramenta. |
Nuvem do Azure |
Identidade gerenciada atribuída pelo usuário |
Crie uma variável de ambiente AZURE_CLIENT_ID contendo o ID do cliente da identidade gerenciada atribuída pelo usuário para autenticar como. |
Instalar a biblioteca de clientes da Identidade do Azure
Use o link a seguir para instalar a biblioteca de clientes do Azure Identity.
Instale a biblioteca do cliente Java de identidade do Azure 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>
Use DefaultAzureCredential
A biblioteca de Identidades do Azure DefaultAzureCredential
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 DefaultAzureCredential
para .NET, consulte a visão geral DefaultAzureCredential
.
Siga uma destas abordagens para configurar a ID de cliente da identidade gerenciada atribuída pelo usuário:
Definir variável de ambiente AZURE_CLIENT_ID
. O construtor sem parâmetros de DefaultAzureCredential
usará 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());
Defina a propriedade ManagedIdentityClientId no 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 DefaultAzureCredential
para Go, consulte a visão geral 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
.
Siga uma destas abordagens para configurar a ID de cliente da identidade gerenciada atribuída pelo usuário:
Definir variável de ambiente AZURE_CLIENT_ID
. O construtor sem parâmetros de DefaultAzureCredential
usará 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 específica atribuída pelo usuário com DefaultAzureCredential
usando o DefaultAzureCredentialBuilder
para configurá-la com uma ID do 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 DefaultAzureCredential
.
Siga uma destas abordagens para configurar a ID de cliente da identidade gerenciada atribuída pelo usuário:
Definir variável de ambiente AZURE_CLIENT_ID
. O construtor sem parâmetros de DefaultAzureCredential
usará 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 específica atribuída pelo usuário com DefaultAzureCredential
usando o parâmetro managedIdentityClientId
para configurá-la com uma ID do 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 DefaultAzureCredential
.
Siga uma destas abordagens para configurar a ID de cliente da identidade gerenciada atribuída pelo usuário:
Definir variável de ambiente AZURE_CLIENT_ID
. O construtor sem parâmetros de DefaultAzureCredential
usará 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 específica atribuída pelo usuário com DefaultAzureCredential
usando o parâmetro managed_identity_client_id
para configurá-la com uma ID do 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