Краткое руководство: Настройка и получение токенов доступа для пользователей Microsoft Entra ID

В этом кратком руководстве показано, как использовать общий пакет SDK служб коммуникации вместе с пакетом SDK для удостоверений Azure в консольном приложении для проверки подлинности пользователя Microsoft Entra ID и получения маркера доступа к Службам коммуникации Azure. Полученный маркер доступа к службам коммуникации Azure позволяет интегрировать функции звонков с помощью пакета SDK для вызовов служб коммуникации. Обмен сообщениями (чат) с помощью интеграции идентификатора Microsoft Entra не поддерживается в общедоступной предварительной версии.

Prerequisites

• Учетная запись Azure с активной подпиской. Создайте учетную запись бесплатно .
• Активный ресурс Azure Communication Services и URI его конечной точки. Для получения дополнительной информации см. Создание ресурса Azure Communication Services.
• Экземпляр идентификатора Microsoft Entra. Дополнительные сведения см. в обзоре идентификатора Microsoft Entra.

Introduction

Приложение может поддерживать пользователей из того же клиента или из других клиентов. В этой инструкции по быстрому старту вы изучите многотенантный сценарий, включающий пользователей, разработчиков и администраторов из вымышленных компаний Contoso и Fabrikam. В этом примере Contoso предоставляет программное обеспечение как услуга (SaaS) для Fabrikam.

В следующих разделах описаны действия, необходимые для администраторов, разработчиков и пользователей. Представленные схемы иллюстрируют многопользовательский сценарий. Если вы работаете в среде с одним клиентом, выполните все действия для Contoso и Fabrikam в одном клиенте.

Действия администратора

Роль администратора имеет расширенные разрешения в идентификаторе Microsoft Entra. Члены этой роли могут настраивать ресурсы и управлять ими. На схеме ниже показаны все действия, которые выполняет администратор.

1. Администратор Contoso создает субъект-службу для приложения клиентов служб коммуникации в клиенте Contoso Entra ID. Этот шаг необходим, чтобы разрешить приложению Contoso доступ к разрешениям API приложений клиентов служб коммуникации.
2. Администратор Contoso создает или выбирает существующее приложение в идентификаторе Microsoft Entra. Свойство Поддерживаемые типы учетных записей определяет, могут ли пользователи из различных клиентов проходить в этом приложении проверку подлинности. Свойство URI перенаправления осуществляет перенаправление успешного запроса аутентификации в клиентское приложение Contoso.
3. Администратор Contoso добавляет необходимые разрешения API из приложения клиентов служб коммуникации. Полный список разрешений см. в разделе "Маркеры доступа" с идентификатором Microsoft Entra. (В общедоступной предварительной версии доступны только разрешения, связанные с VoIP; Разрешения чата пока не поддерживаются.)
4. Администратор Contoso создает или выбирает существующие службы коммуникации. Администратор Contoso предоставляет пользователям Fabrikam Entra ID доступ к ресурсу Contoso Azure Communication Services. Общий пакет SDK служб коммуникации Azure будет использоваться для проверки подлинности пользователя Microsoft Entra ID и в фоновом режиме для бесшовного получения токена доступа к Службам коммуникации Azure для пользователя Microsoft Entra ID.
5. Администратор Fabrikam предоставляет согласие администратора на требуемые разрешения API приложения клиента для служб коммуникации для приложения Contoso.

Шаг 1. Создание субъекта-службы для приложения клиентов Служб коммуникации Azure

Чтобы приложение Contoso могло получить доступ к разрешениям API приложения для клиентов Azure Communication Services, администратор Contoso должен создать учетную запись службы для приложения для клиентов Azure Communication Services в арендаторе Microsoft Entra ID Contoso. Администратор Contoso может создать субъект-службу в клиенте Contoso одним из следующих методов:

• Используйте REST API Microsoft Graph для выполнения следующего запроса:

POST https://graph.microsoft.com/v1.0/servicePrincipals
Content-Type: application/json
{
  "appId": "2a04943b-b6a7-4f65-8786-2bb6131b59f6"
}

Этот запрос также можно выполнить в обозревателе Graph. Обязательно включите полный домен клиента в URL-адрес https://developer.microsoft.com/graph/graph-explorer?tenant={tenant domain}, войдите и предоставьте согласие на Application.ReadWrite.All разрешение.

• Используйте Azure CLI для выполнения следующей команды:

az ad sp create --id 2a04943b-b6a7-4f65-8786-2bb6131b59f6

Шаг 2. Создание регистрации приложения Microsoft Entra или выбор приложения Microsoft Entra

Пользователи должны проходить аутентификацию для приложений Microsoft Entra с разрешениями на API клиентов Azure Communication Services. Если у вас нет приложения, которое вы хотите использовать для этого краткого руководства, вы можете зарегистрировать новое приложение.

Следующие настройки приложения влияют на опыт:

• Свойство Поддерживаемые типы учетных записей определяет, является ли приложение однотенантным (учетные записи только в этом каталоге организации) или мультитенантным (учетные записи в каталоге любой организации). В этом сценарии можно использовать мультитенантную архитектуру.
• URI перенаправления определяет адрес, куда запрос аутентификации перенаправляется после успешного завершения процесса аутентификации.

Дополнительные сведения см. в статье о регистрации приложения на платформе удостоверений Майкрософт.

Шаг 3. Добавление разрешений клиентов Служб коммуникации Azure в приложении

Приложение должно объявить клиента Служб коммуникации Azure, чтобы получить доступ к функциям Служб коммуникации Azure. Пользователь Microsoft Entra ID будет запрашивать токен пользователя Microsoft Entra с этими разрешениями.

1. Перейдите к приложению Microsoft Entra на портале Azure и выберите разрешения API
2. Выбор "Добавить разрешения"
3. В меню "Добавление разрешений" выберите API, которые использует моя организация
4. Поиск и выбор клиентов Служб коммуникации Azure
5. Выберите разрешение VoIP (и любое другое разрешение, связанное с VoIP.Join , если требуется), а затем нажмите кнопку "Добавить разрешения".
6. Предоставьте согласие администратора для всех делегированных разрешений.

Шаг 4. Создание или выбор ресурса служб коммуникации и предоставление пользователям Entra ID доступа к нему

Ресурс Служб коммуникации Azure используется для проверки подлинности всех запросов пользователей Идентификатора Майкрософт и предоставления им доступа к ресурсу.

Если вы хотите узнать, как создать ресурс Служб коммуникации, см. статью Создание ресурсов Служб коммуникации и управление ими.

Администратор Contoso может предоставить пользователям Fabrikam Entra ID доступ к ресурсу Служб связи Contoso через портал Azure или с помощью REST API назначения Entra ID.

В настоящее время назначение доступа к ресурсам Служб коммуникации Azure через портал Azure — это предварительная версия функции. Чтобы получить доступ к нему, запустите портал Azure с помощью этого URL-адреса — портал Azure с поддержкой предварительной версии назначения доступа. На портале Azure выполните следующие действия.

1. Перейдите к ресурсу Служб коммуникации.
2. В левой панели выберите Доступ пользователя для Entra ID в группе Настройки.
3. Нажмите кнопку "Добавить ", чтобы предоставить доступ к пользователю, группе или всему клиенту Entra.
4. В типе главной сущности выберите правильное значение. В этом сценарии администратор Contoso предоставляет доступ для группы из клиента Fabrikam и выбирает группу.
5. В поле "Идентификатор объекта " введите идентификатор объекта группы из клиента Fabrikam Microsoft Entra.
6. В поле идентификатора клиента введите идентификатор клиента клиента Fabrikam Microsoft Entra.
7. В поле идентификатора клиента введите идентификатор клиента приложения Contoso с шага 2.
8. Нажмите кнопку "Сохранить" и выйти , чтобы применить изменения.

Шаг 5. Предоставление согласия администратора и группового доступа к приложению клиентов Azure Communication Services

Клиент Microsoft Entra можно настроить, чтобы требовать согласие администратора Microsoft Entra для разрешений API клиентов служб коммуникации Azure для приложения. В таком случае администратор Microsoft Entra должен предоставить разрешения приложению Contoso для разрешений API клиентов Служб коммуникации Azure. Администратор Microsoft Entra Fabrikam предоставляет согласие с помощью уникального URL-адреса.

Следующие роли могут предоставлять согласие от имени компании:

• Глобальный администратор
• Администратор приложения
• Администратор облачных приложений

Если вы хотите проверить роли в портал Azure, ознакомьтесь со списком назначений ролей Azure.

Чтобы создать URL-адрес согласия администратора, администратор Microsoft Entra Fabrikam выполняет следующие действия:

1. В URL-адресе https://login.microsoftonline.com/{Tenant_ID}/adminconsent?client_id={Application_ID}администратор заменяет {Tenant_ID} идентификатором клиента Fabrikam и заменяет {Application_ID} идентификатором приложения Contoso.
2. Администратор входит в систему и предоставляет разрешения от имени организации.

Если согласие предоставлено, в клиенте Fabrikam создается субъект-служба приложения Contoso. Администратор Fabrikam может просмотреть согласие в идентификаторе Microsoft Entra, выполнив следующие действия:

1. Выполните вход на портал Azure в качестве администратора.
2. Перейдите к идентификатору Microsoft Entra.
3. На панели корпоративных приложений задайте фильтр типа приложениядля всех приложений.
4. В поле для фильтрации приложений введите имя приложения Contoso.
5. Нажмите кнопку "Применить".
6. Выберите субъект-службу с требуемым именем.
7. Перейдите на панель "Разрешения ".

Вы увидите, что статус разрешений API приложения клиентов служб коммуникации предоставлено для {Directory_name}.

При возникновении проблемы "Приложение пытается получить доступ к службе '2a04943b-b6a7-4f65-8786-2bb6131b59f6' (Службы коммуникации Azure для клиентов), у вашей организации '{GUID}' отсутствует служебный принципал. Необходимо создать субъект-службу для клиента, следуя инструкциям на шаге 1. Создание субъекта-службы для приложения клиентов Служб коммуникации Azure.

Доступ группы к приложению Azure Communication Services Clients должен быть предоставлен только в том случае, если администратор Contoso предоставил групповой доступ к ресурсу Служб коммуникации Azure Contoso на предыдущем шаге. Для доступа пользователя или всего клиента к ресурсу Служб коммуникации Azure администратор Fabrikam может пропустить этот шаг.

Для назначения, основанного на группах, требуется выпуск Microsoft Entra ID P1 или P2. Администратор Fabrikam может предоставить доступ к группе из клиента Fabrikam с помощью Центра администрирования Microsoft Entra. Чтобы предоставить доступ к группе, администратор Fabrikam выполняет следующие действия:

1. Войдите в Центр администрирования Microsoft Entra с помощью ролей глобального администратора или администратора клиента .
2. Перейдите к > в меню слева.
3. В поле поиска введите клиенты Служб коммуникации Azure и выберите приложение из результатов поиска.
4. В меню слева выберите "Пользователи" и "Группы" , а затем выберите "Добавить пользователя или группу".
5. На панели "Добавить назначение" выберите "Никто не выбран " в разделе "Пользователи и группы".
6. Найдите и выберите группу, которую вы хотите назначить приложению.
7. Нажмите «Выбрать», а затем «Назначить», чтобы назначить группу приложению.

Действия разработчика

Разработчик Contoso должен настроить клиентское приложение для проверки подлинности пользователей. В клиентском приложении разработчик создает учетные данные с помощью пакета Communication Common SDK вместе с любой реализацией TokenCredential из пакета Azure Identity SDK, способного проверить подлинность пользователей в приложении Microsoft Entra ID.

Необходимые действия разработчика показаны на следующей схеме.

1. Разработчик Contoso инициализирует любую реализацию TokenCredential из пакета SDK для удостоверений Azure, способного получить токен пользователя Microsoft Entra для приложения, созданного ранее администратором Contoso.
2. Разработчик Contoso инициализирует AzureCommunicationTokenCredential из Общего SDK Служб связи с TokenCredential, созданным на шаге 1. Объект AzureCommunicationTokenCredential бесшовно получает токен доступа к службам коммуникации Azure для пользователя, зарегистрированного в Microsoft Entra ID, в фоновом режиме.

dotnet new console -o EntraIdUsersSupportQuickstart

cd EntraIdUsersSupportQuickstart
dotnet build

dotnet add package Azure.Identity
dotnet add package Azure.Communication.Common

using Azure.Communication;
using Azure.Identity;

namespace EntraIdUsersSupportQuickstart
{
    class Program
    {
        static async Task Main(string[] args)
        {
            Console.WriteLine("Azure Communication Services - Obtain Access Token for Entra ID User Quickstart");

            // Quickstart code goes here
        }
    }
}

// This code demonstrates how to fetch your Microsoft Entra client ID and tenant ID from environment variables.
string clientId = Environment.GetEnvironmentVariable("ENTRA_CLIENT_ID");
string tenantId = Environment.GetEnvironmentVariable("ENTRA_TENANT_ID");

//Initialize InteractiveBrowserCredential for use with CommunicationTokenCredential.
var options = new InteractiveBrowserCredentialOptions
{
    TenantId = tenantId,
    ClientId = clientId,
};
var entraTokenCredential = new InteractiveBrowserCredential(options);

// This code demonstrates how to fetch your Azure Communication Services resource endpoint URI
// from an environment variable.
string resourceEndpoint = Environment.GetEnvironmentVariable("COMMUNICATION_SERVICES_RESOURCE_ENDPOINT");

// Set up CommunicationTokenCredential to request a Communication Services access token for a Microsoft Entra ID user.
var entraTokenCredentialOptions = new EntraCommunicationTokenCredentialOptions(
    resourceEndpoint: resourceEndpoint,
    entraTokenCredential: entraTokenCredential)
{
    Scopes = new[] { "https://communication.azure.com/clients/VoIP" }
};

var credential = new CommunicationTokenCredential(entraTokenCredentialOptions);

// To obtain a Communication Services access token for Microsoft Entra ID call GetTokenAsync() method.
var accessToken = await credential.GetTokenAsync();
Console.WriteLine($"Token: {accessToken.Token}");

dotnet run

mkdir entra-id-users-support-quickstart && cd entra-id-users-support-quickstart

npm init -y

npm install @azure/communication-common --save
npm install @azure/identity --save
npm install react react-dom --save
npm install vite --save

"scripts": {
  "dev": "vite",
  "build": "vite build",
  "preview": "vite preview"
}

// Initialize InteractiveBrowserCredential for use with AzureCommunicationTokenCredential.
const entraTokenCredential = new InteractiveBrowserCredential({
    tenantId: tenantId,
    clientId: clientId,
    authorityHost: "https://login.microsoftonline.com/organizations",
});

// Set up AzureCommunicationTokenCredential to request a Communication Services access token for a Microsoft Entra ID user.
const entraCommunicationTokenCredential = new AzureCommunicationTokenCredential({
    resourceEndpoint: resourceEndpoint,
    tokenCredential: entraTokenCredential,
});

// To obtain a Communication Services access token for Microsoft Entra ID call getToken() function.
let accessToken = await entraCommunicationTokenCredential.getToken();
setAccessToken(accessToken.token);

npm run dev 

Действия пользователя

Пользователь представляет пользователей Fabrikam приложения Contoso. Интерфейс пользователя показан на следующей схеме:

1. Пользователь Fabrikam использует клиентское приложение Contoso и запрашивает проверку подлинности.
2. Клиентское приложение Contoso использует пакет SDK для удостоверений Azure для проверки подлинности пользователя в клиенте Fabrikam Microsoft Entra для приложения Contoso с разрешениями клиентов Служб коммуникации. Проверка подлинности перенаправляется в клиентское приложение, как указано в свойстве URI перенаправления приложения Contoso.
3. Унифицированный SDK для коммуникации беспрепятственно получает токен доступа к Службам коммуникации Azure для пользователя Fabrikam Entra ID в фоновом режиме.

Разработчики могут интегрировать пакет SDK для вызовов служб коммуникации, предоставив AzureCommunicationTokenCredential. (Интеграция пакета SDK чата с помощью идентификатора Entra будет доступна при добавлении поддержки обмена сообщениями после общедоступной предварительной версии.)

Дальнейшие шаги

В этом кратком руководстве вы узнали, как выполнить следующие действия:

• Поддержка пользователей идентификатора Microsoft Entra в Службах коммуникации Azure
• Тенант в Microsoft Entra ID