**引入全新的主机体验 AWS WAF**

现在，您可以使用更新的体验访问控制台中任意位置的 AWS WAF 功能。有关更多详细信息，请参阅[使用控制台](https://docs.aws.amazon.com/waf/latest/developerguide/working-with-console.html)。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# AWS WAF 移动 SDK 的工作原理
<a name="waf-mobile-sdk-how-it-works"></a>

本节介绍 AWS WAF 移动 SDK 的类、属性和操作是如何协同工作的。

移动设备 SDKs 为您提供可配置的令牌提供商，可用于令牌检索和使用。令牌提供程序会验证您允许的请求是否来自合法客户。当你向你保护的 AWS 资源发送请求时 AWS WAF，你需要在 Cookie 中加入令牌来验证请求。您可以手动处理令牌 Cookie，也可以让令牌提供程序为您处理。

本节介绍移动软件开发工具包中包含的类、属性和方法之间的交互。有关软件开发工具包规范，请参阅 [AWS WAF 移动 SDK 规范](waf-mobile-sdk-specification.md)。

## 令牌检索和缓存
<a name="waf-mobile-sdk-how-token-basics"></a>

在移动应用程序中创建令牌提供程序实例时，您可以配置您希望它如何管理令牌和令牌检索。您的主要选择是如何维护有效的、未过期的令牌，以便在应用的 web 请求中使用：
+ **启用后台刷新**：这是默认设置。令牌提供程序会在后台自动刷新令牌并将其缓存。启用后台刷新后，当您调用 `getToken()` 时，该操作将检索缓存的令牌。

  令牌提供程序以可配置的时间间隔执行令牌刷新，以便在应用程序处于活动状态时，缓存中始终有未过期的令牌可用。当您的应用程序处于非活动状态时，后台刷新会暂停。有关此问题的信息，请参阅 [在应用程序处于非活动状态后检索令牌](#waf-mobile-sdk-how-back-from-inactive)。
+ **禁用后台刷新**：您可以禁用后台令牌刷新，然后仅按需检索令牌。按需检索的令牌不会被缓存，您可以根据需要检索多个令牌。每个令牌都独立于您检索的任何其他令牌，并且每个令牌都有自己的时间戳，用于计算到期时间。

  禁用后台刷新后，您可以选择以下令牌检索：
  + **`getToken()`**— 当您在禁`getToken()`用后台刷新的情况下呼叫时，调用会同步从中检索新令牌。 AWS WAF这可能是一个阻塞调用，如果在主线程上调用，可能会影响应用程序的响应速度。
  + **`onTokenReady(WAFTokenResultCallback)`**：此调用异步检索新令牌，然后在令牌准备就绪时在后台线程中调用提供的结果回调。

### 令牌提供程序如何重试失败的令牌检索
<a name="waf-mobile-sdk-how-token-retrieval-retries"></a>

检索失败时，令牌提供程序会自动重试令牌检索。重试最初是使用指数回退来执行的，起始重试等待时间为 100 ms。有关指数重试的信息，请参阅 [AWS中的错误重试和指数回退](https://docs.aws.amazon.com/general/latest/gr/api-retries.html)。

当重试次数达到配置的 `maxRetryCount` 时，令牌提供程序要么停止尝试，要么切换为每 `maxErrorTokenRefreshDelayMsec` 毫秒尝试一次，具体取决于令牌检索的类型：
+ **`onTokenReady()`**：令牌提供程序切换到两次尝试之间的等待 `maxErrorTokenRefreshDelayMsec` 毫秒，并继续尝试检索令牌。
+ **后台刷新**：令牌提供程序切换到两次尝试之间的等待 `maxErrorTokenRefreshDelayMsec` 毫秒，并继续尝试检索令牌。
+ **禁用后台刷新时按需 `getToken()` 调用**：令牌提供程序停止尝试检索令牌并返回之前的令牌值，如果没有以前的令牌，则返回空值。

## 令牌检索重试场景
<a name="waf-mobile-sdk-how-token-retrieval-retry-scenarios"></a>

当令牌提供者尝试检索令牌时，可能会导致自动重试，具体取决于令牌获取流中令牌检索失败的位置。本节列出可能出现自动重试的地方。
+ **通过 /inputs 或 /verify 获取或验证 AWS WAF 挑战赛：**
  + 当提出获取和验证 AWS WAF 质询的请求失败时，可能会导致自动重试。
  + 您可能会观察到此处发生的自动重试以及 `socketTimeoutException` 错误。这可能有多种原因，包括：
    + 网络带宽低：确认您的网络连接设置
    + 变更后的应用程序集成 URL：确认集成 URL 未与控制台上显示的内容相比进行修改 AWS WAF 
  + 自动重试次数可通过 `maxRetryCount()` 功能进行配置
+ **刷新令牌：**
  + 通过令牌处理程序发出刷新令牌的请求时，可能会导致自动重试。
  + 此处的自动重试次数可通过 `maxRetryCount()` 功能进行配置。

通过设置 `maxRetryCount(0)` 实现非自动重试的配置。

## 令牌免疫时间和后台刷新
<a name="waf-mobile-sdk-how-token-immunity"></a>

您在 Web ACL 中配置的令牌免疫时间与您在 AWS WAF 移动 SDK 中设置的令牌刷新间隔无关。启用后台刷新后，SDK 会使用 `tokenRefreshDelaySec()`，按照您指定的间隔刷新令牌。这可能导致多个有效令牌同时存在，具体取决于您配置的免疫时间。

要防止出现多个有效令牌，您可以禁用后台刷新，并使用 `getToken()` 功能管理移动应用程序中的令牌生命周期。

## 在应用程序处于非活动状态后检索令牌
<a name="waf-mobile-sdk-how-back-from-inactive"></a>

仅当您的应用类型被视为处于活动状态时，才会执行后台刷新：
+ **iOS**：当应用程序位于前台时，将执行后台刷新。
+ **Android**：无论是在前台还是在后台，都是在应用程序未关闭时执行后台刷新。

如果您的应用程序处于任何不支持后台刷新的状态的时间超过您配置的 `tokenRefreshDelaySec` 秒数，则令牌提供程序会暂停后台刷新。例如，对于 iOS 应用程序，如果 `tokenRefreshDelaySec` 为 300 并且应用程序关闭或进入后台超过 300 秒，则令牌提供程序将停止刷新令牌。当应用程序恢复到活动状态时，令牌提供程序会自动重新启动后台刷新。

当您的应用程序恢复到活动状态时，请调用 `onTokenReady()`，以便在令牌提供程序检索并缓存新令牌时通知您。不要随便调用 `getToken()`，因为缓存中可能还不包含当前有效的令牌。

## 应用程序集成 URL。
<a name="waf-mobile-sdk-application-integration-url"></a>

移 AWS WAF 动 SDK 应用程序集成 URL 指向您为应用程序集成启用的 Web ACL。此 URL 将请求路由到正确的后端服务器，并将其与您的客户关联。此 URL 不具备硬安全控制功能，因此公开集成 URL 不会导致安全风险。

从技术层面，您可以修改所提供的集成 URL，且仍能获取令牌。但是，我们不建议这样做，因为您可能无法查看质询解决率，或者由于 `socketTimeoutException` 错误而遭遇令牌检索失败。

## 依赖项
<a name="waf-mobile-sdk-dependencies"></a>

每个可下载的 AWS WAF 移动 SDK 都包含一个自述文件，其中列出了其特定版本的 SDK 的依赖关系。有关移动 SDK 版本的依赖项，请参阅自述文件。

## 混淆/ProGuard （仅限安卓 SDK）
<a name="waf-mobile-sdk-obfuscation"></a>

如果您使用诸如此类的混淆或缩小产品 ProGuard，则可能需要排除某些命名空间以确保移动 SDK 正常运行。查看移动 SDK 版本的自述文件，以查找命名空间和排除规则的列表。