Skip to content

Latest commit

 

History

History
529 lines (351 loc) · 21.2 KB

keyless-connections.md

File metadata and controls

529 lines (351 loc) · 21.2 KB
title description ms.topic ms.date ms.reviewer ms.custom
Use keyless connections with Azure OpenAI
Use keyless connections for authentication and authorization to Azure OpenAI.
how-to
02/05/2025
scaddie
devx-track-extended-java, devx-track-js, devx-track-python, passwordless-dotnet, passwordless-java, passwordless-js, passwordless-python, passwordless-go, build-2024-intelligent-apps

Use Azure OpenAI without keys

Application requests to most Azure services must be authenticated with keys or passwordless connections. Developers must be diligent to never expose the keys in an unsecure location. Anyone who gains access to the key is able to authenticate to the service. Keyless authentication offers improved management and security benefits over the account key because there's no key (or connection string) to store.

Keyless connections are enabled with the following steps:

  • Configure your authentication.
  • Set environment variables, as needed.
  • Use an Azure Identity library credential type to create an Azure OpenAI client object.

Authentication

Authentication to Microsoft Entra ID is required to use the Azure client libraries.

Authentication differs based on the environment in which the app is running:

Azure OpenAI Keyless Building Block

Use the following link to explore the Azure OpenAI Keyless Building Block AI template. This template provisions an Azure OpenAI account with your user account RBAC role permission for keyless (Microsoft Entra) authentication to access the OpenAI API SDKs.

Note

This article uses one or more AI app templates as the basis for the examples and guidance in the article. AI app templates provide you with well-maintained, easy to deploy reference implementations that help to ensure a high-quality starting point for your AI apps.

.NET

Explore the .NET End to end Azure OpenAI Keyless Authentication Building Block AI template.

Go

Explore the Go End to end Azure OpenAI Keyless Authentication Building Block AI template.

Java

Explore the Java End to end Azure OpenAI Keyless Authentication Building Block AI template.

JavaScript

Explore the JavaScript End to end Azure OpenAI Keyless Authentication Building Block AI template.

Python

Explore the Python End to end Azure OpenAI Keyless Authentication Building Block AI template.

Authenticate for local development

.NET

Select a tool for authentication during local development.

Important

For access to your Azure resources during local development, you must sign-in to a local development tool using the Azure account you assigned the Azure AI Developer role to. For example, Visual Studio or the Azure CLI.

Go

Select a tool for authentication during local development.

Java

Select a tool for authentication during local development.

JavaScript

Select a tool for authentication during local development.

Python

Select a tool for authentication during local development.

Authenticate for Azure-hosted environments

.NET

Learn about how to manage the DefaultAzureCredential for applications deployed to Azure.

Go

Learn about how to manage the DefaultAzureCredential for applications deployed to Azure.

Java

Learn about how to manage the DefaultAzureCredential for applications deployed to Azure.

JavaScript

Learn about how to manage the DefaultAzureCredential for applications deployed to Azure.

Python

Learn about how to manage the DefaultAzureCredential for applications deployed to Azure.

Configure roles for authorization

  1. Find the role for your usage of Azure OpenAI. Depending on how you intend to set that role, you need either the name or ID.

    Role name Role ID
    For Azure CLI or Azure PowerShell, you can use role name. For Bicep, you need the role ID.

  2. Use the following table to select a role and ID.

    Use case Role name Role ID
    Assistants Cognitive Services OpenAI Contributor a001fd3d-188f-4b5d-821b-7da978bf7442
    Chat completions Cognitive Services OpenAI User 5e0bd9bd-7b93-4f28-af87-19fc36ad61bd

  3. Select an identity type to use.

    • Personal identity: This is your personal identity tied to your sign in to Azure.
    • Managed identity: This is an identity managed by and created for use on Azure. For managed identity, create a user-assigned managed identity. When you create the managed identity, you need the Client ID, also known as the app ID.

  4. To find your personal identity, use one of the following commands. Use the ID as the <identity-id> in the next step.

    Azure CLI

    For local development, to get your own identity ID, use the following command. You need to sign in with az login before using this command.

    az ad signed-in-user show \
    --query id -o tsv

    Azure PowerShell

    For local development, to get your own identity ID, use the following command. You need to sign in with Connect-AzAccount before using this command.

    (Get-AzContext).Account.ExtendedProperties.HomeAccountId.Split('.')[0]

    Bicep

    When using Bicep deployed with Azure Developer CLI, the identity of the person or service running the deployment is set to the principalId parameter.

    The following main.parameters.json variable is set to the identity running the process.

    "principalId": {
    "value": "${AZURE_PRINCIPAL_ID}"
  },

    For use in Azure, specify a user-assigned managed identity as part of the Bicep deployment process. Create a user-assigned managed identity separate from the identity running the process.

    resource userAssignedManagedIdentity 'Microsoft.ManagedIdentity/userAssignedIdentities@2018-11-30' = {
  name: managedIdentityName
  location: location
}

    Azure portal

    Use the steps found here: find the user object ID in the Azure portal.

  5. Assign the role-based access control (RBAC) role to the identity for the resource group.

    Azure CLI

    To grant your identity permissions to your resource through RBAC, assign a role using the Azure CLI command az role assignment create.

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

    Azure PowerShell

    To grant your application permissions to your Azure OpenAI resource through RBAC, assign a role using the Azure PowerShell cmdlet New-AzRoleAssignment.

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

    Bicep

    Use the following Azure OpenAI Bicep template to create the resource and set the authentication for the identityId. Bicep requires the role ID. The name shown in this Bicep snippet isn't the Azure role; it's specific to the Bicep deployment.

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

    The following generic Bicep is called from the main.bicep to create any role.

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

    Azure portal

    Use the steps found at open the Add role assignment page in the Azure portal.

    Where applicable, replace <identity-id>, <subscription-id>, and <resource-group-name> with your actual values.

Configure environment variables

To connect to Azure OpenAI, your code needs to know your resource endpoint, and might need other environment variables.

  1. Create an environment variable for your Azure OpenAI endpoint.

    • AZURE_OPENAI_ENDPOINT: This URL is the access point for your Azure OpenAI resource.

  2. Create environment variables based on the location in which your app runs:

    Location Identity Description
    Local Personal For local runtimes with your personal identity, sign in to create your credential with a tool.
    Azure cloud User-assigned managed identity Create an AZURE_CLIENT_ID environment variable containing the client ID of the user-assigned managed identity to authenticate as.

Install Azure Identity client library

Use the following link to install the Azure Identity client library.

.NET

Install the .NET Azure Identity client library:

dotnet add package Azure.Identity

Go

Install the Go Azure Identity client library:

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

Java

Install the Java Azure Identity client library with the following POM file:

<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>

JavaScript

Install the JavaScript Azure Identity client library:

npm install --save @azure/identity

Python

Install the Python Azure Identity client library:

pip install azure-identity

Use DefaultAzureCredential

The Azure Identity library's DefaultAzureCredential allows the customer to run the same code in the local development environment and in the Azure Cloud.

.NET

For more information on DefaultAzureCredential for .NET, see the DefaultAzureCredential overview.

Take one of the following approaches to set the user-assigned managed identity's client ID:

  • Set environment variable AZURE_CLIENT_ID. The parameterless constructor of DefaultAzureCredential uses the value of this environment variable, if present.

    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());

  • Set property ManagedIdentityClientId on 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);

Go

For more information on DefaultAzureCredential for Go, see the DefaultAzureCredential overview.

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
}

Java

For more information on DefaultAzureCredential for Java, see the DefaultAzureCredential overview.

Take one of the following approaches to set the user-assigned managed identity's client ID:

  • Set environment variable AZURE_CLIENT_ID. The parameterless constructor of DefaultAzureCredential uses the value of this environment variable, if present.

    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();

  • Assign a specific user-assigned managed identity with DefaultAzureCredential by using the DefaultAzureCredentialBuilder to configure it with a client ID:

    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();

JavaScript

For more information on DefaultAzureCredential for JavaScript, see the DefaultAzureCredential overview.

Take one of the following approaches to set the user-assigned managed identity's client ID:

  • Set environment variable AZURE_CLIENT_ID. The parameterless constructor of DefaultAzureCredential uses the value of this environment variable, if present.

    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);

  • Assign a specific user-assigned managed identity with DefaultAzureCredential by using the managedIdentityClientId parameter to configure it with a client ID:

    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);

Python

For more information on DefaultAzureCredential for Python, see the DefaultAzureCredential overview.

Take one of the following approaches to set the user-assigned managed identity's client ID:

  • Set environment variable AZURE_CLIENT_ID. The parameterless constructor of DefaultAzureCredential uses the value of this environment variable, if present.

    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
)

  • Assign a specific user-assigned managed identity with DefaultAzureCredential by using the managed_identity_client_id parameter to configure it with a client ID:

    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
)

Resources