GUI を使用する場合

GUI を使用して MFA E メール・チャネルを構成できます。

1. App ID ダッシュボードの**「Cloud Directory」>「多要素認証」**タブに移動します。

2. **「設定」タブの「多要素認証の有効化」**ボックスで MFA を **「有効」に切り替えます。 MFA が拡張セキュリティー・イベントとして課金されることを承認する確認を行います。 デフォルトでは、「E メール」が「認証方式」**として選択されています。

3. **「E メール・チャネル (Email channel)」タブで、「E メール・テンプレート (Email template)」**を確認します。 用意された文言のテンプレートを送信するか、独自のメッセージを作成するかを選択できます。 HTML が正しくタグ付けされていることを確認してください。 コンソールでは、パラメータを追加したり、画像を挿入したりできる。 メッセージの 言語を 変更するには、 APIを使って言語を設定します。 ただし、メッセージの内容と変換については、ご自身の責任になります。 以下の表を参照して、このメッセージ、およびその他の送信できるすべてのメッセージで使用できるパラメーターのリストを確認してください。 パラメーターによってプルされた情報をユーザーが指定していない場合は、ブランクとして表示されます。

   MFAメッセージパラメータ

   パラメーター	説明
   %{display.logo}	ログイン・ウィジェットのために構成したイメージを表示します。
   %{user.displayName}	アプリとやり取りするときに使用する、ユーザーが選択した画面名を表示します。
   %{user.email}	ユーザーが登録した E メール・アドレスを表示します。
   %{user.username}	認証方式がユーザー名とパスワードに設定されているとき、ユーザーが指定したユーザー名を表示します。
   %{user.firstName}	ユーザーが指定した名を表示します。
   %{user.formattedName}	ユーザーのフルネームを表示します。
   %{user.lastName}	ユーザーが指定した姓を表示します。
   %{mfa.code}	ワンタイム MFA 検証コードを表示します。

   パラメーターによってプルされた情報をユーザーが指定していない場合は、ブランクとして表示されます。

API を使用する場合

以下の前提条件を満たしていることを確認してください。

• App ID インスタンスのテナント ID。 この ID は、ダッシュボードの**「サービス資格情報」**セクションにあります。
• Identity and Access Management (IAM) トークン。 IAM トークンの取得については、IAM の資料を参照してください。

MFA を有効にするには、以下のようにします。

1. /config/cloud_directory/mfa を isActive に設定した MFA 構成を使用して true エンドポイントに PUT 要求を行うことによって、MFA チャネルを有効にします。

   curl -X PUT https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/config/cloud_directory/mfa \
      --header 'Content-Type: application/json' \
      --header 'Accept: application/json' \
      --header 'Authorization: Bearer <IAMToken>' \
      -d '"isActive": true'
   

2. MFA チャネルを有効にするには、 /mfa/channels/<channel> エンドポイントに MFA 設定を含む PUT リクエストを行います。 isActive を true に設定すると、MFA チャネルが有効になります。

   $ curl -X PUT https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/mfa/channels/email \
      --header 'Content-Type: application/json' \
      --header 'Accept: application/json' \
      --header 'Authorization: Bearer <IAMToken>' \
      -d '"isActive": true'
   

カスタム E メール送信者を使用するように App ID Cloud Directory インスタンスが構成されている場合、MFA はその同じ送信者を使用してワンタイム・コードを送信します。 詳しくは、Cloud Directory の資料を参照してください。

開始前に

App ID はVonage（正式にはNexmo）を使ってMFA SMSワンタイムコードを送信している。

• Vonage API 鍵と秘密を取得します。 Vonage API 鍵と秘密は Vonage ダッシュボードのアカウント設定ページにあります。 クレデンシャルの取得方法の詳細については、 Vonageのドキュメントをご確認ください。

• 送信者 ID またはfrom番号を Vonage に登録します。 このfrom番号は、SMS の送り主が誰か、ユーザーの電話に表示されるときの番号です。 国によっては、Vonage で英数字の送信者 ID をサポートしています。 App ID は、Vonage の送信者 ID として入力された値を使用します。 したがって、Vonage によってサポートされている場合は、それらの ID を App ID で使用できます。

GUI を使用する場合

GUI を使用して MFA を構成する方法について詳しくは、Cloud Directory を参照してください。

1. App ID ダッシュボードの**「Cloud Directory」>「多要素認証」**タブに移動します。

2. **「設定」タブの「多要素認証の有効化」**ボックスで MFA を **「有効」**に切り替えます。 MFA が拡張セキュリティー・イベントとして課金されることを承認する確認を行います。

3. **「認証方式」として「SMS」**を選択します。

4. **「SMS チャネル (SMS channel)」**タブで Vonage のユーザー・アカウント情報を構成します。

   1. Vonage にまだアカウントがない場合は、 ここで作成してください。

   2. Vonage ダッシュボードから**「SMS」**をクリックします。

   3. **「自分でコーディングする (Code it yourself)」**セクションで API 鍵をコピーし、それを App ID ダッシュボードの **「鍵 (key)」**ボックスに貼り付けます。

   4. Vonage ダッシュボードの**「API 秘密 (API secret)」をコピーしてApp ID ダッシュボードの「秘密 (Secret)」**ボックスに貼り付けます。

   5. メッセージを送信するIDを入力してください。 有効な番号形式は、 E.164 国際番号形式に従う。 例えば、米国の電話番号は +19998887777 のような形をしている。 プラス (+) 記号で始まる国別コードと、国内の加入者番号の両方を指定する必要があります。 国によっては、Vonage で英数字の送信者 ID をサポートしています。 App ID は、Vonage の送信者 ID として入力された値を使用します。 したがって、Vonage によってサポートされている場合は、それらの ID を App ID で使用できます。

API を使用する場合

API の使用を開始する前に、以下の前提条件を満たしていることを確認してください。

• App ID インスタンスのテナント ID。 この ID は、ダッシュボードの**「サービス資格情報」**セクションにあります。
• Identity and Access Management (IAM) トークン。 IAM トークンの取得については、IAM の資料を参照してください。

1. /config/cloud_directory/mfa を isActive に設定した MFA 構成を使用して true エンドポイントに PUT 要求を行うことによって、MFA チャネルを有効にします。

   curl -X PUT https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/config/cloud_directory/mfa \
   --header 'Content-Type: application/json' \
   --header 'Accept: application/json' \
   --header 'Authorization: Bearer <IAMToken>' \
   -d '{"isActive": true}'
   

2. MFA チャネルを有効にするには、 /mfa/channels/<channel> エンドポイントに MFA 設定を含む PUT リクエストを行います。 isActive を true に設定すると、MFA チャネルが有効になります。 config には Nexmo API 鍵と秘密、およびfrom番号が取り込まれます。

   curl -X PUT https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/mfa/channels/nexmo' \
   --header 'Content-Type: application/json' \
   --header 'Accept: application/json' \
   --header 'Authorization: Bearer <IAMToken>' \
   -d '{
      "isActive": true,
      "config": {
         "key": "<nexmoKey>",
         "secret": "<nexmoSecret>",
         "from": <senderPhoneNumber>
      }
   }'
   

3. チャンネルが正常に設定されたら、コンソールのテストボタンを使用するか、管理APIを使用して、Nexmoの設定と接続が正しく設定されていることを確認します。

   curl -X PUT https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/config/cloud_directory/sms_dispatcher/test \
   --header 'Content-Type: application/json' \
   --header 'Accept: application/json' \
   --header 'Authorization: Bearer <IAMToken>' \
   -d '{"phone_number": "+1 999 999 9999"}'
   

開始前に

拡張を登録する前に、次の前提条件となるものを必ず入手しておいてください。

• App ID インスタンスのテナント ID。 この ID は、ダッシュボードの**「アプリケーション」**セクションで見つかります。
• Identity and Access Management (IAM) トークン。 IAM トークンの取得については、IAM の資料を参照してください。

拡張機能を操作するうえでの制約と制限事項について詳しくは、App ID の制約事項を参照してください。

pre-mfa の構成

pre-mfa (MFA の前) 拡張を使用すると、ユーザーがアプリケーションと対話する際に、2 番目の形式の認証を入力する必要がないようにするための基準を定義できます。

1. ユーザーがアプリケーションに正常にサインインすると、App ID によって POST 要求が拡張に送信されます。
2. 拡張では、POST 要求からの情報を使用して、定義された基準に基づいて、その特定のユーザーが第 2 認証要素の要件をスキップできるかどうかを判断します。
3. 構成では、App ID に、{'skipMfa': true} のような JSON 応答を返します。
4. App ID では、構成からの応答に基づいて、MFA フローを続けるか、またはアプリケーションに対するアクセス権限を付与します。

デフォルトでは、拡張ポイントへの要求中にエラーが発生した場合、App ID はユーザーが MFA を完了することを求めます。

pre-MFA 拡張を構成するには、次の手順を実行します。

1. ユーザーが認証の第 2 要素をスキップできるようになる前に、ユーザーに満たしてもらいたい基準を定義します。 この基準がよく分からない場合は、次の各例を確認して理解してください。

   MFAをスキップする基準例

   ユース・ケースの例	検証の例
   ユーザーに、1 日に 1 回だけ第 2 認証要素を提供することを求める場合。	last_successful_first_factor が同日内であることを検証するように拡張を構成します。
   第 2 要素を毎回提供する必要のない承認済みのユーザーの許可リストがある場合。	username または user_id が許可リストに含まれていることを検証するように拡張を構成します。
   デスクトップのアプリにアクセスするユーザーには、第 2 要素を毎回提供することを求めない場合。	device_type が web に設定されていることを検証するように拡張を構成します。

2. 基準が分かっている場合は、POST 要求を listen できる拡張を構成します。 エンドポイントは、App ID から送信されるペイロードを読み取れる必要があります。 MFA フローの開始前に App ID によって送信される本文の形式は、{"jws": "jws-format-string"}です。 拡張によって、ペイロードをデコードおよび検証することもできます。そのペイロードの内容は JSON オブジェクトで、スキーマの {"skipMfa": Boolean }が含まれた JSON 応答を返します。 例えば、{'skipMfa': true} などです。

   App ID、内線ポイントに転送される情報。

   情報	説明
   correlation_id	MFA セッションごとに生成される乱数。 pre-mfa 拡張と post-mfa 拡張の両方がある場合、この数は同じセッションについてそれぞれ同じです。 例えば、3bb9236c-792f-4cca-8ae1-ada754cc4555 です。
   extension	拡張の名前。 このユース・ケースの場合、拡張の名前は premfa です。
   device_type	ユーザーがアプリケーションにアクセスするために使用するデバイスのタイプ。 オプションとして、web と mobile があります。
   source_ip	アプリに要求を行うデバイスの IP アドレス。 例えば、127.0.0.1 です。
   headers	ユーザーがアプリにサインインしようとするときに、ブラウザーによって返される情報。 このヘッダーは、{"user-agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X x.y; rv:42.0) Gecko/20100101 Firefox/42.0"} のようになります。
   tenant_id	アプリケーションのテナント ID。
   client_id	アプリケーションのクライアント ID。
   user_id	認証要求を行うユーザーの ID。 例えば、11112222-3333-4444-2222-555522226666 です。
   username	認証要求を行うユーザーのユーザー名。 例えば、testuser@email.com です。
   application_type	アプリケーションのタイプ。 例えば、アプリケーションがシングル・ページの JavaScript Web アプリの場合、browserapp が返されます。 オプションとして、browserapp、serverapp、mobileapp があります。
   first_name	ユーザーの名。
   last_name	ユーザーの姓。
   last_successful_first_factor	ユーザーが最後に資格情報を正しく入力した日時。 例えば、1660032586651 です。
   last_successful_mfa	ユーザーが最後に完全な MFA フローを完了した日時。 例えば、1660032586651 です。

   エクステンションの例を見るには、 サンプルをご覧ください。

3. config/cloud_directory/mfa/extensions/premfa に PUT 要求を行って、App ID のインスタンスに拡張を登録します。 構成には、拡張の URL と、エンドポイントにアクセスするために必要なすべての許可情報が含まれています。 開発の場合は、isActive を false に設定してください。 有効にする前に、構成を必ずテストしてください。

   curl -X PUT https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/config/cloud_directory/mfa/extensions/premfa' \
   --header 'Content-Type: application/json' \
   --header 'Accept: application/json' \
   --header 'Authorization: Bearer <IAMToken>' \
   -d '{
      "isActive": false,
      "config": {
         "url": "<extensionsURL>",
         "headers": {
               "Authorization": "<customExtensionAuthorizationHeader>"
            }
      }
   }'
   

   接続が暗号化されるように、extensions_URL に HTTP ではなく HTTPS を常に使用することを強くお勧めします。

4. 拡張機能が正常に構成されたら、テスト API を使用してエンドポイントが正しく機能することを確認します。 App ID は、サンプル値を使用して、構成済みの拡張機能に POST 要求を行います。

   curl -X POST https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/config/cloud_directory/mfa/extensions/premfa/test \
   --header 'Content-Type: application/json' \
   --header 'Accept: application/json' \
   --header 'Authorization: Bearer <IAMToken>'
   

5. isActive を true に設定する PUT 要求を行って、拡張を有効にします。

   curl -X PUT https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/config/cloud_directory/mfa/extensions/premfa \
   --header 'Content-Type: application/json' \
   --header 'Accept: application/json' \
   --header 'Authorization: Bearer <IAMToken>' \
   -d '{"isActive": true}'
   

   拡張を無効にするには、isActive を false に設定します。

post-mfa の構成

拡張を構成し、App ID に登録すると、ID の第 2 要素が存在している認証を試みるたびに、サービスによってその拡張が呼び出されます。 ユーザーの判別をよりスマートに行うために、この情報を使用できます。 例えば、ヒューリスティックとルールに post-mfa (MFA の後) 拡張コレクション情報を使用し、pre-mfa 拡張を用いてこれらを強制することができます。

1. ユーザーがアプリケーションに正常にサインインすると、ユーザーの第 2 認証要素の入力を求めるプロンプトが表示されます。

2. その第 2 認証要素が正常に入力されると、次の 2 つのアクションが同時に起こります。

   1. App ID によって、構成した拡張にサインインに関する情報が送信されます。

   2. ユーザーがアプリケーションにリダイレクトされます。

post-MFA 拡張を構成するには、次の手順を実行します。

1. POST 要求を listen できる拡張ポイントを構成します。 エンドポイントは、App ID によって送信されたペイロードを読み取れる必要があります。 エンドポイントは、必要に応じて デコードおよび検証することもでき、App ID によって返された JSON ペイロードが第三者によって全く変更されていないことを確認できます。 次の情報を含む、{"jws": "jws-format-string"} という形式でフォーマットされたストリングが返されます。

   App ID、内線ポイントに転送される情報。

   情報	説明
   correlation_id	MFA セッションごとに生成される乱数。 pre-mfa 拡張と post-mfa 拡張の両方がある場合、この数はそれぞれについて同じです。 例えば、3bb9236c-792f-4cca-8ae1-ada754cc4555 です。
   extension	拡張の名前。 このユース・ケースの場合、拡張の名前は postmfa です。
   status	MFA の状況。 オプションとして、success と failed があります。
   reason	MFA が失敗した理由。 例えば、user locked out - exceeded maximum number of verification attempts です。
   device_type	ユーザーがアプリケーションにアクセスするために使用するデバイスのタイプ。 オプションとして、web と mobile があります。
   source_ip	アプリに要求を行うデバイスの IP アドレス。 例えば、127.0.0.1 です。
   headers	ユーザーがアプリにサインインしようとするときに、ブラウザーによって返される情報。 このヘッダーは、{"user-agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X x.y; rv:42.0) Gecko/20100101 Firefox/42.0"} のようになります。
   tenant_id	アプリケーションのテナント ID。
   client_id	アプリケーションのクライアント ID。
   user_id	認証要求を行うユーザーの ID。
   username	認証要求を行うユーザーのユーザー名。 例えば、testuser@email.com です。
   application_type	アプリケーションのタイプ。 例えば、アプリケーションがシングル・ページの JavaScript Web アプリの場合、browserapp が返されます。 オプションとして、browserapp、serverapp、mobileapp があります。
   first_name	ユーザーの名。
   last_name	ユーザーの姓。

2. config/cloud_directory/mfa/extensions/postmfa に PUT 要求を行って、App ID のインスタンスに拡張を登録します。 構成には、拡張の URL と、エンドポイントにアクセスするために必要なすべての許可情報が含まれています。 開発の場合は、isActive を false に設定してください。 有効にする前に、構成を必ずテストしてください。

   curl -X PUT https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/config/cloud_directory/mfa/extensions/postmfa' \
   --header 'Content-Type: application/json' \
   --header 'Accept: application/json' \
   --header 'Authorization: Bearer <IAMToken>' \
   -d '{
      "isActive": false,
      "config": {
         "url": "<extensionsURL>",
         "headers": {
               "Authorization": "<customExtensionAuthorizationHeader>"
            }
      }
   }'
   

   接続が暗号化されるように、extensions_URL に HTTP ではなく HTTPS を常に使用することを強くお勧めします。

3. 拡張機能が正常に構成されたら、テスト API を使用して、エンドポイントが正しく機能することを確認します。 App ID は、サンプル値を使用して、構成済みの拡張機能に POST 要求を行います。

   curl -X POST https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/config/cloud_directory/mfa/extensions/postmfa/test \
   --header 'Content-Type: application/json' \
   --header 'Accept: application/json' \
   --header 'Authorization: Bearer <IAMToken>'
   

4. isActive を true に設定して、拡張を有効にします。

   curl -X PUT https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/config/cloud_directory/mfa/extensions/postmfa \
   --header 'Content-Type: application/json' \
   --header 'Accept: application/json' \
   --header 'Authorization: Bearer <IAMToken>' \
   -d '{"isActive": true}'
   

   拡張を無効にするには、isActive を false に設定します。