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

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

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

В этой статье описывается, как получить учетные данные с помощью клиентской библиотеки Azure.Identity. В этой статье показаны примеры кода в C#, например то, что вы напишете для пакета SDK для .NET (C#), вы можете использовать версию 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#).

Добавьте Azure.Identity в ваш проект .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 или в 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);
        }
    }
}

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

Метод 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>");
  

  При создании учетных данных без параметров, как показано в предыдущем примере, возвращаются учетные данные для системно назначенного удостоверения функционного приложения, если оно имеется. Чтобы указать удостоверение пользователя, вместо этого передайте идентификатор клиента удостоверения пользователя в параметр конструктора 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.

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

В следующем примере показано, как установить пример ID арендатора для 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