IBM Security Verify APIを触ってみる②～Transient SMS OTP編～

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

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

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

# 1.IBM Security VerifyへのAPIクライアントの登録と2.アクセストークンの発行
IBM Security Verify APIを触ってみる①～Transient EMAIL OTP編～を参考に実施ください。
https://qiita.com/fitz/private/98b0dc6a96b485a0324d

# 3.SMS OTPの送信
SMS OPTを発行するためには、ユーザーの携帯電話番号を渡します。
レスポンスを確認するため、-i オプションを追加します。

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

成功するとレスポンスコード201が返ってくることがわかります。

赤枠部分のIDは、後続のOTP検証要求で利用します。
![OTP-000044.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/678692/c142bddb-3b9b-7871-a5ea-00c416e54834.png)


IBMSecurityからSMS OTPが届きます。
![OTP-000044-2.PNG](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/678692/82d1bdfd-2741-50d8-5857-47d377938996.png)



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

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


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


誤ったOTPを指定した場合は、レスポンスコード400が返ってきます。
![OTP-000045.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/678692/9158cac1-e156-1733-3b03-6dad37f094d5.png)




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

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

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

正しいOTPを指定した場合は、レスポンスコード204が返ってきます。
![OTP-000046.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/678692/d5f898c4-4ba1-0284-1ff9-bd95512a4167.png)


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

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

| 項目 | 型 | 説明 |初期値|
|:-----------|:------------|:------------|:------------|
| retries     | integer        | The number of retry attempts before the verification is marked as failed         |4|
| 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 SMS 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/smsotp" --header "Authorization: Bearer <アクセストークン>"
```
![OTP-000047.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/678692/921a7dcb-b64b-9103-d273-a2d9b419b309.png)


## 5.2.構成情報の更新
変更する部分を変えて構成情報を更新します。
以下の例ではOTPの長さを7桁に変更しています。

```
curl -i -X  PUT "https://<テナント名＞.verify.ibm.com/config/v2.0/factors/smsotp" --header "Content-Type: application/json" --header "Authorization: Bearer <アクセストークン>" --data-raw "{\"retries\": 4,\"length\": 7,\"charset\": \"0123456789\",\"enabled\": true,\"expiry\": 300}"
```

![OTP-000048.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/678692/a4a727fc-2aeb-c910-9a90-f09751730ba0.png)


# 最後に
VOICE OTPもEmail/smsoptと基本的には同じになります。

APIリファレンスの以下の項目をご参照ください。

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