Uso de Azure OpenAI sin claves

2025-02-07

Las solicitudes de aplicación a la mayoría de los servicios de Azure deben autenticarse con claves o conexiones sin contraseña. Los desarrolladores deben ser diligentes para no exponer nunca las claves en una ubicación que no sea segura. Cualquiera que obtenga acceso a la clave se puede autenticar en el servicio. La autenticación sin claves ofrece ventajas mejoradas de administración y seguridad con respecto a la clave de cuenta porque no hay ninguna clave (ni cadena de conexión) que almacenar.

Las conexiones sin claves se habilitan con los pasos siguientes:

Configure la autenticación.
Establezca variables de entorno, según sea necesario.
Use un tipo de credencial de biblioteca de identidades de Azure para crear un objeto de cliente de Azure OpenAI.

Autenticación

Para usar las bibliotecas cliente de Azure es necesaria la autenticación en Microsoft Entra ID.

La autenticación difiere en función del entorno en el que se ejecuta la aplicación:

Desarrollo local
Azure

Bloque de creación sin claves de Azure OpenAI

Use el vínculo siguiente para explorar la plantilla azure OpenAI Keyless Building Block AI. Esta plantilla aprovisiona una cuenta de Azure OpenAI con el permiso de rol RBAC de la cuenta de usuario para la autenticación sin claves (Microsoft Entra) para acceder a los SDK de api de OpenAI.

Nota:

En este artículo se usan una o varias plantillas de aplicaciones de IA como base para los ejemplos e instrucciones del artículo. Las plantillas de aplicaciones de IA le proporcionan implementaciones de referencia bien mantenidas y fáciles de implementar que le ayudan a garantizar un punto inicial de alta calidad para sus aplicaciones de IA.

Explore la plantilla .NET End to end de Azure OpenAI Keyless Authentication Building Block AI.

Autenticación para el desarrollo local

Seleccione una herramienta para la autenticación durante el desarrollo local.

Autenticación para entornos hospedados en Azure

Obtenga información sobre cómo administrar DefaultAzureCredential para las aplicaciones implementadas en Azure.

Configuración de roles para la autorización

Busque el rol para el uso de Azure OpenAI. En función de cómo quiera establecer ese rol, necesita el nombre o el identificador.

Nombre de rol Id. de rol

En el caso de la CLI de Azure o Azure PowerShell, puede usar el nombre del rol. Para Bicep, necesita el identificador de rol.

Nombre de rol	Id. de rol
En el caso de la CLI de Azure o Azure PowerShell, puede usar el nombre del rol.	Para Bicep, necesita el identificador de rol.

Utilice la siguiente tabla para seleccionar un rol y un identificador.

Caso de uso	Nombre de rol	Id. de rol
Asistentes	`Cognitive Services OpenAI Contributor`	`a001fd3d-188f-4b5d-821b-7da978bf7442`
Finalizaciones de chat	`Cognitive Services OpenAI User`	`5e0bd9bd-7b93-4f28-af87-19fc36ad61bd`

Seleccione un tipo de identidad para usarlo.
- Identidad personal: es su identidad personal vinculada al inicio de sesión en Azure.
- Identidad administrada: identidad administrada por Azure y creada para su uso en Azure. Para la identidad administrada, cree una identidad administrada asignada por el usuario. Al crear la identidad administrada, necesitará el Client ID, también conocido como app ID.
Para buscar su identidad personal, utilice uno de los siguientes comandos. Use el identificador como <identity-id> en el paso siguiente.
Para el desarrollo local, para obtener su propio identificador de identidad, use el siguiente comando. Debe iniciar sesión con az login antes de usar este comando.
```
az ad signed-in-user show \
    --query id -o tsv
```
Para el desarrollo local, para obtener su propio identificador de identidad, use el siguiente comando. Debe iniciar sesión con Connect-AzAccount antes de usar este comando.
```
(Get-AzContext).Account.ExtendedProperties.HomeAccountId.Split('.')[0]
```
Al usar Bicep implementado con Azure Developer CLI, la identidad de la persona o el servicio que ejecuta la implementación se establece con el parámetro principalId.

La variable main.parameters.json siguiente se establece con la identidad que ejecuta el proceso.
```
"principalId": {
    "value": "${AZURE_PRINCIPAL_ID}"
  },
```
Para su uso en Azure, especifique una identidad administrada asignada por el usuario como parte del proceso de implementación de Bicep. Cree una identidad administrada asignada por el usuario independiente de la identidad que ejecuta el proceso.
```
resource userAssignedManagedIdentity 'Microsoft.ManagedIdentity/userAssignedIdentities@2018-11-30' = {
  name: managedIdentityName
  location: location
}
```
Siga estos pasos: búsqueda del identificador de objeto de usuario en Azure Portal.

Asigne el rol de control de acceso basado en roles (RBAC) a la identidad del grupo de recursos.

Para conceder permisos de identidad al recurso mediante RBAC, asigne un rol mediante el comando az role assignment create de la CLI de Azure.

az role assignment create \
    --role "Cognitive Services OpenAI User" \
    --assignee "<identity-id>" \
    --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>"

Para conceder permisos de aplicación al recurso de Azure OpenAI mediante RBAC, asigne un rol mediante el cmdlet New-AzRoleAssignment de Azure PowerShell.

New-AzRoleAssignment -ObjectId "<identity-id>" -RoleDefinitionName "Cognitive Services OpenAI User" -Scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>"

Use la siguiente plantilla de Bicep de Azure OpenAI para crear el recurso y establecer la autenticación para el identityId. Bicep necesita el identificador de rol. La instancia de name que se muestra en este fragmento de código de Bicep no es el rol de Azure; es específica de la implementación de 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'
    }
}

Se llama al siguiente Bicep genérico desde el main.bicep para crear cualquier rol.

// 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)
    }
}

Si procede, reemplace <identity-id>, <subscription-id> y <resource-group-name> por los valores reales.

Configuración de las variables de entorno

Para conectarse a Azure OpenAI, el código debe conocer el punto de conexión del recurso y podría necesitar otras variables de entorno.

Cree una variable de entorno para el punto de conexión de Azure OpenAI.
- AZURE_OPENAI_ENDPOINT: esta URL es el punto de acceso para el recurso de Azure OpenAI.

Cree variables de entorno basadas en la ubicación en la que se ejecuta la aplicación:

Location	Identidad	Descripción
Local	Personal	En el caso de los entornos de ejecución locales con su identidad personal, inicie sesión para crear su credencial con una herramienta.
Nube de Azure	Identidad administrada asignada por el usuario	Cree una variable de entorno `AZURE_CLIENT_ID` que contenga el identificador de cliente de la identidad administrada asignada por el usuario para autenticarse.

Instalación de la biblioteca cliente de identidades de Azure

Use el vínculo siguiente para instalar la biblioteca cliente de Azure Identity.

Instale la biblioteca cliente de identidades de Azure para .NET:

dotnet add package Azure.Identity

Instale la biblioteca cliente de Azure Identity para Go.

go get -u github.com/Azure/azure-sdk-for-go/sdk/azidentity

Instale la biblioteca cliente de identidades de Azure para Java con el siguiente archivo 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>

Instale la biblioteca cliente de identidades de Azure para JavaScript:

npm install --save @azure/identity

Instale la biblioteca cliente de identidades de Azure para Python:

pip install azure-identity

Uso de DefaultAzureCredential

DefaultAzureCredential de la biblioteca de identidades de Azure permite al cliente ejecutar el mismo código en el entorno de desarrollo local y en la nube de Azure.

Para obtener más información sobre DefaultAzureCredential para .NET, consulte la información general de DefaultAzureCredential.

Tome uno de los métodos siguientes para establecer el identificador de cliente de la identidad administrada asignada por el usuario:

Establezca la variable de entorno AZURE_CLIENT_ID. El constructor sin parámetros de DefaultAzureCredential usará el valor de esta variable de entorno, si está 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());

Establezca la propiedad ManagedIdentityClientId en 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 obtener más información sobre DefaultAzureCredential para Go, consulte la información general de 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 obtener más información sobre DefaultAzureCredential para Java, consulte la introducción DefaultAzureCredential.

Tome uno de los métodos siguientes para establecer el identificador de cliente de la identidad administrada asignada por el usuario:

Establezca la variable de entorno AZURE_CLIENT_ID. El constructor sin parámetros de DefaultAzureCredential usará el valor de esta variable de entorno, si está 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();

Asigne una identidad administrada específica asignada por el usuario con DefaultAzureCredential utilizando el DefaultAzureCredentialBuilder para configurarla con un identificador 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 obtener más información sobre DefaultAzureCredential para JavaScript, consulte la información general de DefaultAzureCredential.

Tome uno de los métodos siguientes para establecer el identificador de cliente de la identidad administrada asignada por el usuario:

Establezca la variable de entorno AZURE_CLIENT_ID. El constructor sin parámetros de DefaultAzureCredential usará el valor de esta variable de entorno, si está 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);

Asigne una identidad administrada asignada por el usuario específica con DefaultAzureCredential mediante el parámetro managedIdentityClientId para configurarla con un identificador 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 obtener más información sobre DefaultAzureCredential para Python, consulte la información general de DefaultAzureCredential.

Tome uno de los métodos siguientes para establecer el identificador de cliente de la identidad administrada asignada por el usuario:

Establezca la variable de entorno AZURE_CLIENT_ID. El constructor sin parámetros de DefaultAzureCredential usará el valor de esta variable de entorno, si está 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
)

Asigne una identidad administrada asignada por el usuario específica con DefaultAzureCredential mediante el parámetro managed_identity_client_id para configurarla con un identificador 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

Guía para desarrolladores de conexiones sin contraseña

Compartir a través de

Uso de Azure OpenAI sin claves

Autenticación

Bloque de creación sin claves de Azure OpenAI

Autenticación para el desarrollo local

Autenticación para entornos hospedados en Azure

Configuración de roles para la autorización

Configuración de las variables de entorno

Instalación de la biblioteca cliente de identidades de Azure

Uso de DefaultAzureCredential

Recursos

Comentarios

Recursos adicionales