Tworzenie tokenów dostępu dla użytkowników końcowych i zarządzanie nimi

Warning

Azure Communication Services wprowadza nowatorskie zmiany, a niektóre usługi są wycofywane. Dowiedz się więcej w przewodniku po zmianach emerytalnych i przełamowych.

Tokeny dostępu umożliwiają zestawom SDK usług Azure Communication Services uwierzytelnianie bezpośrednio w usługach Azure Communication Services jako konkretnej tożsamości. Musisz utworzyć tokeny dostępu dla użytkowników końcowych, jeśli chcesz, aby dołączyli do połączenia lub wątku czatu w aplikacji.

W tym artykule opisano sposób używania zestawów SDK usług Azure Communication Services do tworzenia tożsamości i zarządzania tokenami dostępu. W przypadku przypadków użycia w środowisku produkcyjnym zalecamy wygenerowanie tokenów dostępu w usłudze po stronie serwera zgodnie z opisem w temacie Architektura klienta i serwera.

Prerequisites

Konfigurowanie środowiska

Dodawanie rozszerzenia

Dodaj rozszerzenie Azure Communication Services dla Azure CLI za pomocą polecenia az extension.

az extension add --name communication

Zaloguj się do Azure CLI

Musisz zalogować się do interfejsu wiersza polecenia platformy Azure. Możesz się zalogować, uruchamiając w terminalu polecenie az login, a następnie wprowadzając swoje dane logowania.

(Opcjonalnie) Użyj operacji tożsamości w interfejsie wiersza polecenia platformy Azure bez przekazywania parametru połączenia

Możesz skonfigurować zmienną środowiskową AZURE_COMMUNICATION_CONNECTION_STRING, aby używać operacji tożsamości Azure CLI bez konieczności używania --connection_string do przekazywania parametrów połączenia. Aby skonfigurować zmienną środowiskową, otwórz okno konsoli i wybierz system operacyjny z poniższych kart. Zastąp <yourConnectionString> rzeczywistym ciągiem połączenia.

Otwórz okno konsoli i wprowadź następujące polecenie:

setx AZURE_COMMUNICATION_CONNECTION_STRING "<yourConnectionString>"

Po dodaniu zmiennej środowiskowej może być konieczne ponowne uruchomienie wszystkich uruchomionych programów, które muszą odczytać zmienną środowiskową, w tym okno konsoli. Jeśli na przykład używasz programu Visual Studio jako edytora, uruchom ponownie program Visual Studio przed uruchomieniem przykładu.

Przechowywanie tokenu dostępu w zmiennej środowiskowej

Aby skonfigurować zmienną środowiskową, otwórz okno konsoli i wybierz system operacyjny z poniższych kart. Zastąp <yourAccessToken> swoim rzeczywistym tokenem dostępu.

Otwórz okno konsoli i wprowadź następujące polecenie:

setx AZURE_COMMUNICATION_ACCESS_TOKEN "<yourAccessToken>"

Po dodaniu zmiennej środowiskowej może być konieczne ponowne uruchomienie wszystkich uruchomionych programów, które muszą odczytać zmienną środowiskową, w tym okno konsoli. Jeśli na przykład używasz programu Visual Studio jako edytora, uruchom ponownie program Visual Studio przed uruchomieniem przykładu.

Operations

Tworzenie tożsamości

Aby utworzyć tokeny dostępu, potrzebna jest tożsamość. W tym celu usługi Azure Communication Services utrzymują uproszczony katalog tożsamości. Użyj polecenia user create, aby utworzyć nowy wpis w katalogu z unikatowym identyfikatorem Id. Tożsamość jest później wymagana do wystawiania tokenów dostępu.

az communication identity user create --connection-string "<yourConnectionString>"
  • Zastąp <yourConnectionString> swoimi parametrami połączenia.

Tworzenie tożsamości i wystawianie tokenu dostępu w tym samym żądaniu

Uruchom następujące polecenie, aby utworzyć tożsamość usług komunikacyjnych i w tym samym czasie wydać token dostępu. Parametr scopes definiuje zestaw uprawnień i ról tokenu dostępu. Aby uzyskać więcej informacji, zobacz listę obsługiwanych akcji w temacie Uwierzytelnianie w usługach Azure Communication Services.

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

Wprowadź tę zmianę w kodzie:

  • Zastąp element <yourConnectionString> parametrami połączenia.

Wydaj token dostępu

Uruchom następujące polecenie, aby wygenerować token dostępu dla tożsamości usługi Communication Services. Parametr scopes definiuje zestaw uprawnień i ról tokenu dostępu. Aby uzyskać więcej informacji, zobacz listę obsługiwanych akcji w temacie Uwierzytelnianie w usługach Azure Communication Services.

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

Wprowadź tę zmianę w kodzie:

  • Zastąp element <yourConnectionString> parametrami połączenia.
  • Zastąp <userId> swoim userId.

Tokeny dostępu to krótkotrwałe poświadczenia, które muszą zostać ponownie wystawione. Niezrobienie tego może spowodować zakłócenia w korzystaniu z aplikacji przez użytkowników. Właściwość expires_on odpowiedzi wskazuje okres istnienia tokenu dostępu.

Wydanie tokenu dostępu z wieloma zakresami

Uruchom następujące polecenie, aby wygenerować token dostępu obejmujący wiele zakresów dla tożsamości usług Communication Services. Parametr scopes definiuje zestaw uprawnień i ról tokenu dostępu. Aby uzyskać więcej informacji, zobacz listę obsługiwanych akcji w modelu tożsamości.

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

Wprowadź tę zamianę w kodzie:

  • Zastąp element <yourConnectionString> parametrami połączenia.
  • Zastąp <userId> swoim identyfikatorem użytkownika.

Tokeny dostępu to krótkotrwałe poświadczenia, które muszą zostać ponownie wystawione. Niezrobienie tego może zakłócić komfort korzystania z aplikacji przez użytkowników. Właściwość expires_on odpowiedzi wskazuje okres istnienia tokenu dostępu.

Wymień token dostępu Microsoft Entra użytkownika aplikacji Teams na token dostępu tożsamości komunikacyjnej

token get-for-teams-user Użyj polecenia , aby wydać token dostępu dla użytkownika usługi Teams, który może być używany z zestawami SDK usług Azure Communication Services.

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

Wprowadź tę zamianę w kodzie:

  • Zastąp <yourConnectionString> swoimi parametrami połączenia.
  • Zastąp element <yourAadUser> swoim identyfikatorem użytkownika Microsoft Entra.
  • Zastąp element <yourAadApplication> identyfikatorem aplikacji Microsoft Entra.
  • Zastąp <yourAadToken> tokenem dostępu Microsoft Entra.

Odwoływanie tokenów dostępu

Może być konieczne jawne odwołanie tokenu dostępu. Można to zrobić na przykład wtedy, gdy użytkownicy aplikacji zmienią hasło, którego używają do uwierzytelniania w usłudze. Polecenie token revoke unieważnia wszystkie aktywne tokeny dostępu, które zostały wydane dla tej tożsamości.

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

Wprowadź tę zamianę w kodzie:

  • Zastąp <yourConnectionString> parametrami połączenia.
  • Zastąp <userId> swoim identyfikatorem użytkownika.

Usuwanie tożsamości

Usunięcie tożsamości powoduje odwołanie wszystkich aktywnych tokenów dostępu i uniemożliwienie dalszego wystawiania tokenów dostępu dla tożsamości. Spowoduje to również usunięcie całej utrwalonej zawartości skojarzonej z tożsamością.

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

Wprowadź tę zmianę w kodzie:

  • Zastąp <yourConnectionString> swoimi parametrami połączenia.
  • Zastąp <userId> swoim identyfikatorem użytkownika.

Prerequisites

Końcowy kod

Znajdź sfinalizowany kod w usłudze GitHub.

Konfigurowanie środowiska

Tworzenie nowej aplikacji w języku C#

  1. W oknie wiersza polecenia, takim jak cmd, PowerShell lub Bash, uruchom dotnet new polecenie , aby utworzyć nową aplikację konsolową o nazwie AccessTokensQuickstart. To polecenie tworzy prosty projekt Hello world C# z jednym plikiem Program.csźródłowym.

    dotnet new console -o AccessTokensQuickstart

  2. Zmień katalog na nowo utworzony folder aplikacji i użyj dotnet build polecenia , aby skompilować aplikację.

    cd AccessTokensQuickstart
dotnet build

    Zostaną wyświetlone proste Hello world dane wyjściowe. Jeśli konfiguracja działa prawidłowo, możesz rozpocząć pisanie kodu usług Azure Communication Services.

Instalowanie pakietu

Będąc nadal w katalogu aplikacji, zainstaluj pakiet biblioteki Azure Communication Services Identity dla platformy .NET za pomocą polecenia dotnet add package.

dotnet add package Azure.Communication.Identity

Konfigurowanie struktury aplikacji

W katalogu projektu wykonaj następujące kroki:

  1. Otwórz plik Program.cs w edytorze tekstów.
  2. Dodaj dyrektywę using , aby uwzględnić Azure.Communication.Identity przestrzeń nazw.
  3. Aby obsługiwać kod asynchroniczny, zaktualizuj deklarację Main metody.

Aby rozpocząć, uruchom następujący kod:

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

Uwierzytelnianie użytkownika

Zainicjuj CommunicationIdentityClient za pomocą swoich parametrów połączenia. Poniższy kod, który zostanie dodany do Main metody, pobiera parametry połączenia dla zasobu ze zmiennej środowiskowej o nazwie COMMUNICATION_SERVICES_CONNECTION_STRING.

Aby uzyskać więcej informacji, zobacz Tworzenie zasobów usługi Communication Services i zarządzanie nimi > Przechowywanie parametrów połączenia.

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

Alternatywnie możesz oddzielić punkt końcowy i klucz dostępu, uruchamiając następujący kod:

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

Jeśli masz już skonfigurowaną aplikację Microsoft Entra, możesz uwierzytelnić się przy użyciu Microsoft Entra ID.

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

Tworzenie tożsamości

Aby utworzyć tokeny dostępu, potrzebna jest tożsamość. W tym celu usługi Azure Communication Services utrzymują uproszczony katalog tożsamości. Użyj metody createUser, aby utworzyć nowy wpis w katalogu z unikatowym identyfikatorem Id. Użyj tej tożsamości później do generowania tokenów dostępu.

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

Przechowuj odebraną tożsamość w powiązaniu z użytkownikami aplikacji (na przykład zapisując ją w bazie danych serwera aplikacji).

(Wersja zapoznawcza) Tworzenie tożsamości za pomocą skojarzonego identyfikatora customId

Important

Ta funkcja jest dostępna od wersji 1.4.0-beta1zestawu SDK.

Note

Ta funkcja jest obecnie dostępna w wersji zapoznawczej.

Można utworzyć tożsamość związaną z customId, aby mapować tożsamości użytkowników aplikacji na tożsamości usług Azure Communication Services. Jeśli ponownie wywołasz metodę CreateUser z tym samym customId, zwróci to samo user.Id. Eliminuje to konieczność samodzielnego przechowywania mapowania.

Response<CommunicationUserIdentifier> user = await client.CreateUserAsync(customId: "alice@contoso.com");
Console.WriteLine($"\nCreated an identity with ID: {user.Id}");

(Wersja zapoznawcza) Uzyskaj szczegóły tożsamości

Important

Ta funkcja jest dostępna od wersji 1.4.0-beta1zestawu SDK.

Note

Ta funkcja jest obecnie dostępna w wersji zapoznawczej.

Możesz użyć GetUserDetail metody, aby pobrać informacje o użytkowniku, w tym customId i lastTokenIssuedAt.

Response<CommunicationUserIdentifier> user = await client.CreateUserAsync(customId: "alice@contoso.com");
var userDetails = client.GetUserDetail(user);
Console.WriteLine($"User ID: {userDetails.Id}");
Console.WriteLine($"Custom ID: {userDetails.CustomId}");
Console.WriteLine($"Last token issued at: {userDetails.LastTokenIssuedAt}");

Wystawianie tokenu dostępu

Po uzyskaniu tożsamości usługi Communication Services użyj metody GetToken, aby wydać token dostępu. Parametr scopes definiuje zestaw uprawnień i ról tokenu dostępu. Aby uzyskać więcej informacji, zobacz listę obsługiwanych akcji w modelu tożsamości. Możesz również utworzyć nowe wystąpienie communicationUser na podstawie ciągu reprezentującego tożsamość usługi Azure Communication Service.

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

Tokeny dostępu to krótkotrwałe poświadczenia, które muszą zostać ponownie wystawione. Niewykonanie tego może spowodować zakłócenia w korzystaniu z aplikacji przez użytkownika. Właściwość expiresOn wskazuje okres istnienia tokenu dostępu.

Ustawianie niestandardowego czasu wygaśnięcia tokenu

Domyślny czas wygaśnięcia tokenu wynosi 24 godziny, ale można go skonfigurować, podając wartość z zakresu od godziny do 24 godzin do opcjonalnego parametru tokenExpiresIn. Podczas żądania nowego tokenu określ oczekiwaną typową długość sesji komunikacji dla czasu wygaśnięcia tokenu.

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

Tworzenie tożsamości i wystawianie tokenu w tym samym żądaniu

Możesz użyć metody CreateUserAndTokenAsync, aby utworzyć tożsamość usług komunikacyjnych i jednocześnie wydać dla niej token dostępu. Parametr scopes definiuje zestaw uprawnień i ról tokenu dostępu. Aby uzyskać więcej informacji, zobacz listę obsługiwanych akcji w temacie Uwierzytelnianie w usługach 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);

(Wersja zapoznawcza) Tworzenie i identyfikacja oraz wystawienie tokenu w tym samym żądaniu przy użyciu identyfikatora niestandardowego

Important

Ta funkcja jest dostępna od wersji 1.4.0-beta1zestawu SDK.

Note

Ta funkcja jest obecnie dostępna w wersji zapoznawczej.

Identyfikator niestandardowy można przekazać do metody CreateUserAndTokenAsync w celu utworzenia tożsamości i wystawienia tokenu dostępu w jednym wywołaniu.

// Issue an identity and an access token with a validity of 24 hours and the "voip" scope for the new identity
Response<CommunicationUserIdentifierAndToken> identityAndTokenResponse = await client.CreateUserAndTokenAsync(customId: "bob@contoso.com", scopes: new[] { CommunicationTokenScope.VoIP });

// Retrieve the identity, token, and expiration date from the response
var identity = identityAndTokenResponse.User;
var token = identityAndTokenResponse.AccessToken.Token;
var expiresOn = identityAndTokenResponse.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);

Odświeżanie tokenu dostępu

Aby odświeżyć token dostępu, przekaż wystąpienie obiektu CommunicationUserIdentifier do GetTokenAsync. Jeśli zapisano ten Id i trzeba utworzyć nowy CommunicationUserIdentifier, można to zrobić, przekazując zapisany Id do konstruktora CommunicationUserIdentifier w następujący sposób:

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

Odwoływanie tokenów dostępu

Może być konieczne jawne odwołanie tokenu dostępu. Na przykład gdy użytkownicy aplikacji zmieniają hasło używane do uwierzytelniania w usłudze. Metoda RevokeTokensAsync unieważnia wszystkie aktywne tokeny dostępu, które zostały wydane dla tej tożsamości.

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

Usuwanie tożsamości

Usunięcie tożsamości powoduje odwołanie wszystkich aktywnych tokenów dostępu i uniemożliwia dalsze wydawanie tokenów dostępu dla tej tożsamości. Spowoduje to również usunięcie całej utrwalonej zawartości skojarzonej z tożsamością.

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

Uruchamianie kodu

Po zakończeniu tworzenia tokenu dostępu możesz uruchomić aplikację z katalogu aplikacji przy użyciu dotnet run polecenia .

dotnet run

Dane wyjściowe aplikacji opisują każdą ukończoną akcję:

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

Prerequisites

  • Konto platformy Azure z aktywną subskrypcją. Utwórz konto bezpłatnie.
  • Node.js Zalecane są wersje Active LTS i Maintenance LTS (zalecane wersje 8.11.1 i 10.14.1).
  • Aktywny zasób usług komunikacyjnych i parametry połączenia. Utwórz zasób usług komunikacyjnych.

Końcowy kod

Znajdź sfinalizowany kod w usłudze GitHub.

Konfigurowanie środowiska

Tworzenie nowej aplikacji Node.js

  1. W oknie terminalu lub wiersza polecenia utwórz nowy katalog dla aplikacji, a następnie otwórz go.

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

  2. Uruchom polecenie npm init -y , aby utworzyć package.json plik z ustawieniami domyślnymi.

    npm init -y

Instalowanie pakietu

Użyj polecenia , npm install aby zainstalować zestaw SDK tożsamości usług Azure Communication Services dla języka JavaScript.

npm install @azure/communication-identity@latest --save

Opcja --save wyświetla bibliotekę jako zależność w package.json pliku.

Konfigurowanie struktury aplikacji

  1. Utwórz plik o nazwie issue-access-token.js w katalogu projektu i dodaj następujący kod:

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

Uwierzytelnianie użytkownika

Utwórz instancję CommunicationIdentityClient za pomocą parametrów połączenia. Poniższy kod, który zostanie dodany do Main metody, pobiera parametry połączenia dla zasobu ze zmiennej środowiskowej o nazwie COMMUNICATION_SERVICES_CONNECTION_STRING.

Aby uzyskać więcej informacji, zobacz Tworzenie zasobów usługi Communication Services i zarządzanie nimi > Przechowywanie parametrów połączenia.

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

Alternatywnie możesz oddzielić punkt końcowy i klucz dostępu, uruchamiając następujący kod:

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

Jeśli masz już skonfigurowaną aplikację Microsoft Entra, możesz uwierzytelnić się przy użyciu Microsoft Entra ID.

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

Tworzenie tożsamości

Aby utworzyć tokeny dostępu, potrzebna jest tożsamość. W tym celu usługi Azure Communication Services utrzymują uproszczony katalog tożsamości. Użyj metody createUser, aby utworzyć nowy wpis w katalogu z unikatowym identyfikatorem Id. Tożsamość będzie potrzebna później, aby wystawiać tokeny dostępu.

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

Zapisz odebraną tożsamość w powiązaniu z użytkownikami aplikacji (na przykład zapisując ją w bazie danych serwera aplikacji).

(Wersja zapoznawcza) Tworzenie tożsamości ze skojarzonym identyfikatorem niestandardowym

Important

Ta funkcja jest dostępna od wersji 1.4.0-beta1zestawu SDK.

Note

Ta funkcja jest obecnie dostępna w wersji zapoznawczej.

Możesz utworzyć tożsamość z powiązanym customId, aby zmapować tożsamości użytkowników aplikacji na tożsamości usług Azure Communication Services. Kiedy wywołujesz createUser z tym samym customId, usługa zwraca ten sam communicationUserId. Eliminuje to konieczność samodzielnego przechowywania mapowania.

const customId = "alice@contoso.com";
let user = await identityClient.createUser({ customId });
console.log(`\nCreated an identity with ID: ${user.communicationUserId}`);

(Wersja zapoznawcza) Uzyskaj szczegóły tożsamości

Important

Ta funkcja jest dostępna od wersji 1.4.0-beta1zestawu SDK.

Note

Ta funkcja jest obecnie dostępna w wersji zapoznawczej.

Możesz użyć getUserDetail metody, aby pobrać informacje o użytkowniku, w tym customId i lastTokenIssuedAt.

const customId = "alice@contoso.com";
let user = await identityClient.createUser({ customId });
let userDetails = client.getUserDetail(user);
console.log(`\nUser ID: ${user.communicationUserId}`);
console.log(`\nCustom ID: ${userDetails.customId}`);
console.log(`\nLast token issued at: ${userDetails.lastTokenIssuedAt}`);

Wystawianie tokenu dostępu

Użyj metody getToken, aby wystawić token dostępu dla tożsamości Communication Services. Parametr scopes definiuje zestaw uprawnień i ról tokenu dostępu. Aby uzyskać więcej informacji, zobacz listę obsługiwanych akcji w modelu tożsamości. Możesz również utworzyć nowe wystąpienie obiektu communicationUser na podstawie reprezentacji ciągowej tożsamości usługi Azure Communication Services.

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

Tokeny dostępu to krótkotrwałe poświadczenia, które muszą zostać ponownie wystawione. Niewykonanie tego może spowodować zakłócenia w korzystaniu z aplikacji przez użytkownika. Właściwość expiresOn wskazuje okres istnienia tokenu dostępu.

Ustawianie niestandardowego czasu wygaśnięcia tokenu

Domyślny czas wygaśnięcia tokenu to 24 godziny (1440 minut), ale można go skonfigurować, podając wartość z zakresu od 60 minut do 1440 minut do opcjonalnego parametru tokenExpiresInMinutes. Podczas żądania nowego tokenu określ oczekiwaną typową długość sesji komunikacji dla czasu wygaśnięcia tokenu.

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

Tworzenie tożsamości i wystawianie tokenu w jednym wywołaniu metody

Możesz użyć metody createUserAndToken, aby utworzyć tożsamość usług komunikacyjnych i jednocześnie wydać dla niej token dostępu. Parametr scopes definiuje zestaw uprawnień i ról tokenu dostępu. Utwórz to w zakresie voip.

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

(Wersja zapoznawcza) Tworzenie tożsamości i wystawianie tokenu w jednym wywołaniu metody, w tym identyfikator customId

Important

Ta funkcja jest dostępna od wersji 1.4.0-beta1zestawu SDK.

Note

Ta funkcja jest obecnie dostępna w wersji zapoznawczej.

Identyfikator niestandardowy można przekazać do metody createUserAndToken w celu utworzenia tożsamości i wystawienia tokenu dostępu w jednym wywołaniu.

// Issue an identity and an access token with a validity of 24 hours and the "voip" scope for the new identity
const customId = "bob@contoso.com";
let identityTokenResponse = await identityClient.createUserAndToken(["voip"], { customId });

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

Odświeżanie tokenu dostępu

Po wygaśnięciu tokenów należy je odświeżyć. Aby odświeżyć tokeny, wywołaj ponownie getToken, używając tej samej tożsamości, która została użyta do wystawienia tokenów. Należy również podać scopes odświeżonych tokenów.

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

Odwoływanie tokenów dostępu

Może być konieczne odwołanie tokenu dostępu. Na przykład, gdy użytkownicy aplikacji zmieniają hasło używane do uwierzytelniania w usłudze. Metoda revokeTokens unieważnia wszystkie aktywne tokeny dostępu, które zostały wydane dla tej tożsamości.

await identityClient.revokeTokens(identityResponse);

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

Usuwanie tożsamości

Usunięcie tożsamości powoduje odwołanie wszystkich aktywnych tokenów dostępu i uniemożliwia dalsze wydawanie tokenów dostępu dla tej tożsamości. Spowoduje to również usunięcie całej utrwalonej zawartości skojarzonej z tożsamością.

await identityClient.deleteUser(identityResponse);

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

Uruchamianie kodu

W wierszu polecenia konsoli przejdź do katalogu zawierającego plik issue-access-token.js , a następnie wykonaj następujące node polecenie, aby uruchomić aplikację:

node ./issue-access-token.js

Dane wyjściowe aplikacji opisują każdą ukończoną akcję:

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

Prerequisites

Końcowy kod

Znajdź sfinalizowany kod w usłudze GitHub.

Konfigurowanie środowiska

Tworzenie nowej aplikacji w języku Python

  1. W oknie terminalu lub wiersza polecenia utwórz nowy katalog dla aplikacji, a następnie otwórz go.

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

  2. Użyj edytora tekstów, aby utworzyć plik o nazwie issue-access-tokens.py w katalogu głównym projektu. Następnie dodaj strukturę programu, w tym podstawową obsługę wyjątków. Do tego pliku zostanie dodany cały kod źródłowy.

    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)

Instalowanie pakietu

W katalogu aplikacji zainstaluj pakiet Azure Communication Services Identity SDK dla języka Python za pomocą polecenia pip install.

pip install azure-communication-identity

Uwierzytelnianie użytkownika

Utwórz obiekt CommunicationIdentityClient, używając parametrów połączenia. Poniższy kod, który zostanie dodany do try bloku, pobiera parametry połączenia dla zasobu ze zmiennej środowiskowej o nazwie COMMUNICATION_SERVICES_CONNECTION_STRING.

Aby uzyskać więcej informacji, zobacz Tworzenie zasobów usługi Communication Services i zarządzanie nimi > Przechowywanie parametrów połączenia.

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

Alternatywnie, jeśli masz już skonfigurowaną aplikację Microsoft Entra, możesz uwierzytelnić się za pomocą Microsoft Entra ID.

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

Tworzenie tożsamości

Aby utworzyć tokeny dostępu, potrzebna jest tożsamość. W tym celu usługi Azure Communication Services utrzymują uproszczony katalog tożsamości. Użyj metody create_user, aby utworzyć nowy wpis w katalogu z unikatowym identyfikatorem Id. Tożsamość jest później wymagana do wystawiania tokenów dostępu.

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

Przechowuj odebraną tożsamość w powiązaniu z użytkownikami aplikacji (na przykład zapisując ją w bazie danych serwera aplikacji).

Wystawianie tokenu dostępu

Użyj metody get_token, aby wystawić token dostępu dla tożsamości Communication Services. Parametr scopes definiuje zestaw uprawnień i ról tokenu dostępu. Aby uzyskać więcej informacji, zobacz listę obsługiwanych akcji w modelu tożsamości. Możesz również utworzyć nowe wystąpienie parametru CommunicationUserIdentifier na podstawie ciągu reprezentacji tożsamości usługi Azure Communication Service.

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

Tokeny dostępu to krótkotrwałe poświadczenia, które muszą zostać ponownie wystawione. Niewykonanie tego może spowodować zakłócenia w korzystaniu z aplikacji przez użytkownika. Właściwość expires_on odpowiedzi wskazuje okres istnienia tokenu dostępu.

Ustawianie niestandardowego czasu wygaśnięcia tokenu

Domyślny czas wygaśnięcia tokenu wynosi 24 godziny, ale można go skonfigurować, podając wartość z zakresu od godziny do 24 godzin do opcjonalnego parametru token_expires_in. Podczas żądania nowego tokenu określ oczekiwaną typową długość sesji komunikacji dla czasu wygaśnięcia tokenu.

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

Tworzenie tożsamości i wystawianie tokenu dostępu w tym samym żądaniu

Możesz użyć metody create_user_and_token, aby utworzyć tożsamość usług komunikacyjnych i jednocześnie wydać dla niej token dostępu. Parametr scopes definiuje zestaw uprawnień i ról tokenu dostępu. Aby uzyskać więcej informacji, zobacz listę obsługiwanych akcji w temacie Uwierzytelnianie w usługach 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)

Odświeżanie tokenu dostępu

Aby odświeżyć token dostępu, użyj obiektu CommunicationUserIdentifier, aby ponownie wydać token, przekazując istniejącą tożsamość:

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

Odwoływanie tokenów dostępu

Może być konieczne jawne odwołanie tokenu dostępu. Na przykład gdy użytkownicy aplikacji zmieniają hasło używane do uwierzytelniania w usłudze. Metoda revoke_tokens unieważnia wszystkie aktywne tokeny dostępu, które zostały wydane dla tej tożsamości.

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

Usuwanie tożsamości

Usunięcie tożsamości powoduje odwołanie wszystkich aktywnych tokenów dostępu i uniemożliwienie dalszego wystawiania tokenów dostępu dla tożsamości. Spowoduje to również usunięcie całej utrwalonej zawartości skojarzonej z tożsamością.

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

Uruchamianie kodu

W wierszu polecenia konsoli przejdź do katalogu zawierającego issue-access-tokens.py plik, a następnie wykonaj następujące python polecenie, aby uruchomić aplikację.

python ./issue-access-tokens.py

Wygenerowane dane wyjściowe opisują każdą ukończoną akcję:

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

Prerequisites

Końcowy kod

Znajdź sfinalizowany kod w usłudze GitHub.

Konfigurowanie środowiska

Tworzenie nowej aplikacji Java

W oknie terminalu lub wiersza polecenia przejdź do katalogu, w którym chcesz utworzyć aplikację Java. Aby wygenerować projekt Java na podstawie szablonu maven-archetype-quickstart, uruchom następujący kod:

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

Zwróć uwagę, że generate zadanie tworzy katalog o takiej samej nazwie jak artifactId. W tym katalogu src/main/java katalog zawiera kod źródłowy projektu, src/test/java katalog zawiera źródło testowe, a pom.xml plik jest projektem Project Object Model lub POM. Ten plik jest używany dla parametrów konfiguracji projektu.

Instalowanie pakietów usług Komunikacyjnych

pom.xml Otwórz plik w edytorze tekstów. Dodaj następujący element zależności do grupy zależności:

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

Ten kod powoduje, że Maven instaluje pakiet SDK Communication Services Identity, którego później użyjesz.

Konfigurowanie struktury aplikacji

W katalogu projektu wykonaj następujące kroki:

  1. Przejdź do /src/main/java/com/communication/quickstart katalogu.
  2. App.java Otwórz plik w edytorze.
  3. Zastąp instrukcję System.out.println("Hello world!");.
  4. Dodaj dyrektywy import.

Użyj następującego kodu, aby rozpocząć:

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

Uwierzytelnianie użytkownika

Utwórz obiekt CommunicationIdentityClient za pomocą klucza dostępu i punktu końcowego zasobu. Aby uzyskać więcej informacji, zobacz Tworzenie zasobów usługi Communication Services i zarządzanie nimi > Przechowywanie parametrów połączenia.

Można również zainicjować klienta przy użyciu dowolnego niestandardowego klienta HTTP, który implementuje com.azure.core.http.HttpClient interfejs.

W pliku App.java dodaj następujący kod do metody main:

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

Zamiast podawać punkt końcowy i klucz dostępu, możesz podać cały ciąg połączenia za pomocą metody connectionString().

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

Jeśli masz już skonfigurowaną aplikację Microsoft Entra, możesz uwierzytelnić się przy użyciu Microsoft Entra ID.

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

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

Tworzenie tożsamości

Aby utworzyć tokeny dostępu, potrzebna jest tożsamość. W tym celu usługi Azure Communication Services utrzymują uproszczony katalog tożsamości. Użyj metody createUser, aby utworzyć nowy wpis w katalogu z unikatowym identyfikatorem Id.

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

Utworzona tożsamość jest później wymagana do wystawiania tokenów dostępu. Zapisz odebraną tożsamość w powiązaniu z użytkownikami aplikacji (na przykład zapisując ją w bazie danych serwera aplikacji).

Wystawianie tokenu dostępu

Użyj metody getToken, aby wystawić token dostępu dla tożsamości Communication Services. Parametr scopes definiuje zestaw uprawnień i ról tokenu dostępu. Aby uzyskać więcej informacji, zobacz listę obsługiwanych akcji w modelu tożsamości.

W poniższym kodzie użyj zmiennej użytkownika utworzonej w poprzednim kroku, aby uzyskać token.

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

Tokeny dostępu to krótkotrwałe poświadczenia, które muszą zostać ponownie wystawione. Niewykonanie tego może spowodować zakłócenia w korzystaniu z aplikacji przez użytkownika. Właściwość expiresAt wskazuje okres istnienia tokenu dostępu.

Ustawianie niestandardowego czasu wygaśnięcia tokenu

Domyślny czas wygaśnięcia tokenu wynosi 24 godziny, ale można go skonfigurować, podając wartość z zakresu od godziny do 24 godzin do opcjonalnego parametru tokenExpiresIn. Podczas żądania nowego tokenu określ oczekiwaną typową długość sesji komunikacji dla czasu wygaśnięcia tokenu.

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

Tworzenie tożsamości i wystawianie tokenu w jednym żądaniu

Alternatywnie możesz użyć metody "createUserAndToken", aby utworzyć nowy wpis w katalogu z unikatowym Id i wystawiać token dostępu w tym samym czasie.

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

Odświeżanie tokenu dostępu

Aby odświeżyć token dostępu, użyj obiektu CommunicationUserIdentifier, aby ponownie go wydać:

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

Odwoływanie tokenu dostępu

Może być konieczne jawne odwołanie tokenu dostępu. Można to zrobić na przykład wtedy, gdy użytkownicy aplikacji zmienią hasło, którego używają do uwierzytelniania w usłudze. Metoda revokeTokens unieważnia wszystkie aktywne tokeny dostępu dla określonego użytkownika. W poniższym kodzie możesz użyć wcześniej utworzonego użytkownika.

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

Usuwanie tożsamości

Usunięcie tożsamości powoduje odwołanie wszystkich aktywnych tokenów dostępu i uniemożliwienie dalszego wystawiania tokenów dostępu dla tożsamości. Spowoduje to również usunięcie całej utrwalonej zawartości skojarzonej z tożsamością.

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

Uruchamianie kodu

  1. Przejdź do katalogu zawierającego pom.xml plik.

  2. Skompiluj projekt przy użyciu następującego mvn polecenia:

    mvn compile

  3. skompiluj pakiet:

    mvn package

  4. Uruchom następujące mvn polecenie, aby wykonać aplikację:

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

Dane wyjściowe opisują każdą ukończoną akcję:

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

Prerequisites

Tworzenie tokenów dostępu

  1. Na portalu Azure przejdź do bloku Tożsamości i tokeny dostępu użytkowników w zasobie usług komunikacyjnych.

  2. Wybierz zakres tokenów dostępu. Możesz wybrać brak, jedną lub wiele usług.

  3. Wybierz Generuj.

    Zrzut ekranu przedstawiający zakresy tożsamości i tokenów dostępu, w których wybierzesz pozycję Generuj.

    System generuje tożsamość i odpowiadający mu token dostępu użytkownika.

  4. Skopiuj te ciągi i użyj ich w przykładowych aplikacjach i innych scenariuszach testowania.

    Zrzut ekranu przedstawiający tokeny tożsamości i dostępu z datą wygaśnięcia

Prerequisites

Utwórz użytkownika

Dodaj nowy krok w przepływie pracy przy użyciu łącznika tożsamości usług Azure Communication Services. Wykonaj te kroki w usłudze Power Automate, otwierając przepływ usługi Power Automate w trybie edycji .

  1. Otwórz projektanta. W kroku, w którym chcesz dodać nową akcję, wybierz pozycję Nowy krok. Alternatywnie, aby dodać nową akcję między krokami, umieść kursor nad strzałką między tymi krokami, wybierz znak plus (+) i wybierz pozycję Dodaj akcję.

  2. W polu wyszukiwania „Wybierz operację” wpisz Communication Services Identity. Z listy akcji wybierz pozycję Utwórz użytkownika.

    Zrzut ekranu pokazujący akcję „Tworzenie użytkownika” łącznika Identity usługi Azure Communication Services.

  3. Podaj parametry połączenia. Można go znaleźć w witrynie Microsoft Azure Portal w ramach zasobu usługi Azure Communication Service. Wybierz opcję „Klucze” w menu w panelu po lewej stronie, aby wyświetlić ciąg połączenia.

    Zrzut ekranu przedstawiający stronę „Klucze” w zasobie Azure Communication Services.

  4. Podaj nazwę połączenia.

  5. Kliknij pozycję Utwórz

    Ta akcja generuje identyfikator użytkownika, który jest tożsamością użytkownika usług komunikacyjnych. Ponadto jeśli klikniesz pozycję Pokaż opcje zaawansowane i wybierzesz pozycję Zakres tokenu, akcja również generuje token dostępu i jego czas wygaśnięcia z określonym zakresem.

    Zrzut ekranu przedstawiający akcję „Utwórz użytkownika” w łączniku Azure Communication Services.

    Zrzut ekranu przedstawiający łącznik Azure Communication Services Create user action advanced options (Tworzenie zaawansowanych opcji akcji użytkownika).

Wystawianie tokenu dostępu użytkownika

Po utworzeniu tożsamości usług komunikacyjnych możesz wydać token dostępu. Zakończ poniższe kroki:

  1. Dodaj nową akcję i wpisz Communication Services Identity w polu wyszukiwania. Z listy akcji wybierz pozycję Wystawianie tokenu dostępu użytkownika.

    Zrzut ekranu przedstawiający akcję Wystawianie tokenu dostępu łącznika Identity usługi Azure Communication Services.

  2. Teraz możesz użyć danych wyjściowych identyfikatora użytkownika z poprzedniego kroku Tworzenie użytkownika .

  3. Określ zakres tokenu: VoIP lub czat. Dowiedz się więcej o tokenach i uwierzytelnianiu.

    Zrzut ekranu przedstawiający akcję Wydaj token dostępu w łączniku tożsamości Azure Communication Services z określonym zakresem tokenu.

System generuje token dostępu i jego czas wygaśnięcia z określonym zakresem.

Odwoływanie tokenów dostępu użytkowników

Po uzyskaniu tożsamości usługi Communication Services możesz użyć akcji Wydaj token dostępu użytkownika, aby unieważnić token dostępu. Wykonaj następujące kroki:

  1. Dodaj nową akcję i wpisz Communication Services Identity w polu wyszukiwania. Z listy akcji wybierz pozycję Odwołaj tokeny dostępu użytkownika.

    Zrzut ekranu przedstawiający akcję „Odwołaj token dostępu” łącznika Identity usługi Azure Communication Services.

  2. Określ identyfikator użytkownika.

    Zrzut ekranu przedstawiający dane wejściowe akcji Unieważnianie tokenu dostępu w łączniku tożsamości usługi Azure Communication Services.

System odwołuje wszystkie tokeny dostępu użytkownika dla określonego użytkownika. Nie ma żadnych danych wyjściowych dla tej akcji.

Usuwanie użytkownika

Po utworzeniu tożsamości usług komunikacyjnych możesz użyć akcji Wystawianie tokenu dostępu użytkownika w celu usunięcia tokenu dostępu. Zakończ poniższe kroki:

  1. Dodaj nową akcję i wprowadź Communication Services Identity w polu wyszukiwania. Z listy akcji wybierz pozycję Usuń użytkownika.

    Zrzut ekranu przedstawiający akcję Usuń użytkownika łącznika tożsamości usług Azure Communication Services.

  2. Określ identyfikator użytkownika.

    Zrzut ekranu przedstawiający łącznik tożsamości usług Azure Communication Services Usuń dane wejściowe akcji użytkownika.

System usuwa użytkownika i odwołuje wszystkie tokeny dostępu użytkownika dla określonego użytkownika. Nie ma żadnych danych wyjściowych dla tej akcji.

Testowanie aplikacji logiki

Aby ręcznie uruchomić przepływ pracy, na pasku narzędzi projektanta wybierz pozycję Uruchom. Przepływ tworzy użytkownika, wydaje dla niego token dostępu, a następnie usuwa token i usuwa użytkownika.

Aby uzyskać więcej informacji, zobacz , jak uruchomić przepływ pracy. Dane wyjściowe tych akcji można sprawdzić po pomyślnym uruchomieniu przepływu pracy.

Używanie tożsamości do monitorowania i metryk

Identyfikator użytkownika działa jako klucz podstawowy dla dzienników i metryk zebranych za pośrednictwem usługi Azure Monitor. Aby na przykład wyświetlić wszystkie połączenia użytkownika, możesz skonfigurować uwierzytelnianie tak, aby przypisać określoną tożsamość usługi Azure Communication Services (lub tożsamości) do jednego użytkownika.

Aby uzyskać więcej informacji, zobacz:

Czyszczenie zasobów

Aby wyczyścić i usunąć subskrypcję usług Komunikacyjnych, usuń zasób lub grupę zasobów. Usunięcie grupy zasobów powoduje również usunięcie wszelkich innych skojarzonych z nią zasobów. Aby uzyskać więcej informacji, zobacz Tworzenie zasobów usług Communication Services i zarządzanie nimi > Czyszczenie zasobów.

Aby usunąć przepływ pracy aplikacji logiki i powiązane zasoby, zobacz Tworzenie przykładowego przepływu pracy aplikacji logiki Consumption przy użyciu portalu Azure > Czyszczenie zasobów.

Dalsze kroki

W tym artykule opisano sposób tworzenia użytkownika i usuwania użytkownika. Opisano również sposób wystawiania tokenu dostępu użytkownikowi i usuwania tokenu dostępu użytkownika przy użyciu łącznika tożsamości usług Azure Communication Services. Aby uzyskać więcej informacji, zobacz Łącznik tożsamości usług Azure Communication Services.

Aby zobaczyć, jak tokeny są używane przez inne łączniki, zobacz jak wysłać wiadomość na czacie z poziomu Power Automate przy użyciu Azure Communication Services.

Aby dowiedzieć się więcej na temat wysyłania wiadomości e-mail przy użyciu łącznika poczty e-mail usług Azure Communication Services, zobacz Wysyłanie wiadomości e-mail w usłudze Power Automate za pomocą usług Azure Communication Services.

  • Ostatnia aktualizacja o