API認証

NTT CPaaS APIを統合に利用するには、何らかの認証方法を使用する必要があります。プライベートアプリの場合、認証情報をアプリに埋め込むことをご検討ください。

複数のアカウントで使用されるアプリの場合、各ユーザーを統合内の適切な機能と連携させるために、ユーザーのNTT CPaaSアカウント情報を取得する必要がある場合があります。

一般的なユースケースでは、NTT CPaaSアカウントを外部プラットフォームのアカウントに接続します。トークン内のアカウント、ユーザーやその他の追加情報は、OAuth 2.0を使って取得できます。

認証方法の選択

次の表に、認証方法を選択する際に役立つ情報を示します。

認証方法	APIキー	OAuth 2.0
セキュリティレベル	Moderate (中) – 簡単に傍受または共有される可能性あり	High (高) – トークンは存続期間が短く、スコープも限定的
実装の難易度	実装と使用が簡単	トークン管理とフローの設定が必要
API 統合に適している	✔	✔
アカウントとユーザーの情報を取得	✖
NTT CPaaS API を使用	✔	✔
埋め込みUI (設定ページ、コンテキストカード) に使用	✖	✔
最適用途	単一アカウントで使用するプライベートアプリ	複数アカウントで使用するアプリ
最適な結果を得るためにスコープを使用	✔	✔

APIキー

APIキーを使用する場合は、適切な API スコープがAPIキーに割り当てられていることを確認します。APIキーは NTT CPaaSアカウントに関連付けられているため、キーが暗号化され、セキュアな状態で保護されていることを確認する手順をいくつかのステップに分けて実行する必要があります。

OAuth 2.0

OAuth 2.0は、ログイン資格情報の代わりに識別トークンを渡すことで、別のサイトからのデータを共有できるようにする承認プロトコルです。

OAuth を使用すると、Exchangeアプリは、パスワードを取得せずに、NTT CPaaSのWebインターフェイスを使用するユーザーのアカウントの詳細情報の認証をリクエストし、承認されたAPI機能にアクセスできるようになります。

つまり、アプリケーションは、NTT CPaaSのWebインターフェイスを使用するユーザーに代わって動作できるようにするトークンをリクエストします。全体的な認証フローは次のように進みます：

アプリのユーザー体験

アプリをインストールするユーザー、またはOAuth経由で認証するユーザーは、次の手順に従います：

ユーザーは、サイトまたはアクティベーションページからリンクをアクティブ化し、NTT CPaaSにリダイレクトされます。
必要に応じて、ユーザーはそれぞれのNTT CPaaSアカウントにログインします。
ユーザーは、OAuth接続に必要なアクセス許可 (スコープ) を確認します。
ユーザーは、必要なアクセス許可を受け入れるか、インストールをキャンセルします。
インストールをキャンセルすると、参照元のウェブページに再ルーティングされます。
アクセス許可を受け入れた場合、認証は完了し、ユーザーはリダイレクトURL にリダイレクトされます。

OAuth 2.0を使った統合またはプラットフォームへのユーザー認証

アプリでOAuthを使用するには：

アプリ用の一意のクライアントIDやクライアントシークレット (OAuthフロー用のユーザー名やパスワードなど) を定め、アプリに必要なスコープを割り当てられるようにするためのアプリシェルを作成します。
1. OAuthフロー中に使用するアプリのリダイレクトURIを入力します。
2. アプリのクライアントIDとクライアントシークレットを取得します。これらの値はアプリに固有であり、NTT CPaaSとの通信に役立ちます。コピーアイコンを使用して、シークレットをクリップボードにコピーします。
サイトアクティベーションリンクを作成します。ウェブページまたはプラットフォームで、ユーザーが NTT CPaaS に接続できるリンクを作成します。

リダイレクトURIのセットアップ

認証されたユーザーがアプリを承認し、クライアントIDとシークレットが有効な場合、NTT CPaaSは、クエリパラメーターとしての一時コードと、ステップ 1 で指定した状態パラメーターを使用して、redirect_uriへのリクエストを作成します。

[redirect_uri?code={code}&state={state}]

状態を照合して、この OAuthフローに対してリクエストが生成されたことを検証できます。

code - [必須] - 16文字の16進文字列の認証コード。
state - [任意] - 前のリクエストと同じ。

例：[https://www.my-app.com/?code=822762fa24e04975&state=xyz]

これが認証コードです。認証コードは一度だけ交換でき、作成後 1 分で有効期限が切れます。

トークン用のコード交換

次の段階では、コードをトークンと交換する必要があります。

ステップ2 (サイトアクティベーションリンクの作成) を正常に完了したら、POSTメソッドを使用してGET Token エンドポイント [https://oneapi.infobip.com/exchange/1/oauth/token] を呼び出して、アクセストークンのコードを交換します。
URLエンコード本文リクエスト (--data-urlencode) として次の値を渡します：
- client_id - [必須] - 32文字の16進数文字列のパブリックアプリ識別子
- client_secret - [必須] - AES暗号化アルゴリズムを使用する256ビットキーを16進数で表すプライベートアプリ識別子
- code - [必須] - ステップ2で認証サーバーから受信した一時的な認証コード
- redirect_uri - [必須] - ステップ1以降の認証リクエストと同じredirect_uri
- grant_type - [必須] - 標準ではauthorization_codeに設定する必要があります

例えば：


    curl --location --request POST 'https://oneapi.infobip.com/exchange/1/oauth/token' \    --header 'Accept: application/json' \    --header 'Content-Type: application/x-www-form-urlencoded' \    --data-urlencode 'client_id=d5e47f02d627e390d615c2e93f168eb6' \    --data-urlencode 'client_secret=YED8Q0KHeYgQxtjdUkR376Uxu0/zdvwAVZb3ZQ3GGZU=' \    --data-urlencode 'code=822762fa24e04975' \    --data-urlencode 'redirect_uri=https://www.my-app.com' \    --data-urlencode 'grant_type=authorization_code'

トークンとその他のユーザー情報を含むJSON応答を受け取ります。

token - [必須] - NTT CPaaSトークン
tokenType - [必須] - IBSSO
accountKey - [必須] - リクエストからのaccountIdを表す16進数の文字列
userKey - [必須] - リクエストからのuserIdを表す16進数の文字列
username - [必須] - NTT CPaaSのWebインターフェイスを使用するユーザーの登録ユーザー名
email - [必須] - NTT CPaaSのWebインターフェイスを使用するユーザーの登録メールアドレス
locale - [必須] - ユーザーによって定義された NTT CPaaS Webインターフェイス言語
roles - [任意] - NTT CPaaS Webインターフェイスのユーザーロールの一覧
groups - [任意] - NTT CPaaS Webインターフェイスのユーザーグループの一覧

JSON例を以下に示します：

 
{    "token": "3d7908aa-7b8c-4c5a-94bf-5cdeef18947b",    "tokenType": "IBSSO",    "accountKey": "8F0792F86035A9F4290821F1EE6BC06A",    "userKey": "F443BCAEB8517F7159F44D0E8CFE725D",    "username": "developeruser",    "email": "developer@infobip.com",    "locale": "en-US",    "roles": [    {    "id": 79,    "name": " Manager 1"    },    {    "id": 81,    "name": " Manager 2"    },    {    "id": 1297,    "name": " Manager 3"    },    {    "id": 1393,    "name": " Designer"    },    {    "id": 1394,    "name": " Supervisor"    }    ],    "groups": [    {    "id": 54004,    "name": "Group1"    },    {    "id": 54242,    "name": "Group2"    },    {    "id": 749187,    "name": "Group3"    }    ]    }

これがOAuthトークンです。トークンの有効期限は作成後 1 分で切れます。

OAuthトークンの使用

トークンを取得したので、NTT CPaaSエンドポイントを呼び出す時にこれを認証方法として使用できます。

認証されるには、ヘッダーにトークンを追加する必要があります：

認証 - [必須] - {tokenType + " " + token}

以下に (SMS メッセージを送信する際の) 例を示します：


curl -L -X POST 'https://3vzg6v.api.infobip.com/sms/2/text/advanced' \    -H 'Authorization: IBSSO 3d7908aa-7b8c-4c5a-94bf-5cdeef18947b' \    -H 'Content-Type: application/json' \    -H 'Accept: application/json' \    --data-raw '{      "messages": [        {          "destinations": [            {              "to": "41793026727"            }          ],          "from": "InfoSMS",          "text": "This is a sample message"        }      ]    }'

トークンの更新

アカウントで利用可能なNTT CPaaSのサービスへのアクセスを継続するには、トークンが期限切れになる前に更新する必要があります。これを行うには、Get Tokenエンドポイントをもう一度呼び出します。

[ https://oneapi.infobip.com/exchange/1/oauth/token ]

code - [必須] – ステップ4で取得する認証トークン
grant_type - [必須] – トークンの有効期限を延長するrefresh_token

リクエストが有効な場合、応答は上記の例と同じになります。

必要に応じて、トークンの更新を続行します。

NTT CPaaSのWebインターフェイスに埋め込まれたUIへのOAuth 2.0の使用

NTT CPaaSのWebインターフェイス (Conversationsのコンテキストカードまたはアプリの設定ページ) に独自のUIを埋め込むことができます。OAuthを使って顧客アカウント情報を取得し、UIの機能を強化することができます。埋め込みUIでOAuthを使用するには：

アプリ用の一意のクライアントIDやクライアントシークレット (OAuthフロー用のユーザー名やパスワードなど) を定められるようにするためのアプリシェルを作成します。
OAuthフロー中に使用するアプリのリダイレクトURIを設定します。
アプリのクライアントIDとクライアントシークレットを取得します。これらの値はアプリに固有であり、NTT CPaaSとの通信に役立ちます。コピーアイコンを使用して、シークレットをクリップボードにコピーします。

OAuthによる顧客アカウント情報の取得

NTT CPaaSでアプリの認証を行うステップを、アプリのオンボードフローに加えます。通常、これはアプリの構成ページおよび／またはコンテクストカードページでトリガーできます。

クライアントのアクセスコードを取得するには、以下の方法があります：

NTT CPaaSがお使いのページをiframeに読み込む際、ユーザーの状態パラメーターをURLに渡します。例えば：

https://yoursite.com/contextcardui?state= WeHH_yy2irpl8UY

この状態値をアプリが一時的に保存し、この認証エンドポイントを使って認証をGETメソッドで行えるようにするために、その値を送信するように動作する必要があります：

https://oneapi.infobip.com/exchange/1/oauth/authorize

クエリパラメーターとして次の値を渡す必要があります：
- response_type - [必須] - 応答として認証コードが必要であることを示すコード
- client_id - [必須] - 32文字の16進数文字列のパブリックアプリ識別子
- state - [必須] - アプリへのリダイレクトリクエストに含まれる値
- redirect_uri - [必須] リクエストをアプリにリダイレクトするURL
- scope - [必須] - 追加のアクセスレベル
例：
http
```
    https://oneapi.infobip.com/exchange/1/oauth/authorize?response_type=code&client_id=d5e47f02d627e390d615c2e93f168eb6&state=xyz&redirect_uri=https://www.my-app.com&scope=api_read
 
```
認証されたユーザーによってページが読み込まれ、クライアントIDとシークレットが有効な場合、Exchange は、クエリパラメーターとして一時コードと、ステップ1で指定した state パラメーターを使ってredirect_uri へのリクエストを作成します。

redirect_uri?code={code}&state={state}

このOAuthフローに対してリクエストが生成されたことを検証するために、状態を照合できます。
- code - [必須] - 16文字の16進文字列の認証コード。
- state - [任意] - 前のリクエストと同じ。
例：
http
```
    https://www.my-app.com/?code=822762fa24e04975&state=xyz
 
```
これが認証コードです。認証コードは一度だけ交換でき、作成後 1 分で有効期限が切れます。
ステップ2が正常に完了したら、次のGET Tokenエンドポイントを POSTメソッドで呼び出して、アクセストークンのコードを交換します。

https://oneapi.infobip.com/exchange/1/oauth/token

URLエンコード本文リクエスト (--data-urlencode) として次の値を渡す必要があります。
- client_id - [必須] - 32文字の16進数文字列のパブリックアプリ識別子
- client_secret - [必須] - AES暗号化アルゴリズムを使用する256ビットキーを16進数で表すプライベートアプリ識別子
- code - [必須] - ステップ2で認証サーバーから受信した一時的な認証コード
- redirect_uri - [必須] - ステップ1以降の認証リクエストの同一の redirect_uri
- grant_type - [必須] - 通常 authorization_code に設定する必要があります
例えば：
curl
```
    curl --location --request POST 'https://oneapi.infobip.com/exchange/1/oauth/token' \
    --header 'Accept: application/json' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'client_id=d5e47f02d627e390d615c2e93f168eb6' \
    --data-urlencode 'client_secret=YED8Q0KHeYgQxtjdUkR376Uxu0/zdvwAVZb3ZQ3GGZU=' \
    --data-urlencode 'code=822762fa24e04975' \
    --data-urlencode 'redirect_uri=https://www.my-app.com' \
    --data-urlencode 'grant_type=authorization_code'
```
トークンとその他のユーザー情報を含むJSON応答を受け取ります。
- token - [必須] - NTT CPaaSトークン
- tokenType - [必須] - IBSSO
- accountKey - [必須] - リクエストからのaccountIdを表す16進数の文字列
- userKey - [必須] - リクエストからのuserIdを表す16進数の文字列
- username - [必須] - NTT CPaaSのWebインターフェイスを使用するユーザーの登録ユーザー名
- email - [必須] - NTT CPaaSのWebインターフェイスを使用するユーザーの登録メールアドレス
- locale - [必須] - ユーザーによって定義された NTT CPaaS Webインターフェイス言語
- roles - [任意] - NTT CPaaS Webインターフェイスのユーザーロールの一覧
- groups - [任意] - NTT CPaaS Webインターフェイスのユーザーグループの一覧
JSON例を以下に示します：
json
```
{
    "token": "3d7908aa-7b8c-4c5a-94bf-5cdeef18947b",
    "tokenType": "IBSSO",
    "accountKey": "8F0792F86035A9F4290821F1EE6BC06A",
    "userKey": "F443BCAEB8517F7159F44D0E8CFE725D",
    "username": "developeruser",
    "email": "developer@infobip.com",
    "locale": "en-US",
    "roles": [
    {
    "id": 79,
    "name": " Manager 1"
    },
    {
    "id": 81,
    "name": " Manager 2"
    },
    {
    "id": 1297,
    "name": " Manager 3"
    },
    {
    "id": 1393,
    "name": " Designer"
    },
    {
    "id": 1394,
    "name": " Supervisor"
    }
    ],
    "groups": [
    {
    "id": 54004,
    "name": "Group1"
    },
    {
    "id": 54242,
    "name": "Group2"
    },
    {
    "id": 749187,
    "name": "Group3"
    }
    ]
    }
```

トークンを取得したので、NTT CPaaSエンドポイントを呼び出す時にこれを認証方法として使用できます。

認証されるには、ヘッダーにトークンを追加する必要があります：

Authorization - [Required] - {tokenType + " " + token}

(SMSメッセージを送信する (opens in a new tab)場合の) 例：

curl


    curl -L -X POST 'https://3vzg6v.api.infobip.com/sms/2/text/advanced' \
    -H 'Authorization: IBSSO 3d7908aa-7b8c-4c5a-94bf-5cdeef18947b' \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    --data-raw '{
      "messages": [
        {
          "destinations": [
            {
              "to": "41793026727"
            }
          ],
          "from": "InfoSMS",
          "text": "This is a sample message"
        }
      ]
    }'

シングルページアプリケーション用の顧客アカウントへの代理アクセス

ネイティブアプリやシングルページアプリなど、クライアントシークレットを保存できないアプリケーションでは、コード交換用証明鍵 (PKCE) フローを使用するようにします。

クライアントのアクセスコードを取得するには、以下の方法があります：

NTT CPaaSがお使いのページをiframeに読み込む際、ユーザーの状態パラメーターをURLに渡します。例えば：

https://yoursite.com/contextcardui?state= WeHH_yy2irpl8UY

この状態値をアプリが一時的に保存し、この認証エンドポイントを使って認証をGETメソッドで行えるようにするために、その値を送信するように動作する必要があります：

https://oneapi.infobip.com/exchange/1/oauth/authorize

次の値をクエリパラメーターとして渡します：
- response_type - [必須] - 応答として認証コードが必要であることを示すコード
- client_id - [必須] - 32文字の16進数文字列のパブリックアプリ識別子
- state - [必須] - アプリへのリダイレクトリクエストに含まれる値。
- redirect_uri - [必須] リクエストをアプリにリダイレクトするURL
- scope - [必須] - 追加のアクセスレベル
- code_challenge - [必須] - コード検証ツールのSHA256ハッシュをパディング文字列なしでBase64URLエンコードしたもの
例えば：
http
```
    https://oneapi.infobip.com/exchange/1/oauth/authorize?code_challenge=pmWkWSBCL51Bfkhn79xPuKBKHz__H6B-mY6G9_eieuM&response_type=code&client_id=d5e47f02d627e390d615c2e93f168eb6&state=xyz&redirect_uri=https://www.my-app.com&scope=api_read
 
```
認証されたユーザーによってページが読み込まれ、クライアントIDとシークレットが有効な場合、Exchange は、クエリパラメーターとして一時コードと、ステップ1で指定した state パラメーターを使ってredirect_uri へのリクエストを作成します。

redirect_uri?code={code}&state={state}

このOAuthフローに対してリクエストが生成されたことを検証するために、状態を照合できます。
- code - [必須] - 16桁の16進数文字列からなる認証コード
- state - [任意] - 前のリクエストと同じ
例えば：

https://www.my-app.com/?code=822762fa24e04975&state=xyz

認証コードは一度だけ交換でき、作成後 1 分で有効期限が切れます。
前のステップを正常に完了したら、次のGET Token エンドポイントを POSTメソッドで呼び出して、アクセストークンのコードを交換します。

https://oneapi.infobip.com/exchange/1/oauth/token

次の値をURLエンコード本文リクエスト (--data-urlencode) として渡します。
- client_id - [必須] - 32文字の16進数文字列のパブリックアプリ識別子
- code_verifier - [必須] - 文字AからZ、aからz、0から9、区切り文字 - . ~ を使用した、43文字から128文字以内の長さの暗号化ランダム文字列 (推奨)
- code - [必須] - ステップ2で認証サーバーから受信した一時的な認証コード
- redirect_uri - [必須] - ステップ1以降の認証リクエストと同じredirect_uri
- grant_type - [必須] - 通常 authorization_code に設定する必要があります
例えば：
curl
```
curl --location --request POST 'https://oneapi.infobip.com/exchange/1/oauth/token' \
    --header 'Accept: application/json' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'client_id=d5e47f02d627e390d615c2e93f168eb6' \
    --data-urlencode 'code_verifier=123' \
    --data-urlencode 'code=822762fa24e04975' \
    --data-urlencode 'redirect_uri=https://www.infobip.com' \
    --data-urlencode 'grant_type=authorization_code'
```
トークンとその他のユーザー情報を含むJSON応答を受け取ります。
- token - [必須] - NTT CPaaSトークン
- tokenType - [必須] - IBSSO
- accountKey - [必須] - リクエストのaccountIdを表す16進数の文字列
- userKey - [必須] - リクエストからのuserIdを表す16進数の文字列
- username - [必須] - NTT CPaaSのWebインターフェイスを使用するユーザーの登録ユーザー名
- email - [必須] - NTT CPaaSのWebインターフェイスを使用するユーザーの登録メールアドレス
- locale - [必須] - ユーザーによって定義された NTT CPaaS Webインターフェイス言語
- roles - [任意] - NTT CPaaSのユーザーロールの一覧
- groups [任意] - NTT CPaaS Webインターフェイスのユーザーグループの一覧
トークンを取得したので、NTT CPaaSエンドポイントを呼び出す時にこれを認証方法として使用できます。

NTT CPaaSで保護されたリソースエンドポイント

GET https://portal.infobip.com/api/amg/exchange/1/apps/\{appId\}/oauth

認証されるには、次のヘッダーを追加する必要があります：

Authorization - [Required] - {tokenType + '" " + token}

JSON応答例を以下に示します：
json
```
{    "clientId": "d5e47f02d627e390d615c2e93f168eb6",    "clientSecret": "YED8Q0KHeYgQxtjdUkR376Uxu0/zdvwAVZb3ZQ3GGZU=",    "appId": "3bb98d89-af5d-4a56-8ccd-c3e0e2ae976b", "redirectUri": "https://www.infobip.com",    "signingSecret": "H+WPXpCaBeLkd5pukqMoqWLZnL/5yEscexA73H7Uffw="    } 
```

アプリを Exchange マーケットプレースに登録するユーザージャーニーと情報フロー