Написание кода проверки подлинности клиентского приложения

После настройки экземпляра и проверки подлинности Azure Digital Twins можно создать клиентское приложение, которое будет использоваться для взаимодействия с экземпляром. После настройки проекта начального клиента необходимо написать код в этом клиентском приложении для проверки подлинности в экземпляре Azure Digital Twins.

Azure Digital Twins проходит проверку подлинности с помощью маркеров безопасности Microsoft Entra на основе OAUTH 2.0. Для проверки подлинности пакета SDK необходимо получить маркер носителя с нужными разрешениями для Azure Digital Twins и передать его вместе с вызовами API.

В этой статье описывается, как получить учетные данные с помощью клиентской библиотеки Azure.Identity. Несмотря на то что в этой статье показаны примеры кода на языке C#, например для пакета SDK для .NET, вы можете использовать версию Azure.Identity независимо от своего пакета SDK (дополнительные сведения о пакетах SDK, которые доступны для Azure Digital Twins, см. в API и пакетах SDK для Azure Digital Twins).

Необходимые компоненты

Сначала выполните действия по настройке, описанные в статье о настройке экземпляра и проверки подлинности. Эта настройка обеспечит наличие экземпляра Azure Digital Twins, а у пользователя есть разрешения на доступ. После установки вы будете готовы написать код клиентского приложения.

Чтобы продолжить, вам потребуется проект клиентского приложения, в котором вы пишете код. Если вы еще не настроили проект клиентского приложения, создайте базовый проект на выбранном вами языке для использования с этим руководством.

Проверка подлинности с помощью библиотеки Azure.Identity

Azure.Identity — это клиентская библиотека, которая предоставляет несколько методов получения учетных данных, которые можно использовать для получения маркера носителя и проверки подлинности с помощью пакета SDK. Хотя в этой статье приведены примеры на языке C#, можно просмотреть Azure.Identity для несколько языков, включая...

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

Три общих метода получения учетных данных в Azure.Identity:

• DefaultAzureCredential предоставляет поток проверки подлинности TokenCredential по умолчанию для приложений, которые будут развернуты в Azure. Это рекомендуемый вариант для локальной разработки. Также можно включить другие два метода, которые рекомендуются в этой статье. Они является оболочкой для ManagedIdentityCredential и могут иметь доступ к InteractiveBrowserCredential с переменной конфигурации.
• ManagedIdentityCredential хорошо работает в тех случаях, когда вам нужны управляемые удостоверения (MSI) и является хорошим кандидатом на работу с Функции Azure и развертыванием в службах Azure.
• InteractiveBrowserCredential предназначен для интерактивных приложений и может использоваться для создания клиента SDK с проверкой подлинности.

В остальной части этой статьи показано, как использовать эти методы с пакетом SDK для .NET (C#).

Добавление пакетов в проект .NET

Чтобы настроить проверку подлинности в проекте .NET с помощью Azure.Identity, выполните указанные ниже действия.

1. Сначала добавьте в проект пакет SDK Azure.DigitalTwins.Core и пакет Azure.Identity. В зависимости от выбранного средства можно включить пакеты с помощью диспетчера пакетов Visual Studio или средства командной dotnet строки.

2. Добавьте в код проекта приведенные ниже инструкции using.

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

Затем добавьте код для получения учетных данных с помощью одного из методов Azure.Identity. Следующие разделы содержат подробные сведения о каждом из них.

Метод DefaultAzureCredential

DefaultAzureCredential предоставляет поток проверки подлинности TokenCredential по умолчанию для приложений, которые будут развернуты в Azure. Это рекомендуемый вариант для локальной разработки.

Чтобы использовать учетные данные Azure по умолчанию, вам потребуется URL-адрес экземпляра Azure Digital Twins (инструкции по поиску).

Ниже приведен пример кода для добавления DefaultAzureCredential в проект:

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

Настройка локальных учетных данных Azure

При использовании DefaultAzureCredential пример будет искать учетные данные в локальной среде, например имя для входа Azure в локальной версии Azure CLI, в Visual Studio либо Visual Studio Code. Поэтому вам нужно войти в Azure локально с помощью одного из этих механизмов, чтобы настроить учетные данные для примера.

Если вы используете Visual Studio или Visual Studio Code для выполнения примеров кода, убедитесь, что вы вошли в этот редактор с теми же учетными данными Azure, которые вы хотите использовать для доступа к экземпляру Azure Digital Twins. Если вы используете локальное окно CLI, выполните az login команду, чтобы войти в учетную запись Azure. После этого при запуске примера кода необходимо автоматически пройти проверку подлинности.

Метод ManagedIdentityCredential

Метод ManagedIdentityCredential хорошо работает в тех случаях, когда требуются управляемые удостоверения (MSI), например при проверке подлинности с помощью Функции Azure.

Это означает, что вы можете использовать ManagedIdentityCredential в том же проекте, что DefaultAzureCredential и InteractiveBrowserCredentialдля проверки подлинности другой части проекта.

Чтобы использовать учетные данные Azure по умолчанию, вам потребуется URL-адрес экземпляра Azure Digital Twins (инструкции по поиску). Вам также может понадобиться регистрация приложения и идентификатор приложения (клиента) регистрации.

В функции Azure учетные данные управляемого удостоверения можно использовать следующим образом:

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

При создании учетных данных, оставляя параметр пустым, как показано выше, возвращает учетные данные для назначаемого системой удостоверения приложения-функции, если он имеет один. Чтобы указать удостоверение, назначаемое пользователем, передайте идентификатор клиента, назначаемого пользователем, в параметр.

Метод InteractiveBrowserCredential

Метод InteractiveBrowserCredential предназначен для интерактивных приложений и позволяет использовать веб-браузер для проверки подлинности. Этот метод можно использовать вместо DefaultAzureCredential тех случаев, когда требуется интерактивная проверка подлинности.

Чтобы использовать учетные данные интерактивного браузера, вам потребуется регистрация приложения с разрешениями на api Azure Digital Twins. Инструкции по настройке регистрации этого приложения см. в статье "Создание регистрации приложений с помощью Доступа к Azure Digital Twins". После настройки регистрации приложения вам потребуется...

• идентификатор приложения (клиента) регистрации приложения;
• идентификатор каталога (арендатора) регистрации приложения;
• URL-адрес экземпляра Azure Digital Twins.

Ниже приведен пример кода для создания клиента пакета SDK с проверкой подлинности.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);
        }
    }
}

Проверка подлинности с помощью Функций Azure

В этом разделе описаны некоторые важные параметры, настраиваемые в контексте проверки подлинности с помощью Функций Azure. Сначала вы прочтете о рекомендуемых переменных уровня класса и коде проверки подлинности, который позволит функции обращаться к Azure Digital Twins. Затем вы узнаете о заключительных этапах настройки, которые необходимо выполнить для функции после публикации ее кода в Azure.

Написание кода приложения

При создании функции Azure вы можете добавить в нее следующие переменные и код:

• Код для чтения URL-адреса службы Azure Digital Twins в качестве переменной среды или параметра конфигурации. Рекомендуется считывать URL-адрес службы из настройки приложения или переменной среды, а не указывать его в коде функции. В функции Azure код для считывания переменной среды может выглядеть следующим образом:

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

  Позже, после публикации функции, вы создадите и настроите значение переменной среды, считываемое этим кодом. Инструкции по настройке параметров приложения см. в разделе "Настройка параметров приложения".

• Статическая переменная для хранения экземпляра HttpClient. Создание HttpClient обходится относительно дорого, поэтому имеет смысл создать этот экземпляр один раз с кодом проверки подлинности, чтобы не делать это повторно для каждого вызова функции.

  private static readonly HttpClient singletonHttpClientInstance = new HttpClient();
  

• Учетные данные управляемого удостоверения. Создайте учетные данные управляемого удостоверения, которые функция будет использовать для доступа к Azure Digital Twins.

  // 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>");
  

  Если у него есть удостоверение, назначаемое системой, параметр пуст, как показано выше, возвращает учетные данные для назначаемого системой приложения-функции. Чтобы указать удостоверение, назначаемое пользователем, передайте идентификатор клиента, назначаемого пользователем, в параметр.

  Позже, после публикации функции, вы будете проверять, есть ли у удостоверения функции разрешение на доступ к API-интерфейсам Azure Digital Twins. Чтобы узнать, как это сделать, перейдите к назначению роли доступа.

• Локальная переменная DigitalTwinsClient. Добавьте переменную в функцию для хранения экземпляра клиента Azure Digital Twins. Не делайте эту переменную статической внутри класса.

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

• Значение NULL проверка для adtInstanceUrl. Добавьте проверку значения NULL и заключите логику функции в блок try/catch, чтобы перехватывать все исключения.

После добавления этих переменных в функцию код функции может выглядеть следующим образом.

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

Когда вы завершите работу с кодом функции, включая добавление проверки подлинности и логики, опубликуйте приложение в Azure.

Настройка опубликованного приложения

Наконец, выполните для опубликованной функции Azure указанные ниже действия, чтобы убедиться, что у нее есть доступ к вашему экземпляру Azure Digital Twins.

Выполните указанные ниже команды в Azure Cloud Shell или локальном экземпляре Azure CLI.

Назначение роли доступа

В функцию Azure необходимо передать токен носителя. Чтобы гарантированно передать токен носителя, предоставьте приложению-функции роль владельца данных Azure Digital Twins для своего экземпляра Azure Digital Twins, который предоставит приложению-функции разрешение на выполнение действий на плоскости данных в экземпляре.

1. Используйте следующую команду, чтобы создать управляемое системой удостоверение для функции (если функция уже имеет одну, эта команда будет выводить сведения о ней). Запишите principalId поле в выходных данных. Этот идентификатор будет использоваться для обращения к функции, чтобы вы могли предоставить ей разрешения на следующем шаге.

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

2. Используйте значение principalId в следующей команде, чтобы предоставить функции роль владельца Azure Digital Twins для вашего экземпляра Azure Digital Twins.

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

Настройка параметров приложения

Затем сделайте URL-адрес экземпляра Azure Digital Twins доступным для функции, задав переменную среды для нее.

Следующая команда задает переменную среды для URL-адреса экземпляра, который будет использоваться функцией при попытке доступа к экземпляру.

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>"

Аутентификация в клиентах

Azure Digital Twins — это служба, которая поддерживает только один клиент Microsoft Entra: основной клиент из подписки, в которой находится экземпляр Azure Digital Twins.

В результате для запросов к API Azure Digital Twins требуется пользователь или субъект-служба, который является частью того же арендатора, где находится экземпляр Azure Digital Twins. Чтобы предотвратить вредоносное сканирование конечных точек Azure Digital Twins, внешние запросы с маркерами доступа (за пределами исходного арендатора) будут возвращать сообщение об ошибке, информирующее о том, что поддомен не найден (404). Эта ошибка будет возвращена, даже если пользователь или субъект-служба получили роль владельца данных Azure Digital Twins или средства чтения данных Azure Digital Twins через совместную работу Microsoft Entra B2B.

Чтобы получить доступ к экземпляру Azure Digital Twins через субъект-службу или учетную запись пользователя, принадлежащую другому арендатору экземпляра, необходимо для каждого федеративного удостоверения другого арендатора запросить маркер из "домашнего" арендатора экземпляра Azure Digital Twins.

Одним из способов этого является следующая команда CLI, в которой <home-tenant-ID> находится идентификатор клиента Microsoft Entra, содержащего экземпляр Azure Digital Twins:

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

После запроса идентификатор получит маркер, выданный для https://digitaltwins.azure.net ресурса Microsoft Entra, который имеет соответствующее утверждение идентификатора клиента экземпляру Azure Digital Twins. Использование этого маркера в запросах API или коде Azure.Identity должно позволить федеративному идентификатору получить доступ к ресурсу Azure Digital Twins.

Также можно указать домашний клиент в параметрах учетных данных в коде.

В следующем примере показано, как задать пример значения идентификатора клиента в InteractiveBrowserTenantId параметрах 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);
}

Доступны аналогичные параметры, позволяющие настроить арендатор для проверки подлинности с помощью Visual Studio и Visual Studio Code. Дополнительные сведения о доступных параметрах см. в документации по DefaultAzureCredentialOptions.

Другие методы учетных данных

Если указанные выше сценарии проверки подлинности не охватывают потребности приложения, вы можете изучить другие типы проверки подлинности, предлагаемые в платформа удостоверений Майкрософт. Документация по этой платформе охватывает дополнительные сценарии проверки подлинности, упорядоченные по типу приложения.

Следующие шаги

Узнайте больше о работе системы безопасности в Azure Digital Twins:

• Безопасность решений Azure Digital Twins

Кроме того, теперь, когда проверка подлинности настроена, можно переходить к созданию моделей и управлению ими в экземпляре.

• Управление моделями DTDL