**の新しいコンソールエクスペリエンスの紹介 AWS WAF**

更新されたエクスペリエンスを使用して、コンソールの任意の場所で AWS WAF 機能にアクセスできるようになりました。詳細については、[「コンソールの使用](https://docs.aws.amazon.com/waf/latest/developerguide/working-with-console.html)」を参照してください。

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

# でのクライアントアプリケーション統合 AWS WAF
<a name="waf-application-integration"></a>

このセクションでは、インテリジェントな脅威統合 APIsと JavaScript CAPTCHA 統合 API を AWS WAF の機能で使用する方法について説明します。

 AWS WAF クライアントアプリケーション統合 APIs を使用して、クライアント側の保護と AWS サーバー側の保護パック (ウェブ ACL) 保護を組み合わせて、保護されたリソースにウェブリクエストを送信するクライアントアプリケーションが意図したクライアントであり、エンドユーザーが人間であることを確認します。

クライアント統合を使用して、サイレントブラウザのチャレンジと CAPTCHA パズルを管理し、ブラウザとエンドユーザーの応答が成功したことを証明するトークンを取得し、保護されたエンドポイントへのリクエストにこれらのトークンを含めます。 AWS WAF トークンの一般的な情報については、「」を参照してください[AWS WAF インテリジェントな脅威の軽減におけるトークンの使用](waf-tokens.md)。

クライアント統合を、リソースへのアクセスに有効なトークンを必要とする保護パック (ウェブ ACL) 保護と組み合わせます。次のセクション [インテリジェントな脅威統合と AWS マネージドルール](waf-application-integration-with-AMRs.md) に示されているような、チャレンジトークンをチェックおよびモニタリングするルールグループを使用できるため、「[CAPTCHA および Challengeの AWS WAF](waf-captcha-and-challenge.md)」の説明に従い、CAPTCHA および Challenge ルールアクションを使用してチェックします。

AWS WAF は、JavaScript アプリケーションには 2 つのレベルの統合を提供し、モバイルアプリケーションには 1 つのレベルの統合を提供します。
+ **インテリジェントな脅威統合** – クライアントアプリケーションを検証し、 AWS トークンの取得と管理を提供します。これは、ルールアクションによって提供される機能に似ています AWS WAF Challenge。この機能により、クライアントアプリケーションは、`AWSManagedRulesACFPRuleSet` マネージドルールグループ、`AWSManagedRulesATPRuleSet` マネージドルールグループ、および `AWSManagedRulesBotControlRuleSet` マネージドルールグループのターゲットを絞った保護レベルと完全に統合されます。

  インテリジェントな脅威統合 APIs AWS WAF 、サイレントブラウザチャレンジを使用して、クライアントが有効なトークンを取得した後にのみ、保護されたリソースへのログイン試行やその他の呼び出しが許可されるようにします。API は、クライアントアプリケーションセッションのトークン認可を管理し、クライアントに関する情報を収集して、ボットによる操作か、人間による操作かを判断します。
**注記**  
JavaScript ならびに Android および iOS モバイルアプリケーションで使用できます。
+ **CAPTCHA 統合** – アプリケーションで管理するカスタマイズされた CAPTCHA パズルでエンドユーザーを検証します。これはルールアクションによって AWS WAF CAPTCHA提供される機能に似ていますが、パズルの配置と動作をさらに制御できます。

  この統合では、JavaScript のインテリジェントな脅威統合を活用してサイレントチャレンジを実行し、顧客のページに AWS WAF トークンを提供します。
**注記**  
これは JavaScript アプリケーションで使用できます。

**Topics**
+ [インテリジェントな脅威統合と AWS マネージドルール](waf-application-integration-with-AMRs.md)
+ [AWS WAF クライアントアプリケーション統合 APIs へのアクセス](waf-application-integration-location-in-console.md)
+ [AWS WAF JavaScript 統合](waf-javascript-api.md)
+ [AWS WAF モバイルアプリケーションの統合](waf-mobile-sdk.md)

# インテリジェントな脅威統合と AWS マネージドルール
<a name="waf-application-integration-with-AMRs"></a>

このセクションでは、インテリジェントな脅威統合 APIs AWS Managed Rules ルールグループと連携する方法について説明します。

インテリジェントな脅威統合 API は、インテリジェントな脅威ルールグループを使用する保護パック (ウェブ ACL) と連携して、これらの高度なマネージドルールグループの全機能を有効にします。
+ AWS WAF Fraud Control アカウント作成不正防止 (ACFP) マネージドルールグループ `AWSManagedRulesACFPRuleSet`。

  アカウント作成の不正行為は、サインアップボーナスの受け取りやなりすましなどの目的で、攻撃者がアプリケーションで無効なアカウントを作成するオンライン上の違法行為です。ACFP マネージドルールグループには、不正なアカウント作成の試みの一部の可能性があるリクエストをブロック、ラベル付け、管理するためのルールが含まれています。API は、ACFP ルールが使用する微調整されたクライアントブラウザの検証および人間のインタラクティビティに関する情報を有効にし、有効なクライアントトラフィックを悪意のあるトラフィックから分離します。

  詳細については、「[AWS WAF Fraud Control アカウント作成不正防止 (ACFP) ルールグループ](aws-managed-rule-groups-acfp.md)」および「[AWS WAF Fraud Control アカウント作成不正防止 (ACFP)](waf-acfp.md)」を参照してください。
+ AWS WAF Fraud Control アカウント乗っ取り防止 (ATP) マネージドルールグループ `AWSManagedRulesATPRuleSet`。

  アカウント乗っ取りは、攻撃者が個人のアカウントへの不正アクセスを得るオンラインの違法行為です。ATP マネージドルールグループには、悪意のあるアカウント乗っ取りの試行の一部の可能性があるリクエストをブロック、ラベル付け、管理するためのルールが含まれています。API は、ATP ルールが使用する微調整されたクライアント検証および動作集約を有効にし、有効なクライアントトラフィックを悪意のあるトラフィックから分離します。

  詳細については、「[AWS WAF Fraud Control アカウント乗っ取り防止 (ATP) ルールグループ](aws-managed-rule-groups-atp.md)」および「[AWS WAF Fraud Control アカウント乗っ取り防止 (ATP)](waf-atp.md)」を参照してください。
+  AWS WAF Bot Control マネージドルールグループ のターゲットを絞った保護レベル`AWSManagedRulesBotControlRuleSet`。

  ボットには、ほとんどの検索エンジンやクローラーなど、自己識別型や便利なボットから、ウェブサイトを狙って動作し、自己識別を行わない悪意のあるものまでの範囲に及びます。Bot Control マネージドルールグループは、ウェブトラフィックのボットアクティビティをモニタリング、ラベル付け、管理するルールを提供します。このルールグループのターゲットを絞った保護レベルを使用すると、ターゲットルールは API が提供するクライアントセッション情報を使用し、悪意のあるボットをより適切に検出します。

  詳細については、「[AWS WAF Bot Control ルールグループ](aws-managed-rule-groups-bot.md)」および「[AWS WAF ボットコントロール](waf-bot-control.md)」を参照してください。

これらのマネージドルールグループのいずれかを保護パック (ウェブ ACL) に追加するには、手順 [ACFP マネージドルールグループをウェブ ACL に追加](waf-acfp-rg-using.md)、[ATP マネージドルールグループを保護パック (ウェブ ACL) に追加](waf-atp-rg-using.md)、[AWS WAF Bot Control マネージドルールグループをウェブ ACL に追加する](waf-bot-control-rg-using.md) を参照してください。

**注記**  
マネージドルールグループは現在、トークンが不足しているリクエストをブロックしていません。トークンが不足しているリクエストをブロックするには、アプリケーション統合 API を実装した後、[有効な AWS WAF トークンを持たないリクエストのブロック](waf-tokens-block-missing-tokens.md) のガイダンスに従ってください。

# AWS WAF クライアントアプリケーション統合 APIs へのアクセス
<a name="waf-application-integration-location-in-console"></a>

このセクションでは、 AWS WAF コンソールでアプリケーション統合 APIsを見つける場所について説明します。

JavaScript 統合 API は一般利用可能で、JavaScript を実行するブラウザや他のデバイスに使用できます。

AWS WAF は、Android および iOS モバイルアプリ用のカスタムのインテリジェントな脅威統合 SDKs を提供します。
+ Android モバイルと TV アプリの場合、 SDK は Android API バージョン 23 (Android バージョン 6) 以降で動作します。Android バージョンの詳細については、「[SDK Platform リリースノート](https://developer.android.com/tools/releases/platforms)」を参照してください。
+ iOS モバイルアプリの場合、 SDK は iOS バージョン 13 以降で動作します。iOS バージョンの詳細については、「[iOS と iPadOS のリリースノート](https://developer.apple.com/documentation/ios-ipados-release-notes)」を参照してください。
+ Apple TV アプリの場合、SDK は tvOS バージョン 14 以降で動作します。tvOS バージョンの詳細については、「[tvOS のリリースノート](https://developer.apple.com/documentation/tvos-release-notes)」を参照してください。

**コンソールで統合 API にアクセスするには**

1. にサインイン AWS マネジメントコンソール し、[https://console.aws.amazon.com/wafv2/homev2](https://console.aws.amazon.com/wafv2/homev2) で AWS WAF コンソールを開きます。

1. ナビゲーションペインの **[アプリケーション統合]** を選択してから、関心のあるタブを選択します。
   + **インテリジェントな脅威に対応した統合** は、JavaScript とモバイルアプリケーションで使用できます。

     タブには次のものが含まれています。
     + インテリジェントな脅威に対応したアプリケーション統合が有効になっている保護パック (ウェブ ACL) のリスト。リストには、`AWSManagedRulesACFPRuleSet` マネージドルールグループ、`AWSManagedRulesATPRuleSet` マネージドルールグループ、または `AWSManagedRulesBotControlRuleSet` マネージドルールグループのターゲットを絞った保護レベルを使用する各保護パック (ウェブ ACL) が含まれます。インテリジェントな脅威に対応した API を実装するときは、統合する保護パック (ウェブ ACL) の統合 URL を使用します。
     + ユーザーがアクセスできる API。JavaScript API は常に利用可能です。モバイル SDK にアクセスするには、「[AWSへのお問い合わせ](https://aws.amazon.com/contact-us)」にてサポート担当者までお問い合わせください。
   + **CAPTCHA 統合**は、JavaScript アプリケーションで使用できます。

     タブには次のものが含まれています。
     + 統合で使用する統合 URL。
     + クライアントアプリケーションドメイン用に作成した API キー。CAPTCHA API を使用するには、暗号化された API キーが必要です。これにより、クライアントは自分のドメインから AWS WAF CAPTCHA にアクセスできるようになります。統合するクライアントごとに、クライアントのドメインを含む API キーを使用します。これらの要件とキーの管理の詳細については、「[JS CAPTCHA API の API キーの管理](waf-js-captcha-api-key.md)」を参照してください。

# AWS WAF JavaScript 統合
<a name="waf-javascript-api"></a>

このセクションでは、 AWS WAF JavaScript 統合を使用する方法について説明します。

JavaScript 統合 APIs を使用して、JavaScript を実行するブラウザやその他のデバイスに AWS WAF アプリケーション統合を実装できます。

CAPTCHA パズルとサイレントチャレンジは、ブラウザが HTTPS エンドポイントにアクセスしている場合にのみ実行できます。トークンを取得するには、ブラウザクライアントが安全なコンテキストで実行されている必要があります。
+ インテリジェントな脅威に対応した API を使用すると、クライアント側のサイレントブラウザのチャレンジを通じてトークン認可を管理し、保護されたリソースに送信するリクエストにトークンを含めることができます。
+ CAPTCHA 統合 API にインテリジェントな脅威に対応した API が追加され、クライアントアプリケーションでの CAPTCHA パズルの配置と特性をカスタマイズすることができるようになりました。この API は、インテリジェントな脅威に対応した API を活用し、エンドユーザーが CAPTCHA パズルの完成に成功した後にページで使用する AWS WAF トークンを取得します。

これらの統合を使用すると、クライアントによるリモートプロシージャコールに有効なトークンが含まれていることを確認できます。これらの統合 API がアプリケーションのページで実行されている場合、有効なトークンを含まないリクエストをブロックするなどの緩和ルールを保護パック (ウェブ ACL) で実装できます。ルール内の Challenge または CAPTCHA アクションを使用して、クライアントアプリケーションが取得したトークンの使用を強制するルールを実装することもできます。

**インテリジェントな脅威 API の実施例**  
次のリストは、ウェブアプリケーションページでのインテリジェントな脅威に対応した API の一般的な実装の基本コンポーネントを示しています。

```
<head>
<script type="text/javascript" src="protection pack (web ACL) integration URL/challenge.js" defer></script>
</head>
<script>
const login_response = await AwsWafIntegration.fetch(login_url, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: login_body
  });
</script>
```

**CAPTCHA JavaScript API の実施例**  
CAPTCHA 統合 API を使用すると、エンドユーザーの CAPTCHA パズルエクスペリエンスをカスタマイズできます。CAPTCHA 統合では、ブラウザの検証とトークン管理用に JavaScript のインテリジェントな脅威に対応した統合が活用されているだけでなく、CAPTCHA パズルの設定とレンダリング用の機能も追加されています。

次のリストは、ウェブアプリケーションページでの CAPTCHA JavaScript API の一般的な実装の基本コンポーネントを示しています。

```
<head>
    <script type="text/javascript" src="<Integration URL>/jsapi.js" defer></script>
</head>

<script type="text/javascript">
    function showMyCaptcha() {
        var container = document.querySelector("#my-captcha-container");
        
        AwsWafCaptcha.renderCaptcha(container, {
            apiKey: "...API key goes here...",
            onSuccess: captchaExampleSuccessFunction,
            onError: captchaExampleErrorFunction,
            ...other configuration parameters as needed...
        });
    }
    
    function captchaExampleSuccessFunction(wafToken) {
        // Use WAF token to access protected resources
        AwsWafIntegration.fetch("...WAF-protected URL...", {
            method: "POST",
            ...
        });
    }
    
    function captchaExampleErrorFunction(error) {
        /* Do something with the error */
    }
</script>

<div id="my-captcha-container">
    <!-- The contents of this container will be replaced by the captcha widget -->
</div>
```

**Topics**
+ [トークンで使用するドメインの提供](waf-js-challenge-api-set-token-domain.md)
+ [コンテンツセキュリティポリシーでの JavaScript API の使用](waf-javascript-api-csp.md)
+ [インテリジェントな脅威に対応した JavaScript API の使用](waf-js-challenge-api.md)
+ [CAPTCHA JavaScript API を使用する](waf-js-captcha-api.md)

# トークンで使用するドメインの提供
<a name="waf-js-challenge-api-set-token-domain"></a>

このセクションでは、トークンに追加のドメインを提供する方法について説明します。

デフォルトでは、 がトークン AWS WAF を作成すると、保護パック (ウェブ ACL) に関連付けられているリソースのホストドメインが使用されます。 AWS WAF が JavaScript API 用に作成するトークンには、追加のドメインを指定できます。これを行うには、グローバル変数 `window.awsWafCookieDomainList` に 1 つ以上のトークンドメインを設定します。

がトークン AWS WAF を作成すると、 のドメイン`window.awsWafCookieDomainList`と、保護パック (ウェブ ACL) に関連付けられているリソースのホストドメインの組み合わせの中から、最も適切で最短のドメインが使用されます。

設定の例 

```
window.awsWafCookieDomainList = ['.aws.amazon.com']
```

```
window.awsWafCookieDomainList = ['.aws.amazon.com', 'abc.aws.amazon.com']
```

このリストではパブリックサフィックスを使用できません。例えば、`gov.au` または `co.uk` をリストでトークンドメインとして使用することはできません。

このリストで指定するドメインは、他のドメインやドメイン設定と互換性がある必要があります。
+ ドメインは、保護されたホストドメインと、保護パック (ウェブ ACL) 用に設定されたトークンドメインリストに基づいて、 が AWS WAF 受け入れるドメインである必要があります。詳細については、「[AWS WAF 保護パック (ウェブ ACL) トークンドメインリスト設定](waf-tokens-domains.md#waf-tokens-domain-lists)」を参照してください。
+ JavaScript CAPTCHA API を使用する場合、CAPTCHA API キー内の少なくとも 1 つのドメインが、`window.awsWafCookieDomainList` のトークンドメインの 1 つと完全に一致するか、いずれかのトークンドメインの apex ドメインである必要があります。

  例えば、トークンドメイン `mySubdomain.myApex.com` の場合、API キー `mySubdomain.myApex.com` は完全に一致し、API キー `myApex.com` は apex ドメインです。どちらかのキーがトークンドメインに一致します。

  API キーの詳細については、「[JS CAPTCHA API の API キーの管理](waf-js-captcha-api-key.md)」を参照してください。

`AWSManagedRulesACFPRuleSet` マネージドルールグループを使用する場合、ルールグループ設定に指定したアカウント作成パスのドメインと一致するドメインを設定できます。この設定の詳細については、「[ACFP マネージドルールグループをウェブ ACL に追加](waf-acfp-rg-using.md)」を参照してください。

`AWSManagedRulesATPRuleSet` マネージドルールグループを使用する場合、ルールグループ設定に指定したログインパスのドメインと一致するドメインを設定できます。この設定の詳細については、「[ATP マネージドルールグループを保護パック (ウェブ ACL) に追加](waf-atp-rg-using.md)」を参照してください。

# コンテンツセキュリティポリシーでの JavaScript API の使用
<a name="waf-javascript-api-csp"></a>

このセクションでは、apex AWS WAF ドメインを許可リストに登録するための設定例を示します。

コンテンツセキュリティポリシー (CSP) をリソースに適用し、JavaScript 実装を機能させるには、apex AWS WAF ドメイン を許可リストに登録する必要があります`awswaf.com`。JavaScript SDK は異なる AWS WAF エンドポイントを呼び出すため、このドメインを許可リストに登録すると、SDK の動作に必要な権限が付与されます。

以下は、apex AWS WAF ドメインを許可リストに登録するための設定例です。

```
connect-src 'self' https://*.awswaf.com;
script-src 'self' https://*.awswaf.com;
script-src-elem 'self' https://*.awswaf.com;
```

CSP を使用するリソースで JavaScript SDKs を使用しようとしたときに、 AWS WAF ドメインを許可リストに登録していない場合は、次のようなエラーが表示されます。

```
Refused to load the script ...awswaf.com/<> because it violates the following Content Security Policy directive: “script-src ‘self’
```

# インテリジェントな脅威に対応した JavaScript API の使用
<a name="waf-js-challenge-api"></a>

このセクションでは、クライアントアプリケーションでインテリジェントな脅威 JavaScript API を使用する手順について説明します。

インテリジェントな脅威 APIsは、ユーザーのブラウザに対してサイレントチャレンジを実行するオペレーションと、チャレンジと CAPTCHA レスポンスが成功した証拠を提供する AWS WAF トークンを処理するオペレーションを提供します。

JavaScript 統合を最初にテスト環境で実装し、次に本番環境で実装します。追加のコーディングガイダンスについては、次のセクションを参照してください。

 

**インテリジェントな脅威に対応した API を使用するには**

1. **API のインストール** 

   CAPTCHA API を使用している場合は、このステップをスキップできます。CAPTCHA API をインストールすると、スクリプトはインテリジェントな脅威に対応した API を自動的にインストールします。

   1. にサインイン AWS マネジメントコンソール し、[https://console.aws.amazon.com/wafv2/homev2](https://console.aws.amazon.com/wafv2/homev2) で AWS WAF コンソールを開きます。

   1. ナビゲーションペインで、**[Application integration]** (アプリケーション統合) を選択します。**[アプリケーション統合]** ページに、タブ付きのオプションが表示されます。

   1. **[インテリジェントな脅威に対応した統合]** を選択

   1. タブで、統合する保護パック (ウェブ ACL) を選択します。保護パック (ウェブ ACL) リストには、`AWSManagedRulesACFPRuleSet` マネージドルールグループ、`AWSManagedRulesATPRuleSet` マネージドルールグループ、または `AWSManagedRulesBotControlRuleSet` マネージドルールグループのターゲットを絞った保護レベルを使用する保護パック (ウェブ ACL) のみが含まれます。

   1. **[JavaScript SDK]** ペインを開き、統合で使用するスクリプトタグをコピーします。

   1. `<head>` セクションのアプリケーションページコードに、保護パック (ウェブ ACL) 用にコピーしたスクリプトタグを挿入します。この包含により、クライアントアプリケーションは、ページをロードする際にバックグラウンドでトークンを自動的に取得します。

      ```
      <head>
          <script type="text/javascript" src="protection pack (web ACL) integration URL/challenge.js” defer></script>
      <head>
      ```

      この `<script>` リストは `defer` 属性で設定されていますが、ページに別の動作が必要な場合は、設定を `async` に変更できます。

1. **(オプション) クライアントのトークンにドメイン設定を追加する** – デフォルトでは、 がトークン AWS WAF を作成すると、保護パック (ウェブ ACL) に関連付けられているリソースのホストドメインが使用されます。JavaScript API に追加のドメインを指定するには、「[トークンで使用するドメインの提供](waf-js-challenge-api-set-token-domain.md)」のガイダンスに従ってください。

1. **インテリジェントな脅威に対応した統合をコーディングする** – クライアントで保護されたエンドポイントにリクエストを送信する前に、トークンの取得が完了するようにコードを記述します。既に `fetch` API を使用して呼び出しを行っている場合は、 AWS WAF 統合 `fetch` ラッパーに置き換えることができます。`fetch` API を使用しない場合は、代わりに AWS WAF 統合`getToken`オペレーションを使用できます。コーディングガイダンスについては、次のセクションを参照してください。

1. **保護パック (ウェブ ACL) にトークン検証を追加する** – クライアントで送信するウェブリクエスト内に有効なチャレンジトークンがないかチェックするルールを、保護パック (ウェブ ACL) に少なくとも 1 つ追加します。Bot Control マネージドルールグループのターゲットレベルのような、チャレンジトークンをチェックおよびモニタリングするルールグループを使用できるため、「[CAPTCHA および Challengeの AWS WAF](waf-captcha-and-challenge.md)」の説明に従い、Challenge ルールアクションを使用してチェックします。

   保護パック (ウェブ ACL) を追加すると、保護されたエンドポイントへのリクエストに、クライアント統合で取得したトークンが含まれていることを確認できます。有効で期限が切れていないトークンを含むリクエストは、Challenge 検査に合格し、クライアントに別のサイレントチャレンジを送信することはありません。

1. **(オプション) トークンが不足しているリクエストをブロックする** – ACFP マネージドルールグループ、ATP マネージドルールグループまたは Bot Control ルールグループのターゲットを絞ったルールで API を使用する場合、これらのルールはトークンが不足しているリクエストをブロックしません。トークンが不足しているリクエストをブロックするには、[有効な AWS WAF トークンを持たないリクエストのブロック](waf-tokens-block-missing-tokens.md) のガイダンスに従ってください。

**Topics**
+ [インテリジェントな脅威に対応した API 仕様](waf-js-challenge-api-specification.md)
+ [統合 `fetch` ラッパーの使用方法](waf-js-challenge-api-fetch-wrapper.md)
+ [統合 `getToken` を使用する方法](waf-js-challenge-api-get-token.md)

# インテリジェントな脅威に対応した API 仕様
<a name="waf-js-challenge-api-specification"></a>

このセクションでは、インテリジェントな脅威の軽減を目的とした JavaScript API のメソッドとプロパティの仕様を示します。インテリジェントな脅威に対応したこれらの API と CAPTCHA 統合を使用します。

**`AwsWafIntegration.fetch()`**  
 AWS WAF 統合実装を使用して HTTP `fetch`リクエストをサーバーに送信します。

**`AwsWafIntegration.getToken()`**  
保存された AWS WAF トークンを取得し`aws-waf-token`、現在のページの という名前の Cookie に保存します。値はトークン値に設定されます。

**`AwsWafIntegration.hasToken()`**  
有効期限が切れていないトークンが現在 `aws-waf-token` cookie で保持されているかどうかを示すブール値を返します。

CAPTCHA 統合も使用している場合は、「[CAPTCHA JavaScript API 仕様](waf-js-captcha-api-specification.md)」でその仕様を確認してください。

# 統合 `fetch` ラッパーの使用方法
<a name="waf-js-challenge-api-fetch-wrapper"></a>

このセクションでは、統合 `fetch` ラッパーを使用する手順について説明します。

`AwsWafIntegration` 名前空間の下で `fetch` API に対する通常の `fetch` 呼び出しを変更することにより、 AWS WAF `fetch` ラッパーを使用できます。 AWS WAF ラッパーは、標準の JavaScript `fetch` API コールと同じオプションをすべてサポートし、統合のトークン処理を追加します。このアプローチは、一般的に、アプリケーションを統合する最も簡単な方法です。

**ラッパーの実装前**  
次のリスト例は、`AwsWafIntegration` `fetch` ラッパーを実装する前の標準コードを示しています。

```
const login_response = await fetch(login_url, {
	    method: 'POST',
	    headers: {
	      'Content-Type': 'application/json'
	    },
	    body: login_body
	  });
```

**ラッパー実装後**  
次のリストは、`AwsWafIntegration` `fetch` ラッパー実装と同じコードを示しています。

```
const login_response = await AwsWafIntegration.fetch(login_url, {
	    method: 'POST',
	    headers: {
	      'Content-Type': 'application/json'
	    },
	    body: login_body
	  });
```

# 統合 `getToken` を使用する方法
<a name="waf-js-challenge-api-get-token"></a>

このセクションでは、`getToken` オペレーションの使用方法について説明します。

AWS WAF では、保護されたエンドポイントへのリクエストに、現在のトークンの値`aws-waf-token`を持つ という名前の Cookie を含める必要があります。

`getToken` オペレーションとは、 AWS WAF トークンを取得し、名前を `aws-waf-token` にして、値をトークン値に設定し、現在のページの cookie に保存する非同期 API コールです。このトークン cookie は、必要に応じてページで使用できます。

`getToken` を呼び出すと、次が実行されます。
+ 期限切れでないトークンが既に使用可能な場合、コールは直ちにそれを返します。
+ それ以外の場合、コールは トークンプロバイダーから新しいトークンを取得します。トークン取得ワークフローが完了するまで最大で 2 秒間の猶予があり、この待機期間が経過するとタイムアウトします。オペレーションがタイムアウトすると、呼び出しコードが処理しなければならないエラーがスローされます。

`getToken` オペレーションには付随する `hasToken` オペレーションがあり、`aws-waf-token` cookie が現在有効期限が切れていないトークンを保持しているかどうかを示します。

`AwsWafIntegration.getToken()` は有効なトークンを取得し、それを Cookie として保存します。ほとんどのクライアント呼び出しは、この Cookie を自動的にアタッチしますが、アタッチしないクライアント呼び出しもあります。例えば、ホストドメイン間で行われた呼び出しは Cookie にアタッチしません。以下の実施詳細では、両方のタイプのクライアント呼び出しを操作する方法を示します。

**`aws-waf-token` Cookie にアタッチする呼び出しの基本的な `getToken` 実施**  
次のリストの例は、ログインリクエストで `getToken` オペレーションを実装するための標準コードを示しています。

```
const login_response = await AwsWafIntegration.getToken()
	    .catch(e => {
	        // Implement error handling logic for your use case
	    })
	    // The getToken call returns the token, and doesn't typically require special handling
	    .then(token => {
	        return loginToMyPage()
	    })
	
	async function loginToMyPage() {
	    // Your existing login code
	}
```

**トークンが `getToken` から利用可能になった後にのみフォームを送信する**  
次のリストは、有効なトークンが使用可能になるまで、フォーム送信をインターセプトするイベントリスナーを登録する方法を示しています。

```
<body>
	  <h1>Login</h1>
	  <p></p>
	  <form id="login-form" action="/web/login" method="POST" enctype="application/x-www-form-urlencoded">
	    <label for="input_username">USERNAME</label>
	    <input type="text" name="input_username" id="input_username"><br>
	    <label for="input_password">PASSWORD</label>
	    <input type="password" name="input_password" id="input_password"><br>
	    <button type="submit">Submit<button>
	  </form>
	
	<script>
	  const form = document.querySelector("#login-form");
	
	  // Register an event listener to intercept form submissions
	  form.addEventListener("submit", (e) => {
	      // Submit the form only after a token is available 
	      if (!AwsWafIntegration.hasToken()) {
	          e.preventDefault();
	          AwsWafIntegration.getToken().then(() => {
	              e.target.submit();
	          }, (reason) => { console.log("Error:"+reason) });
	        }
	    });
	</script>
	</body>
```

**クライアントがデフォルトで `aws-waf-token` Cookie にアタッチしない場合のトークンとのアタッチ**  
`AwsWafIntegration.getToken()` は有効なトークンを取得し、それを Cookie として保存しますが、デフォルトの場合、すべてのクライアント呼び出しがこの Cookie にアタッチするわけではありません。例えば、ホストドメイン間で行われた呼び出しは Cookie にアタッチしません。

`fetch` ラッパーはこれらのケースを自動的に処理しますが、`fetch`ラッパーを使用できない場合は、Cookie から読み取るだけでなく、このヘッダーのカスタム `x-aws-waf-token` header. AWS WAF reads `aws-waf-token` トークンを使用して処理できます。次のコードは、ヘッダーの設定例を示しています。

```
const token = await AwsWafIntegration.getToken();
const result = await fetch('/url', {
    headers: {
        'x-aws-waf-token': token,
    },
});
```

デフォルトでは、 はリクエストされたホストドメインと同じドメインを含むトークン AWS WAF のみを受け入れます。クロスドメイントークンには、保護パック (ウェブ ACL) トークンドメインリストの対応するエントリが必要です。詳細については、「[AWS WAF 保護パック (ウェブ ACL) トークンドメインリスト設定](waf-tokens-domains.md#waf-tokens-domain-lists)」を参照してください。

クロスドメイントークンの使用の詳細については、「[aws-samples/aws-waf-bot-control-api-protection-with-captcha](https://github.com/aws-samples/aws-waf-bot-control-api-protection-with-captcha)」を参照してください。

# CAPTCHA JavaScript API を使用する
<a name="waf-js-captcha-api"></a>

このセクションでは、CAPTCHA 統合 API を使用する手順について説明します。

CAPTCHA JavaScript API を使用すると、CAPTCHA パズルを設定し、クライアントアプリケーションの任意の場所に配置できます。この API は、インテリジェントな脅威の JavaScript APIs の機能を活用して、エンドユーザーが CAPTCHA パズルを正常に完了した後に AWS WAF トークンを取得して使用します。

JavaScript 統合を最初にテスト環境で実装し、次に本番環境で実装します。追加のコーディングガイダンスについては、次のセクションを参照してください。

**CAPTCHA 統合 API を使用するには**

1. **API のインストール**

   1. にサインイン AWS マネジメントコンソール し、[https://console.aws.amazon.com/wafv2/homev2](https://console.aws.amazon.com/wafv2/homev2) で AWS WAF コンソールを開きます。

   1. ナビゲーションペインで、**[Application integration]** (アプリケーション統合) を選択します。**[アプリケーション統合]** ページに、タブ付きのオプションが表示されます。

   1. **[CAPTCHA 統合]** を選択します。

   1. リストされている JavaScript 統合スクリプトタグをコピーして、統合で使用します。

   1. `<head>` セクションのアプリケーションページコードに、コピーしたスクリプトタグを挿入します。これにより、CAPTCHA パズルの設定および使用が可能になります。

      ```
      <head>
          <script type="text/javascript" src="integrationURL/jsapi.js" defer></script>
      </head>
      ```

      この `<script>` リストは `defer` 属性で設定されていますが、ページに別の動作が必要な場合は、設定を `async` に変更できます。

      また、CAPTCHA スクリプトは、インテリジェントな脅威に対応した統合のスクリプトがまだ存在しない場合は自動的にロードします。インテリジェントな脅威に対応した統合のスクリプトにより、クライアントアプリケーションは、ページをロードする際にバックグラウンドでトークンを自動的に取得し、CAPTCHA API の使用に必要なその他のトークン管理機能を提供します。

1. **(オプション) クライアントのトークンにドメイン設定を追加する** – デフォルトでは、 がトークン AWS WAF を作成すると、保護パック (ウェブ ACL) に関連付けられているリソースのホストドメインが使用されます。JavaScript API に追加のドメインを指定するには、「[トークンで使用するドメインの提供](waf-js-challenge-api-set-token-domain.md)」のガイダンスに従ってください。

1. **クライアントの暗号化された API キーを取得する** – CAPTCHA API には、有効なクライアントドメインのリストを含む暗号化された API キーが必要です。 はこのキー AWS WAF を使用して、統合で使用しているクライアントドメインが CAPTCHA AWS WAF の使用が承認されていることを確認します。API キーを生成するには、「[JS CAPTCHA API の API キーの管理](waf-js-captcha-api-key.md)」のガイダンスに従ってください。

1. **CAPTCHA ウィジェットの実装をコーディングする** – `renderCaptcha()` API コールを、ページ内の使用したい場所に実装します。この機能の設定および使用方法については、以下のセクション「[CAPTCHA JavaScript API 仕様](waf-js-captcha-api-specification.md)」と「[CAPTCHA パズルをレンダリングする方法](waf-js-captcha-api-render.md)」を参照してください。

   CAPTCHA 実装は、トークン管理と AWS WAF トークンを使用するフェッチ呼び出しを実行するためのインテリジェントな脅威統合 APIs と統合されます。これらの API の使用に関するガイダンスについては、「[インテリジェントな脅威に対応した JavaScript API の使用](waf-js-challenge-api.md)」を参照してください。

1. **保護パック (ウェブ ACL) にトークン検証を追加する** – クライアントで送信するウェブリクエスト内に有効な CAPTCHA トークンがないかチェックするルールを、保護パック (ウェブ ACL) に少なくとも 1 つ追加します。「[CAPTCHA および Challengeの AWS WAF](waf-captcha-and-challenge.md)」の説明に従い、CAPTCHA ルールアクションを使用してチェックします。

   保護パック (ウェブ ACL) の追加により、保護されたエンドポイントに送信されるリクエストに、クライアント統合で取得したトークンが含まれていることを確認できます。有効で期限が切れていない CAPTCHA トークンを含むリクエストは、CAPTCHA ルールアクション検査に合格し、エンドユーザーに別の CAPTCHA パズルを提示することはありません。

JavaScript API を実装したら、CAPTCHA パズルの試行とソリューションの CloudWatch メトリクスを確認できます。メトリクスとディメンションの詳細については、[アカウントメトリクスとディメンション](waf-metrics.md#waf-metrics-account) を参照してください。

**Topics**
+ [CAPTCHA JavaScript API 仕様](waf-js-captcha-api-specification.md)
+ [CAPTCHA パズルをレンダリングする方法](waf-js-captcha-api-render.md)
+ [からの CAPTCHA レスポンスの処理 AWS WAF](waf-js-captcha-api-conditional.md)
+ [JS CAPTCHA API の API キーの管理](waf-js-captcha-api-key.md)

# CAPTCHA JavaScript API 仕様
<a name="waf-js-captcha-api-specification"></a>

このセクションでは、CAPTCHA JavaScript API のメソッドとプロパティの仕様を一覧表示します。CAPTCHA JavaScript API を使用して、クライアントアプリケーションでカスタム CAPTCHA パズルを実行します。

この API は、 AWS WAF トークンの取得と使用を設定および管理するために使用するインテリジェントな脅威 APIs に基づいています。「[インテリジェントな脅威に対応した API 仕様](waf-js-challenge-api-specification.md)」を参照してください。

**`AwsWafCaptcha.renderCaptcha(container, configuration)`**  
エンドユーザーに AWS WAF CAPTCHA パズルを提示し、成功すると、CAPTCHA 検証でクライアントトークンを更新します。これは CAPTCHA 統合でのみ使用できます。この呼び出しをインテリジェントな脅威に対応した API と組み合わせて使用すると、トークンの取得を管理したり、`fetch` コールでトークンを提供したりできます。インテリジェントな脅威に対応した API については、「[インテリジェントな脅威に対応した API 仕様](waf-js-challenge-api-specification.md)」を参照してください。  
が AWS WAF 送信する CAPTCHA インタースティシャルとは異なり、この方法でレンダリングされた CAPTCHA パズルは、最初のタイトル画面なしですぐにパズルを表示します。    
**`container`**  
ページ上のターゲットとなるコンテナ要素の `Element` オブジェクト。これは通常、`document.getElementById()` または `document.querySelector()` を呼び出すことで取得できます。  
必須: はい  
タイプ: `Element`  
**設定**  
以下のような CAPTCHA 構成設定を含むオブジェクト****。    
**`apiKey`**   
クライアントのドメインの許可を有効にする暗号化された API キー。 AWS WAF コンソールを使用して、クライアントドメインの API キーを生成します。1 つのキーを最大 5 つのドメインに使用できます。詳細については、「[JS CAPTCHA API の API キーの管理](waf-js-captcha-api-key.md)」を参照してください。  
必須: はい  
タイプ: `string`  
**`onSuccess: (wafToken: string) => void;`**   
エンドユーザーが CAPTCHA パズルを正常に完了すると、有効な AWS WAF トークンで呼び出されます。 AWS WAF 保護パック (ウェブ ACL) で保護するエンドポイントに送信するリクエストでトークンを使用します。トークンは、パズルの完成に最後に成功したときの証明とタイムスタンプを提供します。  
必須: はい  
**`onError?: (error: CaptchaError) => void;`**   
CAPTCHA 操作中にエラーが発生したときに、エラーオブジェクトとともに呼び出されます。  
必須: いいえ  
**`CaptchaError` クラス定義** – `onError` ハンドラーは、次のクラス定義を使用してエラータイプを提供します。  

```
CaptchaError extends Error {
    kind: "internal_error" | "network_error" | "token_error" | "client_error";
    statusCode?: number;
}
```
+ `kind` – 返されたエラーの種類。
+ `statusCode` – HTTP ステータスコード (利用可能な場合)。これは、エラーが HTTP エラーに起因する場合に `network_error` で使用されます。  
**`onLoad?: () => void;`**   
新しい CAPTCHA パズルがロードされると呼び出されます。  
必須: いいえ  
**`onPuzzleTimeout?: () => void;`**   
CAPTCHA パズルが期限切れになる前に完成しなかった場合に呼び出されます。  
必須: いいえ  
**`onPuzzleCorrect?: () => void;`**   
CAPTCHA パズルに正しい回答が入力されると呼び出されます。  
必須: いいえ  
**`onPuzzleIncorrect?: () => void;`**   
CAPTCHA パズルに間違った回答が入力されると呼び出されます。  
必須: いいえ  
**`defaultLocale`**   
CAPTCHA パズルに使用するデフォルトのロケール。CAPTCHA パズルの説明書は、アラビア語 (ar-SA)、簡体字中国語 (zh-CN)、オランダ語 (nl-NL)、英語 (en-US)、フランス語 (fr-FR)、ドイツ語 (de-DE)、イタリア語 (it-IT)、日本語 (ja-JP)、ブラジルポルトガル語 (pt-BR)、スペイン語 (es-ES)、およびトルコ語 (tr-TR) で提供されています。音声指示はすべての書かれた言語に対して提供されていますが、中国語と日本語の場合、デフォルトでは英語を使用します。デフォルト言語を変更するには、国際言語とロケールコード (例: `ar-SA`) を指定します。  
デフォルト: エンドユーザーのブラウザで現在使用されている言語  
必須: いいえ  
タイプ: `string`  
**`disableLanguageSelector`**   
`true` に設定すると、CAPTCHA パズルの言語セレクタが非表示になります。  
デフォルト: `false`  
必須: いいえ  
タイプ: `boolean`  
**`dynamicWidth`**   
`true` に設定すると、CAPTCHA パズルの幅はブラウザウィンドウの幅に合わせて変更されます。  
デフォルト: `false`  
必須: いいえ  
タイプ: `boolean`  
**`skipTitle`**   
`true` に設定すると、CAPTCHA パズルのパズルタイトルに「**パズルを解く**」という見出しが表示されません。  
デフォルト: `false`  
必須: いいえ  
タイプ: `boolean`

# CAPTCHA パズルをレンダリングする方法
<a name="waf-js-captcha-api-render"></a>

このセクションでは、`renderCaptcha` の実施例を示します。

クライアントインターフェイスで使用する 呼び出しを使用できます AWS WAF `renderCaptcha`。呼び出しは、CAPTCHA パズルを から取得し AWS WAF、レンダリングして、検証 AWS WAF のために に送信します。呼び出しを行うときは、パズルのレンダリング設定と、エンドユーザーがパズルを完成させたときに実行するコールバックを指定します。オプションの詳細については、前のセクション「[CAPTCHA JavaScript API 仕様](waf-js-captcha-api-specification.md)」を参照してください。

この呼び出しは、インテリジェントな脅威に対応した統合 API のトークン管理機能と組み合わせて使用します。この呼び出しにより、CAPTCHA パズルの完成に成功したことを検証するトークンがクライアントに渡されます。インテリジェントな脅威統合 APIs を使用してトークンを管理し、 AWS WAF 保護パック (ウェブ ACLs) で保護されているエンドポイントへのクライアントの呼び出しでトークンを提供します。インテリジェントな脅威に対応した API の詳細については、「[インテリジェントな脅威に対応した JavaScript API の使用](waf-js-challenge-api.md)」を参照してください。

**実装例**  
次のリスト例は、 `<head>`セクション AWS WAF の統合 URL の配置を含む、標準の CAPTCHA 実装を示しています。

このリストは、インテリジェントな脅威に対応した統合 API の `AwsWafIntegration.fetch` ラッパーを使用する成功コールバックを含む `renderCaptcha` 関数で構成されています。この関数については、「[統合 `fetch` ラッパーの使用方法](waf-js-challenge-api-fetch-wrapper.md)」を参照してください。

```
<head>
    <script type="text/javascript" src="<Integration URL>/jsapi.js" defer></script>
</head>

<script type="text/javascript">
    function showMyCaptcha() {
        var container = document.querySelector("#my-captcha-container");
        
        AwsWafCaptcha.renderCaptcha(container, {
            apiKey: "...API key goes here...",
            onSuccess: captchaExampleSuccessFunction,
            onError: captchaExampleErrorFunction,
            ...other configuration parameters as needed...
        });
    }
    
    function captchaExampleSuccessFunction(wafToken) {
        // Captcha completed. wafToken contains a valid WAF token. Store it for
        // use later or call AwsWafIntegration.fetch() to use it easily.
        // It will expire after a time, so calling AwsWafIntegration.getToken()
        // again is advised if the token is needed later on, outside of using the
        // fetch wrapper.
        
        // Use WAF token to access protected resources
        AwsWafIntegration.fetch("...WAF-protected URL...", {
            method: "POST",
            headers: {
                "Content-Type": "application/json",
            },
            body: "{ ... }" /* body content */
        });
    }
    
    function captchaExampleErrorFunction(error) {
        /* Do something with the error */
    }
</script>

<div id="my-captcha-container">
    <!-- The contents of this container will be replaced by the captcha widget -->
</div>
```

**構成設定の例**  
次のリストの例は、幅とタイトルのオプションをデフォルト以外で設定した `renderCaptcha` を示しています。

```
        AwsWafCaptcha.renderCaptcha(container, {
            apiKey: "...API key goes here...",
            onSuccess: captchaExampleSuccessFunction,
            onError: captchaExampleErrorFunction,
            dynamicWidth: true, 
            skipTitle: true
        });
```

設定オプションの詳細な情報については、「[CAPTCHA JavaScript API 仕様](waf-js-captcha-api-specification.md)」を参照してください。

# からの CAPTCHA レスポンスの処理 AWS WAF
<a name="waf-js-captcha-api-conditional"></a>

このセクションでは、CAPTCHA レスポンスを処理する例を示します。

CAPTCHA アクションを持つ AWS WAF ルールは、リクエストに有効な CAPTCHA タイムスタンプを持つトークンがない場合、一致するウェブリクエストの評価を終了します。リクエストが `GET` テキスト/HTML 呼び出しの場合、CAPTCHA アクションは CAPTCHA パズルを含むインタースティシャルをクライアントに提供します。CAPTCHA JavaScript API を統合しない場合、インタースティシャルはパズルを実行し、エンドユーザーが問題を正しく解決すると、自動的にリクエストを再送信します。

CAPTCHA JavaScript API を統合し、CAPTCHA 処理をカスタマイズする場合は、終了 CAPTCHA レスポンスを検出し、カスタム CAPTCHA を提供する必要があります。その後、エンドユーザーがパズルを正しく解決した場合は、クライアントのウェブリクエストを再送信します。

次のコード例は、これを実行する方法を説明しています。

**注記**  
 AWS WAF CAPTCHA アクションレスポンスのステータスコードは HTTP 405 で、このコードのCAPTCHAレスポンスを認識するために使用します。保護されたエンドポイントが HTTP 405 ステータスコードを使用して同じ呼び出しのために他の種類のレスポンスを通信する場合、このサンプルコードはそれらのレスポンスのためにも CAPTCHA パズルをレンダリングします。

```
<!DOCTYPE html>
<html>
<head>
    <script type="text/javascript" src="<Integration URL>/jsapi.js" defer></script>
</head>
<body>
    <div id="my-captcha-box"></div>
    <div id="my-output-box"></div>

    <script type="text/javascript">
    async function loadData() {
        // Attempt to fetch a resource that's configured to trigger a CAPTCHA
        // action if the rule matches. The CAPTCHA response has status=HTTP 405.
        const result = await AwsWafIntegration.fetch("/protected-resource");

        // If the action was CAPTCHA, render the CAPTCHA and return

        // NOTE: If the endpoint you're calling in the fetch call responds with HTTP 405
        // as an expected response status code, then this check won't be able to tell the
        // difference between that and the CAPTCHA rule action response.

        if (result.status === 405) {
            const container = document.querySelector("#my-captcha-box");
            AwsWafCaptcha.renderCaptcha(container, {
                apiKey: "...API key goes here...",
                onSuccess() {
                    // Try loading again, now that there is a valid CAPTCHA token
                    loadData();
                },
            });
            return;
        }

        const container = document.querySelector("#my-output-box");
        const response = await result.text();
        container.innerHTML = response;
    }

    window.addEventListener("load", () => {
        loadData();
    });
    </script>
</body>
</html>
```

# JS CAPTCHA API の API キーの管理
<a name="waf-js-captcha-api-key"></a>

このセクションでは、API キーを生成および削除する手順について説明します。

JavaScript API を使用して AWS WAF CAPTCHA をクライアントアプリケーションに統合するには、JavaScript API 統合タグと、CAPTCHA パズルを実行するクライアントドメインの暗号化された API キーが必要です。

JavaScript の CAPTCHA アプリケーション統合では、暗号化された API キーを使用して、クライアントアプリケーションドメインに CAPTCHA API AWS WAF を使用するアクセス許可があることを確認します。JavaScript クライアントから CAPTCHA API を呼び出すときは、現在のクライアントのドメインを含むドメインリストに API キーを含めます。1 つの暗号化キーに最大 5 つのドメインを列挙することができます。

**API キー要件**  
CAPTCHA 統合で使用する API キーには、そのキーを使用するクライアントに適用されるドメインが含まれている必要があります。
+ クライアントのインテリジェントな脅威に対応した統合で `window.awsWafCookieDomainList` を指定する場合、API キーの少なくとも 1 つのドメインが `window.awsWafCookieDomainList` のトークンドメインの 1 つと完全一致するか、いずれかのトークンドメインの apex ドメインである必要があります。

  例えば、トークンドメイン `mySubdomain.myApex.com` の場合、API キー `mySubdomain.myApex.com` は完全に一致し、API キー `myApex.com` は apex ドメインです。どちらかのキーがトークンドメインに一致します。

  トークンドメインリストの設定については、「[トークンで使用するドメインの提供](waf-js-challenge-api-set-token-domain.md)」を参照してください。
+ それ以外の場合は、現在のドメインが API キーに含まれている必要があります。現在のドメインは、ブラウザのアドレスバーで確認できるドメインです。

使用するドメインは、保護されたホストドメインとウェブ ACL 用に設定されたトークンドメインリストに基づいて、 が AWS WAF 受け入れるドメインである必要があります。詳細については、「[AWS WAF 保護パック (ウェブ ACL) トークンドメインリスト設定](waf-tokens-domains.md#waf-tokens-domain-lists)」を参照してください。

**API キーのリージョンを選択する方法**  
AWS WAF は、 AWS WAF が利用可能な任意のリージョンで CAPTCHA API キーを生成できます。

原則として、保護パック (ウェブ ACL) に使用するのと同じリージョンを CAPTCHA API キーに使用する必要があります。ただし、リージョナル保護パック (ウェブ ACL) のグローバルオーディエンスが予想される場合は、CloudFront にスコープされた CAPTCHA JavaScript 統合タグと CloudFront にスコープされた API キーを取得し、リージョナル保護パック (ウェブ ACL) で使用できます。このアプローチにより、クライアントは自分に最も近いリージョンから CAPTCHA パズルをロードできるため、レイテンシーが短縮されます。

CloudFront 以外のリージョンに限定されている CAPTCHA API キーは、複数のリージョンでは使用できません。これらは、限定されたリージョンでのみ使用できます。

**クライアントドメインの API キーを生成するには**  
統合 URL を取得し、コンソールを介して API キーを生成および取得するには。

1. にサインイン AWS マネジメントコンソール し、[https://console.aws.amazon.com/wafv2/homev2](https://console.aws.amazon.com/wafv2/homev2) で AWS WAF コンソールを開きます。

1. ナビゲーションペインで、**[Application integration]** (アプリケーション統合) を選択します。

1. ペインで、**[アプリケーション統合のために有効にする保護パック (ウェブ ACL)]** で、API キーに使用したいリージョンを選択します。**[CAPTCHA 統合]** タブの **[API キー]** ペインでリージョンを選択することもできます。

1. タブ **[CAPTCHA 統合]** を選択します。このタブには、統合で使用できる CAPTCHA JavaScript 統合タグと API キーリストが表示されます。どちらも選択したリージョンに限定されます。

1. **[API キー]** ペインで、**[キーを生成]** を選択します。[キー生成] ダイアログが表示されます。

1. キーに含めるクライアントドメインを入力します。最大 5 つまで入力できます。完了したら、**[キーを生成]** を選択します。インターフェイスが CAPTCHA 統合タブに戻り、新しいキーが一覧表示されます。

   一度作成された API キーは、イミュータブルです。キーを変更する必要がある場合は、新しいキーを生成し、代わりにそれを使用します。

1. (オプション) 新しく生成されたキーをコピーして、統合で使用します。

この作業には、REST APIs または言語固有の AWS SDKsのいずれかを使用することもできます。REST API コールは 「[CreateAPIKey](https://docs.aws.amazon.com/waf/latest/APIReference/API_CreateAPIKey.html)」と「[ListAPIKeys](https://docs.aws.amazon.com/waf/latest/APIReference/API_ListAPIKeys.html)」です。

**API を削除するには**  
API キーを削除するには、REST API または言語固有の AWS SDKsのいずれかを使用する必要があります。REST API コールは 「[DeleteAPIKey](https://docs.aws.amazon.com/waf/latest/APIReference/API_DeleteAPIKey.html)」です。コンソールでキーを削除することはできません。

キーを削除すると、 がすべてのリージョンでキーの使用を禁止する AWS WAF までに最大 24 時間かかることがあります。

# AWS WAF モバイルアプリケーションの統合
<a name="waf-mobile-sdk"></a>

このセクションでは、 AWS WAF モバイル SDKs を使用して、Android および iOS モバイルアプリと TV アプリ用の AWS WAF インテリジェントな脅威統合 SDKs を実装するトピックを紹介します。TV アプリの場合、SDK は Android TV や Apple TV などの主要なスマート TV プラットフォームと互換性があります。
+ Android モバイルと TV アプリの場合、 SDK は Android API バージョン 23 (Android バージョン 6) 以降で動作します。Android バージョンの詳細については、「[SDK Platform リリースノート](https://developer.android.com/tools/releases/platforms)」を参照してください。
+ iOS モバイルアプリの場合、 SDK は iOS バージョン 13 以降で動作します。iOS バージョンの詳細については、「[iOS と iPadOS のリリースノート](https://developer.apple.com/documentation/ios-ipados-release-notes)」を参照してください。
+ Apple TV アプリの場合、SDK は tvOS バージョン 14 以降で動作します。tvOS バージョンの詳細については、「[tvOS のリリースノート](https://developer.apple.com/documentation/tvos-release-notes)」を参照してください。

モバイル AWS WAF SDK を使用すると、トークン認可を管理し、保護されたリソースに送信するリクエストにトークンを含めることができます。SDK を使用すると、クライアントによるこれらのリモートプロシージャコールに有効なトークンが含まれていることを確認できます。さらに、この統合がアプリケーションのページで実行されている場合、有効なトークンを含まないリクエストをブロックするなど、保護パック (ウェブ ACL) で緩和ルールを実装できます。

モバイル SDK にアクセスするには、「[AWSへのお問い合わせ](https://aws.amazon.com/contact-us)」にてサポート担当者までお問い合わせください。

**注記**  
 AWS WAF モバイル SDKs は CAPTCHA のカスタマイズには使用できません。

SDK を使用するための基本的なアプローチは、設定オブジェクトを使用してトークンプロバイダーを作成し、トークンプロバイダーを使用してトークンを取得することです AWS WAF。デフォルトでは、トークンプロバイダーは、保護されたリソースに対するウェブリクエストに取得したトークンを含めます。

主要なコンポーネントを示す SDK 実装の一部を次に示します。詳細な例については、「[AWS WAF モバイル SDK のコード例](waf-mobile-sdk-coding-examples.md)」を参照してください。

------
#### [ iOS ]

```
let url: URL = URL(string: "protection pack (web ACL) integration URL")!
	let configuration = WAFConfiguration(applicationIntegrationUrl: url, domainName: "Domain name")
	let tokenProvider = WAFTokenProvider(configuration)
	let token = tokenProvider.getToken()
```

------
#### [ Android ]

```
URL applicationIntegrationURL = new URL("protection pack (web ACL) integration URL");
	String domainName = "Domain name";
	WAFConfiguration configuration = WAFConfiguration.builder().applicationIntegrationURL(applicationIntegrationURL).domainName(domainName).build();
	WAFTokenProvider tokenProvider = new WAFTokenProvider(Application context, configuration);
	WAFToken token = tokenProvider.getToken();
```

------

# AWS WAF モバイル SDK のインストール
<a name="waf-mobile-sdk-installing"></a>

このセクションでは、 AWS WAF モバイル SDK をインストールする手順について説明します。

モバイル SDK にアクセスするには、「[AWSへのお問い合わせ](https://aws.amazon.com/contact-us)」にてサポート担当者までお問い合わせください。

モバイル SDK を最初にテスト環境で実装し、次に本番環境で実装します。

**AWS WAF モバイル SDK をインストールするには**

1. にサインイン AWS マネジメントコンソール し、[https://console.aws.amazon.com/wafv2/homev2](https://console.aws.amazon.com/wafv2/homev2) で AWS WAF コンソールを開きます。

1. ナビゲーションペインで、**[Application integration]** (アプリケーション統合) を選択します。

1. **[インテリジェントな脅威に対応した統合]** タブで、次の操作を行います。

   1. **[アプリケーション統合が有効になっている保護パック (ウェブ ACL)]** ペインで、統合する保護パック (ウェブ ACL) を見つけます。実装で使用するアプリケーション統合が有効になっている保護パック (ウェブ ACL) 統合 URL をコピーして保存します。この URL は、API コール `GetWebACL` を通じて取得することもできます。

   1. モバイルデバイスのタイプとバージョンを選択してから、**[Download]** (ダウンロード) を選択します。任意のバージョンを選択できますが、最新バージョンを使用することをお勧めします。 はデバイスの`zip`ファイルを標準のダウンロード場所に AWS WAF ダウンロードします。

1. アプリケーション開発環境で、ファイルを任意の作業場所に解凍します。zip ファイルの最上位ディレクトリで、`README` を見つけて開きます。ファイルの指示`README`に従って、 AWS WAF モバイルアプリコードで使用するモバイル SDK をインストールします。

1. 次のセクションのガイダンスに従って、アプリケーションをプログラムします。

# AWS WAF モバイル SDK 仕様
<a name="waf-mobile-sdk-specification"></a>

このセクションでは、 AWS WAF モバイル SDK の利用可能な最新バージョンに対応する SDK オブジェクト、オペレーション、および構成設定を一覧表示します。構成設定のさまざまな組み合わせでトークンプロバイダーとオペレーションがどのように連携するかについては、「[AWS WAF モバイル SDK の仕組み](waf-mobile-sdk-how-it-works.md)」を参照してください。

**`WAFToken`**  
 AWS WAF トークンを保持します。    
**`getValue()`**  
`WAFToken` の `String` 表現を取得します。

**`WAFTokenProvider`**  
モバイルアプリケーションでトークンを管理します。`WAFConfiguration` オブジェクトを使用してこれを実装します。    
**`getToken()`**  
バックグラウンド更新が有効になっている場合、キャッシュされたトークンが返されます。バックグラウンド更新が無効になっている場合、 への同期呼び出しがブロック AWS WAF され、新しいトークンを取得します。  
**`loadTokenIntoProvider(WAFToken)`**  
指定されたトークンを `WAFTokenProvider` にロードし、プロバイダーが管理していたトークンを置き換えます。トークンプロバイダーは新しいトークンの所有権を取得し、今後の更新を処理します。このオペレーションでは、`WAFConfiguration` で `setTokenCookie` が有効になっている場合、Cookie ストアのトークンも更新されます。  
**`onTokenReady(WAFTokenResultCallback)`**  
アクティブなトークンの準備ができたら、トークンを更新し、指定されたコールバックを呼び出すようにトークンプロバイダーに指示します。トークンプロバイダーは、トークンがキャッシュされて準備ができたときに、バックグラウンドスレッドでコールバックを呼び出します。アプリケーションが最初にロードされたときや、アクティブ状態に戻ったときにこれを呼び出します。アクティブ状態に戻ることの詳細については、「[アプリケーションが非アクティブ状態になった後のトークンの取得](waf-mobile-sdk-how-it-works.md#waf-mobile-sdk-how-back-from-inactive)」を参照してください。  
Android または iOS アプリケーションの場合、`WAFTokenResultCallback` を、リクエストされたトークンの準備ができたときにトークンプロバイダーが呼び出すオペレーションに設定できます。`WAFTokenResultCallback` の実装では、パラメータ `WAFToken`、`SdkError` を取得する必要があります。iOS アプリケーションでは、代わりにインライン関数を作成できます。  
**`storeTokenInCookieStorage(WAFToken)`**  
指定された AWS WAF トークンを SDK の Cookie マネージャーに保存`WAFTokenProvider`するように に指示します。デフォルトでは、トークンは最初に取得されたときと更新されたときのみ、Cookie ストアに追加されます。アプリケーションが何らかの理由で共有 Cookie ストアをクリアした場合、SDK は次回の更新まで AWS WAF トークンを自動的に追加しません。

**`WAFConfiguration`**  
`WAFTokenProvider` の実装のための設定を保持します。これを実装すると、保護パック (ウェブ ACL) の統合 URL、トークンで使用するドメイン名、トークンプロバイダーが使用するデフォルト以外の設定を指定します。  
次のリストは、`WAFConfiguration` オブジェクトで管理できる構成設定を示しています。    
**`applicationIntegrationUrl`**   
アプリケーション統合 URL。これを AWS WAF コンソールまたは `getWebACL` API コールから取得します。  
必須: はい  
タイプ: アプリケーション固有の URL。iOS の場合は、「[iOS URL](https://developer.apple.com/documentation/foundation/url)」を参照してください。Android の場合は、「[java.net URL](https://docs.oracle.com/javase/7/docs/api/java/net/URL.html)」を参照してください。  
**`backgroundRefreshEnabled`**   
トークンプロバイダーがバックグラウンドでトークンを更新するかどうかを示します。これを設定すると、トークンプロバイダーは、自動トークン更新アクティビティを管理する構成設定に従って、バックグラウンドでトークンを更新します。  
必須: いいえ  
タイプ: `Boolean`  
デフォルト値: `TRUE`  
**`domainName`**   
トークンで使用するドメインは、トークン取得とクッキーの保存に使用されます。例えば、`example.com`、`aws.amazon.com` です。これは通常、保護パック (ウェブ ACL) に関連付けられているリソースのホストドメインであり、ウェブリクエストの送信先です。ACFP マネージドルールグループ `AWSManagedRulesACFPRuleSet` の場合、通常はルールグループ設定で指定したアカウント作成パスのドメインと一致する単一のドメインになります。ATP マネージドルールグループ `AWSManagedRulesATPRuleSet` の場合、通常はルールグループ設定で指定したログインパスのドメインと一致する単一のドメインになります。  
パブリックサフィックスは許可されません。たとえば、`gov.au` または `co.uk` をトークンドメインとして使用することはできません。  
ドメインは、保護されたホストドメインと保護パック (ウェブ ACL) のトークンドメインリストに基づいて、 AWS WAF が受け入れるドメインである必要があります。詳細については、「[AWS WAF 保護パック (ウェブ ACL) トークンドメインリスト設定](waf-tokens-domains.md#waf-tokens-domain-lists)」を参照してください。  
必須: はい  
タイプ: `String`   
**`maxErrorTokenRefreshDelayMsec`**   
失敗した試行後にトークンの更新を繰り返すまでの待機時間の最大値 (ミリ秒)。失敗した試行の自動再試行ごとに、指定された入力遅延時間までエクスポネンシャルバックオフが追加されます。この値は、トークンの取得が失敗し、`maxRetryCount` 回再試行された後に使用されます。  
必須: いいえ  
タイプ: `Integer`  
デフォルト値: `5000` (5 秒)  
許容される最小値: `1` (1 ミリ秒)  
許容される最大値: `30000` (30 秒)  
**`maxRetryCount`**   
トークンがリクエストされたときに、エクスポネンシャルバックオフで実行する最大再試行回数。  
必須: いいえ  
タイプ: `Integer`  
デフォルト値: `Infinity`  
許容される最小値: `0`  
許容される最大値: `100`  
**`setTokenCookie`**   
SDK の Cookie マネージャーがリクエストに、およびその他のエリアにトークン Cookie を追加するかどうかを示します。  
`TRUE` 値の場合:   
+ cookie マネージャーは、パスが `tokenCookiePath` で指定されたパスの下にあるすべてのリクエストにトークン Cookie を追加します。
+ `WAFTokenProvider` オペレーションは、トークンプロバイダーにロードするだけでなく、Cookie ストアのトークン `loadTokenIntoProvider()` を更新します。
必須: いいえ  
タイプ: `Boolean`  
デフォルト値: `TRUE`  
**`tokenCookiePath`**   
`setTokenCookie` が `TRUE` の場合に使用されます。SDK の cookie マネージャーでトークン cookie を追加する最上位レベルのパスを示します。マネージャーは、このパスに送信するすべてのリクエストとすべての子パスにトークン cookie を追加します。  
例えば、これを `/web/login` に設定すると、マネージャーには、`/web/login` に送信されるすべてのトークン cookie と、その子パスのいずれかが含まれます (`/web/login/help` など)。`/`、`/web`、`/web/order` などの他のパスに送信されたリクエストのトークンは含まれません。  
必須: いいえ  
タイプ: `String`  
デフォルト値: `/`  
**`tokenRefreshDelaySec`**   
バックグラウンドの更新に使用されます。バックグラウンドトークンが更新されるまでの最大時間 (秒)。  
必須: いいえ  
タイプ: `Integer`  
デフォルト値: `88`  
許容される最小値: `88`  
許容される最大値: `300` (5 分)

## AWS WAF モバイル SDK エラー
<a name="waf-mobile-sdk-errors"></a>

このセクションでは、現在の AWS WAF モバイル SDK バージョンで発生する可能性のあるエラーを一覧表示します。

**`SdkError`**  
トークンの取得に失敗した場合に返されるエラータイプ。Android と iOS SDK のエラータイプは同じです。  
 AWS WAF モバイル SDK には次のエラータイプがあります。    
**`invalidChallenge`**  
このエラーは、トークンサーバーが無効なチャレンジデータを返すか、レスポンス BLOB が攻撃者によって変更された場合に返されます。  
**`errorInvokingGetChallengeEndpoint`**  
このエラーは、トークンサーバーが成功しないレスポンスコードをクライアントに返すか、ネットワークエラーが発生したときに返されます。  
**`invalidVerifyChallengeResponse`**  
このエラーは、 AWS WAF サーバーの検証レスポンス`aws-waf-token`から を取得する際にエラーが発生した場合、またはサーバーレスポンスが改ざんされた場合に返されます。  
**`errorInvokingVerifyEndpoint`**  
このエラーは、クライアントが AWS WAF サーバーから不正な応答を受け取ったとき、または解決されたチャレンジを検証するときにネットワークエラーを受け取ったときに返されます。  
**`internalError`**  
このエラーは、SDK 自体の内部で発生する可能性のある他のすべてのエラーに対して返されます。

**`socketTimeoutException`**  
このエラーは、トークンの取得中にネットワークエラーが発生したときに返されることがよくあります。  
これにエラー、以下によって発生する可能性があります。  
+ 低ネットワーク帯域幅: ネットワーク接続設定を確認する
+ ミューテーションされたアプリケーション統合 URL: AWS WAF コンソールに表示される内容から統合 URL が変更されていないことを確認します。

# AWS WAF モバイル SDK の仕組み
<a name="waf-mobile-sdk-how-it-works"></a>

このセクションでは、 AWS WAF モバイル SDK クラス、プロパティ、およびオペレーションがどのように連携するかについて説明します。

モバイル SDK は、トークンの取得と利用のために使用できる設定可能なトークンプロバイダーを提供します。トークンプロバイダーは、許可するリクエストが正規の顧客からのものであることを検証します。保護するリソースに AWS リクエストを送信するときは AWS WAF、Cookie にトークンを含めてリクエストを検証します。トークン cookie は手動で処理することも、トークンプロバイダーに処理させることもできます。

このセクションでは、モバイル SDK に含まれるクラス、プロパティ、およびメソッド間のインタラクションについて説明します。SDK の仕様については、「[AWS WAF モバイル SDK 仕様](waf-mobile-sdk-specification.md)」を参照してください。

## トークンの取得とキャッシュ
<a name="waf-mobile-sdk-how-token-basics"></a>

モバイルアプリケーションでトークンプロバイダーインスタンスを作成するときに、トークンとトークンの取得を管理する方法を設定します。主に、アプリケーションのウェブリクエストで使用するための、有効で期限切れになっていないトークンを維持する方法を選択できます。
+ **[Background refresh enabled]** (バックグラウンド更新が有効) - これがデフォルトのトランスコードプリセットです。トークンプロバイダーは、バックグラウンドでトークンを自動的に更新し、キャッシュします。バックグラウンド更新が有効になっている場合、`getToken()` を呼び出すと、オペレーションはキャッシュされたトークンを取得します。

  トークンプロバイダーは、設定可能な間隔でトークンの更新を実行します。これにより、アプリケーションがアクティブな間、期限切れでないトークンは常にキャッシュ内で利用可能な状態となります。アプリケーションが非アクティブ状態の間、バックグラウンドの更新が一時停止されます。詳細については、「[アプリケーションが非アクティブ状態になった後のトークンの取得](#waf-mobile-sdk-how-back-from-inactive)」を参照してください。
+ **[Background refresh disabled]** (バックグラウンド更新が無効) - バックグラウンドトークンの更新を無効にして、オンデマンドでのみトークンを取得できます。オンデマンドで取得されたトークンはキャッシュされません。また、必要に応じて複数のトークンを取得できます。各トークンは、取得する他のトークンとは独立しており、有効期限を計算するために使用される独自のタイムスタンプを備えています。

  バックグラウンド更新が無効になっている場合のトークンの取得には、次の選択肢があります。
  + **`getToken()`** – バックグラウンド更新を無効に`getToken()`して を呼び出すと、呼び出しは同期的に新しいトークンを取得します AWS WAF。これは、メインスレッドで呼び出すと、アプリケーションの応答性に影響する可能性のあるブロッキング呼び出しである場合があります。
  + **`onTokenReady(WAFTokenResultCallback)`** - この呼び出しは、新しいトークンを非同期的に取得し、トークンの準備ができたときに提供された結果コールバックをバックグラウンドスレッドで呼び出します。

### トークンプロバイダーが失敗したトークンの取得を再試行する方法
<a name="waf-mobile-sdk-how-token-retrieval-retries"></a>

トークンプロバイダーは、取得に失敗したときにトークンの取得を自動的に再試行します。再試行は、開始の再試行の待ち時間が 100 ミリ秒のエクスポネンシャルバックオフを使用して最初に実行されます。エクスポネンシャル再試行の詳細については、「[AWSでのエラー再試行とエクスポネンシャルバックオフ](https://docs.aws.amazon.com/general/latest/gr/api-retries.html)」を参照してください。

再試行回数が設定された `maxRetryCount` に達すると、トークンプロバイダーは、トークン取得のタイプに応じて、試行を停止するか、`maxErrorTokenRefreshDelayMsec` ミリ秒ごとの試行に切り替えます。
+ **`onTokenReady()`** – トークンプロバイダーは、試行間の待機時間を `maxErrorTokenRefreshDelayMsec` ミリ秒に切り替えて、トークン取得の試行を続行します。
+ **バックグラウンド更新** – トークンプロバイダーは、試行間の待機時間を `maxErrorTokenRefreshDelayMsec` ミリ秒に切り替えて、トークンの取得の試行を続行します。
+ **バックグラウンド更新が無効になっている場合のオンデマンド `getToken()` 呼び出し** – トークンプロバイダーはトークンの取得の試行を停止し、前のトークン値を返します。前のトークンがない場合は null 値を返します。

## トークン取得の再試行シナリオ
<a name="waf-mobile-sdk-how-token-retrieval-retry-scenarios"></a>

トークンプロバイダーがトークンを取得しようとすると、トークンの取得フローのどこでトークンの取得が失敗するかに応じて、自動再試行が発生する可能性があります。このセクションでは、自動再試行が表示される可能性のある場所を一覧表示します。
+ **/inputs または /verify による AWS WAF チャレンジの取得または検証:**
  +  AWS WAF チャレンジを取得して検証するリクエストが行われて失敗すると、自動再試行が発生する可能性があります。
  + ここで自動再試行が `socketTimeoutException` エラーとともに発生することがあります。これには、次のような複数の原因が考えられます。
    + 低ネットワーク帯域幅: ネットワーク接続設定を確認する
    + ミューテーションされたアプリケーション統合 URL: AWS WAF コンソールに表示される内容から統合 URL が変更されていないことを確認します。
  + 自動再試行カウントは、`maxRetryCount()` 関数で設定できます
+ **トークンの更新:**
  + トークンハンドラーを介してトークンの更新リクエストが行われると、自動再試行が発生する可能性があります。
  + ここでの自動再試行数は、`maxRetryCount()` 関数で設定できます。

自動再試行のない設定は、`maxRetryCount(0)` を設定することで可能です。

## トークンイミュニティ時間とバックグラウンド更新
<a name="waf-mobile-sdk-how-token-immunity"></a>

ウェブ 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 は、アプリケーション統合を有効にしたウェブ ACL を指します。この URL は、リクエストを正しいバックエンドサーバーにルーティングし、顧客に関連付けます。ハードセキュリティコントロールとして機能しないため、統合 URL を公開してもセキュリティリスクは生じません。

提供された統合 URL を技術的に変更しても、トークンを取得できます。ただし、チャレンジ解決率の可視性が失われたり、`socketTimeoutException` エラーによるトークンの取得の失敗が発生する可能性があるため、これはお勧めしません。

## 依存関係
<a name="waf-mobile-sdk-dependencies"></a>

ダウンロード可能な各 AWS WAF モバイル SDK には、SDK の特定バージョンの依存関係を一覧表示する README ファイルが含まれています。お使いのバージョンのモバイル SDK の依存関係については、README を参照してください。

## 難読化/ProGuard (Android SDK のみ)
<a name="waf-mobile-sdk-obfuscation"></a>

ProGuard などの難読化または最小化製品を使用する場合は、モバイル SDK が正しく動作するように特定の名前空間を除外する必要がある場合があります。お使いのバージョンのモバイル SDK の README をチェックして、名前空間と除外ルールのリストを見つけます。

# AWS WAF モバイル SDK のコード例
<a name="waf-mobile-sdk-coding-examples"></a>

このセクションでは、モバイル SDK を使用するためのコード例を提供します。

## トークンプロバイダーの初期化とトークンの取得
<a name="waf-mobile-sdk-coding-basic"></a>

設定オブジェクトを使用して、トークンプロバイダーインスタンスを開始します。その後、使用可能なオペレーションを使用してトークンを取得できます。必要なコードの基本コンポーネントを次に示します。

------
#### [ iOS ]

```
let url: URL = URL(string: "protection pack (web ACL) integration URL")!
let configuration = WAFConfiguration(applicationIntegrationUrl: url, domainName: "Domain name")
let tokenProvider = WAFTokenProvider(configuration)

//onTokenReady can be add as an observer for UIApplication.willEnterForegroundNotification
self.tokenProvider.onTokenReady() { token, error in
	if let token = token {
	//token available
	}

	if let error = error {
	//error occurred after exhausting all retries
	}
}

//getToken()
let token = tokenProvider.getToken()
```

------
#### [ Android ]

Java の例:

```
String applicationIntegrationURL = "protection pack (web ACL) integration URL";
//Or
URL applicationIntegrationURL = new URL("protection pack (web ACL) integration URL");

String domainName = "Domain name";

WAFConfiguration configuration = WAFConfiguration.builder().applicationIntegrationURL(applicationIntegrationURL).domainName(domainName).build();
WAFTokenProvider tokenProvider = new WAFTokenProvider(Application context, configuration);

// implement a token result callback
WAFTokenResultCallback callback = (wafToken, error) -> {
	if (wafToken != null) {
	// token available
	} else {  
	// error occurred in token refresh  
	}
};

// Add this callback to application creation or activity creation where token will be used
tokenProvider.onTokenReady(callback);

// Once you have token in token result callback
// if background refresh is enabled you can call getToken() from same tokenprovider object
// if background refresh is disabled you can directly call getToken()(blocking call) for new token
WAFToken token = tokenProvider.getToken();
```

Kotlin の例:

```
import com.amazonaws.waf.mobilesdk.token.WAFConfiguration
import com.amazonaws.waf.mobilesdk.token.WAFTokenProvider

private lateinit var wafConfiguration: WAFConfiguration
private lateinit var wafTokenProvider: WAFTokenProvider

private val WAF_INTEGRATION_URL = "protection pack (web ACL) integration URL"
private val WAF_DOMAIN_NAME = "Domain name"

fun initWaf() {
	// Initialize the tokenprovider instance
	val applicationIntegrationURL = URL(WAF_INTEGRATION_URL)
	wafConfiguration =
		WAFConfiguration.builder().applicationIntegrationURL(applicationIntegrationURL)
			.domainName(WAF_DOMAIN_NAME).backgroundRefreshEnabled(true).build()
	wafTokenProvider = WAFTokenProvider(getApplication(), wafConfiguration)
	
		// getToken from tokenprovider object
		println("WAF: "+ wafTokenProvider.token.value)
	
		// implement callback for where token will be used
		wafTokenProvider.onTokenReady {
			wafToken, sdkError ->
		run {
			println("WAF Token:" + wafToken.value)
		}
	}
}
```

------

## SDK による HTTP リクエストでのトークン cookie の提供の許可
<a name="waf-mobile-sdk-coding-auto-token-cookie"></a>

`setTokenCookie` が `TRUE` である場合、トークンプロバイダーは、`tokenCookiePath` で指定されたパスの下のすべての場所に対するウェブリクエストにトークン cookie を含めます。デフォルトでは、`setTokenCookie` は `TRUE`、`tokenCookiePath` は `/` です。

トークン cookie のパスを指定することで、トークン cookie を含むリクエストの範囲を絞り込むことができます (例: `/web/login`)。これを行う場合は、他のパスに送信するリクエストのトークンが AWS WAF ルールで検査されていないことを確認します。`AWSManagedRulesACFPRuleSet` ルールグループを使用する場合、アカウントの登録パスと作成パスを設定すると、ルールグループはそれらのパスに送信されるリクエスト内のトークンをチェックします。詳細については、「[ACFP マネージドルールグループをウェブ ACL に追加](waf-acfp-rg-using.md)」を参照してください。同様に、`AWSManagedRulesATPRuleSet` ルールグループを使用する場合は、ログインパスを設定し、ルールグループはそのパスに送信されるリクエストのトークンをチェックします。詳細については、「[ATP マネージドルールグループを保護パック (ウェブ ACL) に追加](waf-atp-rg-using.md)」を参照してください。

------
#### [ iOS ]

`setTokenCookie` が の場合`TRUE`、トークンプロバイダーは AWS WAF トークンを に保存`HTTPCookieStorage.shared`し、 で指定したドメインへのリクエストに Cookie を自動的に含めます`WAFConfiguration`。

```
let request = URLRequest(url: URL(string: domainEndpointUrl)!)
//The token cookie is set automatically as cookie header
let task = URLSession.shared.dataTask(with: request) { data, urlResponse, error  in
}.resume()
```

------
#### [ Android ]

`setTokenCookie` が の場合`TRUE`、トークンプロバイダーはアプリケーション全体で共有されている`CookieHandler`インスタンスに AWS WAF トークンを保存します。トークンプロバイダーは、`WAFConfiguration` で指定したドメインへのリクエストに cookie を自動的に含めます。

Java の例:

```
URL url = new URL("Domain name");
//The token cookie is set automatically as cookie header
HttpsURLConnection connection = (HttpsURLConnection) url.openConnection();
connection.getResponseCode();
```

Kotlin の例:

```
val url = URL("Domain name")
//The token cookie is set automatically as cookie header
val connection = (url.openConnection() as HttpsURLConnection)
connection.responseCode
```

`CookieHandler` デフォルトインスタンスが既に初期化されている場合、トークンプロバイダーは、それを使用して cookie を管理します。そうでない場合、トークンプロバイダーは AWS WAF トークンを使用して新しい`CookieManager`インスタンスを初期化`CookiePolicy.ACCEPT_ORIGINAL_SERVER`し、この新しいインスタンスを のデフォルトインスタンスとして設定します`CookieHandler`。

次のコードは、アプリケーションで使用できない場合に cookie マネージャーと cookie ハンドラーを SDK が初期化する方法を示しています。

Java の例:

```
CookieManager cookieManager = (CookieManager) CookieHandler.getDefault();
if (cookieManager == null) {
	// Cookie manager is initialized with CookiePolicy.ACCEPT_ORIGINAL_SERVER
	cookieManager = new CookieManager();
	CookieHandler.setDefault(cookieManager);
}
```

Kotlin の例:

```
var cookieManager = CookieHandler.getDefault() as? CookieManager
if (cookieManager == null) {
	// Cookie manager is initialized with CookiePolicy.ACCEPT_ORIGINAL_SERVER
	cookieManager = CookieManager()
	CookieHandler.setDefault(cookieManager)
}
```

------

## HTTP リクエストにおけるトークン cookie の手動による提供
<a name="waf-mobile-sdk-coding-manual-token-cookie"></a>

`setTokenCookie` を `FALSE` に設定した場合、保護されたエンドポイントに対するリクエストで、cookie HTTP リクエストヘッダーとしてトークン cookie を手動で提供する必要があります。次のコードは、これを実行する方法を説明しています。

------
#### [ iOS ]

```
var request = URLRequest(url: wafProtectedEndpoint)
request.setValue("aws-waf-token=token from token provider", forHTTPHeaderField: "Cookie")
request.httpShouldHandleCookies = true
URLSession.shared.dataTask(with: request) { data, response, error in }
```

------
#### [ Android ]

Java の例:

```
URL url = new URL("Domain name");
HttpsURLConnection connection = (HttpsURLConnection) url.openConnection();
String wafTokenCookie = "aws-waf-token=token from token provider";
connection.setRequestProperty("Cookie", wafTokenCookie);
connection.getInputStream();
```

Kotlin の例:

```
val url = URL("Domain name")
val connection = (url.openConnection() as HttpsURLConnection)
val wafTokenCookie = "aws-waf-token=token from token provider"
connection.setRequestProperty("Cookie", wafTokenCookie)
connection.inputStream
```

------