Mulai cepat: Menyiapkan dan mengelola token akses untuk pengguna Teams

Artikel
10/18/2023

Dalam mulai cepat ini, Anda akan membuat aplikasi konsol .NET untuk mengautentikasi pengguna Microsoft 365 dengan menggunakan Microsoft Authentication Library (MSAL) dan mengambil token pengguna Microsoft Entra. Anda kemudian akan menukar token tersebut dengan token akses pengguna Teams dengan Azure Communication Services Identity SDK. Token akses untuk pengguna Teams kemudian dapat digunakan oleh SDK Panggilan Communication Services untuk mengintegrasikan kemampuan panggilan sebagai pengguna Teams.

Catatan

Ketika Anda berada di lingkungan produksi, kami sarankan Anda menerapkan mekanisme pertukaran ini dalam layanan ujung belakang, karena permintaan pertukaran ditandatangani dengan rahasia.

Prasyarat

Akun Azure dengan langganan aktif. Buat akun secara gratis.
Sumber daya Azure Communication Services dan string koneksi aktif. Untuk detailnya selengkapnya, lihat Membuat sumber daya Azure Communication Services.
Instans Microsoft Entra dengan pengguna yang memiliki lisensi Teams. Untuk informasi selengkapnya, lihat Persyaratan Lisensi Teams.

Pendahuluan

Identitas Teams terikat dengan penyewa di ID Microsoft Entra. Aplikasi Anda dapat digunakan oleh pengguna dari penyewa yang sama atau berbeda. Dalam mulai cepat ini, kita akan bekerja melalui kasus penggunaan multipenyewa dengan beberapa aktor: pengguna, pengembang, dan administrator dari perusahaan fiktif Contoso dan Fabrikam. Dalam kasus penggunaan ini, Contoso adalah perusahaan yang membangun software as a service (SaaS) untuk Fabrikam.

Bagian berikut ini akan memandu Anda melalui langkah-langkah untuk administrator, pengembang, dan pengguna. Diagram menunjukkan kasus penggunaan multipenyewa. Jika Anda bekerja dengan satu penyewa, jalankan semua langkah dari Contoso dan Fabrikam dalam satu penyewa.

Tindakan administrator

Peran Administrator memiliki izin yang diperluas di ID Microsoft Entra. Anggota peran ini dapat menyiapkan sumber daya dan dapat membaca informasi dari portal Azure. Dalam diagram berikut, Anda dapat melihat semua tindakan yang harus dijalankan oleh Administrator.

Tindakan administrator untuk mengaktifkan dukungan Azure Communication Services untuk identitas Teams.

Administrator Contoso membuat atau memilih aplikasi yang sudah ada di ID Microsoft Entra. Properti Jenis akun yang didukung menentukan apakah pengguna dari penyewa yang berbeda dapat melakukan autentikasi ke aplikasi. Properti URI Pengalihan mengalihkan permintaan autentikasi yang berhasil ke server Contoso.
Administrator Contoso menambahkan izin API ke Teams.ManageCalls dan Teams.ManageChats dari Communication Services.
Administrator Contoso memungkinkan aliran klien publik untuk aplikasi.
Admin Contoso membuat atau memilih layanan komunikasi yang ada, yang akan digunakan untuk autentikasi permintaan pertukaran. Token pengguna Microsoft Entra akan ditukar dengan token akses pengguna Teams. Untuk detailnya selengkapnya, lihat Membuat dan mengelola sumber daya Communication Services.
Administrator Fabrikam memberikan Communication Services Teams.ManageCalls dan Teams.ManageChats izin ke aplikasi Contoso. Langkah ini diperlukan jika hanya Administrator Fabrikam yang dapat memberikan akses ke aplikasi dengan Teams.ManageCalls izin dan Teams.ManageChats .

Langkah 1: Buat pendaftaran aplikasi Microsoft Entra atau pilih aplikasi Microsoft Entra

Pengguna harus diautentikasi terhadap aplikasi Microsoft Entra dengan izin Azure Communication Service Teams.ManageCalls dan Teams.ManageChats. Jika Anda tidak memiliki aplikasi yang sudah ada yang ingin Anda gunakan untuk mulai cepat ini, Anda dapat membuat pendaftaran aplikasi baru.

Pengaturan aplikasi berikut memengaruhi pengalaman:

Properti Jenis akun yang didukung menentukan apakah aplikasi adalah penyewa tunggal ("Akun hanya dalam direktori organisasi ini") atau multipenyewa ("Akun dalam direktori organisasi mana pun"). Untuk skenario ini, Anda dapat menggunakan multipenyewa.
URI pengalihan menentukan URI tempat permintaan autentikasi dialihkan setelah autentikasi. Untuk skenario ini, Anda dapat menggunakan Klien publik/asli (seluler & desktop) dan mengisi http://localhost sebagai URI.

Untuk informasi selengkapnya, lihat Mendaftarkan aplikasi dengan platform identitas Microsoft.

Saat aplikasi terdaftar, Anda akan melihat pengidentifikasi dalam gambaran umum. Pengidentifikasi ini, ID Aplikasi (klien), digunakan dalam langkah berikutnya.

Langkah 2. Mengizinkan alur klien publik

Pada panel Autentikasi aplikasi, Anda dapat melihat platform yang dikonfigurasi untuk Klien publik/asli(seluler &desktop) dengan URI pengalihan yang menunjuk ke http://localhost. Di bagian bawah panel, Anda akan melihat kontrol pengalih Izinkan klien publik mengalir, yang harus diatur ke Ya untuk mulai cepat ini.

Langkah 3: Tambahkan izin Communication Services dalam aplikasi

Aplikasi harus mendeklarasikan izin Teams.ManageCalls dan Teams.ManageChats untuk memiliki akses ke kemampuan panggilan Teams di Penyewa. Pengguna Teams akan meminta token pengguna Microsoft Entra dengan izin ini untuk pertukaran token.

Navigasi ke aplikasi Microsoft Entra Anda di portal Azure dan pilih izin API
Pilih Tambah izin
Di menu Tambahkan Izin, pilih Azure Communication Services
Pilih izin Teams.ManageCalls dan Teams.ManageChats, lalu pilih Tambahkan izin

Tambahkan izin Teams.ManageCalls dan Teams.ManageChats ke aplikasi Microsoft Entra yang dibuat di langkah sebelumnya.

Langkah 4: Membuat atau memilih sumber daya Communication Services

Sumber daya Communication Services Anda digunakan untuk mengautentikasi semua permintaan untuk bertukar token pengguna Microsoft Entra dengan token akses pengguna Teams. Anda dapat memicu pertukaran ini dengan menggunakan Communication Services Identity SDK, yang dapat Anda autentikasi dengan kunci akses, atau dengan menggunakan kontrol akses berbasis peran Azure (Azure RBAC). Anda bisa mendapatkan kunci akses baik di portal Azure atau dengan mengonfigurasi Azure RBAC pada panel Kontrol akses (IAM) menurut sumber daya Communication Services.

Jika Anda ingin membuat sumber daya Communication Services baru, lihat Membuat dan mengelola sumber daya Communication Services.

Penyewa Microsoft Entra dapat dikonfigurasi, untuk memerlukan persetujuan administrator Microsoft Entra untuk izin Teams.ManageCalls dan Teams.ManageChats aplikasi. Dalam kasus seperti itu, Administrator Microsoft Entra harus memberikan izin ke aplikasi Contoso untuk Communication Services Teams.ManageCalls dan Teams.ManageChats. Administrator Fabrikam Microsoft Entra memberikan persetujuan melalui URL unik.

Peran berikut dapat memberikan persetujuan atas nama perusahaan:

Admin global
Admin aplikasi
Admin aplikasi cloud

Jika Anda ingin memeriksa peran di portal Azure, lihat Mencantumkan penetapan peran Azure.

Untuk membuat URL persetujuan Administrator, Administrator Microsoft Entra Fabrikam melakukan langkah-langkah berikut:

Di URL https://login.microsoftonline.com/{Tenant_ID}/adminconsent?client_id={Application_ID}, Administrator mengganti {Tenant_ID} dengan ID Penyewa Fabrikam, dan mengganti {Application_ID} dengan ID Aplikasi Contoso.
Administrator masuk dan memberikan izin atas nama organisasi.

Prinsip layanan aplikasi Contoso di penyewa Fabrikam dibuat jika persetujuan diberikan. Administrator Fabrikam dapat meninjau persetujuan di ID Microsoft Entra dengan melakukan langkah-langkah berikut:

Masuk ke portal Microsoft Azure sebagai administrator.
Buka Microsoft Entra ID.
Pada panel Aplikasi perusahaan, atur filter Jenis aplikasi ke Semua aplikasi.
Di bidang untuk memfilter aplikasi, masukkan nama aplikasi Contoso.
Pilih Terapkan.
Pilih perwakilan layanan dengan menggunakan nama yang diperlukan.
Buka panel Izin.

Anda dapat melihat bahwa status izin Communication Services Teams.ManageCalls dan Teams.ManageChats Diberikan untuk {Directory_name}.

Jika Anda mengalami masalah "Aplikasi mencoba mengakses layanan '1fd5118e-2576-4263-8130-9503064c837a'(Azure Communication Services) tempat organisasi Anda '{GUID}' tidak memiliki perwakilan layanan. Hubungi Admin TI Anda untuk meninjau konfigurasi langganan layanan anda atau menyetujui aplikasi untuk membuat perwakilan layanan yang diperlukan." Penyewa Microsoft Entra Anda tidak memiliki perwakilan layanan untuk aplikasi Azure Communication Services. Untuk memperbaiki masalah ini, gunakan PowerShell sebagai administrator Microsoft Entra untuk menyambungkan ke penyewa Anda. Ganti Tenant_ID dengan ID penyewaan Microsoft Entra Anda.

Anda akan memerlukan Application.ReadWrite.All seperti yang ditunjukkan di bawah ini.

Connect-MgGraph -TenantId "Tenant_ID" -Scopes Application.ReadWrite.All

Jika perintah tidak ditemukan, mulai PowerShell sebagai administrator dan instal paket Microsoft Graph.

Install-Module Microsoft.Graph

Kemudian jalankan perintah berikut untuk menambahkan perwakilan layanan ke penyewa Anda. Jangan ubah GUID ID Aplikasi.

New-MgServicePrincipal -AppId "1fd5118e-2576-4263-8130-9503064c837a"

Tindakan pengembang

Pengembang Contoso harus menyiapkan aplikasi klien untuk mengautentikasi pengguna. Pengembang kemudian perlu membuat titik akhir di server back-end untuk memproses token pengguna Microsoft Entra setelah pengalihan. Ketika token pengguna Microsoft Entra diterima, token tersebut ditukar dengan token akses pengguna Teams dan dikembalikan ke aplikasi klien.

Tindakan yang diperlukan pengembang ditunjukkan dalam diagram berikut:

Diagram tindakan pengembang untuk mengaktifkan dukungan Azure Communication Services untuk identitas Teams.

Pengembang Contoso mengonfigurasi Microsoft Authentication Library (MSAL) untuk mengautentikasi pengguna untuk aplikasi yang dibuat sebelumnya oleh Administrator untuk Izin Communication Services Teams.ManageCalls dan Teams.ManageChats.
Pengembang Contoso menginisialisasi SDK Identitas Communication Services dan menukar token pengguna Microsoft Entra yang masuk dengan token akses pengguna Teams melalui SDK identitas. Token akses pengguna Teams kemudian dikembalikan ke aplikasi klien.

Dengan menggunakan MSAL, pengembang dapat memperoleh token pengguna Microsoft Entra dari titik akhir platform identitas Microsoft untuk mengautentikasi pengguna dan mengakses API web yang aman. Token ini dapat digunakan untuk menyediakan akses aman ke Communication Services. MSAL mendukung berbagai arsitektur dan platform aplikasi termasuk .NET, JavaScript, Java, Python, Android, dan iOS.

Untuk informasi selengkapnya tentang menyiapkan lingkungan dalam dokumentasi publik, lihat Gambaran umum Pustaka Autentikasi Microsoft.

Catatan

Bagian berikut menjelaskan cara menukar token akses Microsoft Entra dengan token akses pengguna Teams untuk aplikasi konsol.

Menyiapkan prasyarat

Versi terbaru .NET SDK untuk sistem operasi Anda.

Kode akhir

Menemukan kode final untuk mulai cepat ini di GitHub.

Penyiapan

Membuat aplikasi C# baru

Di jendela konsol (seperti cmd, PowerShell, atau Bash), gunakan perintah dotnet new untuk membuat aplikasi konsol baru dengan nama CommunicationAccessTokensQuickstart. Perintah ini membuat proyek C# "Halo Dunia" sederhana dengan file sumber tunggal: Program.cs.

dotnet new console -o CommunicationAccessTokensQuickstart

Ubah direktori Anda ke folder aplikasi yang baru dibuat dan gunakan perintah dotnet build untuk mengompilasi aplikasi Anda.

cd CommunicationAccessTokensQuickstart
dotnet build

Pasang paket

Ketika masih dalam direktori aplikasi, instal pustaka klien Azure Communication Services Identity library untuk paket .NET dengan menggunakan perintah dotnet add package.

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

Menyiapkan kerangka kerja aplikasi

Dari direktori proyek:

Di editor teks, buka Program.cs
Tambahkan petunjuk using untuk menyertakan namespace layanan Azure.Communication.Identity.
Main Memperbarui deklarasi metode untuk mendukung kode asinkron

Tambahkan kode berikut ke memulai:

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

Langkah 1: Menerima token pengguna Microsoft Entra dan ID objek melalui pustaka MSAL

Langkah pertama dalam alur pertukaran token adalah mendapatkan token untuk pengguna Teams Anda dengan menggunakan Microsoft.Identity.Client. Kode di bawah ini mengambil ID klien Microsoft Entra dan ID penyewa dari variabel lingkungan bernama AAD_CLIENT_ID dan AAD_TENANT_ID. Sangat penting untuk mengonfigurasi klien MSAL dengan otoritas yang benar, berdasarkan AAD_TENANT_ID variabel lingkungan, untuk dapat mengambil klaim ID Objek (oid) yang sesuai dengan pengguna di penyewa Fabrikam dan menginisialisasi userObjectId variabel.

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

Langkah 2: Menginisialisasi CommunicationIdentityClient

Inisiasi CommunicationIdentityClient dengan string koneksi Anda. Kode di bawah ini mengambil string koneksi dari variabel lingkungan bernama COMMUNICATION_SERVICES_CONNECTION_STRING untuk sumber daya. Pelajari cara mengelola string koneksi sumber daya Anda.

Tambahkan kode berikut ke metode 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);

Langkah 3: Menukar token akses Microsoft Entra pengguna Teams untuk token akses Identitas Komunikasi

Gunakan metode GetTokenForTeamsUser untuk menerbitkan token akses untuk pengguna Teams yang dapat digunakan dengan SDK Azure Communication Services.

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

Menjalankan kode

Menjalankan aplikasi dari direktori aplikasi Anda dengan perintah dotnet run.

dotnet run

Menyiapkan prasyarat

Node.js Active LTS dan versi Pemeliharaan LTS (disarankan versi 8.11.1 and 10.14.1).

Kode akhir

Menemukan kode final untuk mulai cepat ini di GitHub.

Penyiapan

Membuat aplikasi Node.js baru

Buka terminal atau jendela perintah buat direktori baru untuk aplikasi Anda, dan navigasikan ke sana.

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

Jalankan npm init -y untuk membuat file package.json dengan pengaturan default.

npm init -y

Pasang paket

Gunakan perintah npm install untuk menginstal Azure Communication Services Identity SDK untuk JavaScript.


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

Opsi --save mencantumkan pustaka sebagai dependensi di file package.json Anda.

Menyiapkan kerangka kerja aplikasi

Dari direktori proyek:

Membuka file teks baru di editor kode Anda
Tambahkan panggilan require call untuk memuat CommunicationIdentityClient

Buat struktur program, termasuk penanganan pengecualian dasar

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}!`))

Simpan file baru sebagai issue-communication-access-token.js di direktori access-tokens-quickstart.

Langkah 1: Menerima token pengguna Microsoft Entra dan ID objek melalui pustaka MSAL

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

Langkah 2: Menginisialisasi CommunicationIdentityClient

Buat instans CommunicationIdentityClient dengan string koneksi Anda. Kode di bawah ini mengambil string koneksi dari variabel lingkungan bernama COMMUNICATION_SERVICES_CONNECTION_STRING untuk sumber daya. Pelajari cara mengelola string koneksi sumber daya Anda.

Tambahkan kode berikut ke metode 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);

Langkah 3: Menukar token akses Microsoft Entra pengguna Teams untuk token akses Identitas Komunikasi

Gunakan metode getTokenForTeamsUser untuk menerbitkan token akses untuk pengguna Teams yang dapat digunakan dengan SDK Azure Communication Services.

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

Menjalankan kode

Dari permintaan konsol, navigasikan ke direktori yang berisi file issue-communication-access-token.js lalu jalankan perintah node untuk menjalankan aplikasi.

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

Menyiapkan prasyarat

Python 3.8+.

Kode akhir

Menemukan kode final untuk mulai cepat ini di GitHub.

Penyiapan

Membuat aplikasi Python baru

Buka terminal atau jendela perintah buat direktori baru untuk aplikasi Anda, dan navigasikan ke sana.
```
mkdir communication-access-tokens-quickstart && cd communication-access-tokens-quickstart
```

Gunakan editor teks untuk membuat file yang disebut exchange-communication-access-tokens.py di direktori akar proyek dan menambahkan struktur untuk program, termasuk penanganan pengecualian dasar. Anda akan menambahkan semua kode sumber untuk mulai cepat ini ke file di bagian berikut.

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

Pasang paket

Ketika masih dalam direktori aplikasi, pasang pustaka klien Azure Communication Services Identity library untuk paket .NET dengan menggunakan perintah pip install.

pip install azure-communication-identity
pip install msal

Langkah 1: Menerima token pengguna Microsoft Entra dan ID objek melalui pustaka MSAL

Langkah pertama dalam alur pertukaran token adalah mendapatkan token untuk pengguna Teams Anda dengan menggunakan Microsoft.Identity.Client. Di portal Azure, konfigurasikan URI Pengalihan "Aplikasi Seluler dan Desktop" Anda sebagai http://localhost. Kode di bawah ini mengambil ID klien Microsoft Entra dan ID penyewa dari variabel lingkungan bernama AAD_CLIENT_ID dan AAD_TENANT_ID. Sangat penting untuk mengonfigurasi klien MSAL dengan otoritas yang benar, berdasarkan AAD_TENANT_ID variabel lingkungan, untuk dapat mengambil klaim ID Objek (oid) yang sesuai dengan pengguna di penyewa Fabrikam dan menginisialisasi user_object_id variabel.

# 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"]

Langkah 2: Menginisialisasi CommunicationIdentityClient

Tambahkan kode ini di dalam blok 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)

Langkah 3: Menukar token akses Microsoft Entra pengguna Teams untuk token akses Identitas Komunikasi

Gunakan metode get_token_for_teams_user untuk menerbitkan token akses untuk pengguna Teams yang dapat digunakan dengan SDK Azure Communication Services.

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

Menjalankan kode

Dari permintaan konsol, navigasikan ke direktori yang berisi file exchange-teams-access-tokens.py, lalu jalankan perintah python berikut untuk menjalankan aplikasi.

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

Menyiapkan prasyarat

Java Development Kit (JDK) versi 8 atau lebih tinggi.
Apache Maven.

Kode akhir

Menemukan kode final untuk mulai cepat ini di GitHub.

Penyiapan

Membuat aplikasi Java baru

Buka jendela perintah atau terminal Anda. Arahkan ke direktori tempat Anda ingin membuat aplikasi Java. Jalankan perintah di bawah ini untuk menghasilkan proyek Java dari templat maven-archetype-quickstart.

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

Anda akan melihat bahwa tugas 'hasilkan' membuat direktori dengan nama yang sama dengan artifactId. Di bawah direktori ini, src/main/java direktori berisi kode sumber proyek, src/test/java directory berisi sumber pengujian, dan pom.xml file adalah Project Object Model proyek, atau POM.

Pasang paket

Buka file pom.xml di editor teks Anda. Tambahkan elemen dependensi berikut ke grup dependensi.

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

Menyiapkan kerangka kerja aplikasi

Dari direktori proyek:

Menavigasi ke direktori /src/main/java/com/communication/quickstart
Buka file App.java di editor Anda
Ganti pernyataan System.out.println("Hello world!");
Tambahkan direktif import

Tambahkan kode berikut ke memulai:

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

Langkah 1: Menerima token pengguna Microsoft Entra dan ID objek melalui pustaka MSAL

Langkah pertama dalam alur pertukaran token adalah mendapatkan token untuk pengguna Teams Anda dengan menggunakan Microsoft.Identity.Client. Sangat penting untuk mengonfigurasi klien MSAL dengan otoritas yang benar, berdasarkan tenantId variabel, untuk dapat mengambil klaim ID Objek (oid) yang sesuai dengan pengguna di penyewa Fabrikam dan menginisialisasi userObjectId variabel.

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

Langkah 2: Menginisialisasi CommunicationIdentityClient

Buat instans pada CommunicationIdentityClient dengan kunci akses dan titik akhir sumber daya Anda. Pelajari cara mengelola string koneksi sumber daya Anda. Selain itu, Anda dapat menginisialisasi klien dengan klien HTTP kustom apa pun yang mengimplementasikan antarmuka com.azure.core.http.HttpClient.

Tambahkan kode berikut ke metode 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();

Langkah 3: Menukar token akses Microsoft Entra pengguna Teams untuk token akses Identitas Komunikasi

Gunakan metode getTokenForTeamsUser untuk menerbitkan token akses untuk pengguna Teams yang dapat digunakan dengan SDK Azure Communication Services.

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

Menjalankan kode

Navigasi ke direktori yang berisi pom.xml file dan kompilasi proyek dengan menggunakan mvn compile perintah .

Kemudian, bangun paketnya.

mvn package

Jalankan perintah mvn berikut untuk menjalankan aplikasi.

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

Pengguna mewakili pengguna Fabrikam dari aplikasi Contoso. Pengalaman pengguna diperlihatkan dalam diagram berikut:

Diagram tindakan pengguna untuk mengaktifkan dukungan Azure Communication Services untuk identitas Teams.

Pengguna Fabrikam menggunakan aplikasi klien Contoso dan diminta untuk mengautentikasi.
Aplikasi klien Contoso menggunakan MSAL untuk mengautentikasi pengguna terhadap penyewa Fabrikam Microsoft Entra untuk aplikasi Contoso dengan izin Communication Services Teams.ManageCalls dan Teams.ManageChats.
Autentikasi dialihkan ke server, sebagaimana didefinisikan dalam properti URI Pengalihan di MSAL dan aplikasi Contoso.
Server Contoso menukar token pengguna Microsoft Entra dengan token akses pengguna Teams dengan menggunakan Communication Services Identity SDK dan mengembalikan token akses pengguna Teams ke aplikasi klien.

Dengan token akses yang valid untuk pengguna Teams di aplikasi klien, pengembang dapat mengintegrasikan SDK Panggilan Communication Services dan mengelola panggilan sebagai pengguna Teams.

Langkah berikutnya

Dalam mulai cepat ini, Anda belajar cara:

Membuat dan mengonfigurasi aplikasi di ID Microsoft Entra.
Gunakan Microsoft Authentication Library (MSAL) untuk mengeluarkan token pengguna Microsoft Entra.
Gunakan Communication Services Identity SDK untuk menukar token pengguna Microsoft Entra dengan token akses pengguna Teams.

Membangun layanan autentikasi tepercaya untuk pengguna Teams Melakukan panggilan sebagai pengguna Teams ke pengguna Teams

Pelajari tentang konsep berikut:

Bagikan melalui

Mulai cepat: Menyiapkan dan mengelola token akses untuk pengguna Teams

Prasyarat

Pendahuluan

Tindakan administrator

Langkah 1: Buat pendaftaran aplikasi Microsoft Entra atau pilih aplikasi Microsoft Entra

Langkah 2. Mengizinkan alur klien publik

Langkah 3: Tambahkan izin Communication Services dalam aplikasi

Langkah 4: Membuat atau memilih sumber daya Communication Services

Langkah 5: Berikan persetujuan Administrator

Tindakan pengembang

Menyiapkan prasyarat

Kode akhir

Penyiapan

Membuat aplikasi C# baru

Pasang paket

Menyiapkan kerangka kerja aplikasi

Langkah 1: Menerima token pengguna Microsoft Entra dan ID objek melalui pustaka MSAL

Langkah 2: Menginisialisasi CommunicationIdentityClient

Langkah 3: Menukar token akses Microsoft Entra pengguna Teams untuk token akses Identitas Komunikasi

Menjalankan kode

Menyiapkan prasyarat

Kode akhir

Penyiapan

Membuat aplikasi Node.js baru

Pasang paket

Menyiapkan kerangka kerja aplikasi

Langkah 1: Menerima token pengguna Microsoft Entra dan ID objek melalui pustaka MSAL

Langkah 2: Menginisialisasi CommunicationIdentityClient

Langkah 3: Menukar token akses Microsoft Entra pengguna Teams untuk token akses Identitas Komunikasi

Menjalankan kode

Menyiapkan prasyarat

Kode akhir

Penyiapan

Membuat aplikasi Python baru

Pasang paket

Langkah 1: Menerima token pengguna Microsoft Entra dan ID objek melalui pustaka MSAL

Langkah 2: Menginisialisasi CommunicationIdentityClient

Langkah 3: Menukar token akses Microsoft Entra pengguna Teams untuk token akses Identitas Komunikasi

Menjalankan kode

Menyiapkan prasyarat

Kode akhir

Penyiapan

Membuat aplikasi Java baru

Pasang paket

Menyiapkan kerangka kerja aplikasi

Langkah 1: Menerima token pengguna Microsoft Entra dan ID objek melalui pustaka MSAL

Langkah 2: Menginisialisasi CommunicationIdentityClient

Langkah 3: Menukar token akses Microsoft Entra pengguna Teams untuk token akses Identitas Komunikasi

Menjalankan kode

Tindakan pengguna

Langkah berikutnya

Saran dan Komentar

Sumber Daya Tambahan: