Twilio Flexでのユーザ管理方法

:::note alert
2023年5月1日を持ちまして、株式会社KDDIウェブコミュニケーションズのTwilioリセール事業が終了したため、本記事に記載されている内容は正確ではないことを予めご了承ください。
:::

# はじめに

本記事は、 Twilio のコンタクトセンタープラットフォームである Twilio Flex で、ユーザ管理をどのように行うかについて記載しています。

[Twilio Flex](https://jp.twilio.com/flex)

## 開発者の追加

インストールの記事でも一部触れていますが、 Flex をインストールした Twilio デベロッパーアカウントは、 Flex をカスタマイズしたり、スーパーバイザーとしてエージェントの管理をしたり、もちろん Flex を利用して自身でコールに応対することができます。
ここでは便宜的に、 Flex をインストールしたユーザを「オーナー」と呼ぶことにします。
オーナー以外の方が、オーナーの所有する Flex プロジェクトをカスタマイズする必要がある場合は、以下の手順でオーナーのプロジェクトに招待することができます（ Flex セットアップ時に開発者を追加することもできます）。

- オーナーは Twilio の管理コンソールにログインします。
- ダッシュボードの**設定**から**ユーザー管理**を選択します。
![スクリーンショット 2018-12-27 13.44.02.png](https://qiita-image-store.s3.amazonaws.com/0/86046/d52b5194-5341-3040-4fd0-d4a851020db4.png)

- 赤いプラスアイコンを押します。
- 招待したい人のメールアドレス（相手がTwilioアカウントを持っていない場合は、まずはアカウント登録してもらってください）を入力し、ロールには、**管理者**もしくは**開発者**を選択して、**招待メールを送信**を押します。
![スクリーンショット 2018-12-27 13.45.50.png](https://qiita-image-store.s3.amazonaws.com/0/86046/019f5b80-a4c0-efec-d3a9-87943719b8d1.png)

招待したい方にメールが送信され、相手方が招待を受け入れることでオーナーのプロジェクトの開発が可能になります。

## エージェントの追加

コンタクトセンターは通常、複数人のエージェント（電話対応をするオペレータ）で構成されます。すべてのエージェントが Flex のカスタマイズをするわけではないので、彼ら全てに Twilio アカウントを取得してもらうのは現実的ではありません。
そこで、 Flex のエージェントとしてだけ利用したい人は、外部のアカウント管理サービスにユーザ情報を登録して、それを Flex と連携させることができます。
Flex と連携が可能なアカウント管理サービス（ Identity Provider ）は、  SAML2.0 に対応した SSO （ Single Sign-On ）となります。ここでは、 
 [OKTA](https://www.okta.com) というサービスを使って、アカウントの管理を行っていきたいと思います。

#### OKTA とは

OKTA は、主に企業のIDを管理するクラウドサービスです。 OKTA に対応したサービスを利用する場合、ユーザは一度 OKTA にログインしておけば、それぞれのサービスで再度ログインする必要がなくなります。もちろん、ユーザ情報も OKTA にだけ登録しておけば良いので、アカウント管理も簡単になります。
![スクリーンショット 2018-12-27 16.50.25.png](https://qiita-image-store.s3.amazonaws.com/0/86046/d13e0cbe-1bcb-78c6-3912-082320fb38c8.png)


### 準備

- 作業に先立ち、[こちらのリンク](https://developer.okta.com)から OKTA のデベロッパーアカウントを作成してください。デベロッパーアカウントは、月間1,000アクティブユーザまでは無料で利用できます。
- Flex のセットアップを完了させておいてください。セットアップ方法については、以下の記事を御覧ください。
[5分で完了！Twilio Flexのセットアップ](https://qiita.com/mobilebiz/items/28ca15684e2f4a82b7f2)

## 作業手順

では早速 OKTA にユーザを登録していきましょう。大まかな手順は以下の通りです。

1. Flex をアプリケーションとして登録する。
2. アプリケーションの環境設定を行う。
3. Flex に引き渡すユーザ情報を定義する。
4. アプリケーション連携URLを取得する。
5. ユーザを作成して、アプリケーションに紐付ける。
6. Flex 側での設定を行う。

### Flex をアプリケーションとして登録する

- OKTA [デベロッパーサイト](https://developer.okta.com)にログインします。
- 右上の**Developer Console**リストをプルダウンして、**Classic UI**を選択します（Classic UI に切り替えないと、 SAML2 の設定ができません）。
![スクリーンショット 2018-12-28 14.08.58.png](https://qiita-image-store.s3.amazonaws.com/0/86046/1fd65653-9caf-3396-12f0-34dc188b359f.png)

- **Applications**メニューを選択して、**Add Application**ボタンを押します。
![OKTA_AddNewApplication (1).png](https://qiita-image-store.s3.amazonaws.com/0/86046/7496b101-9a5c-d77f-1a9b-0f3e84ae4350.png)

- **Create New App**ボタンを押します。
![スクリーンショット 2018-12-28 14.20.45.png](https://qiita-image-store.s3.amazonaws.com/0/86046/fc9b9188-39e0-2796-d226-afb394f34dd8.png)

- **Create a New Application Integration**ダイアログが開くので、**Platform**は、「Web」を選択し、さらに**Sign on method**には、「SAML 2.0」を選択してから**Create**ボタンを押します。
![スクリーンショット 2018-12-28 14.21.46.png](https://qiita-image-store.s3.amazonaws.com/0/86046/e5961395-e7af-8bdf-c05e-a680b2eed5cf.png)

- **App name**になにか適当な名前を入力して、**Next**ボタンを押します。
![スクリーンショット 2018-12-28 14.24.37.png](https://qiita-image-store.s3.amazonaws.com/0/86046/8df15d85-0d19-5ef0-f0e2-171a3c1953f1.png)

### アプリケーションの環境設定を行う

- **SAML Setting**画面に遷移するので、**Single sign on URL**と**Audience URI**に、以下のURLを指定します。

`https://preview.twilio.com/iam/Accounts/ACXXXXX/saml2`
ACXXXXX の部分は、ご自分の Twilio Flex Project の Account Sid に置き換えてください。

- **Show Advanced Settings**をクリックして、詳細画面を表示させます。
- **Response**と**Assertion Signature**が共に「Signed」になっていることを確認します。
- **Assertion Encryption**が、「Unencrypted」になっていることも確認します。
![OKTA_SAMLConfiguration.png](https://qiita-image-store.s3.amazonaws.com/0/86046/689f9e8f-b259-7da3-f686-f1f7fc97ca8c.png)

### Flex に引き渡すユーザ情報を定義する

OKTA 側で登録したユーザに関する情報を、 Flex に引き渡す設定を行います。

- **ATTRIBUTE STATEMENTS (OPTIONAL)**セクションに移動し、以下の内容で設定をしていきます。

Name|Name format|Value
:--|:--|:--
full_name|Basic|String.join("", user.firstName, user.lastName)
image_url|URI Reference|user.profileUrl
roles|Basic|user.roles
email|Basic|user.email

この例では、 OKTA 側で設定したユーザの姓名を full_name 、ユーザのプロファイル画像を image_url 、ユーザの役割を roles 、ユーザのメールアドレスを email をいうパラメータ名で Flex に渡しています。このように、 Flex 側に渡したいユーザ個別のパラメータはここで設定していきます。

- **Next**ボタンを押して、設定を保存します。
- **Are you a customer or partner?**は「I'm an Okta customer adding an internal app」にチェックを入れずに、**Finish**ボタンを押します。
![スクリーンショット 2018-12-28 15.31.20.png](https://qiita-image-store.s3.amazonaws.com/0/86046/27ca95f4-6600-6faf-3e0a-9852dbecaca3.png)

### アプリケーション連携URLを取得する

- 作成したアプリケーションの**Sign On**タブに移動し、**View Setup Instructions**ボタンを押します。
![OKTA_SAML_Instructions.png](https://qiita-image-store.s3.amazonaws.com/0/86046/d2deac70-483d-9e7b-7379-4919abdbfbc6.png)

- 各種設定情報が表示されます。
![OKTA_Signed.png](https://qiita-image-store.s3.amazonaws.com/0/86046/c2369d05-cdb9-2bd5-e555-29a559ab7623.png)

- 以下の３つの情報をメモ帳にコピーします。
 - Identity Provider Single Sign-On URL
 - Identity Provider Issuer
 - X.509 Certificate（-----BEGIN CERTIFICATE-----と-----END CERTIFICATE-----も含みます）

これらの情報は、このあと Flex 側の設定で必要となります。 

### ユーザを作成して、アプリケーションに紐付ける

OKTA のデフォルト設定では、 Flex 側に引き渡すパラメータ**roles**が定義されていないので、まずはそちらのパラメータを設定します。

- ＊＊Directory**メニューの中の**Profile Editor**を開き、**okta**の**Profile**ボタンを押します。
![OKTA_Profile.png](https://qiita-image-store.s3.amazonaws.com/0/86046/9bdcc467-5ca4-7a38-dcdf-052a4b7a0727.png)

- **Attributes**セクションの**Add Attribute**ボタンを押します。
![OKTA_Profile_Added.png](https://qiita-image-store.s3.amazonaws.com/0/86046/dd62e322-3a19-4f1f-2535-248ec0664411.png)

- 以下の内容で新しい Attribute を登録します。

項目名|値
:--|:--
Data Type|String
Display name|Roles
Variable name|roles
Attribute required|チェック

![スクリーンショット 2018-12-28 18.13.24.png](https://qiita-image-store.s3.amazonaws.com/0/86046/ee3e1929-3e54-eef9-df87-1c2458569faf.png)

- **Save**ボタンを押してしばらくするとダイアログが閉じます。

では、続いてユーザを追加しましょう。

- **Directory**メニューの中の**Person**を選択し、**Add Person**ボタンを押します。
![OKTA_Directory_Person.png](https://qiita-image-store.s3.amazonaws.com/0/86046/a49be892-f213-0f6e-4c37-3ae3e62a3d02.png)

- ユーザ登録画面が開くので、以下のように各項目を追加していきます。
![OKTA_Person_Added.png](https://qiita-image-store.s3.amazonaws.com/0/86046/fceb0ebe-5773-ac2e-aa19-f59db91cde39.png)

**Send user activation email now**にチェックを入れて、**Save**ボタンを押すと、登録したいユーザにメールが届きますので、パスワードを設定してもらってください。

- ユーザ一覧画面から、今作成したユーザをクリックします。
- **Profile**タブを選択して、**Edit**ボタンを押します。
- 一番下の項目に、**Roles**が表示されるので、エージェントのみの利用者は、「agent」、スーパーバイザーとして利用するには、「supervisor」と入力します。
- **Save**ボタンを押して、設定を保存します。

次に作成したユーザをアプリケーションにアサインしましょう。

- **Directories**メニューの中の**People**今作成したユーザを選択します。
- **Assign Applications**ボタンを押します。
![OKTA_Application_Assign.png](https://qiita-image-store.s3.amazonaws.com/0/86046/a77fecfc-da81-ef60-9bda-9bed4e9cb74b.png)

- Flex の横に表示されている**Assign**ボタンを押します。
![スクリーンショット 2018-12-28 18.33.09.png](https://qiita-image-store.s3.amazonaws.com/0/86046/3b38ee7a-ca2f-1096-3813-f74a08a0638e.png)

- **User name**を確認するダイアログが表示されるので、**Save and Go Back**ボタンを押します。
- Flex がアサインされるので、**Done**ボタンを押します。

### Flex 側での設定を行う

- Twilio の管理コンソールにログインします。
- **Flex**メニューの中の**Single Sign-On**を選択します。
- **FRIENDRY NAME**には、「Okta」と入力します（ここは何でもかまいません）。
- **X.509 CERTIFICATE**、**IDENTITY PROVIDER ISSUER**、**SINGLE SIGN-ON URL**の各項目に、先程メモ帳に保存しておいた値をコピーします。
![OKTA_Flex_SSO.png](https://qiita-image-store.s3.amazonaws.com/0/86046/08a37d99-246d-47b8-ff26-195aa0df2407.png)

- **Save**ボタンを押します。

## テスト

ログインに先立ち、 Twilio Runtime ドメイン名が必要になりますので、以下の手順で調べておきます。

- ~~Twilio 管理コンソールから**RUNTIME**メニューを選択し、さらに**概要**メニューを選択します。~~
- <https://jp.twilio.com/console/runtime/overview>を開いて概要を確認します。

![Runtime_Domain (1).png](https://qiita-image-store.s3.amazonaws.com/0/86046/469d59ca-236e-d437-2d44-37d8af683140.png)

- ドメイン名の右側にあるコピーアイコンをクリックして、ドメイン名をコピーしておきます。

では、実際にログインしてみましょう。
OKTA のサイトにログインしている場合は、このタイミングで一度ログアウトしてください。

- ブラウザを開き、 `https://flex.twilio.com/` を開きます。
- Runtime Domain を入力する画面が表示されます。

![スクリーンショット 2018-12-30 11.07.14.png](https://qiita-image-store.s3.amazonaws.com/0/86046/c512f0a2-5b99-0c5d-322e-81106831e06d.png)

- 先ほどコピーしたドメイン名を入力して、**LAUNCH**ボタンを押します。
- OKTA のログイン画面が表示されます。

![OKTA_Sign-in.png](https://qiita-image-store.s3.amazonaws.com/0/86046/f058a01e-4dfe-8e0b-6d85-c39dbb817b13.png)

- OKTA で作成したアカウント（メールアドレスとパスワード）でサインインをしてみます。
- 無事にログインができれば成功です。 

# まとめ

- Flexのユーザ管理は、外部の SAML2.0 に対応したSSOプロバイダーと連携させることができます。
- OKTA以外にも連携させることができます。詳しくは、[こちらのドキュメント](https://jp.twilio.com/docs/flex/configuring-single-sign-and-identity-provider-integration)を御覧ください。
- OKTA 上で登録しておいたユーザーの属性を、 Flex に引き渡すことができるので、それを使って Flex の動作を変えることができます。