IBM Security Verify APIを触ってみる①～Transient EMAIL OTP編～

# はじめに
IBM Security Verify(ISV) では、様々なREST APIが提供されています。
今回は、ISVをEMAIL OTP プロバイダーとして利用し、他のアプリケーションからEMAIL OTPを呼び出す方法についてまとめます。
EMAIL OTP プロバイダーとしてのみ利用する場合は、ISVユーザー登録は必要ありません。
永続的なユーザーデータを保存しないため、一時的(Transient)EMAIL OTPと表記されています。

# APIのリファレンス
APIのリファレンスはKnowledge Centerには公開されていません。
以下のURLから確認できます。
https://<自分のテナント名＞.verify.ibm.com/developer/explorer/#

- EMAIL OTPのAPIは、以下の項目になります。
- Email One-time Password 2.0 
- EMAIL OTPの構成に関するAPIは、以下の項目になります。
- Email One-time Password Configuration 2.0 

# 1.IBM Security VerifyへのAPIクライアントの登録
OAuth アクセストークンを取得するために使用するクライアント ID とクライアントシークレットを準備します。
ブラウザで、IBM Security Verifyの管理画面にアクセスします。
https://<自分のテナント名＞.verify.ibm.com/ui/admin

「構成」-「API クライアント」タブを開きます。
![OTP-000002.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/678692/9799fa7c-cb28-7726-df1d-ccdece0060e8.png)
「APIクライアントの追加」をクリックします。
![OTP-000003.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/678692/47e91160-3fd1-5d26-c341-612cd77249f5.png)


アクセス件を与えるAPIとしては以下の7つを選択して、「保存」します。
- オーセンティケーター構成の管理
- すべてのユーザーのオーセンティケーター登録の管理
- すべてのユーザーの第2要素認証登録の管理
- ユーザー、標準グループ、および予約済みグループの管理
- ユーザーおよび標準グループの管理
- 第2要素認証方式の構成の管理
- 任意のユーザーの認証
![OTP-000004.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/678692/4029376d-6f71-5a90-531a-09202322e7f6.png)

登録したAPIクライアントを編集モードにすると、クライアントID/クライアント秘密鍵をコピーできます。
![OTP-000007.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/678692/14729de9-a462-0630-6ab9-e1501f345418.png)

# 2.アクセストークンの取得

```
curl -X POST "https://<テナント名＞.verify.ibm.com/oidc/endpoint/default/token" --header "Content-Type: application/x-www-form-urlencoded" --data-urlencode "grant_type=client_credentials" --data-urlencode "client_id=<クライアントID>" --data-urlencode "client_secret=＜クライアント秘密鍵＞"
```
取得したアクセストークンは赤枠部分になります。
![OTP-000008.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/678692/18cad35f-7fd7-b288-5620-7db65baa28e7.png)

レスポンスを確認したい場合は、-i オプションを追加します。

```
curl -i -X POST "https://<テナント名＞.verify.ibm.com/oidc/endpoint/default/token" --header "Content-Type: application/x-www-form-urlencoded" --data-urlencode "grant_type=client_credentials" --data-urlencode "client_id=<クライアントID>" --data-urlencode "client_secret=＜クライアント秘密鍵＞"
```
![OTP-000009.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/678692/542f1cff-34fa-c367-7b4b-8618c17386c3.png)

# 3.EMAIL OTPの送信
EMAIL OPTを発行するためには、ユーザーのEMAILアドレスを渡します。

```
curl -X  POST "https://<テナント名＞.verify.ibm.com/v2.0/factors/emailotp/transient/verifications" --header "Content-Type: application/json" --header "Authorization: Bearer <アクセストークン>" --data-raw "{\"emailAddress\": \"<Emailアドレス＞\"}"
```
![OTP-000015.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/678692/2566dd1c-a116-95b3-3c97-55c5d0aa58fa.png)

レスポンスを確認したい場合は、-i オプションを追加します。


```
curl -i -X  POST "https://<テナント名＞.verify.ibm.com/v2.0/factors/emailotp/transient/verifications" --header "Content-Type: application/json" --header "Authorization: Bearer <アクセストークン>" --data-raw "{\"emailAddress\": \"<Emailアドレス＞\"}"
```

成功するとレスポンスコード201が返ってくることがわかります。
赤枠部分のIDは、後続のOTP検証要求で利用します。
![OTP-000014.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/678692/c7042b7a-3a64-a3f6-d75d-cde812c174db.png)


IBM SecurityからメールでEMAIL OTPが届きます。
![OTP-000016.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/678692/103354c2-b5a8-a438-524f-59947af5ad4d.png)

# 4.EMAIL OTPの検証要求
EMAIL OTPの検証要求を行います。
-i　オプションを付けてレスポンスコードを確認します。

## 4.1 間違ったOTPを送信した場合
①にOTP発行時のIDを、②にメールで受信したEMAIL OTPを指定します。
今回は②に誤った値を指定して実行します。


```
curl -i -X  POST "https://<テナント名＞.verify.ibm.com/v2.0/factors/emailotp/transient/verifications/<OTP 発行時のID>" --header "Content-Type: application/json" --header "Authorization: Bearer <アクセストークン>" --data-raw "{\"otp\": \"<検証するOTP＞\"}"
```


誤ったOTPを指定した場合は、レスポンスコード400が返ってきます。
![OTP-000029.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/678692/eb50e9dd-8b95-653a-32fe-ed24e09a4f3b.png)


## 4.2 正しいOTPを送信した場合

次に正しいOTPを指定して実行します。

```
curl -i -X  POST "https://<テナント名＞.verify.ibm.com/v2.0/factors/emailotp/transient/verifications/<OTP 発行時のID>" --header "Content-Type: application/json" --header "Authorization: Bearer <アクセストークン>" --data-raw "{\"otp\": \"<検証するOTP＞\"}"
```

正しいOTPを指定した場合は、レスポンスコード201が返ってきます。
![OTP-000031.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/678692/6d4d9a5c-7350-4a7f-73b3-cae87133fbb3.png)



# 5.EMAIL OTPに関する構成変更

EMAIL OTPの構成要素は以下の５つです。
「Email One-time Password Configuration 2.0 」APIを利用して設定を管理できます。

| 項目 | 型 | 説明 |初期値|
|:-----------|:------------|:------------|:------------|
| retries     | integer        | The number of retry attempts before the verification is marked as failed         |5|
| length     | integer     | The length of the one-time password      |6|
| charset     | string      | The allowed character set for one-time password generation         |"0123456789"|
| enabled         | boolean          | The enabled state of email one-time password to be used in runtime flows           |true|
| expiry       | integer      | The number of seconds until the one-time password expires      |300|

# 5.1.構成情報の取得
上記の構成情報を取得します。

```
curl -i -X  GET "https://<テナント名＞.verify.ibm.com/config/v2.0/factors/emailotp" --header "Authorization: Bearer <アクセストークン>"
```
![OTP-000033.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/678692/4bfdd743-c8d9-39ea-3d40-98b77b6d0cff.png)


# 5.2.構成情報の更新
変更する部分を変えて構成情報を更新します。
以下の例ではOTPの長さを7桁に変更しています。
```
curl -i -X  PUT "https://<テナント名＞.verify.ibm.com/config/v2.0/factors/emailotp" --header "Content-Type: application/json" --header "Authorization: Bearer <アクセストークン>" --data-raw "{\"retries\": 5,\"length\": 7,\"charset\": \"0123456789\",\"enabled\": true,\"expiry\": 300}"
```
![OTP-000035.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/678692/5f8f62d3-8f68-56e7-ce97-25a617c7b4d0.png)




# 最後に
SMS OTP編、VOICE OTP編も作成予定です。