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

Depois de configurar uma instância e autenticação do Azure Digital Twins, você pode criar um aplicativo cliente que usará para interagir com a instância. Depois de configurar um projeto de cliente inicial, você precisará escrever código nesse aplicativo cliente para autenticá-lo na instância do Azure Digital Twins.

O Azure Digital Twins autentica usando Tokens de Segurança do Microsoft Entra com base no OAUTH 2.0. Para autenticar seu SDK, você precisará obter um token de portador com as permissões certas para os Gêmeos Digitais do Azure e passá-lo junto com suas chamadas de API.

Este artigo descreve como obter credenciais usando a biblioteca de Azure.Identity cliente. Embora este artigo mostre exemplos de código em C#, como o que você escreveria para o SDK do .NET (C#), você pode usar uma versão do SDK independentemente do Azure.Identity SDK que estiver usando (para obter mais informações sobre os SDKs disponíveis para Gêmeos Digitais do Azure, consulte APIs e SDKs do Azure Digital Twins.

Pré-requisitos

Primeiro, conclua as etapas de configuração em Configurar uma instância e autenticação. Essa configuração garantirá que você tenha uma instância do Azure Digital Twins e que seu usuário tenha permissões de acesso. Após essa configuração, você estará pronto para escrever o código do aplicativo cliente.

Para continuar, você precisará de um projeto de aplicativo cliente no qual escreva seu código. Se você ainda não tiver um projeto de aplicativo cliente configurado, crie um projeto básico no idioma de sua escolha para usar com este tutorial.

Autenticar usando a biblioteca Azure.Identity

Azure.Identity é uma biblioteca de cliente que fornece vários métodos de obtenção de credenciais que você pode usar para obter um token de portador e autenticar com seu SDK. Embora este artigo dê exemplos em C#, você pode visualizar Azure.Identity para vários idiomas, incluindo...

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

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

• DefaultAzureCredential fornece um fluxo de autenticação padrão TokenCredential para aplicativos que serão implantados no Azure e é a opção recomendada para desenvolvimento local. Ele também pode ser habilitado para tentar os outros dois métodos recomendados neste artigo; ele envolve e pode acessar InteractiveBrowserCredential com uma variável de ManagedIdentityCredential 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.
• InteractiveBrowserCredential destina-se a aplicativos interativos e pode ser usado para criar um cliente SDK autenticado.

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

Adicionar Azure.Identity ao seu projeto .NET

Para configurar seu projeto .NET para autenticar com Azure.Identity, conclua as seguintes etapas:

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

2. Adicione as seguintes instruções using ao código do projeto:

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

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

Método DefaultAzureCredential

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

Para usar as credenciais padrão do Azure, você precisará da URL da instância do Azure Digital Twins (instruções para localizar).

Aqui está um exemplo de código para adicionar um DefaultAzureCredential ao seu 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);
        }
    }
}

Nota

Atualmente, há um problema conhecido que afeta a classe wrapper que pode resultar em um erro durante a DefaultAzureCredential autenticação. Se você encontrar esse problema, você pode tentar instanciar DefaultAzureCredential com o seguinte parâmetro opcional para resolvê-lo: 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 DefaultAzureCredentialo , o exemplo procurará credenciais em seu ambiente local, como uma entrada do Azure em uma CLI do Azure local ou no Visual Studio ou Visual Studio Code. Por esse motivo, você deve entrar no Azure localmente por meio de um desses mecanismos para configurar credenciais para o exemplo.

Se estiver a utilizar o Visual Studio ou o Visual Studio Code para executar exemplos de código, certifique-se de que tem sessão iniciada nesse editor com as mesmas credenciais do Azure que pretende utilizar para aceder à sua instância do Azure Digital Twins. Se você estiver usando uma janela de CLI local, execute o az login comando para entrar em sua conta do Azure. Depois disso, quando você executa seu exemplo de código, você deve 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ê precisará da URL da instância do Azure Digital Twins (instruções para localizar). Você também pode precisar de um registro de aplicativo e do ID do aplicativo (cliente) do registro.

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

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, como 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 o ID do cliente da identidade atribuída pelo usuário para o parâmetro.

Método InteractiveBrowserCredential

O método InteractiveBrowserCredential destina-se a aplicativos interativos e exibirá um navegador da Web para autenticação. Você pode usar esse método em vez de nos casos em que você precisa de DefaultAzureCredential autenticação interativa.

Para usar as credenciais do navegador interativo, você precisará de um registro de aplicativo que tenha permissões para as APIs do Azure Digital Twins. Para obter etapas sobre como configurar esse registro de aplicativo, consulte Criar um registro de aplicativo com acesso ao Azure Digital Twins. Assim que o registro do aplicativo estiver configurado, você precisará...

• o ID do aplicativo de registro do aplicativo (cliente)
• o ID do diretório (locatário) do registro do aplicativo
• a URL da instância do Azure Digital Twins

Aqui está um exemplo do código para criar um cliente SDK autenticado usando InteractiveBrowserCredentialo .

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

Nota

Embora você possa colocar o ID do cliente, o 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.

Autenticar o Azure Functions

Esta seção contém algumas das 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, você lerá sobre algumas etapas de configuração finais a serem concluídas para sua função depois que seu código for publicado no Azure.

Escrever código do aplicativo

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

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

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

  Mais tarde, depois de publicar a função, você criará e definirá o valor da variável de ambiente para que esse código seja lido. Para obter instruções sobre como fazer isso, pule para Definir configurações do aplicativo.

• Uma variável estática para manter uma instância HttpClient. HttpClient é relativamente caro para criar, então você provavelmente vai querer criá-lo uma vez com o código de autenticação para evitar criá-lo para cada chamada de função.

  private static readonly HttpClient singletonHttpClientInstance = new HttpClient();
  

• Credencial de identidade gerenciada. Crie uma credencial de identidade gerenciada que sua função usará 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, como 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 o ID do cliente da identidade atribuída pelo usuário para o parâmetro.

  Mais tarde, depois de publicar a função, você verificará se a identidade da função tem permissão para acessar as APIs do Azure Digital Twins. 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 sua instância de cliente do Azure Digital Twins. Não torne essa variável estática dentro da sua 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, envolva sua lógica de função em um bloco try/catch para capturar quaisquer exceções.

Depois que essas variáveis são adicionadas a uma função, seu código de função pode se parecer com o 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 terminar o código da função, incluindo a adição de autenticação e a lógica da função, publique o aplicativo no Azure

Configurar aplicativo publicado

Por fim, conclua as etapas de configuração a seguir para uma função do Azure publicada para garantir que ela possa acessar sua instância do Azure Digital Twins.

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

Nota

Esta seção deve 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 a concessão e delegação de permissões. As funções comuns que atendem a esse requisito são Proprietário, Administrador de conta ou a combinação de Administrador de Acesso de Usuário e Colaborador. Para obter mais informações sobre os requisitos de permissão para funções do Azure Digital Twins, consulte Configurar uma instância e autenticação.

Atribuir uma função de acesso

A função do Azure requer que um token de portador seja passado para ela. Para garantir que o token de portador seja passado, conceda ao aplicativo de função a função Proprietário de Dados de Gêmeos Digitais do Azure para sua instância de Gêmeos Digitais do Azure, que dará permissão ao aplicativo de função para executar atividades de 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á seus detalhes). Anote o principalId campo na saída. Você usará essa ID para fazer referência à função para que possa conceder-lhe permissões na próxima etapa.

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

2. Use o principalId valor no comando a seguir para dar à função a função Proprietário de Dados de Gêmeos Digitais do Azure para sua instância de 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"
   

Configurar definições da aplicação

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

Gorjeta

A URL da instância do Azure Digital Twins é feita adicionando https:// ao início do nome de host da sua instância. Para ver o nome do host, juntamente com todas as propriedades da sua 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 sua 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 inquilinos

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

Como resultado, as solicitações para as APIs do Azure Digital Twins exigem um usuário ou entidade de serviço que faça parte do mesmo locatário onde a instância do Azure Digital Twins reside. Para evitar a verificação mal-intencionada dos pontos de extremidade do Azure Digital Twins, as solicitações com tokens de acesso de fora do locatário de origem retornarão uma mensagem de erro "Subdomínio 404 não encontrado". Este erro será devolvido mesmo que o utilizador ou entidade de serviço tenha recebido uma função de Proprietário de Dados dos Gêmeos Digitais do Azure ou de Leitor de Dados dos Gêmeos Digitais do Azure por meio da colaboração B2B do Microsoft Entra.

Se você precisar acessar sua instância do Azure Digital Twins usando uma entidade de serviço ou conta de usuário que pertença a um locatário diferente da instância, poderá fazer com que cada identidade federada de outro locatário solicite um token do locatário "doméstico" da instância do Azure Digital Twins.

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 Azure Digital Twins:

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 Azure Digital Twins. Usar esse token em solicitações de API ou com seu Azure.Identity código deve permitir que a identidade federada acesse o recurso Gêmeos Digitais do Azure.

Você também pode especificar o locatário doméstico nas opções de credenciais em seu código.

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

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 Visual Studio e Visual Studio Code. Para obter 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 cobrirem as necessidades do seu aplicativo, você poderá explorar outros tipos de autenticação oferecidos na plataforma de identidade da Microsoft. A documentação para esta plataforma abrange mais cenários de autenticação, organizados por tipo de aplicativo.

Próximos passos

Leia mais sobre como funciona 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 o gerenciamento de modelos em sua instância:

• Gerenciar modelos DTDL