Twilio クライアント ケイパビリティ トークン

Twilio ClientはケパビリティトークンをデバイスとTwilioからの通信に署名するために使います。これらのトークンは多様なTwilioの機能にデバイスをアクセスさせるセキュアな方法です。ケイパビリティトークンを利用することにより、Javascriptやその他クライアンサイドの環境でAuthTokenを晒すこと無くTwilioの機能をウェブ、モバイルアプリケーションに追加することができます。

自分のサーバーでトークンを生成し、デバイスに持たせたいケイパビリティを指定します。 不正な利用を防止するため、すべてのトークンには有効期限があります。有効期限は 24 時間まで設定できますが、できるだけ短くするべきです。

トークンを生成する

Twilio のケイパビリティ トークンは、 JSON Web Token (JWT) 標準に基づいています。 ただし、 Twilio の公式の Helper ライブラリ を使用している場合は、Helper ライブラリのトークン生成機能を使って簡単にトークンを生成でき、トークンの書式を意識する必要はありません。 詳細については、使用しているライブラリのドキュメントを参照してください。

次の例では、 twilio-python モジュールを使ってケイパビリティ トークンの設定と生成を行います。

着信の接続を許可する

デバイスへの着信の接続を許可するには、デバイスにクライアント名をつける必要があります。 このクライアント名への接続が実行されると、クライアントの環境では着信イベントが発生します。 twilio.js では、着信の接続が実行されると、 Twilio.Device.incoming イベント ハンドラーが実行されます。

from twilio.jwt.client import ClientCapabilityToken

account_sid = 'ACXXXXXXXXXXXXXXX'
auth_token = 'secret'

capability = ClientCapabilityToken(account_sid, auth_token)
capability.allow_client_incoming('tommy')
print(capability.to_jwt())

トークンの設定されたデバイスは、tommyに接続する着信接続をいつでも受けることができます。
その際、<Dial>動詞の<Client>名詞を使うか、REST APIを使うことができます。

複数のデバイスが同じクライアント名を使用するように構成されている場合、着信接続は各デバイスが受信しますが、接続を受け入れるのは 1 つのデバイスのみです。一方、コンタクトセンターや他の着信通話シナリオでは、1 つのユニークなクライアント名を各デバイス（エージェント）で使用することを強く推奨します。複数のエージェント間で通話を振り分けるには、<Dial> 動詞の<Queue> 名詞を使用します。Twilio では、1 つのクライアント名を使用して同時に作成できるデバイス数が制限されています。

発信の接続を許可する

デバイスから発信の接続を行うには、接続を処理する際に使う VoiceUrl が Twilio にわかるように、ケイパビリティ トークンに Twilio アプリケーション の SID を設定します。 Twilio アプリケーション は、名前のついた URL の集まりで、通話や SMS を制御するための TwiML 命令を返す役割を持っています。

from twilio.jwt.client import ClientCapabilityToken

account_sid = 'ACXXXXXXXXXXXXXXX'
auth_token = 'secret'
application_sid = 'AP123123'

capability = ClientCapabilityToken(account_sid, auth_token)
capability.allow_client_outgoing(application_sid)
print(capability.to_jwt())

このトークンで設定されたデバイスは、AP123123 で識別される Twilio アプリケーションの VoiceUrl に対して、発信の接続を行うことができます。

複数のケイパビリティ

デバイスに複数のケイパビリティを設定することもできます。 たとえば、着信接続の受信と発信接続の実行ができるようにクライアントを設定するには、両方のケイパビリティを持つトークンを生成し、そのトークンでデバイスを開始します。

from twilio.jwt.client import ClientCapabilityToken

account_sid = 'ACXXXXXXXXXXXXXXX'
auth_token = 'secret'
application_sid = 'AP123123'

capability = ClientCapabilityToken(account_sid, auth_token)
capability.allow_client_incoming('tommy')
capability.allow_client_outgoing(application_sid)
print(capability.to_jwt())

セキュリティ

セキュリティはわたしたち開発者にはとても重要な要素です。Twilio は、ユーザーが開発者としてセキュリティをコントロールできるよう考慮しています。 ユーザーは Twilio の Helper ライブラリを使ってケイパビリティ トークンを生成し、Twlio クライアント デバイスに許可するアクセス権を決定します。 トークンのパラメーターが不正に改竄された場合は確実に検知され、適切な処置が取られます。

トークンの有効期限

デフォルトでは、Twilio の Helper ライブラリで生成されたすべてのトークンは、1 時間で有効期限が切れます。 ただし、この有効期限をできるだけ短く設定するべきです。 たとえば、発信専用のアプリケーションでは、トークンの有効期限は発信の接続を確立するのに十分な時間 (たとえば 5 秒) に設定し、利用者が新しい接続を行うたびに新しいトークンを生成します。

有効な接続があるにも関わらず、トークンの有効期限が切れた場合でも、接続は切断されません。しかし、デバイスは次回接続を行う場合はトークンの再初期化が必要です。

10分間有効なトークンを作成しています。expiresの記述は秒単位で記述します。

capability = ClientCapabilityToken(account_sid, auth_token, ttl=600)
print(capability.to_jwt())