Schnellstart: Erstellen und Verwalten von Zugriffstoken

Zugriffstoken ermöglichen die direkte Authentifizierung von Azure Communication Services SDKs bei Azure Communication Services als bestimmte Identität. Sie müssen Zugriffstoken erstellen, wenn Sie möchten, dass Ihre Benutzer an einem Anruf oder einem Chat-Thread in Ihrer Anwendung teilnehmen können.

In dieser Schnellstartanleitung erfahren Sie, wie Sie die Azure Communication Services SDKs verwenden, um Identitäten zu erstellen und Ihre Zugriffstoken zu verwalten. Für Anwendungsfälle in der Produktion empfehlen wir, Zugriffstoken mit einem serverseitigen Dienst zu erzeugen.

Voraussetzungen

Einrichten

Hinzufügen der Erweiterung

Fügen Sie die Azure Communication Services-Erweiterung für Azure CLI mithilfe des Befehls az extension hinzu.

az extension add --name communication

Anmelden bei der Azure-Befehlszeilenschnittstelle

Sie müssen sich bei Azure CLI anmelden. Sie können sich beim Ausführen des az login-Befehls vom Terminal anmelden und Ihre Anmeldeinformationen bereitstellen.

(Optional) Verwenden von Azure CLI-Identitätsvorgängen ohne Übergeben einer Verbindungszeichenfolge

Sie können die Umgebungsvariable AZURE_COMMUNICATION_CONNECTION_STRING so konfigurieren, dass Azure CLI-Identitätsvorgänge verwendet werden, ohne dass Sie --connection_string zum Übergeben der Verbindungszeichenfolge verwenden müssen. Öffnen Sie zum Konfigurieren einer Umgebungsvariablen ein Konsolenfenster, und wählen Sie über die folgenden Registerkarten Ihr Betriebssystem aus. Ersetzen Sie <yourConnectionString> durch Ihre Verbindungszeichenfolge.

Öffnen Sie ein Konsolenfenster, und geben Sie den folgenden Befehl ein:

setx AZURE_COMMUNICATION_CONNECTION_STRING "<yourConnectionString>"

Nachdem Sie die Umgebungsvariable hinzugefügt haben, müssen Sie unter Umständen alle ausgeführten Programme neu starten, von denen die Umgebungsvariable gelesen werden muss, z.B. das Konsolenfenster. Wenn Sie beispielsweise Visual Studio als Editor verwenden, müssen Sie Visual Studio neu starten, bevor Sie das Beispiel ausführen.

Speichern des Zugriffstokens in einer Umgebungsvariable

Öffnen Sie zum Konfigurieren einer Umgebungsvariablen ein Konsolenfenster, und wählen Sie über die folgenden Registerkarten Ihr Betriebssystem aus. Ersetzen Sie <yourAccessToken> durch Ihr eigentliches Zugriffstoken.

Öffnen Sie ein Konsolenfenster, und geben Sie den folgenden Befehl ein:

setx AZURE_COMMUNICATION_ACCESS_TOKEN "<yourAccessToken>"

Nachdem Sie die Umgebungsvariable hinzugefügt haben, müssen Sie unter Umständen alle ausgeführten Programme neu starten, von denen die Umgebungsvariable gelesen werden muss, z.B. das Konsolenfenster. Wenn Sie beispielsweise Visual Studio als Editor verwenden, müssen Sie Visual Studio neu starten, bevor Sie das Beispiel ausführen.

Operations

Erstellen einer Identität

Zum Erstellen von Zugriffstoken benötigen Sie eine Identität. Von Azure Communication Services wird zu diesem Zweck ein einfaches Identitätsverzeichnis gepflegt. Verwenden Sie den Befehl user create, um im Verzeichnis einen neuen Eintrag mit einem eindeutigen Id zu erstellen. Die Identität ist später erforderlich, um Zugriffstoken auszustellen.

az communication identity user create --connection-string "<yourConnectionString>"
  • Ersetzen Sie <yourConnectionString> durch Ihre Verbindungszeichenfolge.

Erstellen einer Identität und Ausstellen eines Zugriffstokens in derselben Anforderung

Führen Sie den folgenden Befehl aus, um eine Communication Services-Identität zu erstellen und zugleich ein Zugriffstoken dafür auszustellen. Der scopes-Parameter definiert einen Satz von Zugriffstokenberechtigungen und -rollen. Weitere Informationen finden Sie in der Liste der unterstützten Aktionen unter Authentifizieren bei Azure Communication Services.

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

Nehmen Sie im Code diese Ersetzung vor:

  • Ersetzen Sie <yourConnectionString> durch Ihre Verbindungszeichenfolge.

Ausstellen von Zugriffstoken

Führen Sie den folgenden Befehl aus, um ein Zugriffstoken für Ihre Communication Services-Identität auszustellen. Der scopes-Parameter definiert einen Satz von Zugriffstokenberechtigungen und -rollen. Weitere Informationen finden Sie in der Liste der unterstützten Aktionen unter Authentifizieren bei Azure Communication Services.

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

Nehmen Sie im Code diese Ersetzung vor:

  • Ersetzen Sie <yourConnectionString> durch Ihre Verbindungszeichenfolge.
  • Ersetzen Sie <userId> durch Ihre Benutzer-ID.

Zugriffstoken sind kurzlebige Anmeldeinformationen, die erneut ausgestellt werden müssen. Wenn dies nicht der Fall ist, kann die Benutzerumgebung Ihrer Anwendung unterbrochen werden. Die Antworteigenschaft expires_on gibt die Lebensdauer des Zugriffstokens an.

Ausstellen eines Zugriffstokens mit mehreren Bereichen

Führen Sie den folgenden Befehl aus, um ein Zugriffstoken mit mehreren Bereichen für Ihre Communication Services-Identität auszustellen. Der scopes-Parameter definiert einen Satz von Zugriffstokenberechtigungen und -rollen. Weitere Informationen finden Sie in der Liste der unterstützten Aktionen im Identitätsmodell.

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

Nehmen Sie im Code diese Ersetzung vor:

  • Ersetzen Sie <yourConnectionString> durch Ihre Verbindungszeichenfolge.
  • Ersetzen Sie <userId> durch Ihre Benutzer-ID.

Zugriffstoken sind kurzlebige Anmeldeinformationen, die erneut ausgestellt werden müssen. Wenn dies nicht der Fall ist, kann die Benutzerumgebung Ihrer Anwendung unterbrochen werden. Die Antworteigenschaft expires_on gibt die Lebensdauer des Zugriffstokens an.

Austauschen eines Azure AD-Zugriffstokens des Teams-Benutzers gegen ein Zugriffstoken für die Communication-Identität

Verwenden Sie den Befehl token get-for-teams-user, um ein Zugriffstoken für den Teams-Benutzer auszustellen, das mit den Azure Communication Services SDKs verwendet werden kann.

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

Nehmen Sie im Code diese Ersetzung vor:

  • Ersetzen Sie <yourConnectionString> durch Ihre Verbindungszeichenfolge.
  • Ersetzen Sie <yourAadUser> mit Ihrer Microsoft Entra-Mandanten-ID.
  • Ersetzen Sie sie <yourAadApplication> durch Ihre Microsoft Entra-Anwendungs-ID.
  • Ersetzen Sie <yourAadToken> es durch Ihr Microsoft Entra-Zugriffstoken.

Widerrufen von Zugriffstoken

Möglicherweise müssen Sie ein Zugriffstoken gelegentlich explizit widerrufen. Sie würden dies beispielsweise tun, wenn Anwendungsbenutzer das Kennwort ändern, das sie für die Authentifizierung bei Ihrem Dienst verwenden. Der Befehl token revoke erklärt alle aktiven Zugriffstoken für ungültig, die für die Identität ausgestellt wurden.

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

Nehmen Sie im Code diese Ersetzung vor:

  • Ersetzen Sie <yourConnectionString> durch Ihre Verbindungszeichenfolge.
  • Ersetzen Sie <userId> durch Ihre Benutzer-ID.

Löschen einer Identität

Wenn Sie eine Identität löschen, widerrufen Sie alle aktiven Zugriffstoken und verhindern die weitere Ausstellung von Zugriffstoken für die Identität. Außerdem werden damit alle gespeicherten Inhalte entfernt, die der Identität zugeordnet sind.

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

Nehmen Sie im Code diese Ersetzung vor:

  • Ersetzen Sie <yourConnectionString> durch Ihre Verbindungszeichenfolge.
  • Ersetzen Sie <userId> durch Ihre Benutzer-ID.

Voraussetzungen

Endgültiger Code

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

Einrichten der Umgebung

Erstellen einer neuen C#-Anwendung

Verwenden Sie in einem Eingabeaufforderungsfenster (z. B. cmd, PowerShell oder Bash) den Befehl dotnet new zum Erstellen einer neuen Konsolen-App mit dem Namen AccessTokensQuickstart. Dieser Befehl erstellt ein einfaches C#-Projekt vom Typ „Hallo Welt“ mit einer einzelnen Quelldatei, program.cs.

dotnet new console -o AccessTokensQuickstart

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

cd AccessTokensQuickstart
dotnet build

Es sollte eine einfache „Hallo Welt“-Ausgabe angezeigt werden. Wenn ja, funktioniert Ihr Setup ordnungsgemäß, und Sie können mit dem Schreiben Ihres Codes für Azure Communication Services beginnen.

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

Einrichten des App-Frameworks

Führen Sie im Projektverzeichnis die folgenden Schritte aus:

  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 Sie die Deklaration der Methode Main, sodass asynchroner Code unterstützt wird.

Führen Sie zum Einstieg den folgenden Code aus:

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

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

            // Quickstart code goes here
        }
    }
}

Authentifizieren des Clients

Initialisieren Sie einen CommunicationIdentityClient mit Ihrer Verbindungszeichenfolge. Der folgende Code, den Sie der Main-Methode hinzufügen, ruft die Verbindungszeichenfolge für die Ressource aus einer Umgebungsvariablen mit dem Namen COMMUNICATION_SERVICES_CONNECTION_STRING ab.

Weitere Informationen finden Sie im Abschnitt „Speichern Ihrer Verbindungszeichenfolge“ unter Erstellen und Verwalten Communication Services Ressourcen.

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

Alternativ können Sie den Endpunkt und den Zugriffsschlüssel trennen, indem Sie den folgenden Code ausführen:

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

Wenn Sie bereits eine Microsoft Entra-Anwendung eingerichtet haben, können Sie sich mithilfe der Microsoft Entra-IDauthentifizieren.

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

Erstellen einer Identität

Zum Erstellen von Zugriffstoken benötigen Sie eine Identität. Von Azure Communication Services wird zu diesem Zweck ein einfaches Identitätsverzeichnis gepflegt. Verwenden Sie die Methode createUser, um in dem Verzeichnis einen neuen Eintrag mit einer eindeutigen Id zu erstellen. Die Identität ist später erforderlich, um Zugriffstoken auszustellen.

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

Speichern Sie die empfangene Identität mit Zuordnung zu den Benutzern Ihrer Anwendung (z. B. durch Speichern in Ihrer Anwendungsserver-Datenbank).

Ausgeben eines Zugriffstokens

Verwenden Sie die GetToken-Methode, nachdem Sie eine Communication Services-Identität haben, um ein Zugriffstoken dafür auszustellen. Der scopes-Parameter definiert einen Satz von Zugriffstokenberechtigungen und -rollen. Weitere Informationen finden Sie in der Liste der unterstützten Aktionen im Identitätsmodell. Sie können auch eine neue Instanz von communicationUser basierend auf der Zeichenfolgendarstellung der Azure Communication Service-Identität generieren.

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

// Get the token from the response
var token =  tokenResponse.Value.Token;
var expiresOn = tokenResponse.Value.ExpiresOn;
Console.WriteLine($"\nIssued an access token with 'voip' scope that expires at {expiresOn}:");
Console.WriteLine(token);

Zugriffstoken sind kurzlebige Anmeldeinformationen, die erneut ausgestellt werden müssen. Wenn dies nicht der Fall ist, kann die Benutzerumgebung Ihrer Anwendung unterbrochen werden. Die expiresOn-Eigenschaft gibt die Lebensdauer des Zugriffstokens an.

Festlegen einer benutzerdefinierten Tokenablaufzeit

Die Standardablaufzeit für Token beträgt 24 Stunden, sie kann jedoch konfiguriert werden, indem Sie einen Wert zwischen einer Stunde und 24 Stunden für den optionalen Parameter tokenExpiresIn angeben. Wenn Sie ein neues Token anfordern, empfiehlt es sich, für die Tokenablaufzeit die erwartete typische Länge einer Kommunikationssitzung anzugeben.

// Issue an access token with a validity of an hour and the "voip" scope for an identity 
TimeSpan tokenExpiresIn = TimeSpan.FromHours(1);
CommunicationTokenScope[] scopes = new[] { CommunicationTokenScope.VoIP };
var tokenResponse = await client.GetTokenAsync(identity, scopes, tokenExpiresIn);

Erstellen einer Identität und Ausstellen eines Tokens in derselben Anforderung

Mit der CreateUserAndTokenAsync-Methode können Sie eine Communication Services-Identität erstellen und gleichzeitig ein Zugriffstoken dafür ausstellen. Der scopes-Parameter definiert einen Satz von Zugriffstokenberechtigungen und -rollen. Weitere Informationen finden Sie in der Liste der unterstützten Aktionen unter Authentifizieren bei Azure Communication Services.

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

// Retrieve the identity, token, and expiration date from the response
var identity = identityAndTokenResponse.Value.User;
var token = identityAndTokenResponse.Value.AccessToken.Token;
var expiresOn = identityAndTokenResponse.Value.AccessToken.ExpiresOn;
Console.WriteLine($"\nCreated an identity with ID: {identity.Id}");
Console.WriteLine($"\nIssued an access token with 'voip' scope that expires at {expiresOn}:");
Console.WriteLine(token);

Aktualisieren eines Zugriffstokens

Um ein Zugriffstoken zu aktualisieren, übergeben Sie eine Instanz des CommunicationUserIdentifier-Objekts an GetTokenAsync. Wenn Sie diese Id gespeichert haben und einen neuen CommunicationUserIdentifier erstellen müssen, können Sie zu diesem Zweck die gespeicherte Id wie folgt an den CommunicationUserIdentifier-Konstruktor übergeben:

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

Widerrufen von Zugriffstoken

Möglicherweise müssen Sie ein Zugriffstoken gelegentlich explizit widerrufen. Sie würden dies beispielsweise tun, wenn Anwendungsbenutzer das Kennwort ändern, das sie für die Authentifizierung bei Ihrem Dienst verwenden. Die RevokeTokensAsync-Methode erklärt alle aktiven Zugriffstoken für ungültig, die für die Identität ausgestellt wurden.

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

Löschen einer Identität

Wenn Sie eine Identität löschen, widerrufen Sie alle aktiven Zugriffstoken und verhindern die weitere Ausstellung von Zugriffstoken für die Identität. Außerdem werden damit alle gespeicherten Inhalte entfernt, die der Identität zugeordnet sind.

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

Ausführen des Codes

Wenn Sie die Erstellung des Zugriffstokens abgeschlossen haben, können Sie die Anwendung über Ihr Anwendungsverzeichnis ausführen, indem Sie den dotnet run-Befehl verwenden.

dotnet run

In der Ausgabe der App wird jede abgeschlossene Aktion beschrieben:

Azure Communication Services - Access Tokens Quickstart

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

Issued an access token with 'voip' scope that expires at 10/11/2022 7:34:29 AM +00:00:
eyJhbGciOiJSUzI1NiIsImtpZCI6IjEwNiIsIng1dCI6Im9QMWFxQnlfR3hZU3pSaXhuQ25zdE5PU2p2cyIsInR5cCI6IkpXVCJ9.eyJza3lwZWlkIjoiYWNzOjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMF8wMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJzY3AiOjE3OTIsImNzaSI6IjE2NjUzODcyNjkiLCJleHAiOjE2NjUzOTA4NjksImFjc1Njb3BlIjoidm9pcCIsInJlc291cmNlSWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJyZXNvdXJjZUxvY2F0aW9uIjoidW5pdGVkc3RhdGVzIiwiaWF0IjoxNjY1Mzg3MjY5fQ.kTXpQQtY7w6O82kByljZXrKtBvNNOleDE5m06LapzLeoWfRZCCpJQcDzBoLRA146mOhNzLZ0b5WMNTa5tD-0hWCiicDwgKLMASEGY9g0EvNQOidPff47g2hh6yqi9PKiDPp-t5siBMYqA6Nh6CQ-Oeh-35vcRW09VfcqFN38IgSSzJ7QkqBiY_QtfXz-iaj81Td0287KO4U1y2LJIGiyJLWC567F7A_p1sl6NmPKUmvmwM47tyCcQ1r_lfkRdeyDmcrGgY6yyI3XJZQbpxyt2DZqOTSVPB4PuRl7iyXxvppEa4Uo_y_BdMOOWFe6YTRB5O5lhI8m7Tf0LifisxX2sw

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

Issued an access token with 'voip' scope that expires at 10/11/2022 7:34:29 AM +00:00:
eyJhbGciOiJSUzI1NiIsImtpZCI6IjEwNiIsIng1dCI6Im9QMWFxQnlfR3hZU3pSaXhuQ25zdE5PU2p2cyIsInR5cCI6IkpXVCJ9.eyJza3lwZWlkIjoiYWNzOjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMF8wMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJzY3AiOjE3OTIsImNzaSI6IjE2NjUzODcyNjkiLCJleHAiOjE2NjUzOTA4NjksImFjc1Njb3BlIjoidm9pcCIsInJlc291cmNlSWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJyZXNvdXJjZUxvY2F0aW9uIjoidW5pdGVkc3RhdGVzIiwiaWF0IjoxNjY1Mzg3MjY5fQ.kTXpQQtY7w6O82kByljZXrKtBvNNOleDE5m06LapzLeoWfRZCCpJQcDzBoLRA146mOhNzLZ0b5WMNTa5tD-0hWCiicDwgKLMASEGY9g0EvNQOidPff47g2hh6yqi9PKiDPp-t5siBMYqA6Nh6CQ-Oeh-35vcRW09VfcqFN38IgSSzJ7QkqBiY_QtfXz-iaj81Td0287KO4U1y2LJIGiyJLWC567F7A_p1sl6NmPKUmvmwM47tyCcQ1r_lfkRdeyDmcrGgY6yyI3XJZQbpxyt2DZqOTSVPB4PuRl7iyXxvppEa4Uo_y_BdMOOWFe6YTRB5O5lhI8m7Tf0LifisxX2sw

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

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

Voraussetzungen

Endgültiger Code

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

Einrichten der Umgebung

Erstellen einer neuen Node.js-Anwendung

Erstellen Sie in einem Terminal- oder Eingabeaufforderungsfenster ein neues Verzeichnis für Ihre App, und öffnen Sie es.

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

Führen Sie npm init -y aus, um die 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

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

Einrichten des App-Frameworks

  1. Erstellen Sie im Projektverzeichnis eine Datei mit dem Namen issue-access-token.js, und fügen Sie den folgenden Code hinzu:

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

Authentifizieren des Clients

Instanziieren Sie CommunicationIdentityClient mit Ihrer Verbindungszeichenfolge. Der folgende Code, den Sie der Main-Methode hinzufügen, ruft die Verbindungszeichenfolge für die Ressource aus einer Umgebungsvariablen mit dem Namen COMMUNICATION_SERVICES_CONNECTION_STRING ab.

Weitere Informationen finden Sie im Abschnitt „Speichern Ihrer Verbindungszeichenfolge“ unter Erstellen und Verwalten Communication Services Ressourcen.

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

Alternativ können Sie den Endpunkt und den Zugriffsschlüssel trennen, indem Sie den folgenden Code ausführen:

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

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

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

Wenn Sie bereits eine Microsoft Entra-Anwendung eingerichtet haben, können Sie sich mithilfe der Microsoft Entra-IDauthentifizieren.

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

Erstellen einer Identität

Zum Erstellen von Zugriffstoken benötigen Sie eine Identität. Von Azure Communication Services wird zu diesem Zweck ein einfaches Identitätsverzeichnis gepflegt. Verwenden Sie die Methode createUser, um in dem Verzeichnis einen neuen Eintrag mit einer eindeutigen Id zu erstellen. Die Identität ist später erforderlich, um Zugriffstoken auszustellen.

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

Speichern Sie die empfangene Identität mit Zuordnung zu den Benutzern Ihrer Anwendung (z. B. durch Speichern in Ihrer Anwendungsserver-Datenbank).

Ausgeben eines Zugriffstokens

Verwenden Sie die Methode getToken, um ein Zugriffstoken für Ihre Communication Services-Identität auszustellen. Der scopes-Parameter definiert einen Satz von Zugriffstokenberechtigungen und -rollen. Weitere Informationen finden Sie in der Liste der unterstützten Aktionen im Identitätsmodell. Sie können auch eine neue Instanz von communicationUser basierend auf der Zeichenfolgendarstellung einer Azure Communication Service-Identität generieren.

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

// Get the token and its expiration date from the response
const { token, expiresOn } = tokenResponse;
console.log(`\nIssued an access token with 'voip' scope that expires at ${expiresOn}:`);
console.log(token);

Zugriffstoken sind kurzlebige Anmeldeinformationen, die erneut ausgestellt werden müssen. Wenn dies nicht der Fall ist, kann die Benutzerumgebung Ihrer Anwendung unterbrochen werden. Die expiresOn-Eigenschaft gibt die Lebensdauer des Zugriffstokens an.

Festlegen einer benutzerdefinierten Tokenablaufzeit

Die Standardablaufzeit für Token beträgt 24 Stunden (1.440 Minuten), sie kann jedoch konfiguriert werden, indem Sie einen Wert zwischen 60 Minuten und 1440 Minuten für den optionalen Parameter tokenExpiresInMinutes angeben. Wenn Sie ein neues Token anfordern, empfiehlt es sich, für die Tokenablaufzeit die erwartete typische Länge einer Kommunikationssitzung anzugeben.

// Issue an access token with a validity of an hour and the "voip" scope for an identity
const tokenOptions: GetTokenOptions = { tokenExpiresInMinutes: 60 };
let tokenResponse = await identityClient.getToken
(identityResponse, ["voip"], tokenOptions);

Erstellen einer Identität und Ausgeben eines Tokens in einem Methodenaufruf

Mit der createUserAndToken-Methode können Sie eine Communication Services-Identität erstellen und gleichzeitig ein Zugriffstoken dafür ausstellen. Der scopes-Parameter definiert einen Satz von Zugriffstokenberechtigungen und -rollen. Auch hier erstellen Sie sie mit dem voip-Bereich.

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

// Get the token, its expiration date, and the user from the response
const { token, expiresOn, user } = identityTokenResponse;
console.log(`\nCreated an identity with ID: ${user.communicationUserId}`);
console.log(`\nIssued an access token with 'voip' scope that expires at ${expiresOn}:`);
console.log(token);

Aktualisieren eines Zugriffstokens

Da Token ablaufen, müssen Sie sie in regelmäßigen Abständen aktualisieren. Für die Aktualisierung rufen Sie einfach getToken erneut mit derselben Identität auf, die beim Ausstellen der Token verwendet wurde. Außerdem müssen Sie die scopes der aktualisierten Token angeben.

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

Widerrufen von Zugriffstoken

Möglicherweise müssen Sie ein Zugriffstoken gelegentlich widerrufen. Sie würden dies beispielsweise tun, wenn Anwendungsbenutzer das Kennwort ändern, das sie für die Authentifizierung bei Ihrem Dienst verwenden. Die revokeTokens-Methode erklärt alle aktiven Zugriffstoken für ungültig, die für die Identität ausgestellt wurden.

await identityClient.revokeTokens(identityResponse);

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

Löschen einer Identität

Wenn Sie eine Identität löschen, widerrufen Sie alle aktiven Zugriffstoken und verhindern die weitere Ausstellung von Zugriffstoken für die Identität. Außerdem werden damit alle gespeicherten Inhalte entfernt, die der Identität zugeordnet sind.

await identityClient.deleteUser(identityResponse);

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

Ausführen des Codes

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

node ./issue-access-token.js

In der Ausgabe der App wird jede abgeschlossene Aktion beschrieben:

Azure Communication Services - Access Tokens Quickstart

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

Issued an access token with 'voip' scope that expires at 2022-10-11T07:34:29.9028648+00:00:
eyJhbGciOiJSUzI1NiIsImtpZCI6IjEwNiIsIng1dCI6Im9QMWFxQnlfR3hZU3pSaXhuQ25zdE5PU2p2cyIsInR5cCI6IkpXVCJ9.eyJza3lwZWlkIjoiYWNzOjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMF8wMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJzY3AiOjE3OTIsImNzaSI6IjE2NjUzODcyNjkiLCJleHAiOjE2NjUzOTA4NjksImFjc1Njb3BlIjoidm9pcCIsInJlc291cmNlSWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJyZXNvdXJjZUxvY2F0aW9uIjoidW5pdGVkc3RhdGVzIiwiaWF0IjoxNjY1Mzg3MjY5fQ.kTXpQQtY7w6O82kByljZXrKtBvNNOleDE5m06LapzLeoWfRZCCpJQcDzBoLRA146mOhNzLZ0b5WMNTa5tD-0hWCiicDwgKLMASEGY9g0EvNQOidPff47g2hh6yqi9PKiDPp-t5siBMYqA6Nh6CQ-Oeh-35vcRW09VfcqFN38IgSSzJ7QkqBiY_QtfXz-iaj81Td0287KO4U1y2LJIGiyJLWC567F7A_p1sl6NmPKUmvmwM47tyCcQ1r_lfkRdeyDmcrGgY6yyI3XJZQbpxyt2DZqOTSVPB4PuRl7iyXxvppEa4Uo_y_BdMOOWFe6YTRB5O5lhI8m7Tf0LifisxX2sw

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

Issued an access token with 'voip' scope that expires at 2022-10-11T07:34:29.9028648+00:00:
eyJhbGciOiJSUzI1NiIsImtpZCI6IjEwNiIsIng1dCI6Im9QMWFxQnlfR3hZU3pSaXhuQ25zdE5PU2p2cyIsInR5cCI6IkpXVCJ9.eyJza3lwZWlkIjoiYWNzOjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMF8wMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJzY3AiOjE3OTIsImNzaSI6IjE2NjUzODcyNjkiLCJleHAiOjE2NjUzOTA4NjksImFjc1Njb3BlIjoidm9pcCIsInJlc291cmNlSWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJyZXNvdXJjZUxvY2F0aW9uIjoidW5pdGVkc3RhdGVzIiwiaWF0IjoxNjY1Mzg3MjY5fQ.kTXpQQtY7w6O82kByljZXrKtBvNNOleDE5m06LapzLeoWfRZCCpJQcDzBoLRA146mOhNzLZ0b5WMNTa5tD-0hWCiicDwgKLMASEGY9g0EvNQOidPff47g2hh6yqi9PKiDPp-t5siBMYqA6Nh6CQ-Oeh-35vcRW09VfcqFN38IgSSzJ7QkqBiY_QtfXz-iaj81Td0287KO4U1y2LJIGiyJLWC567F7A_p1sl6NmPKUmvmwM47tyCcQ1r_lfkRdeyDmcrGgY6yyI3XJZQbpxyt2DZqOTSVPB4PuRl7iyXxvppEa4Uo_y_BdMOOWFe6YTRB5O5lhI8m7Tf0LifisxX2sw

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

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

Voraussetzungen

Endgültiger Code

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

Einrichten der Umgebung

Erstellen einer neuen Python-Anwendung

  1. Erstellen Sie in einem Terminal- oder Eingabeaufforderungsfenster ein neues Verzeichnis für Ihre App, und öffnen Sie es.

    mkdir access-tokens-quickstart && cd access-tokens-quickstart
    
  2. Erstellen Sie mithilfe eines Text-Editors eine Datei mit dem Namen issue-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 fügen Sie der Datei den gesamten Quellcode für diese Schnellstartanleitung hinzu.

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

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

Authentifizieren des Clients

Instanziieren Sie einen Kommunikationsidentitätsclient (CommunicationIdentityClient) mit Ihrer Verbindungszeichenfolge. Der folgende Code, den Sie dem try-Block hinzufügen, ruft die Verbindungszeichenfolge für die Ressource aus einer Umgebungsvariablen mit dem Namen COMMUNICATION_SERVICES_CONNECTION_STRING ab.

Weitere Informationen finden Sie im Abschnitt „Speichern Ihrer Verbindungszeichenfolge“ unter Erstellen und Verwalten Communication Services Ressourcen.

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

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

Wenn Sie bereits eine Microsoft Entra-Anwendung eingerichtet haben, können Sie sich auch mithilfe der Microsoft Entra-IDauthentifizieren.

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

Erstellen einer Identität

Zum Erstellen von Zugriffstoken benötigen Sie eine Identität. Von Azure Communication Services wird zu diesem Zweck ein einfaches Identitätsverzeichnis gepflegt. Verwenden Sie die Methode create_user, um in dem Verzeichnis einen neuen Eintrag mit einer eindeutigen Id zu erstellen. Die Identität ist später erforderlich, um Zugriffstoken auszustellen.

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

Speichern Sie die empfangene Identität mit Zuordnung zu den Benutzern Ihrer Anwendung (z. B. durch Speichern in Ihrer Anwendungsserver-Datenbank).

Ausgeben eines Zugriffstokens

Verwenden Sie die Methode get_token, um ein Zugriffstoken für Ihre Communication Services-Identität auszustellen. Der scopes-Parameter definiert einen Satz von Zugriffstokenberechtigungen und -rollen. Weitere Informationen finden Sie in der Liste der unterstützten Aktionen im Identitätsmodell. Sie können auch eine neue Instanz des Parameters CommunicationUserIdentifier basierend auf der Zeichenfolgendarstellung der Azure Communication Service-Identität generieren.

# Issue an access token with a validity of 24 hours and the "voip" scope for an identity
token_result = client.get_token(identity, ["voip"])
print("\nIssued an access token with 'voip' scope that expires at " + token_result.expires_on + ":")
print(token_result.token)

Zugriffstoken sind kurzlebige Anmeldeinformationen, die erneut ausgestellt werden müssen. Wenn dies nicht der Fall ist, kann die Benutzerumgebung Ihrer Anwendung unterbrochen werden. Die Antworteigenschaft expires_on gibt die Lebensdauer des Zugriffstokens an.

Festlegen einer benutzerdefinierten Tokenablaufzeit

Die Standardablaufzeit für Token beträgt 24 Stunden, sie kann jedoch konfiguriert werden, indem Sie einen Wert zwischen einer Stunde und 24 Stunden für den optionalen Parameter token_expires_in angeben. Wenn Sie ein neues Token anfordern, empfiehlt es sich, für die Tokenablaufzeit die erwartete typische Länge einer Kommunikationssitzung anzugeben.

# Issue an access token with a validity of an hour and the "voip" scope for an identity
token_expires_in = timedelta(hours=1)
token_result = client.get_token(identity, ["voip"], token_expires_in=token_expires_in)

Erstellen einer Identität und Ausstellen eines Zugriffstokens in derselben Anforderung

Mit der create_user_and_token-Methode können Sie eine Communication Services-Identität erstellen und gleichzeitig ein Zugriffstoken dafür ausstellen. Der scopes-Parameter definiert einen Satz von Zugriffstokenberechtigungen und -rollen. Weitere Informationen finden Sie in der Liste der unterstützten Aktionen unter Authentifizieren bei Azure Communication Services.

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

# Get the token details from the response
identity = identity_token_result[0]
token = identity_token_result[1].token
expires_on = identity_token_result[1].expires_on
print("\nCreated an identity with ID: " + identity.properties['id'])
print("\nIssued an access token with 'voip' scope that expires at " + expires_on + ":")
print(token)

Aktualisieren eines Zugriffstokens

Verwenden Sie zum Aktualisieren eines Zugriffstokens das CommunicationUserIdentifier-Objekt, um ein Token erneut auszugeben, indem Sie die vorhandene Identität übergeben:

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

Widerrufen von Zugriffstoken

Möglicherweise müssen Sie ein Zugriffstoken gelegentlich explizit widerrufen. Sie würden dies beispielsweise tun, wenn Anwendungsbenutzer das Kennwort ändern, das sie für die Authentifizierung bei Ihrem Dienst verwenden. Die revoke_tokens-Methode erklärt alle aktiven Zugriffstoken für ungültig, die für die Identität ausgestellt wurden.

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

Löschen einer Identität

Wenn Sie eine Identität löschen, widerrufen Sie alle aktiven Zugriffstoken und verhindern die weitere Ausstellung von Zugriffstoken für die Identität. Außerdem werden damit alle gespeicherten Inhalte entfernt, die der Identität zugeordnet sind.

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

Ausführen des Codes

Gehen Sie an einer Konsoleneingabeaufforderung zum Verzeichnis mit der Datei issue-access-token.py, und führen Sie anschließend den folgenden Befehl vom Typ python aus, um die App auszuführen:

python ./issue-access-tokens.py

In der Ausgabe der App wird jede abgeschlossene Aktion beschrieben:

Azure Communication Services - Access Tokens Quickstart

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

Issued an access token with 'voip' scope that expires at 2022-10-11T07:34:29.9028648+00:00:
eyJhbGciOiJSUzI1NiIsImtpZCI6IjEwNiIsIng1dCI6Im9QMWFxQnlfR3hZU3pSaXhuQ25zdE5PU2p2cyIsInR5cCI6IkpXVCJ9.eyJza3lwZWlkIjoiYWNzOjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMF8wMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJzY3AiOjE3OTIsImNzaSI6IjE2NjUzODcyNjkiLCJleHAiOjE2NjUzOTA4NjksImFjc1Njb3BlIjoidm9pcCIsInJlc291cmNlSWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJyZXNvdXJjZUxvY2F0aW9uIjoidW5pdGVkc3RhdGVzIiwiaWF0IjoxNjY1Mzg3MjY5fQ.kTXpQQtY7w6O82kByljZXrKtBvNNOleDE5m06LapzLeoWfRZCCpJQcDzBoLRA146mOhNzLZ0b5WMNTa5tD-0hWCiicDwgKLMASEGY9g0EvNQOidPff47g2hh6yqi9PKiDPp-t5siBMYqA6Nh6CQ-Oeh-35vcRW09VfcqFN38IgSSzJ7QkqBiY_QtfXz-iaj81Td0287KO4U1y2LJIGiyJLWC567F7A_p1sl6NmPKUmvmwM47tyCcQ1r_lfkRdeyDmcrGgY6yyI3XJZQbpxyt2DZqOTSVPB4PuRl7iyXxvppEa4Uo_y_BdMOOWFe6YTRB5O5lhI8m7Tf0LifisxX2sw

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

Issued an access token with 'voip' scope that expires at 2022-10-11T07:34:29.9028648+00:00:
eyJhbGciOiJSUzI1NiIsImtpZCI6IjEwNiIsIng1dCI6Im9QMWFxQnlfR3hZU3pSaXhuQ25zdE5PU2p2cyIsInR5cCI6IkpXVCJ9.eyJza3lwZWlkIjoiYWNzOjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMF8wMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJzY3AiOjE3OTIsImNzaSI6IjE2NjUzODcyNjkiLCJleHAiOjE2NjUzOTA4NjksImFjc1Njb3BlIjoidm9pcCIsInJlc291cmNlSWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJyZXNvdXJjZUxvY2F0aW9uIjoidW5pdGVkc3RhdGVzIiwiaWF0IjoxNjY1Mzg3MjY5fQ.kTXpQQtY7w6O82kByljZXrKtBvNNOleDE5m06LapzLeoWfRZCCpJQcDzBoLRA146mOhNzLZ0b5WMNTa5tD-0hWCiicDwgKLMASEGY9g0EvNQOidPff47g2hh6yqi9PKiDPp-t5siBMYqA6Nh6CQ-Oeh-35vcRW09VfcqFN38IgSSzJ7QkqBiY_QtfXz-iaj81Td0287KO4U1y2LJIGiyJLWC567F7A_p1sl6NmPKUmvmwM47tyCcQ1r_lfkRdeyDmcrGgY6yyI3XJZQbpxyt2DZqOTSVPB4PuRl7iyXxvppEa4Uo_y_BdMOOWFe6YTRB5O5lhI8m7Tf0LifisxX2sw

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

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

Voraussetzungen

Endgültiger Code

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

Einrichten der Umgebung

Erstellen einer neuen Java-Anwendung

Wechseln Sie in einem Terminal- oder Eingabeaufforderungsfenster zu dem Verzeichnis, in dem Sie Ihre Java-Anwendung erstellen möchten. Führen Sie den folgenden Code 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 artifactId. In diesem Verzeichnis enthält das Verzeichnis src/main/java den Quellcode des Projekts. Das Verzeichnis src/test/java enthält die Testquelle, und die Datei pom.xml ist das Projektobjektmodell (POM) des Projekts. Diese Datei wird für die Parameter der Projektkonfiguration verwendet.

Installieren der Communication Services-Pakete

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

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-communication-identity</artifactId>
    <version>[1.4.0,)</version>
</dependency>

Dieser Code weist Maven an, das Communication Services Identity SDK zu installieren, das Sie später verwenden werden.

Einrichten des App-Frameworks

Führen Sie im Projektverzeichnis die folgenden Schritte aus:

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

Verwenden Sie zum Einstieg den folgenden Code:

package com.communication.quickstart;

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

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

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

Authentifizieren des Clients

Instanziieren Sie einen Kommunikationsidentitätsclient (CommunicationIdentityClient) mit dem Zugriffsschlüssel und dem Endpunkt Ihrer Ressource. Weitere Informationen finden Sie im Abschnitt „Speichern Ihrer Verbindungszeichenfolge“ unter Erstellen und Verwalten Communication Services Ressourcen.

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 in der Projektdatei App.java der Methode main den folgenden Code hinzu:

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

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

Anstelle des Endpunkts und des Zugriffsschlüssels können Sie mithilfe der connectionString()-Methode auch die gesamte Verbindungszeichenfolge bereitstellen.

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

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

Wenn Sie bereits eine Microsoft Entra-Anwendung eingerichtet haben, können Sie sich mithilfe der Microsoft Entra-IDauthentifizieren.

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

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

Erstellen einer Identität

Zum Erstellen von Zugriffstoken benötigen Sie eine Identität. Von Azure Communication Services wird zu diesem Zweck ein einfaches Identitätsverzeichnis gepflegt. Verwenden Sie die Methode createUser, um in dem Verzeichnis einen neuen Eintrag mit einer eindeutigen Id zu erstellen.

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

Die erstellte Identität ist später erforderlich, um Zugriffstoken auszustellen. Speichern Sie die empfangene Identität mit Zuordnung zu den Benutzern Ihrer Anwendung (z. B. durch Speichern in Ihrer Anwendungsserver-Datenbank).

Ausgeben eines Zugriffstokens

Verwenden Sie die Methode getToken, um ein Zugriffstoken für Ihre Communication Services-Identität auszustellen. Der scopes-Parameter definiert einen Satz von Zugriffstokenberechtigungen und -rollen. Weitere Informationen finden Sie in der Liste der unterstützten Aktionen im Identitätsmodell.

Verwenden Sie im folgenden Code die Benutzervariable, die Sie im vorherigen Schritt erstellt haben, um ein Token abzurufen.

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

Zugriffstoken sind kurzlebige Anmeldeinformationen, die erneut ausgestellt werden müssen. Wenn dies nicht der Fall ist, kann die Benutzerumgebung Ihrer Anwendung unterbrochen werden. Die expiresAt-Eigenschaft gibt die Lebensdauer des Zugriffstokens an.

Festlegen einer benutzerdefinierten Tokenablaufzeit

Die Standardablaufzeit für Token beträgt 24 Stunden, sie kann jedoch konfiguriert werden, indem Sie einen Wert zwischen einer Stunde und 24 Stunden für den optionalen Parameter tokenExpiresIn angeben. Wenn Sie ein neues Token anfordern, empfiehlt es sich, für die Tokenablaufzeit die erwartete typische Länge einer Kommunikationssitzung anzugeben.

// Issue an access token with a validity of an hour and the "voip" scope for a user identity
List<CommunicationTokenScope> scopes = new ArrayList<>(Arrays.asList(CommunicationTokenScope.VOIP));
Duration tokenExpiresIn = Duration.ofHours(1);
AccessToken accessToken = communicationIdentityClient.getToken(user, scopes, tokenExpiresIn);

Erstellen einer Identität und Ausstellen eines Tokens in einer einzigen Anforderung

Alternativ können Sie die createUserAndToken-Methode verwenden, um im Verzeichnis einen neuen Eintrag mit einer eindeutigen Id zu erstellen und gleichzeitig ein Zugriffstoken auszustellen.

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

Aktualisieren eines Zugriffstokens

Verwenden Sie zum Aktualisieren eines Zugriffstokens das CommunicationUserIdentifier-Objekt für die erneute Ausstellung:

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

Widerrufen eines Zugriffstokens

Möglicherweise müssen Sie ein Zugriffstoken gelegentlich explizit widerrufen. Sie würden dies beispielsweise tun, wenn Anwendungsbenutzer das Kennwort ändern, das sie für die Authentifizierung bei Ihrem Dienst verwenden. Die revokeTokens-Methode erklärt alle aktiven Zugriffstoken für einen bestimmten Benutzer für ungültig. Im folgenden Code können Sie den zuvor erstellten Benutzer verwenden.

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

Löschen einer Identität

Wenn Sie eine Identität löschen, widerrufen Sie alle aktiven Zugriffstoken und verhindern die weitere Ausstellung von Zugriffstoken für die Identität. Außerdem werden damit alle gespeicherten Inhalte entfernt, die der Identität zugeordnet sind.

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

Ausführen des Codes

Gehen Sie zum Verzeichnis, das die Datei pom.xml enthält, und kompilieren Sie dann das Projekt mit dem folgenden mvn-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

In der Ausgabe der App wird jede abgeschlossene Aktion beschrieben:

Azure Communication Services - Access Tokens Quickstart

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

Issued an access token with 'voip' scope that expires at 2022-10-11T07:34:29.902864800Z:
eyJhbGciOiJSUzI1NiIsImtpZCI6IjEwNiIsIng1dCI6Im9QMWFxQnlfR3hZU3pSaXhuQ25zdE5PU2p2cyIsInR5cCI6IkpXVCJ9.eyJza3lwZWlkIjoiYWNzOjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMF8wMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJzY3AiOjE3OTIsImNzaSI6IjE2NjUzODcyNjkiLCJleHAiOjE2NjUzOTA4NjksImFjc1Njb3BlIjoidm9pcCIsInJlc291cmNlSWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJyZXNvdXJjZUxvY2F0aW9uIjoidW5pdGVkc3RhdGVzIiwiaWF0IjoxNjY1Mzg3MjY5fQ.kTXpQQtY7w6O82kByljZXrKtBvNNOleDE5m06LapzLeoWfRZCCpJQcDzBoLRA146mOhNzLZ0b5WMNTa5tD-0hWCiicDwgKLMASEGY9g0EvNQOidPff47g2hh6yqi9PKiDPp-t5siBMYqA6Nh6CQ-Oeh-35vcRW09VfcqFN38IgSSzJ7QkqBiY_QtfXz-iaj81Td0287KO4U1y2LJIGiyJLWC567F7A_p1sl6NmPKUmvmwM47tyCcQ1r_lfkRdeyDmcrGgY6yyI3XJZQbpxyt2DZqOTSVPB4PuRl7iyXxvppEa4Uo_y_BdMOOWFe6YTRB5O5lhI8m7Tf0LifisxX2sw

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

Issued an access token with 'chat' scope that expires at 2022-10-11T07:34:29.902864800Z:
eyJhbGciOiJSUzI1NiIsImtpZCI6IjEwNiIsIng1dCI6Im9QMWFxQnlfR3hZU3pSaXhuQ25zdE5PU2p2cyIsInR5cCI6IkpXVCJ9.eyJza3lwZWlkIjoiYWNzOjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMF8wMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJzY3AiOjE3OTIsImNzaSI6IjE2NjUzODcyNjkiLCJleHAiOjE2NjUzOTA4NjksImFjc1Njb3BlIjoidm9pcCIsInJlc291cmNlSWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJyZXNvdXJjZUxvY2F0aW9uIjoidW5pdGVkc3RhdGVzIiwiaWF0IjoxNjY1Mzg3MjY5fQ.kTXpQQtY7w6O82kByljZXrKtBvNNOleDE5m06LapzLeoWfRZCCpJQcDzBoLRA146mOhNzLZ0b5WMNTa5tD-0hWCiicDwgKLMASEGY9g0EvNQOidPff47g2hh6yqi9PKiDPp-t5siBMYqA6Nh6CQ-Oeh-35vcRW09VfcqFN38IgSSzJ7QkqBiY_QtfXz-iaj81Td0287KO4U1y2LJIGiyJLWC567F7A_p1sl6NmPKUmvmwM47tyCcQ1r_lfkRdeyDmcrGgY6yyI3XJZQbpxyt2DZqOTSVPB4PuRl7iyXxvppEa4Uo_y_BdMOOWFe6YTRB5O5lhI8m7Tf0LifisxX2sw

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

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

Voraussetzungen

Erstellen der Zugriffstoken

Navigieren Sie im Azure-Portal zu dem Blatt Identitäten und Benutzerzugriffstoken in Ihrer Communication Services-Ressource.

Wählen Sie den Umfang der Zugriffstoken aus. Sie können keine, eine oder mehrere auswählen. Klicken Sie auf Generate (Generieren) .

Select the scopes of the identity and access tokens.

Sie werden sehen, dass eine Identität und ein entsprechendes Benutzerzugriffstoken generiert werden. Sie können diese Zeichenfolgen kopieren und in den Beispiel-Apps und anderen Testszenarien verwenden.

The identity and access tokens are generated and show the expiration date.

Voraussetzungen

Benutzer erstellen

Fügen Sie in Ihrem Workflow mithilfe des Azure Communication Services Identity-Connectors einen neuen Schritt hinzu. Führen Sie die dazu erforderlichen Schritte in Power Automate aus, wobei Ihr Power Automate-Flow im Bearbeitungsmodus geöffnet ist.

  1. Wählen Sie im Designer unter dem Schritt, zu dem Sie die neue Aktion hinzufügen möchten, die Option Neuer Schritt aus. Alternativ können Sie die neue Aktion zwischen Schritten hinzufügen, indem Sie den Mauszeiger über den Pfeil zwischen diesen Schritten bewegen, das Pluszeichen (+) und dann „Aktion hinzufügen“ auswählen.

  2. Geben Sie im Suchfeld „Vorgang auswählen“ den Suchbegriff „Communication Services Identity“ ein. Wählen Sie in der Aktionsliste die Aktion „Benutzer erstellen“ aus.

    Screenshot that shows the Azure Communication Services Identity connector Create user action.

  3. Geben Sie die Verbindungszeichenfolge an. Sie können sie in Microsoft Azure innerhalb Ihrer Azure Communication Services-Ressource in der Option „Schlüssel“ im linken Menü > „Verbindungszeichenfolge“ finden.

    Screenshot that shows the Keys page within an Azure Communication Services Resource.

  4. Angeben eines Verbindungsnamens

  5. Klicken Sie auf Erstellen

    Diese Aktion gibt eine Benutzer-ID aus, die eine Benutzeridentität von Communication Services ist. Wenn Sie auf „Erweiterte Optionen anzeigen“ klicken und den Tokenbereich auswählen, gibt die Aktion außerdem ein Zugriffstoken und dessen Ablaufzeit mit dem angegebenen Bereich aus.

    Screenshot that shows the Azure Communication Services connector Create user action.

    Screenshot that shows the Azure Communication Services connector Create user action advanced options.

Ausgeben eines Benutzerzugriffstokens

Nachdem Sie eine Communication Services-Identität haben, können Sie mithilfe der Aktion „Benutzerzugriffstoken ausgeben“ ein Zugriffstoken ausgeben. In den folgenden Schritten wird Ihnen die Vorgehensweise erläutert:

  1. Fügen Sie eine neue Aktion hinzu, und geben Sie im Suchfeld den Suchbegriff „Communication Services Identity“ ein. Wählen Sie in der Aktionsliste die Aktion „Benutzerzugriffstoken ausgeben“ aus.

    Screenshot that shows the Azure Communication Services Identity connector Issue access token action.

  2. Anschließend können Sie die Benutzer-ID-Ausgabe aus dem vorhergehenden Schritt Benutzer erstellen verwenden.

  3. Geben Sie den Tokenbereich an: „VoIP“ oder „Chat“. Erfahren Sie mehr über Token und Authentifizierung.

    Screenshot that shows the Azure Communication Services Identity connector Issue access token action, specifying the token scope.

Dadurch wird ein Zugriffstoken und dessen Ablaufzeit mit dem angegebenen Bereich ausgegeben.

Widerrufen von Benutzerzugriffstoken

Nachdem Sie eine Communication Services-Identität haben, können Sie mithilfe der Aktion „Benutzerzugriffstoken ausgeben“ ein Zugriffstoken widerrufen. In den folgenden Schritten wird Ihnen die Vorgehensweise erläutert:

  1. Fügen Sie eine neue Aktion hinzu, und geben Sie im Suchfeld den Suchbegriff „Communication Services Identity“ ein. Wählen Sie in der Aktionsliste die Aktion „Benutzerzugriffstoken widerrufen“ aus.

    Screenshot that shows the Azure Communication Services Identity connector Revoke access token action.

  2. Angeben der Benutzer-ID

    Screenshot that shows the Azure Communication Services Identity connector Revoke access token action input.

Dadurch werden alle Benutzerzugriffstoken für den angegebenen Benutzer widerrufen. Bei dieser Aktion gibt es keine Ausgaben.

Löschen eines Benutzers

Nachdem Sie eine Communication Services-Identität haben, können Sie mithilfe der Aktion „Benutzerzugriffstoken ausgeben“ ein Zugriffstoken löschen. In den folgenden Schritten wird Ihnen die Vorgehensweise erläutert:

  1. Fügen Sie eine neue Aktion hinzu, und geben Sie im Suchfeld den Suchbegriff „Communication Services Identity“ ein. Wählen Sie in der Aktionsliste die Aktion „Benutzer löschen“ aus.

    Screenshot that shows the Azure Communication Services Identity connector Delete user action.

  2. Angeben der Benutzer-ID

    Screenshot that shows the Azure Communication Services Identity connector Delete user action input.

    Dadurch wird der Benutzer entfernt, und alle Benutzerzugriffstoken für den angegebenen Benutzer werden widerrufen. Bei dieser Aktion gibt es keine Ausgaben.

Testen Ihrer Logik-App

Wählen Sie auf der Symbolleiste des Designers die Option Ausführen aus, um Ihren Workflow manuell zu starten. Der Workflow sollte einen Benutzer erstellen, ein Zugriffstoken für ihn ausstellen, es dann entfernen und den Benutzer löschen. Weitere Informationen finden Sie im Abschnitt zum Ausführen Ihres Workflows. Sie können die Ausgaben dieser Aktionen überprüfen, nachdem der Workflow erfolgreich ausgeführt wurde.

Verwenden der Identität für Überwachung und Metriken

Die Benutzer-ID dient als Primärschlüssel für Protokolle und Metriken, die über Azure Monitor gesammelt werden. Für eine Ansicht aller Aufrufe eines bestimmten Benutzers können Sie Ihre Authentifizierung so einrichten, dass eine bestimmte Azure Communication Services-Identität (oder mehrere dieser Identitäten) einem einzelnen Benutzer zugeordnet wird.

Erfahren Sie mehr über Authentifizierungskonzepte, Aufrufdiagnosen mit Log Analytics und die für Sie verfügbaren Metriken.

Bereinigen von Ressourcen

Wenn Sie ein Communication Services-Abonnement bereinigen und entfernen möchten, löschen Sie die Ressource oder Ressourcengruppe. Wenn Sie eine Ressourcengruppe löschen, werden auch alle anderen Ressourcen gelöscht, die ihr zugeordnet sind. Weitere Informationen finden Sie im Abschnitt „Bereinigen von Ressourcen“ unter Erstellen und Verwalten Communication Services Ressourcen.

Wenn Sie Ihren Logik-App-Workflow und verwandte Ressourcen bereinigen möchten, lesen Sie die Informationen zum Bereinigen von Azure Logic Apps-Ressourcen.

Nächste Schritte

In diesem Schnellstart haben Sie gelernt, wie Sie mithilfe des Azure Communication Services Identity-Connectors einen Benutzer erstellen, ihn löschen, einem Benutzer ein Zugriffstoken ausstellen und das Benutzerzugriffstoken entfernen können. Weitere Informationen finden Sie in der Dokumentation zum Azure Communication Services Identity-Connector.

Wenn Sie sehen möchten, wie Token von anderen Connectors verwendet werden, lesen Sie Senden einer Chatnachricht von Power Automate mithilfe von Azure Communication Services.

Weitere Informationen zum Senden einer E-Mail mithilfe des Azure Communication Services Email-Connectors finden Sie unter Senden einer E-Mail-Nachricht in Power Automate mit Azure Communication Services.