Criar código de autenticação de aplicativo cliente

Depois de configurar uma instância e autenticação dos Gêmeos Digitais do Azure, você pode criar um aplicativo cliente que será usado para interagir com a instância. Depois de configurar um projeto de cliente inicial, você precisa criar código nesse aplicativo cliente para autenticá-lo na instância dos Gêmeos Digitais do Azure.

O Azure Digital Twins autentica usando os Tokens de Segurança do Microsoft Entra com base no OAUTH 2.0. Para autenticar o SDK, você precisa passar, junto com as chamadas à API, um token de portador com as permissões corretas dos Gêmeos Digitais do Azure.

Este artigo descreve como obter as credenciais usando a biblioteca de cliente Azure.Identity. Embora este artigo mostre exemplos de código em C#, como os gravados no SDK do .NET (C#), é possível usar uma versão de Azure.Identity independentemente do SDK usado. Veja mais informações sobre os SDKs disponíveis de Gêmeos Digitais do Azure em APIs e SDKs dos Gêmeos Digitais do Azure.

Pré-requisitos

Primeiro, conclua as etapas de configuração em Configurar uma instância e uma autenticação. Essa configuração garantirá que você tenha uma instância dos Gêmeos Digitais do Azure e que o usuário tenha as permissões de acesso. Após essa configuração, você poderá criar o código do aplicativo cliente.

Para continuar, você precisará de um projeto de aplicativo cliente no qual escrever o código. Se você ainda não configurou um projeto de aplicativo cliente, crie um projeto básico em uma linguagem à sua escolha para usar neste tutorial.

Autenticar-se com a biblioteca Azure.Identity

O Azure.Identity é uma biblioteca de cliente que oferece vários métodos de obtenção de credencial, que você usa para obter um token de portador e autenticar-se no SDK. Este artigo contém exemplos em C#, mas você pode ver o Azure.Identity para várias linguagens, incluindo:

• .NET (C#)
• Java
• JavaScript
• Python

Três métodos comuns de obtenção de credenciais no Azure.Identity são:

• O DefaultAzureCredential é um TokenCredential fluxo de autenticação padrão para aplicativos que serão implantados no Azure, sendo a opção recomendada para o desenvolvimento local. Você também pode habilitá-lo para testar os outros dois métodos recomendados neste artigo. Ele encapsula ManagedIdentityCredential e pode acessar InteractiveBrowserCredential com uma variável de configuração.
• ManagedIdentityCredential funciona bem nos casos em que você precisa de identidades gerenciadas (MSI) e é um bom candidato para trabalhar com o Azure Functions e implantar nos serviços do Azure.
• O InteractiveBrowserCredential, voltado para aplicativos interativos, pode ser usado para criar um cliente autenticado do SDK.

O restante deste artigo mostra como usar esses métodos com o SDK do .NET (C#).

Adicionar o Azure.Identity ao projeto .NET

Configure o projeto do .NET para autenticação com Azure.Identity seguindo estas etapas:

1. Inclua o pacote do SDK Azure.DigitalTwins.Core e o pacote Azure.Identity no projeto. Dependendo das ferramentas de sua escolha, você pode incluir os pacotes usando o gerenciador de pacotes do Visual Studio ou a ferramenta de linha de comando dotnet.

2. Adicione o seguinte usando instruções para o código do projeto:

   using Azure.DigitalTwins.Core;
   using Azure.Identity;
   using System;
   

Em seguida, adicione o código para obter as credenciais usando um dos métodos em Azure.Identity. As seções a seguir fornecem mais detalhes sobre o uso de cada um deles.

Método DefaultAzureCredential

O DefaultAzureCredential é um TokenCredential fluxo de autenticação padrão para aplicativos que serão implantados no Azure, sendo a opção recomendada para o desenvolvimento local.

Para usar as credenciais padrão do Azure, você precisa da URL da instância dos Gêmeos Digitais do Azure (instruções para localizá-las).

Este é um exemplo de código para adicionar um DefaultAzureCredential ao projeto:

public class DefaultAzureCredentialSample
{
    // The URL of your instance, starting with the protocol (https://)
    private const string adtInstanceUrl = "https://<your-Azure-Digital-Twins-instance-URL>";

    internal void RunSample()
    {
        //...

        DigitalTwinsClient client;
        try
        {
            var credential = new DefaultAzureCredential();
            client = new DigitalTwinsClient(new Uri(adtInstanceUrl), credential);
        }
        catch (Exception e)
        {
            Console.WriteLine($"Authentication or client creation error: {e.Message}");
            Environment.Exit(0);
        }
    }
}

Observação

Atualmente, há um problema conhecido que afeta a classe wrapper DefaultAzureCredential que pode resultar em erro durante a autenticação. Se encontrar esse problema, você pode tentar criar uma instância DefaultAzureCredential com o seguinte parâmetro opcional para resolver: new DefaultAzureCredential(new DefaultAzureCredentialOptions { ExcludeSharedTokenCacheCredential = true });

Para obter mais informações sobre esse problema, consulte Problemas conhecidos dos Gêmeos Digitais do Azure.

Configurar credenciais locais do Azure

Com DefaultAzureCredential, o exemplo pesquisará as credenciais no ambiente local, como uma conexão do Azure em uma DefaultAzureCredential local ou no Visual Studio ou Visual Studio Code. Por isso, será necessário entrar no Azure localmente por meio de um desses mecanismos para configurar as credenciais do exemplo.

Caso esteja usando o Visual Studio ou o Visual Studio Code para executar exemplos de código, verifique se está conectado a esse editor com as mesmas credenciais do Azure que deseja usar para acessar a instância dos Gêmeos Digitais do Azure. Se estiver usando uma janela da CLI local, execute o comando az login para entrar na sua conta do Azure. Depois disso, quando você executar o exemplo de código, será autenticado automaticamente.

Método ManagedIdentityCredential

O método ManagedIdentityCredential funciona bem nos casos em que você precisa de identidades gerenciadas (MSI) — por exemplo, ao autenticar com o Azure Functions.

Isso significa que você pode usar ManagedIdentityCredential no mesmo projeto como DefaultAzureCredential ou InteractiveBrowserCredential, para autenticar uma parte diferente do projeto.

Para usar as credenciais padrão do Azure, você precisa da URL da instância dos Gêmeos Digitais do Azure (instruções para localizá-las). Você também pode precisar de um registro de aplicativo e da ID do aplicativo (cliente) do registro.

Em uma função do Azure, você pode usar as credenciais de identidade gerenciadas da seguinte maneira:

public class ManagedIdentityCredentialSample
{
    // The URL of your instance, starting with the protocol (https://)
    private const string adtInstanceUrl = "https://<your-Azure-Digital-Twins-instance-URL>";

    internal void RunSample()
    {
        DigitalTwinsClient client;
        try
        {
            // To use the function app's system-assigned identity:
            ManagedIdentityCredential cred = new ManagedIdentityCredential();
            // To use a user-assigned identity for the function app:
            //ManagedIdentityCredential cred = new ManagedIdentityCredential("<uai-client-ID>");

            client = new DigitalTwinsClient(new Uri(adtInstanceUrl), cred);
        }
        catch (Exception e)
        {
            Console.WriteLine($"Authentication or client creation error: {e.Message}");
            Environment.Exit(0);
        }
    }
}

Ao criar a credencial, deixar o parâmetro vazio, conforme mostrado acima, retornará a credencial para a identidade atribuída pelo sistema do aplicativo de função, se ela tiver uma. Para especificar uma identidade atribuída pelo usuário, passe a ID do cliente da identidade atribuída pelo usuário para o parâmetro.

Método InteractiveBrowserCredential

O método InteractiveBrowserCredential é destinado a aplicativos interativos e abre um navegador da Web para autenticação. Você pode usar esse método no lugar do DefaultAzureCredential quando precisa de autenticação interativa.

Para usar as credenciais interativas do navegador, você precisará de um registro de aplicativo que tenha permissões das APIs dos Gêmeos Digitais do Azure. Veja as etapas de configuração do registro de aplicativo em Criar um registro de aplicativo com acesso aos Gêmeos Digitais do Azure. Depois de configurar o registro do aplicativo, você precisará do seguinte:

• a ID do Aplicativo (cliente) do registro do aplicativo
• a ID do Diretório (locatário) do registro do aplicativo
• a URL da instância dos Gêmeos Digitais do Azure

Este é um exemplo do código para criar um cliente SDK autenticado usando o InteractiveBrowserCredential.

public class InteractiveBrowserCredentialSample
{
    // Your client / app registration ID
    private const string clientId = "<your-client-ID>";
    // Your tenant / directory ID
    private const string tenantId = "<your-tenant-ID>";
    // The URL of your instance, starting with the protocol (https://)
    private const string adtInstanceUrl = "https://<your-Azure-Digital-Twins-instance-URL>";

    internal void RunSample()
    {
        //...

        DigitalTwinsClient client;
        try
        {
            var credential = new InteractiveBrowserCredential(tenantId, clientId);
            client = new DigitalTwinsClient(new Uri(adtInstanceUrl), credential);
        }
        catch (Exception e)
        {
            Console.WriteLine($"Authentication or client creation error: {e.Message}");
            Environment.Exit(0);
        }
    }
}

Observação

Embora você possa colocar a ID do cliente, a ID do locatário e a URL da instância diretamente no código, como mostrado acima, é uma boa ideia fazer com que seu código obtenha esses valores de um arquivo de configuração ou variável de ambiente.

Autenticação com o Azure Functions

Esta seção contém algumas opções de configuração importantes no contexto da autenticação com o Azure Functions. Primeiro, você lerá sobre as variáveis de nível de classe recomendadas e o código de autenticação que permitirá que a função acesse os Gêmeos Digitais do Azure. Em seguida, lerá sobre algumas etapas de configuração final a serem concluídas para sua função depois que o código dela for publicado no Azure.

Escrever o código do aplicativo

Ao escrever a função do Azure, considere adicionar estas variáveis e códigos a ela:

• Código para ler a URL do serviço Gêmeos Digitais do Azure como uma variável de ambiente ou uma definição de configuração. É uma boa prática ler a URL do serviço em uma variável de ambiente/configuração de aplicativo em vez de codificá-la na função por hard-coding. Em uma função do Azure, esse código para ler a variável de ambiente pode ser semelhante ao seguinte:

  private static readonly string adtInstanceUrl = Environment.GetEnvironmentVariable("ADT_SERVICE_URL");
  

  Depois de publicar a função, você criará e definirá o valor da variável de ambiente para a leitura do código. Para obter instruções sobre como fazer isso, pule para Definir as configurações do aplicativo.

• Uma variável estática para manter uma instância de HttpClient. Como a criação do HttpClient é relativamente cara, você provavelmente desejará criá-lo uma vez com o código de autenticação para evitar uma nova criação a cada invocação de função.

  private static readonly HttpClient singletonHttpClientInstance = new HttpClient();
  

• Credencial de identidade gerenciada. Crie uma credencial de identidade gerenciada a ser usada por sua função para acessar os Gêmeos Digitais do Azure.

  // To use the function app's system-assigned identity:
  var cred = new ManagedIdentityCredential();
  // To use a user-assigned identity for the function app:
  //var cred = new ManagedIdentityCredential("<uai-client-ID>");
  

  Deixar o parâmetro vazio, conforme mostrado acima, retornará a credencial para a identidade atribuída ao sistema do aplicativo de função, se ele tiver uma. Para especificar uma identidade atribuída pelo usuário, passe a ID do cliente da identidade atribuída pelo usuário para o parâmetro.

  Depois de publicar a função, você verificará se a identidade dela tem permissão para acessar as APIs dos Gêmeos Digitais do Azure. Para obter instruções sobre como fazer isso, pule para Atribuir uma função de acesso.

• Uma variável local DigitalTwinsClient. Adicione a variável dentro de sua função para manter a instância do cliente dos Gêmeos Digitais do Azure. Não torne essa variável estática dentro da classe.

  var client = new DigitalTwinsClient(
      new Uri(adtInstanceUrl),
      cred,
      new DigitalTwinsClientOptions
      {
          Transport = new HttpClientTransport(singletonHttpClientInstance)
      });
  

• Uma verificação nula para adtInstanceUrl. Adicione a verificação nula e, em seguida, coloque a lógica de função em um bloco try/catch para capturar as exceções.

Depois que esses variáveis forem adicionadas a uma função, seu código de função poderá ser semelhante ao exemplo a seguir.

// Default URL for triggering event grid function in the local environment.
// http://localhost:7071/runtime/webhooks/EventGrid?functionName={functionname}
//<Function_dependencies>
using Azure.Core.Pipeline;
using Azure.DigitalTwins.Core;
using Azure.Identity;
using Azure.Messaging.EventGrid;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.EventGrid;
using Microsoft.Extensions.Logging;
using System;
using System.Net.Http;
//</Function_dependencies>

namespace DigitalTwins_Samples
{
    public class DigitalTwinsIngestFunctionSample
    {
        // Your Digital Twin URL is stored in an application setting in Azure Functions
        // <ADT_service_URL>
        private static readonly string adtInstanceUrl = Environment.GetEnvironmentVariable("ADT_SERVICE_URL");
        // </ADT_service_URL>
        // <HTTP_client>
        private static readonly HttpClient singletonHttpClientInstance = new HttpClient();
        // </HTTP_client>

        [FunctionName("TwinsFunction")]
        public void Run([EventGridTrigger] EventGridEvent eventGridEvent, ILogger log)
        {
            log.LogInformation(eventGridEvent.Data.ToString());
            if (adtInstanceUrl == null) log.LogError("Application setting \"ADT_SERVICE_URL\" not set");
            try
            {
                // Authenticate with Digital Twins
                // <ManagedIdentityCredential>
                // To use the function app's system-assigned identity:
                var cred = new ManagedIdentityCredential();
                // To use a user-assigned identity for the function app:
                //var cred = new ManagedIdentityCredential("<uai-client-ID>");
                // </ManagedIdentityCredential>
                // <DigitalTwinsClient>
                var client = new DigitalTwinsClient(
                    new Uri(adtInstanceUrl),
                    cred,
                    new DigitalTwinsClientOptions
                    {
                        Transport = new HttpClientTransport(singletonHttpClientInstance)
                    });
                // </DigitalTwinsClient>
                log.LogInformation($"ADT service client connection created.");

                // Add your business logic here.
            }
            catch (Exception e)
            {
                log.LogError(e.Message);
            }
        }
    }
}

Quando você terminar o código de função, incluindo a adição da autenticação e da lógica da função, publique o aplicativo no Azure.

Configurar o aplicativo publicado

Por fim, conclua as seguintes etapas de configuração para uma função publicada do Azure a fim de garantir que ela possa acessar sua instância dos Gêmeos Digitais do Azure.

Execute os comandos a seguir no Azure Cloud Shell ou em uma CLI do Azure local.

Observação

Esta seção precisa ser concluída por um usuário do Azure que tenha permissões para gerenciar o acesso do usuário aos recursos do Azure, incluindo concessão e delegação de permissões. Funções comuns que atendem a esse requisito são Proprietário, Administrador da conta ou a combinação de Colaborador e Administrador de Acesso do Usuário. Para obter mais informações sobre os requisitos de permissão para funções dos Gêmeos Digitais do Azure, confira Configurar uma instância e a autenticação.

Atribuir uma função de acesso

A função do Azure exige o recebimento de um token de portador. Para garantir que o token de portador seja recebido, conceda ao aplicativo de funções a função Proprietário de Dados dos Gêmeos Digitais do Azure à instância dos Gêmeos Digitais do Azure, que dará ao aplicativo de funções a permissão para executar atividades do plano de dados na instância.

1. Use o comando a seguir para criar uma identidade gerenciada pelo sistema para sua função (se a função já tiver uma, esse comando imprimirá os respectivos detalhes). Anote o principalId campo na saída. Você usará essa ID para se referir à função a fim de conceder a ela as permissões na próxima etapa.

   az functionapp identity assign --resource-group <your-resource-group> --name <your-function-app-name>	
   

2. Use o valor de principalId no comando a seguir para atribuir a função Proprietário de Dados dos Gêmeos Digitais do Azure à instância dos Gêmeos Digitais do Azure.

   az dt role-assignment create --dt-name <your-Azure-Digital-Twins-instance> --assignee "<principal-ID>" --role "Azure Digital Twins Data Owner"
   

Definir as configurações do aplicativo

Em seguida, torne a URL da sua instância do Gêmeos Digitais do Azure acessível à sua função definindo uma variável de ambiente para ela.

Dica

A URL da instância dos Gêmeos Digitais do Azure é criada adicionando https:// ao início do nome do host da instância do Azure. Para ver o nome do host, juntamente com todas as propriedades da instância, execute az dt show --dt-name <your-Azure-Digital-Twins-instance>.

O comando a seguir define uma variável de ambiente para a URL da instância que sua função usará sempre que precisar acessar a instância.

az functionapp config appsettings set --resource-group <your-resource-group> --name <your-function-app-name> --settings "ADT_SERVICE_URL=https://<your-Azure-Digital-Twins-instance-host-name>"

Autenticar entre locatários

Os Gêmeos Digitais do Azure são um serviço que oferece suporte apenas a um locatário do Microsoft Entra: o locatário principal da assinatura onde a instância do Gêmeos Digitais do Azure está localizada.

Como resultado, as solicitações para as APIs dos Gêmeos Digitais do Azure exigem um usuário ou uma entidade de serviço que faça parte do mesmo locatário em que reside a instância dos Gêmeos Digitais do Azure. Para impedir a verificação mal-intencionada de pontos de extremidade dos Gêmeos Digitais do Azure, as solicitações com tokens de acesso de fora do locatário de origem retornarão uma mensagem de erro "404 Sub-Domain não encontrado". Esse erro será retornado mesmo se o usuário ou a entidade de serviço tiver recebido uma função de Proprietário de Dados dos Gêmeos Digitais do Azure ou Leitor de Dados dos Gêmeos Digitais do Azure por meio da colaboração B2B do Microsoft Entra.

Se precisar acessar sua instância dos Gêmeos Digitais do Azure usando uma entidade de serviço ou uma conta de usuário que pertence a um locatário diferente da instância, cada identidade federada de outro locatário poderá solicitar um token do locatário "Home" da instância dos Gêmeos Digitais do Azure.

Uma maneira de fazer isso é com o seguinte comando da CLI, onde <home-tenant-ID> é a ID do locatário do Microsoft Entra que contém a instância do Gêmeos Digitais do Azure:

az account get-access-token --tenant <home-tenant-ID> --resource https://digitaltwins.azure.net

Depois de solicitar isso, a identidade receberá um token emitido para o https://digitaltwins.azure.net recurso Microsoft Entra, que tem uma declaração de ID de locatário correspondente à instância do Gêmeos Digitais do Azure. Usar esse token em solicitações de API ou com o código Azure.Identity deve permitir que a identidade federada acesse o recurso dos Gêmeos Digitais do Azure.

Também é possível especificar o locatário inicial nas opções de credencial no código.

O seguinte exemplo mostra como definir um valor de amostra de ID de locatário para InteractiveBrowserTenantId nas opções DefaultAzureCredential:

public class DefaultAzureCredentialOptionsSample
{
    // The URL of your instance, starting with the protocol (https://)
    private const string adtInstanceUrl = "https://<your-Azure-Digital-Twins-instance-URL>";

    private static DefaultAzureCredentialOptions credentialOptions = new DefaultAzureCredentialOptions()
    {
        ExcludeSharedTokenCacheCredential = true,
        ExcludeVisualStudioCodeCredential = true,
        TenantId = "<your-Azure-Active-Directory-tenant-ID>"
    };

    private static DefaultAzureCredential credential = new DefaultAzureCredential(credentialOptions);

    DigitalTwinsClient client = new DigitalTwinsClient(new Uri(adtInstanceUrl), credential);
}

Há opções semelhantes disponíveis para definir um locatário para autenticação com o Visual Studio e o Visual Studio Code. Para mais informações sobre as opções disponíveis, consulte a documentação DefaultAzureCredentialOptions.

Outros métodos de credencial

Se os cenários de autenticação destacados acima não atenderem às necessidades do seu aplicativo, explore outros tipos de autenticação oferecidos na plataforma de identidade da Microsoft. A documentação desta plataforma abrange mais cenários de autenticação, organizados por tipo de aplicativo.

Próximas etapas

Leia mais sobre a segurança nos Gêmeos Digitais do Azure:

• Segurança para soluções de Gêmeos Digitais do Azure

Ou, agora que a autenticação está configurada, passe para a criação e gerenciamento de modelos na sua instância:

• Gerenciar modelos DTDL