Conectando-se de seu aplicativo a recursos sem manipular credenciais
Artigo
Os recursos do Azure com suporte a identidades gerenciadas sempre fornecem uma opção para especificar uma identidade gerenciada para se conectar aos recursos do Azure que dão suporte à autenticação do Microsoft Entra. O suporte a identidades gerenciadas torna desnecessário para os desenvolvedores gerenciar credenciais no código. As identidades gerenciadas são a opção de autenticação recomendada ao trabalhar com recursos do Azure que oferecem suporte a elas.
Leia uma visão geral das identidades gerenciadas.
Esta página demonstra como configurar um Serviço de Aplicativo para que ele possa se conectar ao Cofre da Chave do Azure, ao Armazenamento do Azure e ao Microsoft SQL Server. Os mesmos princípios podem ser usados para qualquer recurso do Azure que ofereça suporte a identidades gerenciadas e que se conecte a recursos que dão suporte à autenticação do Microsoft Entra.
Os exemplos de código usam a biblioteca de cliente do Azure Identity, que é o método recomendado, pois ele lida automaticamente com muitas das etapas para você, incluindo a aquisição de um token de acesso usado na conexão.
A quais recursos as identidades gerenciadas podem se conectar?
Uma identidade gerenciada pode se conectar a qualquer recurso que ofereça suporte à autenticação do Microsoft Entra. Em geral, não há suporte especial necessário para que o recurso permita que identidades gerenciadas se conectem a ele.
Alguns recursos não suportam a autenticação do Microsoft Entra ou a biblioteca do cliente não suporta a autenticação com um token. Continue lendo para ver nossas orientações sobre como usar uma identidade gerenciada para acessar as credenciais com segurança sem precisar armazená-las em seu código ou configuração de aplicativo.
Criando uma identidade gerenciada
Existem dois tipos de identidades gerenciadas: atribuídas pelo sistema e atribuídas pelo usuário. As identidades atribuídas ao sistema estão diretamente ligadas a um único recurso do Azure. Quando o recurso do Azure é excluído, a identidade também é. Uma identidade gerenciada atribuída pelo usuário pode ser associada a vários recursos do Azure e seu ciclo de vida é independente desses recursos.
Recomendamos que você use uma identidade gerenciada atribuída pelo usuário para a maioria dos cenários. Se o recurso de origem que você está usando não oferecer suporte a identidades gerenciadas atribuídas pelo usuário, consulte a documentação desse provedor de recursos para saber como configurá-lo para ter uma identidade gerenciada atribuída ao sistema.
Importante
A conta usada para criar identidades gerenciadas precisa de uma função como "Colaborador de Identidade Gerenciada" para criar uma nova identidade gerenciada atribuída pelo usuário.
Crie uma identidade gerenciada atribuída pelo usuário usando sua opção preferida:
Depois de criar uma identidade gerenciada atribuída pelo usuário, anote os clientId valores retornados principalId quando a identidade gerenciada é criada. Você usa principalId ao adicionar permissões e clientId no código do seu aplicativo.
Configurar o Serviço de Aplicativo com uma identidade gerenciada atribuída pelo usuário
Antes de poder utilizar a identidade gerida no seu código, temos de atribuí-la ao Serviço de Aplicação que a irá utilizar. O processo de configuração de um Serviço de Aplicativo para usar uma identidade gerenciada atribuída pelo usuário requer que você especifique o identificador de recurso da identidade gerenciada na configuração do aplicativo.
Adicionando permissões à identidade
Depois de configurar o Serviço de Aplicativo para usar uma identidade gerenciada atribuída pelo usuário, conceda as permissões necessárias para a identidade. Nesse cenário, estamos usando essa identidade para interagir com o Armazenamento do Azure, portanto, você precisa usar o sistema RBAC (Controle de Acesso Baseado em Função) do Azure para conceder as permissões de identidade gerenciada atribuídas pelo usuário ao recurso.
Importante
Você precisará de uma função como "Administrador de Acesso de Usuário" ou "Proprietário" para o recurso de destino para adicionar atribuições de Função. Certifique-se de que está a conceder o menor privilégio necessário para que a aplicação seja executada.
Todos os recursos que você deseja acessar exigem que você conceda as permissões de identidade. Por exemplo, se você solicitar um token para acessar o Cofre da Chave, também deverá adicionar uma política de acesso que inclua a identidade gerenciada do seu aplicativo ou função. Caso contrário, suas chamadas para o Cofre da Chave serão rejeitadas, mesmo se você usar um token válido. O mesmo é verdadeiro para o Banco de Dados SQL do Azure. Para saber mais sobre quais recursos oferecem suporte a tokens do Microsoft Entra, consulte Serviços do Azure que oferecem suporte à autenticação do Microsoft Entra.
Usando identidades gerenciadas em seu código
Depois de concluir as etapas descritas acima, seu Serviço de Aplicativo terá uma identidade gerenciada com permissões para um recurso do Azure. Você pode usar a identidade gerenciada para obter um token de acesso que seu código pode usar para interagir com recursos do Azure, em vez de armazenar credenciais em seu código.
Recomendamos que você use as bibliotecas de clientes que fornecemos para sua linguagem de programação preferida. Essas bibliotecas adquirem tokens de acesso para você, facilitando a autenticação com o Microsoft Entra ID. Para obter mais informações, consulte bibliotecas de cliente para autenticação de identidades gerenciadas.
Usando uma biblioteca de Identidades do Azure para acessar recursos do Azure
Cada uma das bibliotecas de Identidade do Azure fornece um DefaultAzureCredential tipo.
DefaultAzureCredential tenta autenticar automaticamente o usuário por meio de diferentes fluxos, incluindo variáveis de ambiente ou uma entrada interativa. O tipo de credencial pode ser usado em um ambiente de desenvolvimento com suas próprias credenciais. Ele também pode ser usado em seu ambiente de produção do Azure usando uma identidade gerenciada. Nenhuma alteração de código é necessária quando você implanta seu aplicativo.
Se você estiver usando identidades gerenciadas atribuídas pelo usuário, também deverá especificar explicitamente a identidade gerenciada atribuída pelo usuário com a qual deseja autenticar, passando o ID do cliente da identidade como um parâmetro. Você pode recuperar a ID do cliente navegando até a identidade no portal do Azure.
using Azure.Identity;
using Azure.Storage.Blobs;
// code omitted for brevity
// Specify the Client ID if using user-assigned managed identities
var clientID = Environment.GetEnvironmentVariable("Managed_Identity_Client_ID");
var credentialOptions = new DefaultAzureCredentialOptions
{
ManagedIdentityClientId = clientID
};
var credential = new DefaultAzureCredential(credentialOptions);
var blobServiceClient1 = new BlobServiceClient(new Uri("<URI of Storage account>"), credential);
BlobContainerClient containerClient1 = blobServiceClient1.GetBlobContainerClient("<name of blob>");
BlobClient blobClient1 = containerClient1.GetBlobClient("<name of file>");
if (blobClient1.Exists())
{
var downloadedBlob = blobClient1.Download();
string blobContents = downloadedBlob.Value.Content.ToString();
}
import com.azure.identity.DefaultAzureCredential;
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.azure.storage.blob.BlobClient;
import com.azure.storage.blob.BlobContainerClient;
import com.azure.storage.blob.BlobServiceClient;
import com.azure.storage.blob.BlobServiceClientBuilder;
// read the Client ID from your environment variables
String clientID = System.getProperty("Client_ID");
DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
.managedIdentityClientId(clientID)
.build();
BlobServiceClient blobStorageClient = new BlobServiceClientBuilder()
.endpoint("<URI of Storage account>")
.credential(credential)
.buildClient();
BlobContainerClient blobContainerClient = blobStorageClient.getBlobContainerClient("<name of blob container>");
BlobClient blobClient = blobContainerClient.getBlobClient("<name of blob/file>");
if (blobClient.exists()) {
String blobContent = blobClient.downloadContent().toString();
}
import { DefaultAzureCredential } from "@azure/identity";
import { BlobServiceClient } from "@azure/storage-blob";
// Specify the Client ID if using user-assigned managed identities
const clientID = process.env.Managed_Identity_Client_ID;
const credential = new DefaultAzureCredential({
managedIdentityClientId: clientID
});
const blobServiceClient = new BlobServiceClient("<URI of Storage account>", credential);
const containerClient = blobServiceClient.getContainerClient("<name of blob>");
const blobClient = containerClient.getBlobClient("<name of file>");
async function downloadBlob() {
if (await blobClient.exists()) {
const downloadBlockBlobResponse = await blobClient.download();
const downloadedBlob = await streamToString(downloadBlockBlobResponse.readableStreamBody);
console.log("Downloaded blob content:", downloadedBlob);
}
}
async function streamToString(readableStream) {
return new Promise((resolve, reject) => {
const chunks = [];
readableStream.on("data", (data) => {
chunks.push(data.toString());
});
readableStream.on("end", () => {
resolve(chunks.join(""));
});
readableStream.on("error", reject);
});
}
downloadBlob().catch(console.error);
from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient
import os
# Specify the Client ID if using user-assigned managed identities
client_id = os.getenv("Managed_Identity_Client_ID")
credential = DefaultAzureCredential(managed_identity_client_id=client_id)
blob_service_client = BlobServiceClient(account_url="<URI of Storage account>", credential=credential)
container_client = blob_service_client.get_container_client("<name of blob>")
blob_client = container_client.get_blob_client("<name of file>")
def download_blob():
if blob_client.exists():
download_stream = blob_client.download_blob()
blob_contents = download_stream.readall().decode('utf-8')
print("Downloaded blob content:", blob_contents)
download_blob()
package main
import (
"context"
"fmt"
"io"
"os"
"strings"
"github.com/Azure/azure-sdk-for-go/sdk/azidentity"
"github.com/Azure/azure-sdk-for-go/sdk/storage/azblob"
)
func main() {
// The client ID for the user-assigned managed identity is read from the AZURE_CLIENT_ID env var
cred, err := azidentity.NewDefaultAzureCredential(nil)
if err != nil {
fmt.Printf("failed to obtain a credential: %v\n", err)
return
}
accountURL := "<URI of Storage account>"
containerName := "<name of blob>"
blobName := "<name of file>"
serviceClient, err := azblob.NewServiceClient(accountURL, cred, nil)
if err != nil {
fmt.Printf("failed to create service client: %v\n", err)
return
}
containerClient := serviceClient.NewContainerClient(containerName)
blobClient := containerClient.NewBlobClient(blobName)
// Check if the blob exists
_, err = blobClient.GetProperties(context.Background(), nil)
if err != nil {
fmt.Printf("failed to get blob properties: %v\n", err)
return
}
// Download the blob
downloadResponse, err := blobClient.Download(context.Background(), nil)
if err != nil {
fmt.Printf("failed to download blob: %v\n", err)
return
}
// Read the blob content
blobData := downloadResponse.Body(nil)
defer blobData.Close()
blobContents := new(strings.Builder)
_, err = io.Copy(blobContents, blobData)
if err != nil {
fmt.Printf("failed to read blob data: %v\n", err)
return
}
fmt.Println("Downloaded blob content:", blobContents.String())
}
using Azure.Identity;
using Azure.Security.KeyVault.Secrets;
using Azure.Core;
// code omitted for brevity
// Specify the Client ID if using user-assigned managed identities
var clientID = Environment.GetEnvironmentVariable("Managed_Identity_Client_ID");
var credentialOptions = new DefaultAzureCredentialOptions
{
ManagedIdentityClientId = clientID
};
var credential = new DefaultAzureCredential(credentialOptions);
var client = new SecretClient(
new Uri("https://<your-unique-key-vault-name>.vault.azure.net/"),
credential);
KeyVaultSecret secret = client.GetSecret("<my secret>");
string secretValue = secret.Value;
using Azure.Identity;
using Microsoft.Data.SqlClient;
// code omitted for brevity
// Specify the Client ID if using user-assigned managed identities
var clientID = Environment.GetEnvironmentVariable("Managed_Identity_Client_ID");
var credentialOptions = new DefaultAzureCredentialOptions
{
ManagedIdentityClientId = clientID
};
AccessToken accessToken = await new DefaultAzureCredential(credentialOptions).GetTokenAsync(
new TokenRequestContext(new string[] { "https://database.windows.net//.default" }));
using var connection = new SqlConnection("Server=<DB Server>; Database=<DB Name>;")
{
AccessToken = accessToken.Token
};
var cmd = new SqlCommand("select top 1 ColumnName from TableName", connection);
await connection.OpenAsync();
SqlDataReader dr = cmd.ExecuteReader();
while(dr.Read())
{
Console.WriteLine(dr.GetValue(0).ToString());
}
dr.Close();
Se você usar o Azure Spring Apps, poderá se conectar aos Bancos de Dados SQL do Azure usando uma identidade gerenciada sem fazer alterações no seu código.
Abra o src/main/resources/application.properties arquivo e adicione Authentication=ActiveDirectoryMSI; no final da linha a seguir. Certifique-se de usar o valor correto para $AZ_DATABASE_NAME a variável.
import { DefaultAzureCredential } from "@azure/identity";
import { Connection, Request } from "tedious";
// Specify the Client ID if using a user-assigned managed identity
const clientID = process.env.Managed_Identity_Client_ID;
const credential = new DefaultAzureCredential({
managedIdentityClientId: clientID
});
async function getAccessToken() {
const tokenResponse = await credential.getToken("https://database.windows.net//.default");
return tokenResponse.token;
}
async function queryDatabase() {
const accessToken = await getAccessToken();
const config = {
server: "<your-server-name>",
authentication: {
type: "azure-active-directory-access-token",
options: {
token: accessToken
}
},
options: {
database: "<your-database-name>",
encrypt: true
}
};
const connection = new Connection(config);
connection.on("connect", err => {
if (err) {
console.error("Connection failed:", err);
return;
}
const request = new Request("SELECT TOP 1 ColumnName FROM TableName", (err, rowCount, rows) => {
if (err) {
console.error("Query failed:", err);
return;
}
rows.forEach(row => {
console.log(row.value);
});
connection.close();
});
connection.execSql(request);
});
connection.connect();
}
queryDatabase().catch(err => console.error("Error:", err));
import os
from azure.identity import DefaultAzureCredential
from azure.core.credentials import AccessToken
import pyodbc
# Specify the Client ID if using a user-assigned managed identity
client_id = os.getenv("Managed_Identity_Client_ID")
credential = DefaultAzureCredential(managed_identity_client_id=client_id)
# Get the access token
token = credential.get_token("https://database.windows.net//.default")
access_token = token.token
# Set up the connection string
connection_string = "Driver={ODBC Driver 18 for SQL Server};Server=<your-server-name>;Database=<your-database-name>;"
# Connect to the database
connection = pyodbc.connect(connection_string, attrs_before={"AccessToken": access_token})
# Execute the query
cursor = connection.cursor()
cursor.execute("SELECT TOP 1 ColumnName FROM TableName")
# Fetch and print the result
row = cursor.fetchone()
while row:
print(row)
row = cursor.fetchone()
# Close the connection
cursor.close()
connection.close()
package main
import (
"context"
"database/sql"
"fmt"
"os"
"github.com/Azure/azure-sdk-for-go/sdk/azidentity"
"github.com/denisenkom/go-mssqldb"
)
func main() {
// The client ID for the user-assigned managed identity is read from the AZURE_CLIENT_ID env var
cred, err := azidentity.NewDefaultAzureCredential(nil)
if err != nil {
fmt.Printf("failed to obtain a credential: %v\n", err)
return
}
// Get the access token
token, err := credential.GetToken(context.TODO(), azidentity.TokenRequestOptions{
Scopes: []string{"https://database.windows.net//.default"},
})
if err != nil {
fmt.Printf("Failed to get token: %v\n", err)
return
}
// Set up the connection string
connString := fmt.Sprintf("sqlserver://<your-server-name>?database=<your-database-name>&access_token=%s", token.Token)
// Connect to the database
db, err := sql.Open("sqlserver", connString)
if err != nil {
fmt.Printf("Failed to connect to the database: %v\n", err)
return
}
defer db.Close()
// Execute the query
rows, err := db.QueryContext(context.TODO(), "SELECT TOP 1 ColumnName FROM TableName")
if err != nil {
fmt.Printf("Failed to execute query: %v\n", err)
return
}
defer rows.Close()
// Fetch and print the result
for rows.Next() {
var columnValue string
if err := rows.Scan(&columnValue); err != nil {
fmt.Printf("Failed to scan row: %v\n", err)
return
}
fmt.Println(columnValue)
}
}
Usando a Biblioteca de Autenticação da Microsoft (MSAL) para acessar recursos do Azure
Além das bibliotecas de Identidade do Azure, você também pode usar o MSAL para acessar recursos do Azure usando identidades gerenciadas. Os trechos de código a seguir demonstram como usar o MSAL para acessar recursos do Azure em várias linguagens de programação.
Para identidades gerenciadas atribuídas ao sistema, o desenvolvedor não precisa passar nenhuma informação adicional. A MSAL infere automaticamente os metadados relevantes sobre a identidade atribuída. Para identidades gerenciadas atribuídas pelo usuário, o desenvolvedor precisa passar a ID do cliente, o identificador de recurso completo ou a ID do objeto da identidade gerenciada.
Em seguida, você pode adquirir um token para acessar um recurso. Antes de usar identidades gerenciadas, os desenvolvedores devem habilitá-las para os recursos que desejam usar.
using Microsoft.Identity.Client;
using System;
string resource = "https://vault.azure.net";
// Applies to system-assigned managed identities only
IManagedIdentityApplication mi = ManagedIdentityApplicationBuilder.Create(ManagedIdentityId.SystemAssigned)
.Build();
// Applies to user-assigned managed identities only
string userAssignedManagedIdentityClientId = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";
IManagedIdentityApplication mi = ManagedIdentityApplicationBuilder.Create(ManagedIdentityId.WithUserAssignedClientId(userAssignedManagedIdentityClientId))
.Build();
// Acquire token
AuthenticationResult result = await mi.AcquireTokenForManagedIdentity(resource)
.ExecuteAsync()
.ConfigureAwait(false);
if (!string.IsNullOrEmpty(result.AccessToken))
{
Console.WriteLine(result.AccessToken);
}
import com.microsoft.aad.msal4j.IAuthenticationResult;
import com.microsoft.aad.msal4j.ManagedIdentityApplication;
import com.microsoft.aad.msal4j.ManagedIdentityId;
import com.microsoft.aad.msal4j.ManagedIdentityParameters;
String resource = "https://vault.azure.net";
// Use this for user-assigned managed identities
private static final String USER_ASSIGNED_MI_CLIENT_ID = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";
// Use this for system-assigned managed identities
ManagedIdentityApplication miApp = ManagedIdentityApplication
.builder(ManagedIdentityId.systemAssigned())
.build();
// Use this for user-assigned managed identities
ManagedIdentityApplication miApp = ManagedIdentityApplication
.builder(ManagedIdentityId.userAssignedClientId(USER_ASSIGNED_MI_CLIENT_ID))
.build();
// Acquire token
IAuthenticationResult result = miApp.acquireTokenForManagedIdentity(
ManagedIdentityParameters.builder(resource)
.build()).get();
System.out.println(result.accessToken());
import {
LogLevel,
LoggerOptions,
AuthenticationResult,
} from "@azure/msal-common";
import {
ManagedIdentityRequestParams,
ManagedIdentityConfiguration,
ManagedIdentityApplication,
ManagedIdentityIdParams,
NodeSystemOptions,
} from "@azure/msal-node";
// Define resource
const managedIdentityRequestParams: ManagedIdentityRequestParams = {
resource: "https://vault.azure.net",
};
// This section applies to user-assigned managed identities only
const userAssignedManagedIdentityIdParams: ManagedIdentityIdParams = {
userAssignedClientId: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
};
const userAssignedManagedIdentityConfig: ManagedIdentityConfiguration = {
userAssignedManagedIdentityIdParams, // applicable to user-assigned managed identities only
// optional for logging
system: {
loggerOptions: {
logLevel: LogLevel.Verbose,
} as LoggerOptions,
} as NodeSystemOptions,
};
const userSystemAssignedManagedIdentityApplication: ManagedIdentityApplication =
new ManagedIdentityApplication(userAssignedManagedIdentityConfig);
// Acquire token: user-assigned managed identity
const response: AuthenticationResult =
await userAssignedManagedIdentityApplication.acquireToken(
managedIdentityRequestParams
);
// This section applies to system-assigned managed identities only
const systemAssignedManagedIdentityConfig: ManagedIdentityConfiguration = {
// optional for logging
system: {
loggerOptions: {
logLevel: LogLevel.Verbose,
} as LoggerOptions,
} as NodeSystemOptions,
};
const systemAssignedManagedIdentityApplication: ManagedIdentityApplication =
new ManagedIdentityApplication(systemAssignedManagedIdentityConfig);
// Acquire token: system-assigned managed identity
const response: AuthenticationResult =
await systemAssignedManagedIdentityApplication.acquireToken(
managedIdentityRequestParams
);
console.log(response);
import msal
import requests
# Use this for system-assigned managed identities
managed_identity = msal.SystemAssignedManagedIdentity()
# Use this for user-assigned managed identities
userAssignedClientId = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
managed_identity = msal.UserAssignedManagedIdentity(client_id=userAssignedClientId)
global_app = msal.ManagedIdentityClient(managed_identity, http_client=requests.Session())
result = global_app.acquire_token_for_client(resource='https://vault.azure.net')
if "access_token" in result:
print("Token obtained!")
O MSAL Go ainda não suporta identidades gerenciadas. Você pode usar a biblioteca de Identidades do Azure para adquirir tokens para identidades gerenciadas.
Conectando-se a recursos que não suportam ID do Microsoft Entra ou autenticação baseada em token em bibliotecas
Alguns recursos do Azure ainda não oferecem suporte à autenticação do Microsoft Entra ou suas bibliotecas de cliente não oferecem suporte à autenticação com um token. Normalmente, esses recursos são tecnologias de código aberto que esperam um nome de usuário e senha ou uma chave de acesso em uma cadeia de conexão.
Para evitar armazenar credenciais em seu código ou na configuração do aplicativo, você pode armazenar as credenciais como um segredo no Cofre de Chaves do Azure. Usando o exemplo exibido acima, você pode recuperar o segredo do Azure KeyVault usando uma identidade gerenciada e passar as credenciais para sua cadeia de conexão. Essa abordagem significa que nenhuma credencial precisa ser manipulada diretamente em seu código ou ambiente. Para obter um exemplo detalhado, consulte Usar identidades gerenciadas para acessar certificados do Azure Key Vault. Para mais informações sobre a autenticação do Azure Key Vault, consulte autenticação do Azure Key Vault.
Diretrizes se você estiver lidando com tokens diretamente
Em alguns cenários, talvez você queira adquirir tokens para identidades gerenciadas manualmente em vez de usar um método interno para se conectar ao recurso de destino. Esses cenários não incluem nenhuma biblioteca de cliente para a linguagem de programação que você está usando ou o recurso de destino ao qual você está se conectando, ou conectando-se a recursos que não estão sendo executados no Azure. Ao adquirir tokens manualmente, fornecemos as seguintes diretrizes:
Armazene em cache os tokens que você adquire
Para desempenho e confiabilidade, recomendamos que seu aplicativo armazene tokens em cache na memória local ou criptografados se você quiser salvá-los no disco. Como os tokens de identidade gerenciados são válidos por 24 horas, não há nenhum benefício em solicitar novos tokens regularmente, pois um em cache será retornado do ponto de extremidade de emissão do token. Se você exceder os limites de solicitação, terá uma taxa limitada e receberá um erro HTTP 429.
Ao adquirir um token, você pode definir seu cache de token para expirar 5 minutos antes da (ou propriedade equivalente) que será retornada expires_on quando o token for gerado.
Inspeção de tokens
Seu aplicativo não deve depender do conteúdo de um token. O conteúdo do token destina-se apenas ao público (recurso de destino) que está sendo acessado, não ao cliente que está solicitando o token. O conteúdo do token pode mudar ou ser criptografado no futuro.
Não exponha ou mova tokens
Os tokens devem ser tratados como credenciais. Não os exponha a utilizadores ou outros serviços; por exemplo, soluções de registo/monitorização. Eles não devem ser movidos do recurso de origem que os está usando, exceto para autenticar no recurso de destino.