Краткое руководство. Настройка маркеров доступа для пользователей Teams и управление ими

Настройка предварительных условий

• Последняя версия пакета SDK для .NET для вашей операционной системы.

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

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

Настройка

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

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

dotnet new console -o CommunicationAccessTokensQuickstart

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

cd CommunicationAccessTokensQuickstart
dotnet build

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

Находясь в каталоге приложения, установите пакет для .NET библиотеки идентификации Azure Communication Services с помощью команды dotnet add package.

dotnet add package Azure.Communication.Identity
dotnet add package Microsoft.Identity.Client

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

Из каталога проекта:

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

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

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Azure.Communication.Identity;
using Microsoft.Identity.Client;

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

            // Quickstart code goes here
        }
    }
}

Шаг 1. Получите токен пользователя Microsoft Entra и идентификатор объекта через библиотеку MSAL.

Первый шаг в потоке обмена маркерами — получение маркера для пользователя Teams с помощью Microsoft.Identity.Client. Приведенный ниже код извлекает идентификатор клиента (Client ID) и идентификатор арендатора (Tenant ID) Microsoft Entra из переменных среды с именами AAD_CLIENT_ID и AAD_TENANT_ID. Важно настроить клиент MSAL с правильной полномочий на основе AAD_TENANT_ID переменной среды, чтобы получить утверждение объекта (oid), соответствующее пользователю в арендаторе Fabrikam, и инициализировать переменную userObjectId.

// This code demonstrates how to fetch an Microsoft Entra ID client ID and tenant ID 
// from an environment variable.
string appId = Environment.GetEnvironmentVariable("AAD_CLIENT_ID");
string tenantId = Environment.GetEnvironmentVariable("AAD_TENANT_ID");
string authority = $"https://login.microsoftonline.com/{tenantId}";
string redirectUri = "http://localhost";

// Create an instance of PublicClientApplication
var aadClient = PublicClientApplicationBuilder
                .Create(appId)
                .WithAuthority(authority)
                .WithRedirectUri(redirectUri)
                .Build();

List<string> scopes = new() {
    "https://auth.msft.communication.azure.com/Teams.ManageCalls",
    "https://auth.msft.communication.azure.com/Teams.ManageChats"
};

// Retrieve the Microsoft Entra ID token and object ID of a Teams user
var result = await aadClient
                        .AcquireTokenInteractive(scopes)
                        .ExecuteAsync();
string teamsUserAadToken =  result.AccessToken;
string userObjectId =  result.UniqueId;

Шаг 2. Инициализация CommunicationIdentityClient

Инициализируйте экземпляр CommunicationIdentityClient с использованием строки подключения. Приведенный ниже код извлекает строку подключения для ресурса из переменной среды с именем COMMUNICATION_SERVICES_CONNECTION_STRING. Узнайте, как управлять строкой подключения вашего ресурса.

Добавьте указанный ниже код в метод Main:

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

Шаг 3. Обмен токеном доступа Microsoft Entra пользователя Teams на токен для доступа к удостоверению связи

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

var options = new GetTokenForTeamsUserOptions(teamsUserAadToken, appId, userObjectId);
var accessToken = await client.GetTokenForTeamsUserAsync(options);
Console.WriteLine($"Token: {accessToken.Value.Token}");

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

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

dotnet run

Настройка предварительных условий

• Node.js, активная версия LTS и версия Maintenance LTS (рекомендуются версии 8.11.1 и 10.14.1).

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

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

Настройка

Создание нового приложения Node.js

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

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

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

npm init -y

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

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

npm install @azure/communication-identity@latest --save
npm install @azure/msal-node --save
npm install express --save
npm install dotenv --save

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

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

Из каталога проекта:

1. Откройте новый текстовый файл в редакторе кода.

2. Добавьте вызов require, чтобы загрузить CommunicationIdentityClient.

3. Создайте структуру программы, включая простую обработку исключений.

   const { CommunicationIdentityClient } = require('@azure/communication-identity');    
   const { PublicClientApplication, CryptoProvider } = require('@azure/msal-node');
   const express = require("express");
   
   // You will need to set environment variables in .env
   const SERVER_PORT = process.env.PORT || 80;
   const REDIRECT_URI = `http://localhost:${SERVER_PORT}/redirect`;
   const clientId = process.env['AAD_CLIENT_ID'];
   const tenantId = process.env['AAD_TENANT_ID'];
   
   // Quickstart code goes here
   
   app.listen(SERVER_PORT, () => console.log(`Communication access token application started on ${SERVER_PORT}!`))
   
   

4. Сохраните новый файл как issue-communication-access-token.js в каталоге access-tokens-quickstart.

Шаг 1. Получите токен пользователя Microsoft Entra и идентификатор объекта через библиотеку MSAL.

Первый шаг в потоке обмена маркерами — получение маркера для пользователя Teams с помощью Microsoft.Identity.Client. Приведенный ниже код извлекает идентификатор клиента (Client ID) и идентификатор арендатора (Tenant ID) Microsoft Entra из переменных среды с именами AAD_CLIENT_ID и AAD_TENANT_ID. Важно настроить клиент MSAL с правильной полномочий на основе AAD_TENANT_ID переменной среды, чтобы получить утверждение объекта (oid), соответствующее пользователю в арендаторе Fabrikam, и инициализировать переменную userObjectId.

// Create configuration object that will be passed to MSAL instance on creation.
const msalConfig = {
    auth: {
        clientId: clientId,
        authority: `https://login.microsoftonline.com/${tenantId}`,
    }
};

// Create an instance of PublicClientApplication
const pca = new PublicClientApplication(msalConfig);
const provider = new CryptoProvider();

const app = express();

let pkceVerifier = "";
const scopes = [
            "https://auth.msft.communication.azure.com/Teams.ManageCalls",
            "https://auth.msft.communication.azure.com/Teams.ManageChats"
        ];

app.get('/', async (req, res) => {
    // Generate PKCE Codes before starting the authorization flow
    const {verifier, challenge} = await provider.generatePkceCodes();
    pkceVerifier = verifier;
    
    const authCodeUrlParameters = {
        scopes: scopes,
        redirectUri: REDIRECT_URI,
        codeChallenge: challenge, 
        codeChallengeMethod: "S256"
    };
    // Get url to sign user in and consent to scopes needed for application
    pca.getAuthCodeUrl(authCodeUrlParameters).then((response) => {
        res.redirect(response);
    }).catch((error) => console.log(JSON.stringify(error)));
});

app.get('/redirect', async (req, res) => {
    // Create request parameters object for acquiring the Microsoft Entra ID token and object ID of a Teams user
    const tokenRequest = {
        code: req.query.code,
        scopes: scopes,
        redirectUri: REDIRECT_URI,
        codeVerifier: pkceVerifier,
    };
    // Retrieve the Microsoft Entra ID token and object ID of a Teams user
    pca.acquireTokenByCode(tokenRequest).then(async(response) => {
        console.log("Response:", response);
        let teamsUserAadToken = response.accessToken;
        let userObjectId = response.uniqueId;
        //TODO: the following code snippets go here
        res.sendStatus(200);
    }).catch((error) => {
        console.log(error);
        res.status(500).send(error);
    });
});

Шаг 2. Инициализация CommunicationIdentityClient

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

Добавьте указанный ниже код в метод then:

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

Шаг 3. Обмен токеном доступа Microsoft Entra пользователя Teams на токен для доступа к удостоверению связи

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

//Exchange the Azure AD access token of the Teams User for a Communication Identity access token
let accessToken = await identityClient.getTokenForTeamsUser({
    teamsUserAadToken: teamsUserAadToken,
    clientId: clientId,
    userObjectId: userObjectId,
  });
console.log("Token:", accessToken);

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

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

node ./issue-communication-access-token.js

Настройка предварительных условий

• Python 3.8+.

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

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

Настройка

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

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

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

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

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

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

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

pip install azure-communication-identity
pip install msal

Шаг 1. Получите токен пользователя Microsoft Entra и идентификатор объекта через библиотеку MSAL.

Первый шаг в потоке обмена маркерами — получение маркера для пользователя Teams с помощью Microsoft.Identity.Client. В портал Azure настройте универсальный код ресурса (URI перенаправления) приложения "Мобильный и классический" в качествеhttp://localhost. Приведенный ниже код извлекает идентификатор клиента (Client ID) и идентификатор арендатора (Tenant ID) Microsoft Entra из переменных среды с именами AAD_CLIENT_ID и AAD_TENANT_ID. Важно настроить клиент MSAL с правильной полномочий на основе AAD_TENANT_ID переменной среды, чтобы получить утверждение объекта (oid), соответствующее пользователю в арендаторе Fabrikam, и инициализировать переменную user_object_id.

# This code demonstrates how to fetch your Azure AD client ID and tenant ID
# from an environment variable.
client_id = os.environ["AAD_CLIENT_ID"]
tenant_id = os.environ["AAD_TENANT_ID"]
authority = "https://login.microsoftonline.com/%s" % tenant_id

# Create an instance of PublicClientApplication
app = PublicClientApplication(client_id, authority=authority)

scopes = [ 
"https://auth.msft.communication.azure.com/Teams.ManageCalls",
"https://auth.msft.communication.azure.com/Teams.ManageChats"
 ]

# Retrieve the Microsoft Entra ID token and object ID of a Teams user
result = app.acquire_token_interactive(scopes)
aad_token =  result["access_token"]
user_object_id = result["id_token_claims"]["oid"] 

Шаг 2. Инициализация CommunicationIdentityClient

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

Добавьте этот код в блок try.

# This code demonstrates how to fetch 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)

Шаг 3. Обмен токеном доступа Microsoft Entra пользователя Teams на токен для доступа к удостоверению связи

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

# Exchange the Azure AD access token of the Teams User for a Communication Identity access token
token_result = client.get_token_for_teams_user(aad_token, client_id, user_object_id)
print("Token: " + token_result.token)

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

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

python ./exchange-communication-access-tokens.py

Настройка предварительных условий

• комплект SDK для Java (JDK) версии 8 или более поздней версии.
• Apache Maven.

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

Окончательный код для этого краткого руководства можно найти на 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 directory содержит источник теста, а файл pom.xml является объектной моделью проекта или POM.

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

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

<dependencies>
    <dependency>
        <groupId>com.azure</groupId>
        <artifactId>azure-communication-identity</artifactId>
        <version>[1.2.0,)</version>
    </dependency>
    <dependency>
      <groupId>com.microsoft.azure</groupId>
      <artifactId>msal4j</artifactId>
      <version>1.11.0</version>
    </dependency>
</dependencies>

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

Из каталога проекта:

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.identity.CommunicationIdentityClient;
import com.azure.communication.identity.CommunicationIdentityClientBuilder;
import com.azure.communication.identity.models.GetTokenForTeamsUserOptions;
import com.azure.core.credential.AccessToken;
import com.microsoft.aad.msal4j.IAuthenticationResult;
import com.microsoft.aad.msal4j.InteractiveRequestParameters;
import com.microsoft.aad.msal4j.PublicClientApplication;

import java.net.URI;
import java.util.HashSet;
import java.util.Set;

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

Шаг 1. Получите токен пользователя Microsoft Entra и идентификатор объекта через библиотеку MSAL.

Первый шаг в потоке обмена маркерами — получение маркера для пользователя Teams с помощью Microsoft.Identity.Client. Важно настроить клиент MSAL с правильным авторитетом на основе переменной tenantId, чтобы получить утверждение идентификатора объекта (oid), соответствующее пользователю в арендаторе Fabrikam, и инициализировать переменную userObjectId.

// You need to provide your Azure AD client ID and tenant ID
String appId = "<contoso_application_id>";
String tenantId = "<contoso_tenant_id>";
String authority = "https://login.microsoftonline.com/" + tenantId;

// Create an instance of PublicClientApplication
PublicClientApplication pca = PublicClientApplication.builder(appId)
        .authority(authority)
        .build();

String redirectUri = "http://localhost";
Set<String> scope = new HashSet<String>();
scope.add("https://auth.msft.communication.azure.com/Teams.ManageCalls");
scope.add("https://auth.msft.communication.azure.com/Teams.ManageChats");

// Create an instance of InteractiveRequestParameters for acquiring the Microsoft Entra ID token and object ID of a Teams user
InteractiveRequestParameters parameters = InteractiveRequestParameters
                    .builder(new URI(redirectUri))
                    .scopes(scope)
                    .build();

// Retrieve the Microsoft Entra ID token and object ID of a Teams user
IAuthenticationResult result = pca.acquireToken(parameters).get();
String teamsUserAadToken = result.accessToken();
String[] accountIds = result.account().homeAccountId().split("\\.");
String userObjectId = accountIds[0];
System.out.println("Teams token: " + teamsUserAadToken);

Шаг 2. Инициализация CommunicationIdentityClient

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

Добавьте указанный ниже код в метод main:

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

// Instantiate the identity client
CommunicationIdentityClient communicationIdentityClient = new CommunicationIdentityClientBuilder()
    .connectionString(connectionString)
    .buildClient();

Шаг 3. Обмен токеном доступа Microsoft Entra пользователя Teams на токен для доступа к удостоверению связи

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

// Exchange the Azure AD access token of the Teams User for a Communication Identity access token
GetTokenForTeamsUserOptions options = new GetTokenForTeamsUserOptions(teamsUserAadToken, appId, userObjectId);
var accessToken = communicationIdentityClient.getTokenForTeamsUser(options);
System.out.println("Token: " + accessToken.getToken());

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

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

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

mvn package

Выполните следующую команду mvn для запуска приложения.

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