Краткое руководство. Создание маркеров доступа и управление ими

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

Из этого краткого руководства вы узнаете, как использовать пакеты SDK для Службы коммуникации Azure для создания удостоверений и управления маркерами доступа. Для рабочих вариантов использования рекомендуется создавать маркеры доступа на стороне сервера.

Предварительные требования

Настройка

Добавление расширения

Добавьте расширение Службы коммуникации Azure для Azure CLI с помощью az extension команды.

az extension add --name communication

Вход в Azure CLI

Вам потребуется войти в Azure CLI. Вы можете выполнить az login команду из терминала и предоставить учетные данные.

(Необязательно) Использование операций идентификации Azure CLI без передачи строки подключения

Переменную среды можно настроить AZURE_COMMUNICATION_CONNECTION_STRING для использования операций идентификации Azure CLI без необходимости --connection_string передавать строку подключения. Чтобы настроить переменную среды, откройте окно консоли и выберите операционную систему на следующих вкладках. Замените <yourConnectionString> фактической строкой подключения.

Откройте окно консоли и введите следующую команду:

setx AZURE_COMMUNICATION_CONNECTION_STRING "<yourConnectionString>"

После добавления переменной среды может потребоваться перезапустить все запущенные приложения, которым может понадобиться считать переменную среды, в том числе окно консоли. Например, если вы используете Visual Studio в качестве редактора, перезапустите Visual Studio перед запуском примера.

Сохранение маркера доступа в переменной среды

Чтобы настроить переменную среды, откройте окно консоли и выберите операционную систему на следующих вкладках. Замените <yourAccessToken> фактическим маркером доступа.

Откройте окно консоли и введите следующую команду:

setx AZURE_COMMUNICATION_ACCESS_TOKEN "<yourAccessToken>"

После добавления переменной среды может потребоваться перезапустить все запущенные приложения, которым может понадобиться считать переменную среды, в том числе окно консоли. Например, если вы используете Visual Studio в качестве редактора, перезапустите Visual Studio перед запуском примера.

Operations

Создание удостоверения

Чтобы создать маркеры доступа, вам потребуется удостоверение. Службы коммуникации Azure позволяют использовать упрощенный каталог удостоверений. user create Используйте команду для создания новой записи в каталоге с уникальнымId. Удостоверение потребуется позже для выдачи маркеров доступа.

az communication identity user create --connection-string "<yourConnectionString>"
  • Замените <yourConnectionString> вашей строкой подключения.

Создание удостоверения и выдача маркера доступа в том же запросе

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

az communication identity token issue --scope chat --connection-string "<yourConnectionString>"

Внесите эту замену в код:

  • Замените <yourConnectionString> вашей строкой подключения.

Выдача маркера доступа

Выполните следующую команду, чтобы выдать маркер доступа для удостоверения Служб коммуникации. Параметр scopes определяет набор разрешений и ролей маркера доступа. Дополнительные сведения см. в списке поддерживаемых действий в Службы коммуникации Azure аутентификации.

az communication identity token issue --scope chat --user "<userId>" --connection-string "<yourConnectionString>"

Внесите эту замену в код:

  • Замените <yourConnectionString> вашей строкой подключения.
  • Замените <userId> идентификатором пользователя.

Маркеры доступа — это недолговечные учетные данные, которые необходимо выдавать повторно. Это может привести к нарушению работы пользователей приложения. Свойство ответа expires_on указывает время существования маркера доступа.

Выдача маркера доступа с несколькими областями

Выполните следующую команду, чтобы выдать маркер доступа с несколькими областями для удостоверения Служб коммуникации. Параметр scopes определяет набор разрешений и ролей маркера доступа. Дополнительные сведения см. в списке поддерживаемых действий в модели удостоверений.

az communication identity token issue --scope chat voip --user "<userId>" --connection-string "<yourConnectionString>"

Внесите эту замену в код:

  • Замените <yourConnectionString> вашей строкой подключения.
  • Замените <userId> идентификатором пользователя.

Маркеры доступа — это недолговечные учетные данные, которые необходимо выдавать повторно. Это может привести к нарушению работы пользователей приложения. Свойство ответа expires_on указывает время существования маркера доступа.

Обмен маркером доступа Azure AD пользователя Teams для маркера доступа к удостоверениям связи

token get-for-teams-user Используйте команду, чтобы выдать маркер доступа для пользователя Teams, который можно использовать с пакетами SDK для Службы коммуникации Azure.

az communication identity token get-for-teams-user --aad-token "<yourAadToken>" --client "<yourAadApplication>" --aad-user "<yourAadUser>" --connection-string "<yourConnectionString>"

Внесите эту замену в код:

  • Замените <yourConnectionString> вашей строкой подключения.
  • Замените <yourAadUser> идентификатор пользователя Azure Active Directory.
  • Замените <yourAadApplication> идентификатором приложения Azure Active Directory.
  • Замените <yourAadToken> маркер доступа Azure Active Directory.

Отмена маркеров доступа

Иногда может потребоваться явно отозвать маркер доступа. Например, это можно сделать, когда пользователи приложения изменяют пароль, используемый для проверки подлинности в службе. Команда token revoke делает недействительными все активные маркеры доступа, выданные удостоверению.

az communication identity token revoke --user "<userId>" --connection-string "<yourConnectionString>"

Внесите эту замену в код:

  • Замените <yourConnectionString> вашей строкой подключения.
  • Замените <userId> идентификатором пользователя.

Удаление удостоверения

При удалении удостоверения вы отменяете все активные маркеры доступа и предотвращаете дальнейшую выдачу маркеров доступа для удостоверения. При этом также удаляются все сохраненные содержимое, связанное с удостоверением.

az communication identity user delete --user "<userId>" --connection-string "<yourConnectionString>"

Внесите эту замену в код:

  • Замените <yourConnectionString> вашей строкой подключения.
  • Замените <userId> идентификатором пользователя.

Предварительные требования

Окончательный код

Итоговый код для этого краткого руководства можно найти на сайте GitHub.

Настройка среды

Создание нового приложения C#

В окне командной строки, например cmd, PowerShell или Bash, выполните dotnet new команду, чтобы создать консольное приложение с именем AccessTokensQuickstart. Эта команда создает простой проект "Hello World" на языке C# с одним файлом исходного кода Program.cs.

dotnet new console -o AccessTokensQuickstart

Измените каталог на только что созданную папку приложения и выполните команду dotnet build, чтобы скомпилировать приложение.

cd AccessTokensQuickstart
dotnet build

Должны отображаться простые выходные данные "Hello World". Если это так, ваша настройка работает правильно, и вы можете приступить к написанию кода, относящийся к Службы коммуникации Azure.

Установка пакета

Оставаясь в каталоге приложения, установите пакет библиотеки удостоверений Служб коммуникации Azure для .NET с помощью команды dotnet add package.

dotnet add package Azure.Communication.Identity --version 1.0.0

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

В каталоге проекта выполните следующие действия.

  1. Откройте файл Program.cs в текстовом редакторе.
  2. Добавьте директиву using для включения Azure.Communication.Identity пространства имен.
  3. Обновите объявление метода Main, чтобы он поддерживал асинхронный код.

Для начала выполните следующий код:

using System;
using Azure;
using Azure.Core;
using Azure.Communication.Identity;

namespace AccessTokensQuickstart
{
    class Program
    {
        static async System.Threading.Tasks.Task Main(string[] args)
        {
            Console.WriteLine("Azure Communication Services - Access Tokens Quickstart");

            // Quickstart code goes here
        }
    }
}

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

Инициализируйте CommunicationIdentityClient строку подключения. Следующий код, добавляемый в Main метод, извлекает строку подключения для ресурса из переменной среды с именем COMMUNICATION_SERVICES_CONNECTION_STRING.

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

// This code demonstrates how to retrieve your connection string
// from an environment variable.
string connectionString = Environment.GetEnvironmentVariable("COMMUNICATION_SERVICES_CONNECTION_STRING");
var client = new CommunicationIdentityClient(connectionString);

Кроме того, можно разделить конечную точку и ключ доступа, выполнив следующий код:

// This code demonstrates how to fetch your endpoint and access key
// from an environment variable.
string endpoint = Environment.GetEnvironmentVariable("COMMUNICATION_SERVICES_ENDPOINT");
string accessKey = Environment.GetEnvironmentVariable("COMMUNICATION_SERVICES_ACCESSKEY");
var client = new CommunicationIdentityClient(new Uri(endpoint), new AzureKeyCredential(accessKey));

Если вы уже настроили приложение Azure Active Directory (Azure AD), вы можете пройти проверку подлинности с помощью Azure AD.

TokenCredential tokenCredential = new DefaultAzureCredential();
var client = new CommunicationIdentityClient(new Uri(endpoint), tokenCredential);

Создание удостоверения

Чтобы создать маркеры доступа, вам потребуется удостоверение. Службы коммуникации Azure позволяют использовать упрощенный каталог удостоверений. Чтобы создать новую запись в каталоге с уникальным идентификатором (Id), используйте метод createUser. Удостоверение потребуется позже для выдачи маркеров доступа.

var identityResponse = await client.CreateUserAsync();
var identity = identityResponse.Value;
Console.WriteLine($"\nCreated an identity with ID: {identity.Id}");

Сохраните полученное удостоверение с сопоставлением с пользователями приложения (например, сохраняя его в базе данных сервера приложений).

Выпуск маркеров доступа

После получения удостоверения Служб коммуникации используйте GetToken метод для выдачи маркера доступа. Параметр scopes определяет набор разрешений и ролей маркера доступа. Дополнительные сведения см. в списке поддерживаемых действий в модели удостоверений. Вы также можете создать новый экземпляр communicationUser на основе строкового представления удостоверения Службы коммуникации Azure.

// Issue an access token with the "voip" scope for an identity
var tokenResponse = await client.GetTokenAsync(identity, scopes: new [] { CommunicationTokenScope.VoIP });

// Get the token from the response
var token =  tokenResponse.Value.Token;
var expiresOn = tokenResponse.Value.ExpiresOn;

// Write the token details to the screen
Console.WriteLine($"\nIssued an access token with 'voip' scope that expires at {expiresOn}:");
Console.WriteLine(token);

Маркеры доступа — это недолговечные учетные данные, которые необходимо выдавать повторно. Это может привести к нарушению работы пользователей приложения. Свойство expiresOn обозначает время существования маркера доступа.

Создание удостоверения и выдача маркера в том же запросе

Чтобы создать удостоверение Служб коммуникации и одновременно выдать маркер доступа для него, можно воспользоваться методом CreateUserAndTokenAsync. Параметр scopes определяет набор разрешений и ролей маркера доступа. Дополнительные сведения см. в списке поддерживаемых действий в Службы коммуникации Azure аутентификации.

// Issue an identity and an access token with the "voip" scope for the new identity
var identityAndTokenResponse = await client.CreateUserAndTokenAsync(scopes: new[] { CommunicationTokenScope.VoIP });

// Retrieve the identity, token, and expiration date from the response
var identity = identityAndTokenResponse.Value.User;
var token = identityAndTokenResponse.Value.AccessToken.Token;
var expiresOn = identityAndTokenResponse.Value.AccessToken.ExpiresOn;

// Print the details to the screen
Console.WriteLine($"\nCreated an identity with ID: {identity.Id}");
Console.WriteLine($"\nIssued an access token with 'voip' scope that expires at {expiresOn}:");
Console.WriteLine(token);

Обновление токенов доступа

Чтобы обновить маркер доступа, передайте экземпляр объекта CommunicationUserIdentifier в метод GetTokenAsync. Если вы сохранили значение Id и вам нужно создать новый объект CommunicationUserIdentifier, для этого можно передать сохраненное значение Id в конструктор CommunicationUserIdentifier следующим образом:

var identityToRefresh = new CommunicationUserIdentifier(identity.Id);
var tokenResponse = await client.GetTokenAsync(identityToRefresh, scopes: new [] { CommunicationTokenScope.VoIP });

Отмена маркеров доступа

Иногда может потребоваться явно отозвать маркер доступа. Например, это можно сделать, когда пользователи приложения изменяют пароль, используемый для проверки подлинности в службе. Этот RevokeTokensAsync метод делает недействительными все активные маркеры доступа, выданные удостоверению.

await client.RevokeTokensAsync(identity);
Console.WriteLine($"\nSuccessfully revoked all access tokens for identity with ID: {identity.Id}");

Удаление удостоверения

При удалении удостоверения вы отменяете все активные маркеры доступа и предотвращаете дальнейшую выдачу маркеров доступа для удостоверения. При этом также удаляются все сохраненные содержимое, связанное с удостоверением.

await client.DeleteUserAsync(identity);
Console.WriteLine($"\nDeleted the identity with ID: {identity.Id}");

Выполнение кода

Завершив создание маркера доступа, вы можете запустить приложение из каталога приложения с помощью dotnet run команды.

dotnet run

Выходные данные приложения описывают каждое завершенное действие:

Azure Communication Services - Access Tokens Quickstart

Created an identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

Issued an access token with 'voip' scope that expires at 30/03/21 08:09 09 AM:
<token signature here>

Created an identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-1ce9-31b4-54b7-a43a0d006a52

Issued an access token with 'voip' scope that expires at 30/03/21 08:09 09 AM:
<token signature here>

Successfully revoked all access tokens for identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

Deleted the identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

Предварительные требования

Окончательный код

Итоговый код для этого краткого руководства можно найти на сайте GitHub.

Настройка среды

создание приложения Node.js;

В окне терминала или командной строки создайте каталог для приложения, а затем откройте его.

mkdir access-tokens-quickstart && cd access-tokens-quickstart

Воспользуйтесь командой npm init -y, чтобы создать файл package.json с параметрами по умолчанию.

npm init -y

Установка пакета

Используйте команду npm install, чтобы установить пакет SDK для Служб коммуникации Azure для удостоверений для JavaScript.

npm install @azure/communication-identity --save

Параметр --save указывает библиотеку как зависимость в файле пакета package.json.

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

  1. Создайте файл с именем issue-access-token.js в каталоге проекта и добавьте следующий код:

    const { CommunicationIdentityClient } = require('@azure/communication-identity');
    
    const main = async () => {
      console.log("Azure Communication Services - Access Tokens Quickstart")
    
      // Quickstart code goes here
    };
    
    main().catch((error) => {
      console.log("Encountered an error");
      console.log(error);
    })
    

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

Создайте CommunicationIdentityClient экземпляр со строкой подключения. Следующий код, добавляемый в Main метод, извлекает строку подключения для ресурса из переменной среды с именем COMMUNICATION_SERVICES_CONNECTION_STRING.

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

// This code demonstrates how to fetch your connection string
// from an environment variable.
const connectionString = process.env['COMMUNICATION_SERVICES_CONNECTION_STRING'];

// Instantiate the identity client
const identityClient = new CommunicationIdentityClient(connectionString);

Кроме того, можно разделить конечную точку и ключ доступа, выполнив следующий код:

// This code demonstrates how to fetch your endpoint and access key
// from an environment variable.
const endpoint = process.env["COMMUNICATION_SERVICES_ENDPOINT"];
const accessKey = process.env["COMMUNICATION_SERVICES_ACCESSKEY"];

// Create the credential
const tokenCredential = new AzureKeyCredential(accessKey);

// Instantiate the identity client
const identityClient = new CommunicationIdentityClient(endpoint, tokenCredential)

Если вы уже настроили приложение Azure Active Directory (Azure AD), вы можете пройти проверку подлинности с помощью Azure AD.

const endpoint = process.env["COMMUNICATION_SERVICES_ENDPOINT"];
const tokenCredential = new DefaultAzureCredential();
const identityClient = new CommunicationIdentityClient(endpoint, tokenCredential);

Создание удостоверения

Чтобы создать маркеры доступа, вам потребуется удостоверение. Службы коммуникации Azure позволяют использовать упрощенный каталог удостоверений. Чтобы создать новую запись в каталоге с уникальным идентификатором (Id), используйте метод createUser. Удостоверение потребуется позже для выдачи маркеров доступа.

let identityResponse = await identityClient.createUser();
console.log(`\nCreated an identity with ID: ${identityResponse.communicationUserId}`);

Сохраните полученное удостоверение с сопоставлением с пользователями приложения (например, сохраняя его в базе данных сервера приложений).

Выпуск маркеров доступа

Используйте метод для выдачи getToken маркера доступа для удостоверения Служб коммуникации. Параметр scopes определяет набор разрешений и ролей маркера доступа. Дополнительные сведения см. в списке поддерживаемых действий в модели удостоверений. Вы также можете создать новый экземпляр на communicationUser основе строкового представления удостоверения Службы коммуникации Azure.

// Issue an access token with the "voip" scope for an identity
let tokenResponse = await identityClient.getToken(identityResponse, ["voip"]);

// Get the token and its expiration date from the response
const { token, expiresOn } = tokenResponse;

// Print the expiration date and token to the screen
console.log(`\nIssued an access token with 'voip' scope that expires at ${expiresOn}:`);
console.log(token);

Маркеры доступа — это недолговечные учетные данные, которые необходимо выдавать повторно. Это может привести к нарушению работы пользователей приложения. Свойство expiresOn обозначает время существования маркера доступа.

Создание удостоверения и выдача маркера в одном вызове метода

Чтобы создать удостоверение Служб коммуникации и одновременно выдать маркер доступа для него, можно воспользоваться методом createUserAndToken. Параметр scopes определяет набор разрешений и ролей маркера доступа. Опять же, вы создадите его с областью voip .

// Issue an identity and an access token with the "voip" scope for the new identity
let identityTokenResponse = await identityClient.createUserAndToken(["voip"]);

// Get the token, its expiration date, and the user from the response
const { token, expiresOn, user } = identityTokenResponse;

// print these details to the screen
console.log(`\nCreated an identity with ID: ${user.communicationUserId}`);
console.log(`\nIssued an access token with 'voip' scope that expires at ${expiresOn}:`);
console.log(token);

Обновление токенов доступа

Маркеры необходимо периодически обновлять по мере истечения срока их действия. Для обновления достаточно снова вызвать метод getToken с тем же идентификатором, который использовался для выдачи маркеров. Также необходимо указать scopes для обновляемых маркеров.

// Value of identityResponse represents the Azure Communication Services identity stored during identity creation and then used to issue the tokens being refreshed
let refreshedTokenResponse = await identityClient.getToken(identityResponse, ["voip"]);

Отмена маркеров доступа

Иногда может потребоваться отозвать маркер доступа. Например, это можно сделать, когда пользователи приложения изменяют пароль, используемый для проверки подлинности в службе. Этот revokeTokens метод делает недействительными все активные маркеры доступа, выданные удостоверению.

await identityClient.revokeTokens(identityResponse);

console.log(`\nSuccessfully revoked all access tokens for identity with ID: ${identityResponse.communicationUserId}`);

Удаление удостоверения

При удалении удостоверения вы отменяете все активные маркеры доступа и предотвращаете дальнейшую выдачу маркеров доступа для удостоверения. При этом также удаляются все сохраненные содержимое, связанное с удостоверением.

await identityClient.deleteUser(identityResponse);

console.log(`\nDeleted the identity with ID: ${identityResponse.communicationUserId}`);

Выполнение кода

В командной строке консоли перейдите в каталог, содержащий файлissue-access-token.js , а затем выполните следующую node команду, чтобы запустить приложение:

node ./issue-access-token.js

Выходные данные приложения описывают каждое завершенное действие:

Azure Communication Services - Access Tokens Quickstart

Created an identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

Issued an access token with 'voip' scope that expires at 30/03/21 08:09 09 AM:
<token signature here>

Created an identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-1ce9-31b4-54b7-a43a0d006a52

Issued an access token with 'voip' scope that expires at 30/03/21 08:09 09 AM:
<token signature here>

Successfully revoked all access tokens for identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

Deleted the identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

Предварительные требования

Окончательный код

Итоговый код для этого краткого руководства можно найти на сайте GitHub.

Настройка среды

Создание приложения Python

  1. В окне терминала или командной строки создайте каталог для приложения, а затем откройте его.

    mkdir access-tokens-quickstart && cd access-tokens-quickstart
    
  2. Используйте текстовый редактор, чтобы создать файл с именем issue-access-tokens.py в корневом каталоге проекта и добавить структуру для программы, включая базовую обработку исключений. Вы добавите весь исходный код для этого краткого руководства в этот файл в следующих разделах.

    import os
    from azure.communication.identity import CommunicationIdentityClient, CommunicationUserIdentifier
    
    try:
       print("Azure Communication Services - Access Tokens Quickstart")
       # Quickstart code goes here
    except Exception as ex:
       print("Exception:")
       print(ex)
    

Установка пакета

Пока вы все еще находитесь в каталоге приложения, установите пакет SDK для удостоверений Службы коммуникации Azure для Python с помощью pip install команды.

pip install azure-communication-identity

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

Создайте экземпляр CommunicationIdentityClient с использованием строки подключения. Следующий код, добавляемый в try блок, извлекает строку подключения для ресурса из переменной среды с именем COMMUNICATION_SERVICES_CONNECTION_STRING.

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

# This code demonstrates how to retrieve your connection string
# from an environment variable.
connection_string = os.environ["COMMUNICATION_SERVICES_CONNECTION_STRING"]

# Instantiate the identity client
client = CommunicationIdentityClient.from_connection_string(connection_string)

Кроме того, если вы уже настроили приложение Azure Active Directory (Azure AD), вы можете пройти проверку подлинности с помощью Azure AD.

endpoint = os.environ["COMMUNICATION_SERVICES_ENDPOINT"]
client = CommunicationIdentityClient(endpoint, DefaultAzureCredential())

Создание удостоверения

Чтобы создать маркеры доступа, вам потребуется удостоверение. Службы коммуникации Azure позволяют использовать упрощенный каталог удостоверений. Чтобы создать новую запись в каталоге с уникальным идентификатором (Id), используйте метод create_user. Удостоверение потребуется позже для выдачи маркеров доступа.

identity = client.create_user()
print("\nCreated an identity with ID: " + identity.properties['id'])

Сохраните полученное удостоверение с сопоставлением с пользователями приложения (например, сохраняя его в базе данных сервера приложений).

Выпуск маркеров доступа

Используйте метод для выдачи get_token маркера доступа для удостоверения Служб коммуникации. Параметр scopes определяет набор разрешений и ролей маркера доступа. Дополнительные сведения см. в списке поддерживаемых действий в модели удостоверений. Можно также создать новый экземпляр параметра CommunicationUserIdentifier на основе строкового представления удостоверения Службы коммуникации Azure.

# Issue an access token with the "voip" scope for an identity
token_result = client.get_token(identity, ["voip"])
expires_on = token_result.expires_on.strftime("%d/%m/%y %I:%M %S %p")

# Print the details to the screen
print("\nIssued an access token with 'voip' scope that expires at " + expires_on + ":")
print(token_result.token)

Маркеры доступа — это недолговечные учетные данные, которые необходимо выдавать повторно. Это может привести к нарушению работы пользователей приложения. Свойство ответа expires_on указывает время существования маркера доступа.

Создание удостоверения и выдача маркера доступа в том же запросе

Чтобы создать удостоверение Служб коммуникации и одновременно выдать маркер доступа для него, можно воспользоваться методом create_user_and_token. Параметр scopes определяет набор разрешений и ролей маркера доступа. Дополнительные сведения см. в списке поддерживаемых действий в Службы коммуникации Azure аутентификации.

# Issue an identity and an access token with the "voip" scope for the new identity
identity_token_result = client.create_user_and_token(["voip"])

# Get the token details from the response
identity = identity_token_result[0]
token = identity_token_result[1].token
expires_on = identity_token_result[1].expires_on.strftime("%d/%m/%y %I:%M %S %p")

# Print the details to the screen
print("\nCreated an identity with ID: " + identity.properties['id'])
print("\nIssued an access token with 'voip' scope that expires at " + expires_on + ":")
print(token)

Обновление токенов доступа

Чтобы обновить маркер доступа, используйте объект CommunicationUserIdentifier, чтобы повторно выдать маркер, передав существующее удостоверение:

# The existingIdentity value represents the Communication Services identity that's stored during identity creation
identity = CommunicationUserIdentifier(existingIdentity)
token_result = client.get_token(identity, ["voip"])

Отмена маркеров доступа

Иногда может потребоваться явно отозвать маркер доступа. Например, это можно сделать, когда пользователи приложения изменяют пароль, используемый для проверки подлинности в службе. Этот revoke_tokens метод делает недействительными все активные маркеры доступа, выданные удостоверению.

client.revoke_tokens(identity)
print("\nSuccessfully revoked all access tokens for identity with ID: " + identity.properties['id'])

Удаление удостоверения

При удалении удостоверения вы отменяете все активные маркеры доступа и предотвращаете дальнейшую выдачу маркеров доступа для удостоверения. При этом также удаляются все сохраненные содержимое, связанное с удостоверением.

client.delete_user(identity)
print("\nDeleted the identity with ID: " + identity.properties['id'])

Выполнение кода

В командной строке консоли перейдите в каталог, содержащий файл issue-access-tokens.py , а затем выполните следующую python команду, чтобы запустить приложение.

python ./issue-access-tokens.py

Выходные данные приложения описывают каждое завершенное действие:

Azure Communication Services - Access Tokens Quickstart

Created an identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

Issued an access token with 'voip' scope that expires at 30/03/21 08:09 09 AM:
<token signature here>

Created an identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-1ce9-31b4-54b7-a43a0d006a52

Issued an access token with 'voip' scope that expires at 30/03/21 08:09 09 AM:
<token signature here>

Successfully revoked all access tokens for identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

Deleted the identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

Предварительные требования

Окончательный код

Итоговый код для этого краткого руководства можно найти на сайте GitHub.

Настройка среды

Создание нового приложения Java

В окне терминала или командной строки перейдите в каталог, в котором нужно создать приложение Java. Чтобы создать проект Java из шаблона maven-archetype-quickstart, выполните следующий код:

mvn archetype:generate -DgroupId=com.communication.quickstart -DartifactId=communication-quickstart -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.4 -DinteractiveMode=false

Вы заметите, что задача создает каталог с тем же именем, что generate и artifactId. В этом каталоге каталог src/main/java содержит исходный код проекта, каталог src/test/java содержит тестовый источник, а файл pom.xml — объектную модель проекта или POM проекта. Этот файл используется для параметров конфигурации проекта.

Установка пакетов Служб коммуникации

Откройте файл pom.xml в текстовом редакторе. Добавьте следующий элемент зависимости в группу зависимостей:

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-communication-identity</artifactId>
    <version>1.1.1</version>
</dependency>

Этот код предписывает Maven установить пакет SDK для удостоверений Служб коммуникации, который будет использоваться позже.

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

В каталоге проекта выполните следующие действия.

  1. Перейдите в каталог /src/main/java/com/communication/quickstart .
  2. Откройте файл App.java в редакторе.
  3. Замените инструкцию System.out.println("Hello world!"); .
  4. Добавьте директивы import.

Используйте следующий код:

package com.communication.quickstart;

import com.azure.communication.common.*;
import com.azure.communication.identity.*;
import com.azure.communication.identity.models.*;
import com.azure.core.credential.*;

import java.io.IOException;
import java.time.*;
import java.util.*;

public class App
{
    public static void main( String[] args ) throws IOException
    {
        System.out.println("Azure Communication Services - Access Tokens Quickstart");
        // Quickstart code goes here
    }
}

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

Создайте экземпляр CommunicationIdentityClient с помощью ключа доступа и конечной точки ресурса. Дополнительные сведения см. в разделе "Сохранение строки подключения" статьи "Создание ресурсов Служб коммуникации и управление ими".

Кроме того, вы можете инициализировать клиент с помощью любого пользовательского HTTP-клиента, реализующего интерфейс com.azure.core.http.HttpClient.

В файле App.java добавьте следующий код в main метод:

// You can find your endpoint and access key from your resource in the Azure portal
String endpoint = "https://<RESOURCE_NAME>.communication.azure.com";
String accessKey = "SECRET";

CommunicationIdentityClient communicationIdentityClient = new CommunicationIdentityClientBuilder()
        .endpoint(endpoint)
        .credential(new AzureKeyCredential(accessKey))
        .buildClient();

Вместо предоставления конечной точки и ключа доступа можно указать всю строку подключения с помощью connectionString() метода.

// You can find your connection string from your Communication Services resource in the Azure portal
String connectionString = "<connection_string>";

CommunicationIdentityClient communicationIdentityClient = new CommunicationIdentityClientBuilder()
    .connectionString(connectionString)
    .buildClient();

Если вы уже настроили приложение Azure Active Directory (Azure AD), вы можете пройти проверку подлинности с помощью Azure AD.

String endpoint = "https://<RESOURCE_NAME>.communication.azure.com";
TokenCredential credential = new DefaultAzureCredentialBuilder().build();

CommunicationIdentityClient communicationIdentityClient = new CommunicationIdentityClientBuilder()
        .endpoint(endpoint)
        .credential(credential)
        .buildClient();

Создание удостоверения

Чтобы создать маркеры доступа, вам потребуется удостоверение. Службы коммуникации Azure позволяют использовать упрощенный каталог удостоверений. Чтобы создать новую запись в каталоге с уникальным идентификатором (Id), используйте метод createUser.

CommunicationUserIdentifier user = communicationIdentityClient.createUser();
System.out.println("\nCreated an identity with ID: " + user.getId());

Созданное удостоверение потребуется позже для выдачи маркеров доступа. Сохраните полученное удостоверение с сопоставлением пользователей приложения (например, сохраняя его в базе данных сервера приложений).

Выпуск маркеров доступа

getToken Используйте метод для выдачи маркера доступа для удостоверения Служб коммуникации. Параметр scopes определяет набор разрешений маркера доступа и ролей. Дополнительные сведения см. в списке поддерживаемых действий в модели удостоверений.

В следующем коде используйте пользовательную переменную, созданную на предыдущем шаге, чтобы получить токен.

// Issue an access token with the "voip" scope for a user identity
List<CommunicationTokenScope> scopes = new ArrayList<>(Arrays.asList(CommunicationTokenScope.VOIP));
AccessToken accessToken = communicationIdentityClient.getToken(user, scopes);
OffsetDateTime expiresAt = accessToken.getExpiresAt();
String token = accessToken.getToken();
System.out.println("\nIssued an access token with 'voip' scope that expires at: " + expiresAt + ": " + token);

Создание удостоверения и выдача маркера в одном запросе

Кроме того, можно использовать метод createUserAndToken для создания новой записи в каталоге с уникальным и Id выдачи маркера доступа одновременно.

List<CommunicationTokenScope> scopes = Arrays.asList(CommunicationTokenScope.CHAT);
CommunicationUserIdentifierAndToken result = communicationIdentityClient.createUserAndToken(scopes);
CommunicationUserIdentifier user = result.getUser();
System.out.println("\nCreated a user identity with ID: " + user.getId());
AccessToken accessToken = result.getUserToken();
OffsetDateTime expiresAt = accessToken.getExpiresAt();
String token = accessToken.getToken();
System.out.println("\nIssued an access token with 'chat' scope that expires at: " + expiresAt + ": " + token);

Маркеры доступа — это недолговечные учетные данные, которые необходимо выдавать повторно. Это может привести к нарушению работы пользователей приложения. Свойство expiresAt обозначает время существования маркера доступа.

Обновление токенов доступа

Чтобы обновить маркер доступа, используйте CommunicationUserIdentifier объект для повторной отправки:

// existingIdentity represents the Communication Services identity that's stored during identity creation
CommunicationUserIdentifier identity = new CommunicationUserIdentifier(existingIdentity.getId());
AccessToken response = communicationIdentityClient.getToken(identity, scopes);

Отзыв маркера доступа

Иногда может потребоваться явно отозвать маркер доступа. Например, это можно сделать, когда пользователи приложений изменяют пароль, используемый для проверки подлинности в службе. Метод revokeTokens делает недействительными все активные маркеры доступа для конкретного пользователя. В следующем коде можно использовать ранее созданного пользователя.

communicationIdentityClient.revokeTokens(user);
System.out.println("\nSuccessfully revoked all access tokens for user identity with ID: " + user.getId());

Удаление удостоверения

При удалении удостоверения отменяете все активные маркеры доступа и предотвращаете дальнейшую выдачу маркеров доступа для удостоверения. Это также удаляет все сохраненное содержимое, связанное с удостоверением.

communicationIdentityClient.deleteUser(user);
System.out.println("\nDeleted the user identity with ID: " + user.getId());

Выполнение кода

Перейдите в каталог, содержащий файл pom.xml , а затем скомпилируйте проект с помощью следующей mvn команды:

mvn compile

Затем выполните сборку пакета:

mvn package

Выполните следующую mvn команду, чтобы выполнить приложение:

mvn exec:java -Dexec.mainClass="com.communication.quickstart.App" -Dexec.cleanupDaemonThreads=false

Выходные данные приложения описывают каждое завершенное действие:

Azure Communication Services - Access Tokens Quickstart

Created an identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

Issued an access token with 'voip' scope that expires at 30/03/21 08:09 09 AM:
<token signature here>

Created an identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-1ce9-31b4-54b7-a43a0d006a52

Issued an access token with 'voip' scope that expires at 30/03/21 08:09 09 AM:
<token signature here>

Successfully revoked all access tokens for identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

Deleted the identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

Использование удостоверения для мониторинга и метрик

Идентификатор пользователя предназначен для работы в качестве первичного ключа для журналов и метрик, собираемых с помощью Azure Monitor. Чтобы просмотреть все вызовы пользователя, например, можно настроить проверку подлинности таким образом, чтобы сопоставить определенное удостоверение Службы коммуникации Azure (или удостоверения) с одним пользователем.

Узнайте больше о концепциях проверки подлинности, диагностике вызовов с помощью Log Analytics и доступных метриках .

Очистка ресурсов

Чтобы очистить и удалить подписку на Службы коммуникации, удалите ресурс или группу ресурсов. При удалении группы ресурсов также удаляются все другие связанные с ней ресурсы. Дополнительные сведения см. в разделе "Очистка ресурсов" статьи "Создание ресурсов служб коммуникации и управление ими".

Дальнейшие действия

В этом кратком руководстве рассматривались следующие темы:

  • Управление идентификаторами
  • Выпуск маркеров доступа
  • Использование пакета SDK для удостоверений Служб коммуникации Azure

Кроме того, вам может понадобиться следующее: