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 para interagir com a instância. Este artigo explica como 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, obtenha um token de portador com as permissões certas para os Gêmeos Digitais do Azure e passe-o 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 Azure.Identity SDK independentemente do SDK que estiver usando. Para obter mais informações sobre os SDKs disponíveis para os Gêmeos Digitais do Azure, consulte APIs e SDKs dos Gêmeos Digitais do Azure.

Pré-requisitos

Primeiro, conclua as etapas de configuração em Configurar uma instância e autenticação. Essa configuração garante 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ê precisa de um projeto de aplicativo cliente no qual você escreve 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
• Píton

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 implantados no Azure. Este método é a escolha recomendada para o desenvolvimento local. Também é capaz de tentar os outros dois métodos recomendados neste artigo; envolve ManagedIdentityCredential e pode aceder InteractiveBrowserCredential com uma variável de configuração.
• ManagedIdentityCredential funciona bem nos casos em que você precisa de identidades gerenciadas (MSI). Esse método é um bom candidato para trabalhar com o Azure Functions e implantar nos serviços do Azure.
• InteractiveBrowserCredential destina-se a aplicativos interativos. Este é um método de criação de 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.Identityo , conclua as seguintes etapas:

1. Inclua o pacote Azure.DigitalTwins.Core SDK e o Azure.Identity pacote 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 método.

Método DefaultAzureCredential

DefaultAzureCredential fornece um fluxo de autenticação padrão TokenCredential para aplicativos implantados no Azure. Este método é a escolha recomendada para o desenvolvimento local.

Para usar as credenciais padrão do Azure, você precisa 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);
        }
    }
}

Configurar credenciais locais do Azure

Com DefaultAzureCredential, o exemplo procura credenciais no seu ambiente local, como um início de sessão no Azure numa 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 de iniciar sessão, o exemplo de código autentica-o automaticamente quando é executado.

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.

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 do Azure Digital Twins (instruções para localizar). 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 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);
        }
    }
}

Quando você cria a credencial sem parâmetros, como mostrado no exemplo anterior, ela retorna a credencial para a identidade atribuída ao sistema do aplicativo de função, se 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 id parâmetro do construtor.

Método InteractiveBrowserCredential

O método InteractiveBrowserCredential destina-se a aplicativos interativos e exibe um navegador da Web para autenticação. Use este método em vez de DefaultAzureCredential quando necessitar de autenticação interativa.

Para usar as credenciais do navegador interativo, você precisa 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 a Gêmeos Digitais do Azure. Depois que o registro do aplicativo estiver configurado, você precisará dos seguintes valores:

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

Autenticar o Azure Functions

Esta seção contém opções de configuração importantes para autenticação com o Azure Functions. Primeiro, você leu sobre as variáveis de nível de classe recomendadas e o código de autenticação que permitem que a função acesse os Gêmeos Digitais do Azure. Em seguida, você leu 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, crie e defina o valor da variável de ambiente para que esse código seja lido. Para obter instruções sobre como fazer isso, consulte 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 deseja 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 usa 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>");
  

  Quando você cria a credencial sem parâmetros, como mostrado no exemplo anterior, ela retorna a credencial para a identidade atribuída ao sistema do aplicativo de função, se 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 id parâmetro do construtor.

  Mais tarde, depois de publicar a função, verifique 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, consulte 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. Para capturar quaisquer exceções, adicione a verificação nula e, em seguida, envolva sua lógica de função em um bloco try/catch.

Depois de adicionar essas variáveis a uma função, o código da 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.

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 a sua instância de Gêmeos Digitais do Azure, que dá permissão ao aplicativo de função para executar atividades no 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 dos Gêmeos Digitais do Azure para sua 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"
   

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.

O comando a seguir define uma variável de ambiente para a URL da instância que sua função usa sempre que precisa 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 varredura mal-intencionada dos endpoints do Azure Digital Twins, as solicitações com tokens de acesso de fora do tenant de origem retornam uma mensagem de erro "404 Sub-Domain não encontrado". Este erro é devolvido mesmo que o utilizador ou entidade de serviço tenha recebido um papel de Proprietário de Dados dos Gémeos Digitais do Azure ou de Leitor de Dados dos Gémeos Digitais do Azure através da colaboração Microsoft Entra B2B.

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

Após essa solicitação, a identidade recebe 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 residencial 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 descritos neste artigo não cobrirem as necessidades do seu aplicativo, explore 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

Para saber mais sobre como funciona a segurança nos Gêmeos Digitais do Azure, consulte:

• 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