多因子认证 (MFA)

通过 Cloud Directory for IBM Cloud® App ID，您可以在应用程序登录流期间需要多个认证因子。第二个认证因素不仅通过确认用户具有其凭证的知识，而且还可以访问其注册的电子邮件，电话号码或认证程序应用程序，从而提高应用程序的安全性。扩展 MFA 流程时，您可以配置 MFA 前和 MFA 后扩展，以在运行时做出定制决策，用户必须完成第二个因素，或者向您提供有关登录流程的分析信息。

支持 App ID MFA 作为 Cloud Directory 用户通过登录窗口小部件进行的 OAuth 2.0 授权代码流程的一部分。如果使用的是采用 SAML 2.0 的企业登录或使用的是社交登录，那么可以通过相应的身份提供者来启用 MFA。

请看下图，了解 MFA 流程在电子邮件或短信中的工作原理。

当用户成功登录到应用程序时，他们将完成第一个认证因子。然后，根据您的 MFA 配置，将向用户发送包含 6 数字代码的电子邮件或 SMS。

启用 MFA 后，App ID 登录窗口小部件每次用户尝试登录时都需要第二种形式的验证，除非配置了扩展。
用户应查看其手机或电子邮件以获取代码，然后将其输入到提供的屏幕中。
如果他们输入的代码与他们发送的代码匹配，那么用户将重定向回您的应用程序并登录。如果他们错误地输入了代码，那么第二个认证因子将失败，并且用户无法访问您的资源。

如果未配置电子邮件验证，那么 App ID 将在后台验证 MFA 通道。例如，如果为 MFA 配置电子邮件通道，并且未配置电子邮件验证，那么 App ID 将在首次成功 MFA 登录时验证电子邮件。但是，如果配置 SMS 通道，那么 App ID 将在首次成功登录时验证用户的电话号码。如果您正在使用 SMS 通道并希望验证电子邮件，请确保启用电子邮件验证。

配置电子邮件通道

可以配置 App ID 以通过电子邮件向用户发送 MFA 代码。

第一次启用 MFA 时，会发生以下两个情况：

缺省情况下，会选择电子邮件通道。您可以切换到 SMS 通道。
App ID 会自动注册已连接到 Cloud Directory 用户概要文件的主电子邮件。

如果用户的电子邮件尚未通过管理 API 或通过用户注册时的电子邮件验证进行确认，那么在用户成功验证 MFA 代码后，即会对其进行确认。

首次启用 MFA 时，缺省情况下会将其设置为使用电子邮件。可以将设置更改为使用 SMS，但不能同时配置这两者。

使用 GUI

可以通过 GUI 来配置 MFA 电子邮件通道。

导航至 App ID 控制面板的云目录 > 多因素身份验证选项卡。
在“设置”选项卡上的“启用多因素身份验证”框中，将 MFA 切换为“已启用”。确认您已了解 MFA 是作为高级安全事件收费的。缺省情况下，已选择电子邮件作为认证方法。

在电子邮件通道选项卡中，查看电子邮件模板。可以选择发送包含所提供文字的模板，也可以编写您自己的消息。请确保使用正确的 HTML 标记。在控制台中，您可以添加参数和插入图片。要更改信息的语言，可以使用 API 设置语言。不过，您要对信息的内容和转换负责。请查看下表，了解您可以在此信息和所有其他信息中使用的表格列表。如果用户未提供参数拉出的信息，那么会显示为空。

MFA 报文参数
参数	描述
`%{display.logo}`	显示为登录窗口小部件配置的图像。
`%{user.displayName}`	显示用户所选的在与应用程序交互时要使用的屏幕名称。
`%{user.email}`	显示用户的注册电子邮件地址。
`%{user.username}`	当认证方法设置为用户名和密码时，显示用户指定的用户名。
`%{user.firstName}`	显示用户的指定名字。
`%{user.formattedName}`	显示用户的全名。
`%{user.lastName}`	显示用户的指定姓氏。
`%{mfa.code}`	显示一次性 MFA 验证码。

如果用户未提供参数拉出的信息，那么会显示为空。

使用 API

确保您已满足以下先决条件：

App ID 实例的租户标识。此标识可以在仪表板的服务凭证部分中找到。
Identity and Access Management (IAM) 令牌。有关获取 IAM 令牌的帮助，请查看 IAM 文档。

要启用 MFA，请执行以下操作：

使用 MFA 配置向 /config/cloud_directory/mfa 端点发出 PUT 请求，将 isActive 设置为 true，从而启用 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'

使用 MFA 配置向 /mfa/channels/<channel> 端点发出 PUT 请求，启用 MFA 通道。 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'

如果您的 App ID 云目录实例被配置为与自定义电子邮件发件人一起工作，那么 MFA 将使用同一发件人发送一次性代码。有关更多信息，请参阅 Cloud Directory 文档。

配置 SMS 通道

可以向用户发送 SMS 消息以作为第二种形式的验证。启用 SMS 后，App ID 会自动尝试注册云目录用户配置文件中找到的第一个有效主电话号码。如果该号码无效或在用户概要文件中找不到电话号码，那么会显示注册窗口小部件，供用户添加号码。然后，该号码将成为用户概要文件的一部分，并且在验证后，会成为用于 MFA 的缺省号码。

最初启用 MFA 时，缺省情况下会将其设置为使用电子邮件。可以将设置更改为使用 SMS，但不能同时配置这两者。

准备工作

App ID 使用 Vonage（前身为 Nexmo）发送 MFA SMS 一次性代码。

获取 Vonage API 密钥和秘密。您可以在 Vonage 仪表板上的帐户设置页面找到 Vonage API 密钥和秘密。请查看 Vonage 文档，了解有关如何获取证书的更多信息。
在 Vonage 注册您的发件人 ID 或 from 号码。此 from 号码显示在用户手机上，用于表明 SMS 发送方。在某些国家/地区，Vonage 支持字母数字发件人 ID。App ID 使用您输入的值作为 Vonage 的发件人 ID。因此，如果 Vonage 支持这些 ID，您就可以在 App ID 中使用它们。

使用 GUI

要使用 GUI 来配置 MFA，请查看 Cloud Directory。

导航至 App ID 控制面板的云目录 > 多因素身份验证选项卡。
在“设置”选项卡上的“启用多因素身份验证”框中，将 MFA 切换为“已启用”。确认您已了解 MFA 是作为高级安全事件收费的。
选择 SMS 作为认证方法。
在短信通道选项卡中，配置您的 Vonage 帐户信息。
1. 如果您还没有 Vonage 账户。请进行创建。
2. 从 Vonage 仪表板单击 SMS。
3. 复制自行编码部分中的 API 密钥，并将其粘贴到 App ID 仪表板的密钥框中。
4. 复制 Vonage 仪表板中的 API 保密信息，并将其粘贴到 App ID 仪表板的保密信息框中。
5. 输入要发送信息的 ID。有效号码格式遵循 E.164 国际编号格式。例如，US 号码的形式为 +19998887777。必须同时指定国家/地区代码（以 + 号开头）和国家用户号。在某些国家/地区，Vonage 支持字母数字发件人 ID。App ID 使用您输入的值作为 Vonage 的发件人 ID。因此，如果 Vonage 支持这些 ID，您就可以在 App ID 中使用它们。

使用 API

开始使用 API 之前，请确保满足以下先决条件：

App ID 实例的租户标识。此标识可以在仪表板的服务凭证部分中找到。
Identity and Access Management (IAM) 令牌。有关获取 IAM 令牌的帮助，请查看 IAM 文档。

使用 MFA 配置向 /config/cloud_directory/mfa 端点发出 PUT 请求，将 isActive 设置为 true，从而启用 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}'

使用 MFA 配置向 /mfa/channels/<channel> 端点发出 PUT 请求，启用 MFA 通道。 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>
   }
}'

通道配置成功后，请使用控制台上的测试按钮或管理 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"}'

扩展 MFA

通过扩展，您可以将多因子认证的安全性提升到下一级别。通过对谁需要提供第二种形式的认证进行定制决策，您可以为用户提供更个人化的应用程序体验。您还可以使用扩展来审计 MFA 行为，例如失败的第二个表单认证数。

准备工作

注册扩展前，请确保具备以下前提条件：

App ID 实例的租户标识。此 ID 可在仪表板的“应用程序”部分找到。
Identity and Access Management (IAM) 令牌。有关获取 IAM 令牌的帮助，请查看 IAM 文档。

有关使用扩展的限制和限制的更多信息，请参阅 App ID 限制。

配置预 mfa

通过预 mfa 扩展，您可以定义允许用户在与应用程序交互时避免输入第二种形式的认证的条件。

当用户成功登录到应用程序时，App ID 会向扩展发送 POST 请求。
您的扩展使用 POST 请求中的信息来确定该特定用户是否可以根据您定义的条件跳过第二个认证因子需求。
您的配置将 JSON 响应返回到类似于 {'skipMfa': true} 的 App ID。
根据来自配置的响应，App ID 继续使用 MFA 流或授予对应用程序的访问权。

缺省情况下，如果请求扩展点期间发生错误，那么 App ID 要求用户完成 MFA。

要配置预 MFA 扩展，请执行以下操作:

定义您希望用户在能够跳过第二个认证因素之前满足的条件。如果您不确定，请查看以下示例以获取一些构想。

跳过 MFA 的标准示例
示例用例	示例验证
您希望用户每天仅提供一次第二个认证因子。	配置扩展以验证 `last_successful_first_factor` 是否在同一天内。
您具有已核准用户的允许列表，这些用户不需要每次都提供第二个因素。	配置扩展以验证 `username` 或 `user_id` 是否在允许列表中。
您不希望在桌面上访问应用程序的用户每次都提供第二个因素。	配置扩展以验证 `device_type` 是否设置为 `web`。

了解条件后，配置可侦听 POST 请求的扩展。端点必须能够读取来自 App ID的有效内容。在 MFA 流启动之前由 App ID 发送的主体的格式为: {"jws": "jws-format-string"}。您的扩展还可以解码和验证有效内容，内容为 JSON 对象，并返回具有以下模式的 JSON 响应: {"skipMfa": Boolean }。例如：{'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`	应用程序的租户标识。
`client_id`	应用程序的客户机标识。
`user_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`。

要查看示例扩展，请查看样本。

通过向 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 中始终使用 HTTPS 而不是 HTTP，以确保您的连接是加密的。

成功配置扩展后，通过使用测试 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>'

通过发出将 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注册该扩展时，服务会在每次存在第二因子标识的认证尝试后调用该扩展。您可以使用该信息为用户制定更好的决策。例如，您可以将“mfa 后”扩展集合信息用于您的启发式和规则，然后使用“mfa 前”扩展来实施这些信息。

当用户成功登录到应用程序时，系统会提示他们输入其第二个认证因子。
当第二个认证因子成功完成时，将同时执行两项操作:
1. App ID 将有关登录的信息发送到已配置的扩展。
2. 用户将重定向到您的应用程序。

要配置后 MFA 扩展，请执行以下操作:

配置可监听 POST 请求的扩展点。端点必须能够读取 App ID发送的有效内容。 (可选) 它还可以解码和验证第三方不会以任何方式变更 App ID 返回的 JSON 有效内容。将返回格式为 {"jws": "jws-format-string"} 的字符串，其中包含以下信息:

App ID转发给扩展点的信息。
信息	描述
`correlation_id`	为每个 MFA 会话生成的随机数。如果您同时具有前 mfa 和后 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`	应用程序的租户标识。
`client_id`	应用程序的客户机标识。
`user_id`	发出认证请求的用户的标识。
`username`	发出认证请求的用户的用户名。例如，`testuser@email.com`。
`application_type`	您的应用程序类型。例如，如果应用程序是单个页面 JavaScript Web 应用程序，那么将返回 `browserapp`。选项包括: `browserapp`，`serverapp` 和 `mobileapp`。
`first_name`	用户的名字。
`last_name`	用户姓氏。

通过向 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 中使用 HTTPS 而不是 HTTP，以确保连接是加密的。

成功配置扩展后，使用测试 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>'

通过将 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。