Schnellstart: Einrichten und Verwalten von Zugriffstoken für Teams Benutzer

In dieser Schnellstartanleitung erstellen Sie eine .NET-Konsolenanwendung, um einen Microsoft 365-Benutzer mithilfe der Microsoft Authentication Library (MSAL) und durch den Abruf eines Microsoft Entra-Benutzertokens zu authentifizieren. Dieses Token wird dann mit dem Azure Communication Services-Identitäts-SDK gegen ein Zugriffstoken eines Teams-Benutzers ausgetauscht. Das Zugriffstoken für Teams-Benutzer kann dann vom Communication Services Calling SDK verwendet werden, um Anruffunktionen als Teams-Benutzer zu integrieren.

Hinweis

Wenn Sie sich in einer Produktionsumgebung befinden, wird empfohlen, diesen Austauschmechanismus in Back-End-Diensten zu implementieren, da Anforderungen für einen Austausch mit einem Geheimnis signiert werden.

Voraussetzungen

• Ein Azure-Konto mit einem aktiven Abonnement. Sie können kostenlos ein Konto erstellen.
• Eine aktive Azure Communication Services-Ressource und eine Verbindungszeichenfolge. Ausführlichere Informationen hierzu finden Sie unter Schnellstart: Erstellen und Verwalten einer Communication Services-Ressource.
• Eine Microsoft Entra-Instanz mit Benutzern mit einer Teams-Lizenz. Weitere Informationen finden Sie unter Lizenzanforderungen für Teams.

Einführung

Teams-Identitäten sind an Mandanten in Microsoft Entra ID gebunden. Ihre Anwendung kann von Benutzern desselben oder eines beliebigen anderen Mandanten verwendet werden. In diesem Schnellstart wird ein Anwendungsfall mit mehreren Mandanten und mehreren Mandanten beschrieben: Benutzer, Entwickler und Administratoren der fiktiven Unternehmen Contoso und Fabrikam. In diesem Fall ist Contoso ein Unternehmen, das eine SaaS (Software-as-a-Service) für Fabrikam erstellt.

Die folgenden Abschnitte führen Sie durch die Schritte für Administratoren, Entwickler und Benutzer. Die Diagramme veranschaulichen den Anwendungsfall mit mehreren Mandanten. Wenn Sie nur einen Mandanten verwenden, führen Sie alle Schritte für Contoso und Fabrikam in diesem Mandanten aus.

Administratoraktionen

Die Administratorrolle verfügt in Microsoft Entra ID über erweiterte Berechtigungen. Mitglieder dieser Rolle können Ressourcen einrichten und Informationen im Azure-Portal lesen. Im folgenden Diagramm werden alle Aktionen angezeigt, die von Administratoren ausgeführt werden müssen.

1. Der Administrator von Contoso erstellt eine Anwendung in Microsoft Entra ID oder wählt eine vorhandene aus. Die Eigenschaft Unterstützte Kontotypen legt fest, ob Benutzer aus einem anderen Mandanten sich bei der Anwendung authentifizieren können. Die Eigenschaft Umleitungs-URI dient zur Umleitung einer erfolgreichen Authentifizierungsanforderung an den Server von Contoso.
2. Der Contoso-Administrator fügt in Communication Services die API-Berechtigungen in Teams.ManageCalls und Teams.ManageChats hinzu.
3. Der Contoso-Administrator lässt den öffentlichen Clientflow für die Anwendung zu.
4. Der Administrator von Contoso erstellt die Communication Services-Dienste, die für die Authentifizierung der Austauschanforderungen verwendet werden, oder wählt vorhandene aus. Microsoft Entra-Benutzertoken werden gegen Zugriffstoken für Teams-Benutzer ausgetauscht. Ausführlichere Informationen hierzu finden Sie unter Schnellstart: Erstellen und Verwalten einer Communication Services-Ressource.
5. Der Fabrikam-Administrator erteilt Communication Services die Berechtigungen Teams.ManageCalls und Teams.ManageChats für die Contoso-Anwendung. Dieser Schritt ist erforderlich, wenn nur der Fabrikam-Administrator mit den Berechtigung Teams.ManageCalls und Teams.ManageChats Zugriff auf die Anwendung gewähren kann.

Schritt 1: Erstellen einer Microsoft Entra-Anwendungsregistrierung oder Auswählen einer Microsoft Entra-Anwendung

Benutzer müssen bei Microsoft Entra-Anwendungen mit den Azure Communication Service-Berechtigungen Teams.ManageCalls und Teams.ManageChats authentifiziert werden. Wenn Sie nicht über eine Anwendung verfügen, die Sie für diesen Schnellstart verwenden möchten, können Sie eine neue Anwendungsregistrierung erstellen.

Die folgenden Anwendungseinstellungen haben Einfluss auf die Vorgehensweise:

• Die Eigenschaft Unterstützte Kontotypen legt fest, ob die Anwendung einen einzelnen Mandanten („Nur Konten in diesem Organisationsverzeichnis“) oder mehrere Mandanten („Konten in einem beliebigen Organisationsverzeichnis“) unterstützt. In diesem Szenario verwenden Sie mehrere Mandanten.
• Der Umleitungs-URI definiert den URI, an den die Authentifizierungsanforderung nach der Authentifizierung umgeleitet wird. In diesem Szenario können Sie Öffentlicher Client/nativ (mobil und Desktop) verwenden und als URI http://localhost eingeben.

Weitere Informationen finden Sie unter Registrieren einer Anwendung bei Microsoft Identity Platform.

Wenn die Anwendung registriert ist, wird in der Übersicht ein Bezeichner angezeigt. Dieser Bezeichner Anwendungs-ID (des Client) wird in den folgenden Schritten verwendet.

Schritt 2: Zulassen öffentlicher Clientflows

Im Bereich Authentifizierung Ihrer Anwendung wird als konfigurierte Plattform Öffentlicher Client/nativ (mobil & Desktop) mit einem auf http://localhost verweisenden Umleitungs-URI angezeigt. Am unteren Rand des Bereichs wird das Umschaltsteuerelement Öffentliche Clientflows zulassen angezeigt, das für diesen Schnellstart auf Ja gestellt werden sollte.

Schritt 3: Hinzufügen der Communication Services-Berechtigungen in der Anwendung

Die Anwendung muss die Berechtigungen Teams.ManageCalls und Teams.ManageChats deklarieren, um Zugriff auf die Anruffunktionen von Teams im Mandanten zu haben. Teams-Benutzer würden ein Microsoft Entra-Benutzertoken mit dieser Berechtigung für den Tokenaustausch anfordern.

1. Navigieren Sie im Azure-Portal zu Ihrer Microsoft Entra-App, und wählen Sie API-Berechtigungen aus
2. Wählen Sie Berechtigungen hinzufügen aus.
3. Wählen Sie im Menü Berechtigungen hinzufügen die Option Azure Communication Services aus.
4. Wählen Sie die Berechtigungen Teams.ManageCalls und Teams.ManageChats und dann Berechtigungen hinzufügen aus.

Schritt 4: Erstellen oder Auswählen einer Communication Services-Ressource

Mithilfe Ihrer Communication Services-Ressource werden alle Anforderungen für den Austausch von Microsoft Entra-Benutzertoken mit einem Zugriffstoken für Teams-Benutzer authentifiziert. Sie können diesen Austausch mithilfe des Communication Services Identitäts-SDK auslösen, das Sie mit einem Zugriffsschlüssel authentifizieren können, oder mithilfe der rollenbasierten Zugriffssteuerung (Role-Based Access Control, Azure RBAC) von Azure. Sie können den Zugriffsschlüssel entweder im Azure-Portal abrufen oder Azure RBAC über den Bereich Zugriffssteuerung (IAM) mithilfe der Communication Services-Ressource konfigurieren.

Wenn Sie eine neue Communication Services-Ressource erstellen möchten, finden Sie weitere Informationen unter Schnellstart: Erstellen und Verwalten einer Communication Services-Ressource.

Schritt 5: Erteilen der Administrator-Einwilligung

Der Microsoft Entra-Mandant kann konfiguriert werden, um die Einwilligung des Microsoft Entra-Administrators für die Berechtigung Teams.ManageCalls und Teams.ManageChats der Anwendung anzufordern. In einem solchen Fall muss der Microsoft Entra-Administrator der Contoso-Anwendung die Communication Services-Berechtigungen Teams.ManageCalls und Teams.ManageChats erteilen. Der Microsoft Entra-Administrator von Fabrikam erteilt die Einwilligung über eine eindeutige URL.

Die folgenden Rollen können die Einwilligung im Auftrag eines Unternehmens erteilen:

• Globaler Administrator
• Anwendungsadministrator
• Cloudanwendungsadministrator

Wenn Sie Rollen in Azure-Portal überprüfen möchten, lesen Sie Auflisten von Azure-Rollenzuweisungen über das Azure-Portal.

Der Microsoft Entra-Administrator von Fabrikam führt folgende Schritte aus, um eine URL zur Administrator-Einwilligung zu erstellen:

1. In der URL https://login.microsoftonline.com/{Tenant_ID}/adminconsent?client_id={Application_ID} ersetzt der Administrator {Tenant_ID} durch die Mandanten-ID von Fabrikam und {Application_ID} durch die Anwendungs-ID von Contoso.
2. Der Administrator meldet sich an und erteilt Berechtigungen im Namen der Organisation.

Der Dienstprinzipal der Anwendung von Contoso im Mandanten von Fabrikam wird erstellt, sobald die Einwilligung erteilt wurde. Der Administrator von Fabrikam kann die Einwilligung in Microsoft Entra ID mit den folgenden Schritten überprüfen:

1. Melden Sie sich beim Azure-Portal als Administrator an.
2. Gehen Sie zu Microsoft Entra ID.
3. Stellen Sie im Bereich Unternehmensanwendungen den Filter Anwendungstyp auf Alle Anwendungen ein.
4. Geben Sie im Feld zum Filtern der Anwendungen den Namen der Contoso-Anwendung ein.
5. Wählen Sie Übernehmen.
6. Wählen Sie den Dienstprinzipal mit dem erforderlichen Namen aus.
7. Wechseln Sie zum Bereich Berechtigungen.

Wie Sie sehen, lautet der Status der Communication Services-Berechtigungen Teams.ManageCalls und Teams.ManageChats Gewährt für {Verzeichnisname}.

Wenn das Problem „Die App versucht, auf einen Dienst '1fd5118e-2576-4263-8130-9503064c837a' (Azure Communication Services) zuzugreifen, für den der '{GUID}' Ihrer Organisation ein Dienstprinzipal fehlt. Wenden Sie sich an Ihre*n IT-Administrator*in, um die Konfiguration Ihrer Dienstabonnements zu überprüfen oder der Anwendung zu gestatten, den erforderlichen Dienstprinzipal zu erstellen.“ auftritt, fehlt Ihrem Microsoft Entra-Mandanten ein Dienstprinzipal für die Azure Communication Services-Anwendung. Verwenden Sie PowerShell als Microsoft Entra-Administrator, um eine Verbindung mit Ihrem Mandanten herzustellen und das Problem zu beheben. Ersetzen Sie Tenant_ID mit einer ID Ihres Microsoft Entra-Mandanten.

Sie benötigen Application.ReadWrite.All, wie nachstehend gezeigt.

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

Wenn der Befehl nicht gefunden wird, starten Sie PowerShell als Administrator, und installieren Sie das Microsoft Graph-Paket.

Install-Module Microsoft.Graph

Führen Sie dann den folgenden Befehl aus, um Ihrem Mandanten einen Dienstprinzipal hinzuzufügen. Ändern Sie nicht die GUID der App-ID.

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

Entwickleraktionen

Der Entwickler von Contoso muss die Clientanwendung für die Authentifizierung von Benutzern einrichten. Anschließend muss er einen Endpunkt auf dem Back-End-Server erstellen, um Microsoft Entra-Benutzertoken nach der Umleitung zu verarbeiten. Wenn ein Microsoft Entra-Benutzertoken empfangen wurde, wird es gegen ein Zugriffstoken für Teams-Benutzer ausgetauscht und an die Clientanwendung zurückgegeben.

Die erforderlichen Aktionen des Entwicklers sind in der folgenden Abbildung dargestellt:

1. Der Entwickler von Contoso konfiguriert die MSAL (Microsoft Authentication Library), um den Benutzer für die Anwendung zu authentifizieren, die zuvor vom Administrator für die Communication-Berechtigung Services Teams.ManageCalls und Teams.ManageChats erstellt wurde.
2. Der Entwickler von Contoso initialisiert das Communication Services Identitäts-SDK und tauscht das eingehende Microsoft Entra-Benutzertoken gegen das Zugriffstoken für Teams-Benutzer über das Identitäts-SDK aus. Die Zugriffstoken für Teams-Benutzer werden dann an die Clientanwendung zurückgegeben.

Mithilfe der MSAL können Entwickler Microsoft Entra-Benutzertoken vom Microsoft Identity Platform-Endpunkt abrufen, um Benutzer zu authentifizieren und auf geschützte Web-APIs zuzugreifen. Sie kann verwendet werden, um sicheren Zugriff auf Communication Services zu gewähren. MSAL unterstützt verschiedene Anwendungsarchitekturen und -plattformen einschließlich .NET, JavaScript, Java, Python, Android und iOS.

Weitere Informationen zum Einrichten von Umgebungen in der öffentlichen Dokumentation finden Sie unter Übersicht über die Microsoft-Authentifizierungsbibliothek.

Hinweis

In den folgenden Abschnitten wird beschrieben, wie sie Microsoft Entra-Zugriffstoken für das Zugriffstoken für Teams-Benutzer für die Konsolenanwendung austauschen.

Einrichten erforderlicher Komponenten

• Die aktuelle Version des .NET Core SDK für Ihr Betriebssystem.

Endgültiger Code

Den fertigen Code für diese Schnellstartanleitung finden Sie auf GitHub.

Einrichtung

Erstellen einer neuen C#-Anwendung

Verwenden Sie in einem Konsolenfenster (z. B. cmd, PowerShell oder Bash) den Befehl dotnet new zum Erstellen einer neuen Konsolen-App mit dem Namen CommunicationAccessTokensQuickstart. Dieser Befehl erstellt ein einfaches „Hallo Welt“-C#-Projekt mit einer einzigen Quelldatei: Program.cs.

dotnet new console -o CommunicationAccessTokensQuickstart

Wechseln Sie zum neu erstellten App-Ordner, und verwenden Sie den Befehl dotnet build, um Ihre Anwendung zu kompilieren.

cd CommunicationAccessTokensQuickstart
dotnet build

Installieren des Pakets

Installieren Sie im Anwendungsverzeichnis mithilfe des Befehls dotnet add package die Azure Communication Services-Identitätsbibliothek für das .NET-Paket.

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

Einrichten des App-Frameworks

Über das Projektverzeichnis:

1. Öffnen Sie die Datei Program.cs in einem Text-Editor.
2. Fügen Sie eine Anweisung vom Typ using hinzu, um den Namespace Azure.Communication.Identity einzuschließen.
3. Aktualisieren der Main-Methodendeklaration zur Unterstützung von asynchronem Code

Verwenden Sie zum Einstieg den folgenden Code:

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

Schritt 1: Empfangen von Microsoft Entra-Benutzertoken und Objekt-ID über die MSAL-Bibliothek

Der erste Schritt im Flow für den Tokenaustausch besteht darin, mithilfe von Microsoft.Identity.Client ein Token für Ihre Teams-Benutzer abzurufen. Der folgende Code ruft die Microsoft Entra-Client- und -Mandanten-ID aus Umgebungsvariablen namens AAD_CLIENT_ID und AAD_TENANT_ID ab. Es ist wichtig, den MSAL-Client mit der richtigen Berechtigung basierend auf der Umgebungsvariablen AAD_TENANT_ID zu konfigurieren, um den Anspruch der Objekt-ID (oid), der einem Benutzer im Mandanten von Fabrikam entspricht, abrufen und die Variable userObjectId initialisieren zu können.

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

Schritt 2: Initialisieren von CommunicationIdentityClient

Initialisieren Sie einen Kommunikationsidentitätsclient (CommunicationIdentityClient) mit Ihrer Verbindungszeichenfolge. Im folgenden Code wird die Verbindungszeichenfolge für die Ressource aus einer Umgebungsvariablen namens COMMUNICATION_SERVICES_CONNECTION_STRING abgerufen. Informationen zur Verwaltung der Verbindungszeichenfolge Ihrer Ressource.

Fügen Sie der Main-Methode folgenden Code hinzu:

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

Schritt 3: Austauschen des Microsoft Entra-Zugriffstokens der Teams-Benutzer*innen mit einem Zugriffstoken für die Kommunikationsidentität

Verwenden Sie die Methode GetTokenForTeamsUser, um ein Zugriffstoken für den Teams-Benutzer auszustellen, das mit den Azure Communication Services SDKs verwendet werden kann.

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

Ausführen des Codes

Führen Sie die Anwendung mit dem Befehl dotnet run aus dem Anwendungsverzeichnis aus.

dotnet run

Einrichten erforderlicher Komponenten

• Node.js, Active LTS- und Maintenance LTS-Versionen (8.11.1 und 10.14.1 empfohlen)

Endgültiger Code

Den fertigen Code für diese Schnellstartanleitung finden Sie auf GitHub.

Einrichtung

Erstellen einer neuen Node.js-Anwendung

Öffnen Sie Ihr Terminal- oder Befehlsfenster, erstellen Sie ein neues Verzeichnis für Ihre App, und navigieren Sie zu diesem Verzeichnis.

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

Führen Sie npm init -y aus, um eine Datei package.json mit den Standardeinstellungen zu erstellen.

npm init -y

Installieren des Pakets

Verwenden Sie den Befehl npm install, um das Azure Communication Services Identity SDK für JavaScript zu installieren.

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

Durch die Option --save wird die Bibliothek als Abhängigkeit in der Datei package.json aufgeführt.

Einrichten des App-Frameworks

Über das Projektverzeichnis:

1. Öffnen einer neuen Textdatei im Code-Editor

2. Fügen Sie einen Aufruf vom Typ require hinzu, um den Kommunikationsidentitätsclient (CommunicationIdentityClient) zu laden.

3. Erstellen der Struktur für das Programm, einschließlich einer einfachen Ausnahmebehandlung

   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. Speichern Sie die neue Datei als issue-communication-access-token.js im Verzeichnis access-tokens-quickstart.

Schritt 1: Empfangen von Microsoft Entra-Benutzertoken und Objekt-ID über die MSAL-Bibliothek

Der erste Schritt im Flow für den Tokenaustausch besteht darin, mithilfe von Microsoft.Identity.Client ein Token für Ihre Teams-Benutzer abzurufen. Der folgende Code ruft die Microsoft Entra-Client- und -Mandanten-ID aus Umgebungsvariablen namens AAD_CLIENT_ID und AAD_TENANT_ID ab. Es ist wichtig, den MSAL-Client mit der richtigen Berechtigung basierend auf der Umgebungsvariablen AAD_TENANT_ID zu konfigurieren, um den Anspruch der Objekt-ID (oid), der einem Benutzer im Mandanten von Fabrikam entspricht, abrufen und die Variable userObjectId initialisieren zu können.

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

Schritt 2: Initialisieren von CommunicationIdentityClient

Instanziieren Sie einen Kommunikationsidentitätsclient (CommunicationIdentityClient) mit Ihrer Verbindungszeichenfolge. Im folgenden Code wird die Verbindungszeichenfolge für die Ressource aus einer Umgebungsvariablen namens COMMUNICATION_SERVICES_CONNECTION_STRING abgerufen. Informationen zur Verwaltung der Verbindungszeichenfolge Ihrer Ressource.

Fügen Sie der then-Methode folgenden Code hinzu:

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

Schritt 3: Austauschen des Microsoft Entra-Zugriffstokens der Teams-Benutzer*innen mit einem Zugriffstoken für die Kommunikationsidentität

Verwenden Sie die Methode getTokenForTeamsUser, um ein Zugriffstoken für den Teams-Benutzer auszustellen, das mit den Azure Communication Services SDKs verwendet werden kann.

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

Ausführen des Codes

Navigieren Sie an einer Konsoleneingabeaufforderung zum Verzeichnis mit der Datei issue-communication-access-token.js, und führen Sie anschließend den folgenden node-Befehl aus, um die App auszuführen.

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

Einrichten erforderlicher Komponenten

• Python 3.8+.

Endgültiger Code

Den fertigen Code für diese Schnellstartanleitung finden Sie auf GitHub.

Einrichtung

Erstellen einer neuen Python-Anwendung

1. Öffnen Sie Ihr Terminal- oder Befehlsfenster, erstellen Sie ein neues Verzeichnis für Ihre App, und navigieren Sie zu diesem Verzeichnis.

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

2. Erstellen Sie mithilfe eines Text-Editors eine Datei mit dem Namen exchange-communication-access-tokens.py im Stammverzeichnis des Projekts, und fügen Sie die Struktur für das Programm hinzu (einschließlich einer einfachen Ausnahmebehandlung). In den folgenden Abschnitten wird dieser Datei der gesamte Quellcode für diese Schnellstartanleitung hinzugefügt.

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

Installieren des Pakets

Installieren Sie im Anwendungsverzeichnis mithilfe des Befehls pip install das Python-Paket des SDK für Identitäten von Azure Communication Services.

pip install azure-communication-identity
pip install msal

Schritt 1: Empfangen von Microsoft Entra-Benutzertoken und Objekt-ID über die MSAL-Bibliothek

Der erste Schritt im Flow für den Tokenaustausch besteht darin, mithilfe von Microsoft.Identity.Client ein Token für Ihre Teams-Benutzer abzurufen. Konfigurieren Sie im Azure-Portal den Umleitungs-URI Ihrer „mobilen und Desktopanwendung“ als http://localhost. Der folgende Code ruft die Microsoft Entra-Client- und -Mandanten-ID aus Umgebungsvariablen namens AAD_CLIENT_ID und AAD_TENANT_ID ab. Es ist wichtig, den MSAL-Client mit der richtigen Berechtigung basierend auf der Umgebungsvariablen AAD_TENANT_ID zu konfigurieren, um den Anspruch der Objekt-ID (oid), der einem Benutzer im Mandanten von Fabrikam entspricht, abrufen und die Variable user_object_id initialisieren zu können.

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

Schritt 2: Initialisieren von CommunicationIdentityClient

Instanziieren Sie einen Kommunikationsidentitätsclient (CommunicationIdentityClient) mit Ihrer Verbindungszeichenfolge. Im folgenden Code wird die Verbindungszeichenfolge für die Ressource aus einer Umgebungsvariablen namens COMMUNICATION_SERVICES_CONNECTION_STRING abgerufen. Informationen zur Verwaltung der Verbindungszeichenfolge Ihrer Ressource.

Fügen Sie diesen Code im try-Block hinzu:

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

Schritt 3: Austauschen des Microsoft Entra-Zugriffstokens der Teams-Benutzer*innen mit einem Zugriffstoken für die Kommunikationsidentität

Verwenden Sie die Methode get_token_for_teams_user, um ein Zugriffstoken für den Teams-Benutzer auszustellen, das mit den Azure Communication Services SDKs verwendet werden kann.

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

Ausführen des Codes

Navigieren Sie in einer Konsoleneingabeaufforderung zum Verzeichnis mit der Datei exchange-teams-access-tokens.py, und führen Sie anschließend den folgenden Befehl python aus, um die App auszuführen.

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

Einrichten erforderlicher Komponenten

• Java Development Kit (JDK), Version 8 oder höher.
• Apache Maven.

Endgültiger Code

Den fertigen Code für diese Schnellstartanleitung finden Sie auf GitHub.

Einrichtung

Erstellen einer neuen Java-Anwendung

Öffnen Sie Ihr Terminal oder Befehlsfenster. Navigieren Sie zu dem Verzeichnis, in dem Sie Ihre Java-Anwendung erstellen möchten. Führen Sie den unten angegebenen Befehl aus, um das Java-Projekt aus der Vorlage maven-archetype-quickstart zu generieren.

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

Wie Sie sehen, wurde durch die Aufgabe „generate“ ein Verzeichnis erstellt, das den gleichen Namen besitzt wie die Artefakt-ID (artifactId). In diesem Verzeichnis enthält der Ordner src/main/java den Quellcode des Projekts, src/test/java directory enthält die Testquelle, und die Datei pom.xml repräsentiert das Projektobjektmodell (POM).

Installieren des Pakets

Öffnen Sie die Datei pom.xml in Ihrem Text-Editor. Fügen Sie der Gruppe der Abhängigkeiten das folgende Abhängigkeitselement hinzu:

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

Einrichten des App-Frameworks

Über das Projektverzeichnis:

1. Navigieren Sie zum Verzeichnis /src/main/java/com/communication/quickstart.
2. Öffnen Sie die Datei App.java in Ihrem Editor.
3. Ersetzen Sie die Anweisung System.out.println("Hello world!");.
4. Fügen Sie Anweisungen vom Typ import hinzu.

Verwenden Sie zum Einstieg den folgenden Code:

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

Schritt 1: Empfangen von Microsoft Entra-Benutzertoken und Objekt-ID über die MSAL-Bibliothek

Der erste Schritt im Flow für den Tokenaustausch besteht darin, mithilfe von Microsoft.Identity.Client ein Token für Ihre Teams-Benutzer abzurufen. Es ist wichtig, den MSAL-Client mit der richtigen Berechtigung basierend auf der Variablen tenantId zu konfigurieren, um den Anspruch der Objekt-ID (oid), der einem Benutzer im Mandanten von Fabrikam entspricht, abrufen und die Variable userObjectId initialisieren zu können.

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

Schritt 2: Initialisieren von CommunicationIdentityClient

Instanziieren Sie einen Kommunikationsidentitätsclient (CommunicationIdentityClient) mit dem Zugriffsschlüssel und dem Endpunkt Ihrer Ressource. Informationen zur Verwaltung der Verbindungszeichenfolge Ihrer Ressource. Zusätzlich können Sie den Client mit einem beliebigen benutzerdefinierten HTTP-Client initialisieren, der die Schnittstelle com.azure.core.http.HttpClientimplementiert.

Fügen Sie der main-Methode folgenden Code hinzu:

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

Schritt 3: Austauschen des Microsoft Entra-Zugriffstokens der Teams-Benutzer*innen mit einem Zugriffstoken für die Kommunikationsidentität

Verwenden Sie die Methode getTokenForTeamsUser, um ein Zugriffstoken für den Teams-Benutzer auszustellen, das mit den Azure Communication Services SDKs verwendet werden kann.

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

Ausführen des Codes

Navigieren Sie zum Verzeichnis, das die Datei pom.xml enthält, und kompilieren Sie das Projekt mit dem Befehl mvn compile.

Erstellen Sie dann das Paket.

mvn package

Führen Sie die App mit dem folgenden mvn-Befehl aus.

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

Benutzeraktionen

Der Benutzer stellt die Fabrikam-Benutzer der Contoso-Anwendung dar. Die Benutzeraktionen sind im folgenden Diagramm dargestellt:

1. Der Benutzer von Fabrikam verwendet die Clientanwendung von Contoso und wird zur Authentifizierung aufgefordert.
2. Die Clientanwendung von Contoso authentifiziert den Benutzer mithilfe der MSAL und des Microsoft Entra-Mandanten von Fabrikam mit den Communication Services-Berechtigungen Teams.ManageCalls und Teams.ManageChats für die Contoso-Anwendung.
3. Die Authentifizierung wird an den Server umgeleitet, der in der Eigenschaft Umleitungs-URI in MSAL und in der Anwendung von Contoso definiert ist.
4. Der Server von Contoso tauscht das Microsoft Entra-Benutzertoken mithilfe des Communication Services Identitäts-SDK gegen das Zugriffstoken für Teams-Benutzer aus und gibt das Zugriffstoken für Teams-Benutzer an die Clientanwendung zurück.

Mit einem gültigen Zugriffstoken für Teams-Benutzer in der Clientanwendung können Entwickler das Communication Services Calling SDK integrieren und Anrufe als Teams-Benutzer verwalten.

Nächste Schritte

In diesem Schnellstart haben Sie gelernt, wie Sie:

• Konfigurieren und erstellen einer Anwendung in Microsoft Entra ID.
• Verwenden Sie die Microsoft Authentication Library (MSAL), um ein Microsoft Entra-Benutzertoken auszugeben.
• Sie können das Communication Services Identitäts-SDK verwenden, um das Microsoft Entra-Benutzertoken gegen ein Zugriffstoken für Teams-Benutzer auszutauschen.

Erstellen eines vertrauenswürdigen Authentifizierungsdiensts für Teams-BenutzerTätigen eines Anrufs als Teams-Benutzer mit einem Teams-Benutzer

Erfahren Sie mehr zu den folgenden Konzepten:

• Anwendungsfälle für Kommunikation als Teams-Benutzer
• Azure Communication Services unterstützt Teams-Identitäten.
• Teams-Interoperabilität
• Einzelinstanz- und Mehrinstanzenauthentifizierung für Teams-Benutzer*innen
• Erstellen und Verwalten von Kommunikationszugriffstoken für Teams-Benutzer in einer einzelseitigen Anwendung (SPA)