クイック スタート:アクセス トークンを作成して管理する

アクセス トークンを使用すると、Azure Communication Services SDK は、特定の ID として、Azure Communication Services に対して直接認証を行うことができます。 ユーザーがアプリケーション内の通話またはチャット スレッドに参加できるようにする場合は、アクセス トークンを作成する必要があります。

このクイックスタートでは、Azure Communication Services SDK を使用してアイデンティティを作成し、アクセス トークンを管理する方法を学びます。 運用環境のユースケースでは、サーバーサイドのサービス でアクセス トークンを生成することをお勧めします。

前提条件

設定

拡張機能の追加

az extension コマンドを使用して、Azure CLI の Azure Communication Services 拡張機能を追加します。

az extension add --name communication

Azure CLI へのサインイン

Azure CLI にサインインする必要があります。 ターミナルから az login コマンドを実行し、資格情報を入力してサインインできます。

(省略可能) 接続文字列を渡さずに Azure CLI の ID 操作を使用する

--connection_string を使用して接続文字列を渡すことなく Azure CLI の ID 操作を使用するために、AZURE_COMMUNICATION_CONNECTION_STRING 環境変数を構成できます。 環境変数を構成するには、コンソール ウィンドウを開き、以下のタブからお使いのオペレーティン グシステムを選択します。 <yourConnectionString> は、実際の接続文字列に置き換えてください。

コンソール ウィンドウを開き、次のコマンドを入力します。

setx AZURE_COMMUNICATION_CONNECTION_STRING "<yourConnectionString>"

実行中のプログラムのうち、環境変数の読み取りを必要とするプログラム (コンソール ウィンドウを含む) については、環境変数を追加した後で再起動が必要となる場合があります。 たとえば、Visual Studio をエディターとして使用している場合、サンプルを実行する前に Visual Studio を再起動します。

環境変数にアクセス トークンを格納する

環境変数を構成するには、コンソール ウィンドウを開き、以下のタブからお使いのオペレーティン グシステムを選択します。 <yourAccessToken> は、実際のアクセス トークンに置き換えてください。

コンソール ウィンドウを開き、次のコマンドを入力します。

setx AZURE_COMMUNICATION_ACCESS_TOKEN "<yourAccessToken>"

実行中のプログラムのうち、環境変数の読み取りを必要とするプログラム (コンソール ウィンドウを含む) については、環境変数を追加した後で再起動が必要となる場合があります。 たとえば、Visual Studio をエディターとして使用している場合、サンプルを実行する前に Visual Studio を再起動します。

操作

ID の作成

アクセス トークンを作成するには、ID が必要です。 Azure Communication Services では、軽量の ID ディレクトリが保持されます。 user create コマンドを使用して、一意の Id を持つディレクトリに新しいエントリを作成します。 ID は、後でアクセス トークンを発行するのに必要になります。

az communication identity user create --connection-string "<yourConnectionString>"
  • <yourConnectionString> を対象の接続文字列に置き換えてください。

ID を作成し、同じ要求内でアクセス トークンを発行する

次のコマンドを実行して、Communication Services ID を作成し、同時にそのアクセス トークンを発行します。 scopes パラメーターは、アクセス トークンのアクセス許可とロールのセットを定義します。 詳細は、「Azure Communication Services への認証」でサポートされているアクションの一覧を参照してください。

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

コードで次の置き換えを行います。

  • <yourConnectionString> を対象の接続文字列に置き換えてください。

アクセス トークンの発行

次のコマンドを実行して、Communication Services ID のアクセス トークンを発行します。 scopes パラメーターは、アクセス トークンのアクセス許可とロールのセットを定義します。 詳細は、「Azure Communication Services への認証」でサポートされているアクションの一覧を参照してください。

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

コードで次の置き換えを行います。

  • <yourConnectionString> を対象の接続文字列に置き換えてください。
  • <userId> を対象のユーザー ID に置き換えてください。

アクセス トークンは有効期間の短い資格情報であるため、再発行が必要になります。 そうしなければ、アプリケーションのユーザーの利便性が損なわれる可能性があります。 expires_on 応答プロパティは、アクセス トークンの有効期間を示します。

複数のスコープを持つアクセス トークンを発行する

次のコマンドを実行して、Communication Services ID の複数のスコープを持つアクセス トークンを発行します。 scopes パラメーターは、アクセス トークンのアクセス許可とロールのセットを定義します。 詳細については、「ID モデル」のサポートされるアクションの一覧を参照してください。

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

コードで次の置き換えを行います。

  • <yourConnectionString> を対象の接続文字列に置き換えてください。
  • <userId> を対象のユーザー ID に置き換えてください。

アクセス トークンは有効期間の短い資格情報であるため、再発行が必要になります。 そうしなければ、アプリケーションのユーザーの利便性が損なわれる可能性があります。 expires_on 応答プロパティは、アクセス トークンの有効期間を示します。

Teams ユーザーの Azure AD アクセス トークンを通信 ID アクセス トークンに置き換える

token get-for-teams-user コマンドを使用して、Azure Communication Services SDK で使用できる Teams ユーザーのアクセス トークンを発行します。

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

コードで次の置き換えを行います。

  • <yourConnectionString> を対象の接続文字列に置き換えてください。
  • <yourAadUser> を Azure Active Directory のユーザー ID に置き換えます。
  • <yourAadApplication> を Azure Active Directory のアプリケーション ID に置き換えます。
  • <yourAadToken> を Azure Active Directory のアクセス トークンに置き換えます。

アクセス トークンの取り消し

場合によっては、アクセス トークンを明示的に失効させる必要があるかもしれません。 例えば、アプリケーションのユーザーがサービスの認証に使用するパスワードを変更した場合などに行います。 token revoke コマンドを使用すると、ID に対して発行されたすべてのアクティブなアクセス トークンを無効にできます。

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

コードで次の置き換えを行います。

  • <yourConnectionString> を対象の接続文字列に置き換えてください。
  • <userId> を対象のユーザー ID に置き換えてください。

ID の削除

ID を削除すると、有効なアクセス トークンがすべて取り消され、その ID に対するアクセス トークンが今後発行されなくなります。 これを行うと、その ID に関連するすべてのパーシステッドコンテンツも削除されます。

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

コードで次の置き換えを行います。

  • <yourConnectionString> を対象の接続文字列に置き換えてください。
  • <userId> を対象のユーザー ID に置き換えてください。

前提条件

最終的なコード

このクイックスタートの最終的なコードは GitHub にあります。

環境を設定する

新しい C# アプリケーションを作成する

コマンド プロンプト ウィンドウで、cmd、PowerShell、Bash などのコンソール ウィンドウで dotnet new コマンドを実行して、新しいコンソール アプリを AccessTokensQuickstart という名前で作成します。 このコマンドにより、1 つのソース ファイル (Program.cs) を含む単純な "Hello World" C# プロジェクトが作成されます。

dotnet new console -o AccessTokensQuickstart

ディレクトリを、新しく作成したアプリ フォルダーに変更し、dotnet build コマンドを使用して自分のアプリケーションをコンパイルします。

cd AccessTokensQuickstart
dotnet build

簡単な "Hello World" 出力が表示されます。 そうであれば、セットアップは正しく機能しているので、Azure Communication Services 固有のコードを書き始めることができます。

パッケージをインストールする

まだアプリケーション ディレクトリにいる間に、dotnet add package コマンドを使用して、.NET 用の Azure Communication Services ID ライブラリ パッケージをインストールします。

dotnet add package Azure.Communication.Identity --version 1.0.0

アプリのフレームワークを設定する

プロジェクト ディレクトリから、次の操作を行います。

  1. テキスト エディターで Program.cs ファイルを開きます。
  2. using ディレクティブを追加して、Azure.Communication.Identity 名前空間を含めます。
  3. 非同期コードをサポートするように Main メソッドの宣言を更新します。

開始するには、次のコードを実行します。

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

クライアントを認証する

接続文字列を使用して CommunicationIdentityClient を初期化します。 Main メソッドに追加した次のコードは、COMMUNICATION_SERVICES_CONNECTION_STRING という名前の環境変数からリソースの接続文字列を取得します。

詳細については、「Communication Services リソースの作成と管理」の「接続文字列を保存する」セクションを参照してください。

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

また、以下のコードを実行することで、エンドポイントとアクセスキーを分離することができます。

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

Azure Active Directory (Azure AD) アプリケーションを既にセットアップしている場合は、Azure AD を使用して認証できます。

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

ID の作成

アクセス トークンを作成するには、ID が必要です。 Azure Communication Services では、軽量の ID ディレクトリが保持されます。 createUser メソッドを使用して、一意の Id を持つディレクトリに新しいエントリを作成します。 ID は、後でアクセス トークンを発行するのに必要になります。

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

受信した ID をアプリケーションのユーザーにマッピングして保存します (例えば、アプリケーション サーバーのデータベースに保存します)。

アクセス トークンを発行する

Communication Services の ID を取得したら、GetToken メソッドを使用してその ID 用のアクセストークンを発行します。 scopes パラメーターは、アクセス トークンのアクセス許可とロールのセットを定義します。 詳細については、「ID モデル」のサポートされるアクションの一覧を参照してください。 また、Azure Communication Service の ID の文字列表現に基づいて、communicationUser の新しいインスタンスを構築することもできます。

// Issue an access token with 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;

// Write the token details to the screen
Console.WriteLine($"\nIssued an access token with 'voip' scope that expires at {expiresOn}:");
Console.WriteLine(token);

アクセス トークンは有効期間の短い資格情報であるため、再発行が必要になります。 そうしなければ、アプリケーションのユーザーの利便性が損なわれる可能性があります。 expiresOn プロパティは、アクセス トークンの有効期間を示します。

同じ要求で id を作成し、トークンを発行する

CreateUserAndTokenAsync メソッドを使用して、Communication Services ID を作成し、同時にそのアクセス トークンを発行します。 scopes パラメーターは、アクセス トークンのアクセス許可とロールのセットを定義します。 詳細は、「Azure Communication Services への認証」でサポートされているアクションの一覧を参照してください。

// Issue an identity and an access token with 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;

// Print the details to the screen
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);

アクセス トークンの更新

アクセス トークンを更新するには、CommunicationUserIdentifier オブジェクトのインスタンスを GetTokenAsync に渡します。 この Id を保存済みであり、新しい CommunicationUserIdentifier を作成する必要がある場合、これを行うには、次のように保存済みの IdCommunicationUserIdentifier コンストラクターに渡します。

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

アクセス トークンの取り消し

場合によっては、アクセス トークンを明示的に失効させる必要があるかもしれません。 例えば、アプリケーションのユーザーがサービスの認証に使用するパスワードを変更した場合などに行います。 RevokeTokensAsync メソッドを使用すると、ID に対して発行されたすべてのアクティブなアクセス トークンを無効にできます。

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

ID の削除

ID を削除すると、有効なアクセス トークンがすべて取り消され、その ID に対するアクセス トークンが今後発行されなくなります。 これを行うと、その ID に関連するすべてのパーシステッドコンテンツも削除されます。

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

コードの実行

アクセス トークンの作成が完了したら、アプリケーション ディレクトリから dotnet run コマンドを使ってアプリケーションを実行します。

dotnet run

アプリの出力には、完了した各アクションが表示されます。

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 30/03/21 08:09 09 AM:
<token signature here>

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 30/03/21 08:09 09 AM:
<token signature here>

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

前提条件

最終的なコード

このクイックスタートの最終的なコードは GitHub にあります。

環境を設定する

新しい Node.js アプリケーションを作成する

ターミナルまたはコマンドプロンプトウィンドウで、アプリ用の新しいディレクトリを作成し、それを開きます。

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

既定の設定で npm init -y を実行して、package.json ファイルを作成します。

npm init -y

パッケージをインストールする

npm install コマンドを使用して、JavaScript 用の Azure Communication Services Identity SDK をインストールします。

npm install @azure/communication-identity --save

--save オプションを使用すると、package.json ファイル内の依存関係としてライブラリが表示されます。

アプリのフレームワークを設定する

  1. プロジェクト ディレクトリに issue-access-token.js という名前のファイルを作成し、次のコードを追加します。

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

クライアントを認証する

接続文字列を使用して CommunicationIdentityClient をインスタンス化します。 Main メソッドに追加した次のコードは、COMMUNICATION_SERVICES_CONNECTION_STRING という名前の環境変数からリソースの接続文字列を取得します。

詳細については、「Communication Services リソースの作成と管理」の「接続文字列を保存する」セクションを参照してください。

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

また、以下のコードを実行することで、エンドポイントとアクセスキーを分離することができます。

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

Azure Active Directory (Azure AD) アプリケーションを既にセットアップしている場合は、Azure AD を使用して認証できます。

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

ID の作成

アクセス トークンを作成するには、ID が必要です。 Azure Communication Services では、軽量の ID ディレクトリが保持されます。 createUser メソッドを使用して、一意の Id を持つディレクトリに新しいエントリを作成します。 ID は、後でアクセス トークンを発行するのに必要になります。

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

受信した ID をアプリケーションのユーザーにマッピングして保存します (例えば、アプリケーション サーバーのデータベースに保存します)。

アクセス トークンを発行する

getToken メソッドを使用して、Communication Services の ID のアクセストークンを発行します。 scopes パラメーターは、アクセス トークンのアクセス許可とロールのセットを定義します。 詳細については、「ID モデル」のサポートされるアクションの一覧を参照してください。 また、Azure Communication Service の ID の文字列表現に基づいて、communicationUser の新しいインスタンスを構築することもできます。

// Issue an access token with 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;

// Print the expiration date and token to the screen
console.log(`\nIssued an access token with 'voip' scope that expires at ${expiresOn}:`);
console.log(token);

アクセス トークンは有効期間の短い資格情報であるため、再発行が必要になります。 そうしなければ、アプリケーションのユーザーの利便性が損なわれる可能性があります。 expiresOn プロパティは、アクセス トークンの有効期間を示します。

ID を作成し、1 つのメソッド呼び出しでトークンを発行する

createUserAndToken メソッドを使用して、Communication Services ID を作成し、同時にそのアクセス トークンを発行します。 scopes パラメーターは、アクセス トークンのアクセス許可とロールのセットを定義します。 ここでも、voip スコープで作成します。

// Issue an identity and an access token with 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;

// print these details to the screen
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);

アクセス トークンの更新

トークンは有効期限が切れるので、定期的に更新する必要があります。 更新は、トークンの発行に使用したものと同じ ID を使用して getToken を再度呼び出すだけで簡単に行うことができます。 更新されるトークンの scopes を指定する必要があります。

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

アクセス トークンの取り消し

アクセス トークンを失効させる必要がある場合もあります。 例えば、アプリケーションのユーザーがサービスの認証に使用するパスワードを変更した場合などに行います。 revokeTokens メソッドを使用すると、ID に対して発行されたすべてのアクティブなアクセス トークンを無効にできます。

await identityClient.revokeTokens(identityResponse);

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

ID の削除

ID を削除すると、有効なアクセス トークンがすべて取り消され、その ID に対するアクセス トークンが今後発行されなくなります。 これを行うと、その ID に関連するすべてのパーシステッドコンテンツも削除されます。

await identityClient.deleteUser(identityResponse);

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

コードの実行

コンソール プロンプトから、issue-access-token.js ファイルのあるディレクトリに移動し、以下の node コマンドを実行してアプリを実行します。

node ./issue-access-token.js

アプリの出力には、完了した各アクションが表示されます。

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 30/03/21 08:09 09 AM:
<token signature here>

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 30/03/21 08:09 09 AM:
<token signature here>

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

前提条件

最終的なコード

このクイックスタートの最終的なコードは GitHub にあります。

環境を設定する

新しい Python アプリケーションを作成する

  1. ターミナルまたはコマンド プロンプト ウィンドウで、アプリ用の新しいディレクトリを作成し、それを開きます。

    mkdir access-tokens-quickstart && cd access-tokens-quickstart
    
  2. テキスト エディターを使用して、issue-access-tokens.py という名前のファイルをプロジェクトのルート ディレクトリに作成し、基本的な例外処理を含むプログラムの構造を追加します。 このクイックスタートのすべてのソースコードを、この後のセクションでこのファイルに追加します。

    import os
    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)
    

パッケージをインストールする

引き続きアプリケーション ディレクトリで、pip install コマンドを使用して、Python 用の Azure Communication Services ID SDK パッケージをインストールします。

pip install azure-communication-identity

クライアントを認証する

接続文字列を使用して CommunicationIdentityClient をインスタンス化します。 try ブロックに追加した次のコードは、COMMUNICATION_SERVICES_CONNECTION_STRING という名前の環境変数からリソースの接続文字列を取得します。

詳細については、「Communication Services リソースの作成と管理」の「接続文字列を保存する」セクションを参照してください。

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

あるいは、Azure Active Directory (Azure AD) アプリケーションを既にセットアップしている場合は、Azure AD を使用して認証できます。

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

ID の作成

アクセス トークンを作成するには、ID が必要です。 Azure Communication Services では、軽量の ID ディレクトリが保持されます。 create_user メソッドを使用して、一意の Id を持つディレクトリに新しいエントリを作成します。 ID は、後でアクセス トークンを発行するのに必要になります。

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

受信した ID をアプリケーションのユーザーにマッピングして保存します (例えば、アプリケーション サーバーのデータベースに保存します)。

アクセス トークンを発行する

get_token メソッドを使用して、Communication Services の ID のアクセストークンを発行します。 scopes パラメーターは、アクセス トークンのアクセス許可とロールのセットを定義します。 詳細については、「ID モデル」のサポートされるアクションの一覧を参照してください。 また、Azure Communication Service のアイデンティティの文字列表現に基づいて、パラメーター CommunicationUserIdentifier の新しいインスタンスを構築することもできます。

# Issue an access token with the "voip" scope for an identity
token_result = client.get_token(identity, ["voip"])
expires_on = token_result.expires_on.strftime("%d/%m/%y %I:%M %S %p")

# Print the details to the screen
print("\nIssued an access token with 'voip' scope that expires at " + expires_on + ":")
print(token_result.token)

アクセス トークンは有効期間の短い資格情報であるため、再発行が必要になります。 そうしなければ、アプリケーションのユーザーの利便性が損なわれる可能性があります。 expires_on 応答プロパティは、アクセス トークンの有効期間を示します。

ID を作成し、同じ要求内でアクセス トークンを発行する

create_user_and_token メソッドを使用して、Communication Services ID を作成し、同時にそのアクセス トークンを発行します。 scopes パラメーターは、アクセス トークンのアクセス許可とロールのセットを定義します。 詳細は、「Azure Communication Services への認証」でサポートされているアクションの一覧を参照してください。

# Issue an identity and an access token with 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.strftime("%d/%m/%y %I:%M %S %p")

# Print the details to the screen
print("\nCreated an identity with ID: " + identity.properties['id'])
print("\nIssued an access token with 'voip' scope that expires at " + expires_on + ":")
print(token)

アクセス トークンの更新

アクセス トークンを更新するには、CommunicationUserIdentifier オブジェクトを使用し、既存の ID を渡してトークンを再発行します。

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

アクセス トークンの取り消し

場合によっては、アクセス トークンを明示的に失効させる必要があるかもしれません。 例えば、アプリケーションのユーザーがサービスの認証に使用するパスワードを変更した場合などに行います。 revoke_tokens メソッドを使用すると、ID に対して発行されたすべてのアクティブなアクセス トークンを無効にできます。

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

ID の削除

ID を削除すると、有効なアクセス トークンがすべて取り消され、その ID に対するアクセス トークンが今後発行されなくなります。 これを行うと、その ID に関連するすべてのパーシステッドコンテンツも削除されます。

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

コードの実行

コンソール プロンプトから、issue-access-tokens.py ファイルのあるディレクトリに移動し、以下の python コマンドを実行してアプリを実行します。

python ./issue-access-tokens.py

アプリの出力には、完了した各アクションが表示されます。

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 30/03/21 08:09 09 AM:
<token signature here>

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 30/03/21 08:09 09 AM:
<token signature here>

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

前提条件

最終的なコード

このクイックスタートの最終的なコードは GitHub にあります。

環境を設定する

新しい Java アプリケーションを作成する

ターミナルまたはコマンド プロンプト ウィンドウで、Java アプリケーションを作成するディレクトリに移動します。 maven-archetype-quickstart テンプレートから Java プロジェクトを生成するには、以下のコードを実行します。

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

generate タスクが artifactId と同じ名前のディレクトリを作成していることがわかります。 このディレクトリの下の src/main/java ディレクトリにはプロジェクトのソース コードが、src/test/java ディレクトリにはテスト ソースがそれぞれ含まれており、pom.xml ファイルはプロジェクトのプロジェクト オブジェクト モデル (POM) です。 このファイルは、プロジェクトの構成パラメーターに使用されます。

Communication Services パッケージをインストールする

テキスト エディターで pom.xml ファイルを開きます。 依存関係のグループに、次の dependency 要素を追加します。

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-communication-identity</artifactId>
    <version>1.1.1</version>
</dependency>

このコードは、後に使用する Communication Services Identity SDK をインストールするように Maven に指示しています。

アプリのフレームワークを設定する

プロジェクト ディレクトリから、次の操作を行います。

  1. /src/main/java/com/communication/quickstart ディレクトリに移動します
  2. 使用しているエディターで App.java ファイルを開きます
  3. System.out.println("Hello world!"); ステートメントを置き換えます
  4. import ディレクティブを追加します。

次のコードを使用して開始します。

package com.communication.quickstart;

import com.azure.communication.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
    }
}

クライアントを認証する

リソースのアクセス キーとエンドポイントを使用して、CommunicationIdentityClient をインスタンス化します。 詳細については、「Communication Services リソースの作成と管理」の「接続文字列を保存する」セクションを参照してください。

さらに、クライアントは、com.azure.core.http.HttpClient インターフェイスを実装する任意のカスタム HTTP クライアントを使用して初期化できます。

App.java ファイルで、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();

エンドポイントとアクセス キーを指定する代わりに、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();

Azure Active Directory (Azure AD) アプリケーションを既にセットアップしている場合は、Azure AD を使用して認証できます。

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

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

ID の作成

アクセス トークンを作成するには、ID が必要です。 Azure Communication Services では、軽量の ID ディレクトリが保持されます。 createUser メソッドを使用して、一意の Id を持つディレクトリに新しいエントリを作成します。

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

作成した ID は、後でアクセス トークンを発行するのに必要になります。 受信した ID をアプリケーションのユーザーにマッピングして保存します (例えば、アプリケーション サーバーのデータベースに保存します)。

アクセス トークンを発行する

getToken メソッドを使用して、Communication Services の ID のアクセストークンを発行します。 scopes パラメーターは、アクセス トークンのアクセス許可とロールのセットを定義します。 詳細については、「ID モデル」のサポートされるアクションの一覧を参照してください。

次のコードでは、前のステップで作成したユーザー変数を使って、トークンを取得します。

// Issue an access token with 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);

1 つの要求で ID を作成し、トークンを発行する

また、'createUserAndToken' メソッドを使って、ディレクトリに一意の Id で新しいエントリを作成し、同時にアクセストークンを発行することもできます。

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

アクセス トークンは有効期間の短い資格情報であるため、再発行が必要になります。 そうしなければ、アプリケーションのユーザーの利便性が損なわれる可能性があります。 expiresAt プロパティは、アクセス トークンの有効期間を示します。

アクセス トークンの更新

アクセス トークンを更新するには、CommunicationUserIdentifier オブジェクトを使用して再発行します。

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

アクセス トークンを取り消す

場合によっては、アクセス トークンを明示的に失効させる必要があるかもしれません。 例えば、アプリケーションのユーザーがサービスの認証に使用するパスワードを変更した場合などに行います。 revokeTokens メソッドを使用すると、特定のユーザーのすべてのアクティブなアクセス トークンを無効にできます。 以下のコードでは、以前に作成したユーザーを使用しています。

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

ID の削除

ID を削除すると、有効なアクセス トークンがすべて取り消され、その ID に対するアクセス トークンが今後発行されなくなります。 これを行うと、その ID に関連するすべてのパーシステッドコンテンツも削除されます。

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

コードの実行

pom.xml ファイルのあるディレクトリに移動し、以下の mvn コマンドでプロジェクトをコンパイルします。

mvn compile

次に、パッケージをビルドします

mvn package

次の mvn コマンドを実行して、アプリを実行します。

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

アプリの出力には、完了した各アクションが表示されます。

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 30/03/21 08:09 09 AM:
<token signature here>

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 30/03/21 08:09 09 AM:
<token signature here>

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

監視とメトリックに ID を使用する

ユーザー ID は、Azure Monitor によって収集されるログとメトリックのプライマリ キーとして機能することを目的としています。 たとえば、特定のユーザーのすべての呼び出しを表示する場合は、特定の Azure Communication Services ID (または複数の ID) を単一のユーザーにマップするように認証を設定する必要があります。

詳細については、認証の概念ログ分析による呼び出しの診断、使用可能なメトリックに関するページを参照してください。

リソースをクリーンアップする

Communication Services サブスクリプションをクリーンアップして削除するには、リソースまたはリソース グループを削除します。 リソース グループを削除すると、それに関連付けられている他のリソースも削除されます。 詳細については、「Communication Services リソースの作成と管理」の「リソースのクリーン アップ」セクションを参照してください。

次の手順

このクイック スタートでは、次の方法について説明しました。

  • ID を管理する
  • アクセス トークンを発行する
  • Communication Services Identity SDK を使用する

次の記事もご覧ください。