快速入門：設定和管理 Teams 使用者的存取權杖

設定必要條件

• 適用於您的作業系統的最新版本 .NET SDK。

最終程式碼

在 GitHub 上找到此快速入門的完成程式碼。

設定

建立新的 C# 應用程式

在主控台視窗中 (例如 cmd、PowerShell 或 Bash)，使用 dotnet new 命令建立名為 CommunicationAccessTokensQuickstart 的新主控台應用程式。 此命令會建立簡單的 "Hello World" C# 專案，內含單一原始程式檔：Program.cs。

dotnet new console -o CommunicationAccessTokensQuickstart

將您的目錄變更為新建立的應用程式資料夾，然後使用 dotnet build 命令來編譯您的應用程式。

cd CommunicationAccessTokensQuickstart
dotnet build

Install the package

在仍位於應用程式目錄時，使用 dotnet add package 命令安裝適用於 .NET 套件的 Azure 通訊服務識別程式庫。

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：透過 MSAL 程式庫接收 Microsoft Entra 使用者權杖和物件識別碼

權杖交換流程的第一個步驟是使用 Microsoft.Identity.Client 為您的 Teams 使用者取得權杖。 下列程式碼會從名為 AAD_CLIENT_ID 和 AAD_TENANT_ID 的環境變數擷取 Microsoft Entra 用戶端識別碼和租用戶識別碼。 請務必使用正確的授權單位設定 MSAL 用戶端 (根據 AAD_TENANT_ID 環境變數)，以擷取與 Fabrikam 租用戶中使用者對應的物件識別碼 (oid) 宣告，並初始化 userObjectId 變數。

// This code demonstrates how to fetch an AAD 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 AAD 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：將 Teams 使用者的 Microsoft Entra 存取權杖換成通訊身分識別存取權杖

請使用 GetTokenForTeamsUser 方法為 Teams 使用者核發可與 Azure 通訊服務 SDK 搭配使用的存取權杖。

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 和維修 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

Install the package

使用 npm install 命令安裝適用於 JavaScript 的 Azure 通訊服務識別 SDK。

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：透過 MSAL 程式庫接收 Microsoft Entra 使用者權杖和物件識別碼

權杖交換流程的第一個步驟是使用 Microsoft.Identity.Client 為您的 Teams 使用者取得權杖。 下列程式碼會從名為 AAD_CLIENT_ID 和 AAD_TENANT_ID 的環境變數擷取 Microsoft Entra 用戶端識別碼和租用戶識別碼。 請務必使用正確的授權單位設定 MSAL 用戶端 (根據 AAD_TENANT_ID 環境變數)，以擷取與 Fabrikam 租用戶中使用者對應的物件識別碼 (oid) 宣告，並初始化 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 AAD token and object ID of a Teams user
    const tokenRequest = {
        code: req.query.code,
        scopes: scopes,
        redirectUri: REDIRECT_URI,
        codeVerifier: pkceVerifier,
    };
    // Retrieve the AAD 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：將 Teams 使用者的 Microsoft Entra 存取權杖換成通訊身分識別存取權杖

請使用 getTokenForTeamsUser 方法為 Teams 使用者核發可與 Azure 通訊服務 SDK 搭配使用的存取權杖。

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

Install the package

在應用程式目錄中，繼續使用 pip install 命令安裝適用於 Python 套件的 Azure 通訊服務識別 SDK。

pip install azure-communication-identity
pip install msal

步驟 1：透過 MSAL 程式庫接收 Microsoft Entra 使用者權杖和物件識別碼

權杖交換流程的第一個步驟是使用 Microsoft.Identity.Client 為您的 Teams 使用者取得權杖。 在 Azure 入口網站中，將「行動裝置與傳統型應用程式」的重新導向 URI 設定為 http://localhost。 下列程式碼會從名為 AAD_CLIENT_ID 和 AAD_TENANT_ID 的環境變數擷取 Microsoft Entra 用戶端識別碼和租用戶識別碼。 請務必使用正確的授權單位設定 MSAL 用戶端 (根據 AAD_TENANT_ID 環境變數)，以擷取與 Fabrikam 租用戶中使用者對應的物件識別碼 (oid) 宣告，並初始化 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 AAD 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：將 Teams 使用者的 Microsoft Entra 存取權杖換成通訊身分識別存取權杖

請使用 get_token_for_teams_user 方法為 Teams 使用者核發可與 Azure 通訊服務 SDK 搭配使用的存取權杖。

# 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

設定必要條件

• Java Development Kit (JDK) 第 8 版或更新版本。
• Apache Maven。

最終程式碼

在 GitHub 上找到此快速入門的完成程式碼。

設定

建立新的 Java 應用程式

開啟您的終端機或命令視窗。 瀏覽至您要在其中建立 Java 應用程式的目錄。 執行下列命令以從 maven-archetype-quickstart 範本產生 Java 專案。

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)。

Install the package

在文字編輯器中開啟 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：透過 MSAL 程式庫接收 Microsoft Entra 使用者權杖和物件識別碼

權杖交換流程的第一個步驟是使用 Microsoft.Identity.Client 為您的 Teams 使用者取得權杖。 請務必使用正確的授權單位設定 MSAL 用戶端 (根據 tenantId 變數)，以擷取與 Fabrikam 租用戶中使用者對應的物件識別碼 (oid) 宣告，並初始化 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 AAD token and object ID of a Teams user
InteractiveRequestParameters parameters = InteractiveRequestParameters
                    .builder(new URI(redirectUri))
                    .scopes(scope)
                    .build();

// Retrieve the AAD 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 具現化。 了解如何管理您資源的連接字串。 您可以使用會實作 com.azure.core.http.HttpClient 介面的任何自訂 HTTP 用戶端來初始化用戶端。

將下列程式碼加入 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：將 Teams 使用者的 Microsoft Entra 存取權杖換成通訊身分識別存取權杖

請使用 getTokenForTeamsUser 方法為 Teams 使用者核發可與 Azure 通訊服務 SDK 搭配使用的存取權杖。

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