Conectar-se do aplicativo a recursos sem manipular credenciais

Artigo
10/04/2024

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 compatíveis com a autenticação do Microsoft Entra. O suporte a identidades gerenciadas torna desnecessário que os desenvolvedores gerenciem credenciais no código. As identidades gerenciadas são a opção de autenticação recomendada quando trabalhamos com recursos do Azure que dão 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 Azure Key Vault, ao Armazenamento do Azure e ao Microsoft SQL Server. Esses mesmos princípios podem ser usados para qualquer recurso do Azure compatível com as identidades gerenciadas e que se conecte a recursos compatíveis com a autenticação do Microsoft Entra.

Os exemplos de código usam a biblioteca de clientes de Identidade do Azure, o método recomendado, pois ele gerencia automaticamente muitas das etapas para você, inclusive a aquisição do 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 compatível com a 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 são compatíveis com a autenticação do Microsoft Entra ou a biblioteca de clientes deles não é compatível com a autenticação por meio de um token. Continue lendo para ver nossas diretrizes sobre como usar uma identidade gerenciada para acessar com segurança as credenciais sem precisar armazená-las no código ou nas configurações do aplicativo.

Como criar uma identidade gerenciada

Há dois tipos de identidades gerenciadas: atribuídas pelo sistema e atribuídas pelo usuário. As identidades atribuídas pelo sistema estão diretamente vinculadas a um 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 o ciclo de vida dela é independente desses recursos.

É altamente recomendável usar uma identidade gerenciada atribuída pelo usuário para a maioria dos cenários. Se o recurso de origem que você estiver usando não oferecer suporte a identidades gerenciadas atribuídas pelo usuário, consulte a documentação desse provedor de recursos, a fim de saber como configurá-lo, para ter uma identidade gerenciada atribuída pelo 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:

Após criar uma identidade gerenciada atribuída pelo usuário, anote os valores clientId e principalId retornados quando a identidade gerenciada for criada. Use principalId ao adicionar permissões e clientId no código do aplicativo.

Configurar uma identidade gerenciada atribuída pelo usuário para um centro de desenvolvimento

Antes que você possa usar a identidade gerenciada em seu código, precisamos atribuí-la ao Serviço de Aplicativo que a usará. 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.

Adicionar permissões à identidade

Após configurar o Serviço de Aplicativo para usar uma identidade gerenciada atribuída pelo usuário, conceda as permissões necessárias à 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á dispor de uma função semelhante a "Administrador de Acesso do Usuário" ou "Proprietário" para o recurso de destino, a fim de adicionar atribuições de função. Verifique se você está concedendo o privilégio mínimo necessário para que o aplicativo seja executado.

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 Key Vault, também precisará adicionar uma política de acesso que inclua a identidade gerenciada de seu aplicativo ou função. Caso contrário, as chamadas para o Key Vault serão rejeitadas, mesmo se você usar um token válido. O mesmo é verdadeiro para Banco de Dados SQL do Azure. Para saber mais sobre quais recursos são compatíves com os tokens do Microsoft Entra, consulte os Serviços do Azure que dão suporte à autenticação do Microsoft Entra.

Como usar a identidade gerenciada no seu código

Depois de concluir as etapas descritas acima, o Serviço de Aplicativo tem 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 de destino, em vez de armazenar as credenciais no código.

Recomendamos usar a biblioteca de Identidade do Azure para sua linguagem de programação preferida. A biblioteca adquire tokens de acesso para você, simplificando a conexão com recursos de destino.

Leia mais sobre as bibliotecas de Identidade do Azure abaixo:

Como usar a biblioteca de Identidade do Azure em seu ambiente de desenvolvimento

Cada uma das bibliotecas de Identidade do Azure fornece um tipo DefaultAzureCredential. O DefaultAzureCredential tenta autenticar automaticamente por meio de vários mecanismos, incluindo variáveis de ambiente ou uma entrada interativa. O tipo de credencial pode ser usado no seu ambiente de desenvolvimento, com credenciais próprias. Ele também pode ser usado no ambiente de produção do Azure por meio de uma identidade gerenciada. Nenhuma alteração de código é necessária ao implantar 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 a ID do cliente da identidade como parâmetro. Você pode recuperar a ID do cliente navegando até a identidade no portal do Azure.

Como acessar um Blob no Armazenamento 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())
}

Como acessar um segredo armazenado no Azure Key Vault

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;

import com.azure.core.util.polling.SyncPoller;
import com.azure.identity.DefaultAzureCredentialBuilder;

import com.azure.security.keyvault.secrets.SecretClient;
import com.azure.security.keyvault.secrets.SecretClientBuilder;
import com.azure.security.keyvault.secrets.models.DeletedSecret;
import com.azure.security.keyvault.secrets.models.KeyVaultSecret;

String keyVaultName = "mykeyvault";
String keyVaultUri = "https://" + keyVaultName + ".vault.azure.net";
String secretName = "mysecret";

// read the user-assigned managed identity Client ID from your environment variables
String clientID = System.getProperty("Managed_Identity_Client_ID");
DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
        .managedIdentityClientId(clientID)
        .build();

SecretClient secretClient = new SecretClientBuilder()
    .vaultUrl(keyVaultUri)
    .credential(credential)
    .buildClient();
    
KeyVaultSecret retrievedSecret = secretClient.getSecret(secretName);

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@azure/keyvault-secrets";

// 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 client = new SecretClient("https://<your-key-vault-name>.vault.azure.net/", credential);

async function getSecret() {
    const secret = await client.getSecret("<your-secret-name>");
    const secretValue = secret.value;
    console.log(secretValue);
}

getSecret().catch(err => console.error("Error retrieving secret:", err));

from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient
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)

client = SecretClient(vault_url="https://<your-key-vault-name>.vault.azure.net/", credential=credential)

def get_secret():
    secret = client.get_secret("<your-secret-name>")
    secret_value = secret.value
    print(secret_value)

if __name__ == "__main__":
    try:
        get_secret()
    except Exception as e:
        print(f"Error retrieving secret: {e}")

package main

import (
    "context"
    "fmt"
    "os"

    "github.com/Azure/azure-sdk-for-go/sdk/azidentity"
    "github.com/Azure/azure-sdk-for-go/sdk/keyvault/azsecrets"
)

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
    }

    client, err := azsecrets.NewClient("https://<your-key-vault-name>.vault.azure.net/", credential, nil)
    if err != nil {
        fmt.Printf("Failed to create secret client: %v\n", err)
        return
    }

    secretResp, err := client.GetSecret(context.TODO(), "<your-secret-name>", nil)
    if err != nil {
        fmt.Printf("Failed to get secret: %v\n", err)
        return
    }

    secretValue := *secretResp.Value
    fmt.Println(secretValue)
}

Como acessar o Banco de Dados SQL do Azure

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 ao Banco de Dados SQL do Azure com uma identidade gerenciada, sem precisar fazer alterações no código.

Abra o arquivo src/main/resources/application.properties e adicione Authentication=ActiveDirectoryMSI; ao final da linha a seguir. Verifique se você está usando o valor correto para a variável $AZ_DATABASE_NAME.

spring.datasource.url=jdbc:sqlserver://$AZ_DATABASE_NAME.database.windows.net:1433;database=demo;encrypt=true;trustServerCertificate=false;hostNameInCertificate=*.database.windows.net;loginTimeout=30;Authentication=ActiveDirectoryMSI;


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

Como se conectar a recursos que não são compatíveis com a autenticação do Microsoft Entra ID ou baseada em token nas bibliotecas

Alguns recursos do Azure não são compatíveis com a autenticação do Azure Microsoft Entra ou a biblioteca de clientes deles não é compatível com autenticação por meio de token. Normalmente, esses recursos são tecnologias de código aberto que esperam um nome de usuário e uma senha ou uma chave de acesso em uma cadeia de conexão.

Para evitar armazenar credenciais no código ou na configuração do aplicativo, você pode armazenar as credenciais como um segredo no Azure Key Vault. Usando o exemplo exibido acima, você pode recuperar o segredo do Azure Key Vault usando uma identidade gerenciada e passar as credenciais para a cadeia de conexão. Essa abordagem significa que nenhuma credencial precisa ser tratada diretamente no código ou no ambiente.

Diretrizes para o caso de gerenciamento direto de tokens

Em alguns cenários, talvez seja interessante 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 clientes para a linguagem de programação que você está usando ou o recurso de destino ao qual você está se conectando, ou se estiver se conectando a recursos que não estiverem em execução no Azure. Ao adquirir tokens manualmente, fornecemos as seguintes diretrizes:

Armazenar em cache os tokens adquiridos

Para desempenho e confiabilidade, recomendamos que o aplicativo armazene tokens em cache na memória local ou criptografados, se quiser salvá-los em disco. Como os tokens de identidade gerenciada são válidos por 24 horas, não há nenhum benefício em solicitar novos tokens regularmente, pois um armazenado em cache será retornado do ponto de extremidade emissor do token. Se você exceder os limites de solicitação, será limitado por taxa e receberá um erro HTTP 429.

Ao adquirir um token, você pode definir seu cache de token para expirar 5 minutos antes de expires_on (ou propriedade equivalente) que será retornada quando o token for gerado.

Inspeção de token

Seu aplicativo não deve depender do conteúdo de um token. O conteúdo do token destina-se apenas ao público-alvo (recurso de destino) que está sendo acessado, não ao cliente que está solicitando o token. O conteúdo do token pode ser alterado ou criptografado no futuro.

Não expor nem mover tokens

Os tokens devem ser tratados como credenciais. Não os exponha a usuários ou outros serviços; por exemplo, soluções de registro em log/monitoramento. Eles não devem ser movidos do recurso de origem que os está usando, além de autenticar-se no recurso de destino.

Próximas etapas

Como usar identidades gerenciadas para o Serviço de Aplicativo e o Azure Functions
Como usar identidades gerenciadas com Instâncias de Contêiner do Azure
Como implementar identidades gerenciadas para recursos do Microsoft Azure
Saiba como usar a federação de identidade de carga de trabalho para identidades gerenciadas, para acessar recursos protegidos do Microsoft Entra sem gerenciar segredos

Compartilhar via