**Présentation d'une nouvelle expérience de console pour AWS WAF**

Vous pouvez désormais utiliser l'expérience mise à jour pour accéder aux AWS WAF fonctionnalités n'importe où dans la console. Pour plus de détails, consultez la section [Utilisation de la console](https://docs.aws.amazon.com/waf/latest/developerguide/working-with-console.html). 

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

# Intégrations d'applications clientes dans AWS WAF
<a name="waf-application-integration"></a>

Cette section explique comment utiliser l'intégration intelligente des menaces APIs et l'API d'intégration JavaScript CAPTCHA avec vos AWS WAF fonctionnalités. 

Utilisez l'intégration des applications clientes APIs pour associer les protections côté AWS WAF client aux protections de votre pack de protection AWS côté serveur (Web ACL), afin de vérifier que les applications clientes qui envoient des requêtes Web à vos ressources protégées sont bien les clients visés et que vos utilisateurs finaux sont des êtres humains. 

Utilisez les intégrations du client pour gérer les problèmes liés aux navigateurs silencieux et les puzzles CAPTCHA, obtenir des jetons prouvant que le navigateur et l'utilisateur final ont répondu avec succès, et pour inclure ces jetons dans les demandes adressées à vos terminaux protégés. Pour des informations générales sur AWS WAF les jetons, consultez[Utilisation de jetons pour l'atténuation AWS WAF intelligente des menaces](waf-tokens.md). 

Combinez vos intégrations clientes avec des protections par pack de protection (ACL Web) qui nécessitent des jetons valides pour accéder à vos ressources. Vous pouvez utiliser des groupes de règles qui vérifient et surveillent les jetons de défi, comme ceux répertoriés dans la section suivante[Intégration intelligente des menaces et règles AWS gérées](waf-application-integration-with-AMRs.md), à, et vous pouvez utiliser les actions de Challenge règle CAPTCHA et pour vérifier, comme décrit dans[CAPTCHAet Challenge dans AWS WAF](waf-captcha-and-challenge.md). 

AWS WAF propose deux niveaux d'intégration pour les JavaScript applications et un pour les applications mobiles : 
+ **Intégration intelligente des menaces** : vérifiez l'application cliente et assurez l'acquisition et la gestion des AWS jetons. Cette fonctionnalité est similaire à celle fournie par l'action de AWS WAF Challenge règle. Cette fonctionnalité intègre complètement votre application cliente au groupe de règles `AWSManagedRulesACFPRuleSet` géré, au groupe de règles `AWSManagedRulesATPRuleSet` géré et au niveau de protection ciblé du groupe de règles `AWSManagedRulesBotControlRuleSet` géré. 

  L'intégration intelligente des menaces APIs utilise le défi du navigateur AWS WAF silencieux pour garantir que les tentatives de connexion et les autres appels à votre ressource protégée ne sont autorisés qu'une fois que le client a obtenu un jeton valide. APIs Gérez l'autorisation par jeton pour les sessions de votre application client et collectez des informations sur le client afin de déterminer s'il est géré par un robot ou par un être humain. 
**Note**  
Ceci est disponible pour JavaScript et pour les applications mobiles Android et iOS. 
+ **Intégration des CAPTCHA** — Vérifiez les utilisateurs finaux avec un casse-tête CAPTCHA personnalisé que vous gérez dans votre application. Cette fonctionnalité est similaire à celle fournie par l'action des AWS WAF CAPTCHA règles, mais avec un contrôle accru sur le placement et le comportement du puzzle. 

  Cette intégration tire parti de l'intégration JavaScript intelligente des menaces pour lancer des défis silencieux et fournir des AWS WAF jetons à la page du client. 
**Note**  
Ceci est disponible pour les JavaScript applications. 

**Topics**
+ [Intégration intelligente des menaces et règles AWS gérées](waf-application-integration-with-AMRs.md)
+ [Accès à l'intégration de l'application AWS WAF client APIs](waf-application-integration-location-in-console.md)
+ [AWS WAF JavaScript intégrations](waf-javascript-api.md)
+ [AWS WAF intégration d'applications mobiles](waf-mobile-sdk.md)

# Intégration intelligente des menaces et règles AWS gérées
<a name="waf-application-integration-with-AMRs"></a>

Cette section explique comment APIs fonctionne l'intégration intelligente des menaces avec les groupes de règles AWS gérées.

L'intégration intelligente des menaces APIs fonctionne avec des packs de protection (Web ACLs) qui utilisent les groupes de règles de menaces intelligents pour activer toutes les fonctionnalités de ces groupes de règles gérés avancés. 
+ AWS WAF Groupe `AWSManagedRulesACFPRuleSet` de règles géré par Fraud Control pour la création de comptes et la prévention des fraudes (ACFP). 

  La fraude liée à la création de compte est une activité illégale en ligne dans le cadre de laquelle un attaquant crée des comptes non valides dans votre application dans le but, par exemple, de recevoir des bonus d'inscription ou de se faire passer pour quelqu'un. Le groupe de règles géré par l'ACFP fournit des règles pour bloquer, étiqueter et gérer les demandes susceptibles de faire partie de tentatives de création de compte frauduleuses. Ils APIs permettent d'affiner la vérification du navigateur client et les informations d'interactivité humaine que les règles ACFP utilisent pour séparer le trafic client valide du trafic malveillant.

  Pour plus d’informations, consultez [AWS WAF Groupe de règles de prévention de la fraude (ACFP) pour la création de comptes et la prévention des fraudes](aws-managed-rule-groups-acfp.md) et [AWS WAF Contrôle des fraudes : création de comptes, prévention des fraudes (ACFP)](waf-acfp.md).
+ AWS WAF Groupe de règles géré par Fraud Control pour la prévention des prises de contrôle des comptes (ATP)`AWSManagedRulesATPRuleSet`. 

  Le piratage de compte est une activité illégale en ligne au cours de laquelle un attaquant obtient un accès non autorisé au compte d'une personne. Le groupe de règles géré par ATP fournit des règles pour bloquer, étiqueter et gérer les demandes susceptibles de faire partie de tentatives malveillantes de prise de contrôle de compte. Ils APIs permettent une vérification précise des clients et une agrégation des comportements que les règles ATP utilisent pour séparer le trafic client valide du trafic malveillant.

  Pour plus d’informations, consultez [AWS WAF Groupe de règles de prévention des prises de contrôle des fraudes (ATP)](aws-managed-rule-groups-atp.md) et [AWS WAF Contrôle des fraudes et prévention des prises de contrôle des comptes (ATP)](waf-atp.md).
+ Niveau de protection ciblé du groupe de règles géré par AWS WAF Bot Control`AWSManagedRulesBotControlRuleSet`. 

  Les robots peuvent être des robots utiles et auto-identifiables, comme la plupart des moteurs de recherche et des robots d'exploration, ou des robots malveillants qui agissent contre votre site Web et ne s'identifient pas eux-mêmes. Le groupe de règles géré par Bot Control fournit des règles pour surveiller, étiqueter et gérer l'activité des robots dans votre trafic Web. Lorsque vous utilisez le niveau de protection ciblé de ce groupe de règles, les règles ciblées utilisent les informations de session client qu'elles APIs fournissent pour mieux détecter les robots malveillants. 

  Pour plus d’informations, consultez [AWS WAF Groupe de règles Bot Control](aws-managed-rule-groups-bot.md) et [AWS WAF Contrôle des robots](waf-bot-control.md).

Pour ajouter l'un de ces groupes de règles gérés à votre pack de protection (ACL Web), consultez les procédures [Ajouter le groupe de règles géré par l'ACFP à votre ACL Web](waf-acfp-rg-using.md)[Ajouter le groupe de règles géré par ATP à votre pack de protection (ACL Web)](waf-atp-rg-using.md), et[Ajout du groupe de règles géré par AWS WAF Bot Control à votre ACL Web](waf-bot-control-rg-using.md).

**Note**  
Les groupes de règles gérés ne bloquent actuellement pas les demandes pour lesquelles il manque des jetons. Afin de bloquer les demandes pour lesquelles il manque des jetons, une fois que vous avez implémenté l'intégration de votre application APIs, suivez les instructions sur[Blocage des demandes dont le AWS WAF jeton n'est pas valide](waf-tokens-block-missing-tokens.md). 

# Accès à l'intégration de l'application AWS WAF client APIs
<a name="waf-application-integration-location-in-console"></a>

Cette section explique où trouver l'intégration de l'application APIs dans la AWS WAF console.

Les JavaScript APIs intégrations sont généralement disponibles et vous pouvez les utiliser pour vos navigateurs et autres appareils qui s'exécutent JavaScript. 

AWS WAF propose une intégration intelligente personnalisée des menaces SDKs pour les applications mobiles Android et iOS. 
+ Pour les applications mobiles et TV Android, elles SDKs fonctionnent pour l'API Android version 23 (Android version 6) et versions ultérieures. Pour plus d'informations sur les versions d'Android, consultez les [notes de mise à jour de SDK Platform](https://developer.android.com/tools/releases/platforms).
+ Pour les applications mobiles iOS, elles SDKs fonctionnent pour iOS version 13 et versions ultérieures. Pour plus d'informations sur les versions d'iOS, consultez les [notes de mise à jour pour iOS et iPadOS](https://developer.apple.com/documentation/ios-ipados-release-notes).
+ Pour les applications Apple TV, elles SDKs fonctionnent pour tvOS version 14 ou ultérieure. Pour plus d'informations sur les versions de tvOS, consultez les notes de [mise à jour de tvOS](https://developer.apple.com/documentation/tvos-release-notes).

**Pour accéder à l'intégration APIs via la console**

1. Connectez-vous à la AWS WAF console AWS Management Console et ouvrez-la sur [https://console.aws.amazon.com/wafv2/homev2](https://console.aws.amazon.com/wafv2/homev2). 

1. Choisissez **Intégration des applications** dans le volet de navigation, puis sélectionnez l'onglet qui vous intéresse.
   + **L'intégration intelligente des menaces** est disponible pour JavaScript les applications mobiles. 

     L'onglet contient les éléments suivants :
     + Liste des packs de protection (Web ACLs) activés pour l'intégration intelligente des applications contre les menaces. La liste inclut chaque pack de protection (ACL Web) qui utilise le groupe de règles `AWSManagedRulesACFPRuleSet` `AWSManagedRulesATPRuleSet` géré, le groupe de règles géré ou le niveau de protection ciblé du groupe de règles `AWSManagedRulesBotControlRuleSet` géré. Lorsque vous implémentez la menace intelligente APIs, vous utilisez l'URL d'intégration du pack de protection (ACL Web) que vous souhaitez intégrer.
     + Celui APIs auquel vous avez accès. Ils JavaScript APIs sont toujours disponibles. Pour accéder au mobile SDKs, contactez l'assistance via [Contact AWS](https://aws.amazon.com/contact-us).
   + L'**intégration du CAPTCHA** est disponible pour les JavaScript applications. 

     L'onglet contient les éléments suivants : 
     + URL d'intégration à utiliser dans votre intégration. 
     + Les clés d'API que vous avez créées pour les domaines de vos applications clientes. Votre utilisation de l'API CAPTCHA nécessite une clé d'API cryptée qui donne aux clients le droit d'accéder au AWS WAF CAPTCHA depuis leurs domaines. Pour chaque client auquel vous effectuez l'intégration, utilisez une clé d'API contenant le domaine du client. Pour plus d'informations sur ces exigences et sur la gestion de ces clés, consultez[Gestion des clés d'API pour l'API JS CAPTCHA](waf-js-captcha-api-key.md).

# AWS WAF JavaScript intégrations
<a name="waf-javascript-api"></a>

Cette section explique comment utiliser les AWS WAF JavaScript intégrations.

Vous pouvez utiliser l' JavaScript intégration APIs pour implémenter des intégrations AWS WAF d'applications dans vos navigateurs et autres appareils qui s'exécutent JavaScript. 

Les puzzles CAPTCHA et les défis silencieux ne peuvent être exécutés que lorsque les navigateurs accèdent à des points de terminaison HTTPS. Les clients du navigateur doivent fonctionner dans des contextes sécurisés pour acquérir des jetons. 
+ Cette menace APIs intelligente vous permet de gérer l'autorisation des jetons par le biais d'un défi de navigateur silencieux côté client et d'inclure les jetons dans les demandes que vous envoyez à vos ressources protégées. 
+ L'API d'intégration CAPTCHA renforce la menace APIs intelligente et vous permet de personnaliser l'emplacement et les caractéristiques du puzzle CAPTCHA dans vos applications clientes. Cette API exploite la menace intelligente pour acquérir des AWS WAF jetons APIs à utiliser sur la page une fois que l'utilisateur final a réussi à résoudre le casse-tête CAPTCHA. 

En utilisant ces intégrations, vous vous assurez que les appels de procédure à distance de votre client contiennent un jeton valide. Lorsque ces intégrations APIs sont en place sur les pages de votre application, vous pouvez implémenter des règles d'atténuation dans votre pack de protection (ACL Web), telles que le blocage des demandes qui ne contiennent pas de jeton valide. Vous pouvez également implémenter des règles qui imposent l'utilisation des jetons que vos applications clientes obtiennent, en utilisant les CAPTCHA actions Challenge ou de vos règles. 

**Exemple de mise en œuvre d'une menace intelligente APIs**  
La liste suivante présente les composants de base d'une implémentation typique de la menace intelligente APIs dans une page d'application Web. 

```
<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>
```

**Exemple d'implémentation de l'API CAPTCHA JavaScript**  
L'API d'intégration CAPTCHA vous permet de personnaliser l'expérience de puzzle CAPTCHA de vos utilisateurs finaux. L'intégration CAPTCHA tire parti de l'intégration JavaScript intelligente des menaces, pour la vérification du navigateur et la gestion des jetons, et ajoute une fonction pour configurer et afficher le puzzle CAPTCHA. 

La liste suivante présente les composants de base d'une implémentation typique de l' JavaScript API CAPTCHA dans une page d'application Web. 

```
<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**
+ [Fournir des domaines à utiliser dans les jetons](waf-js-challenge-api-set-token-domain.md)
+ [Utilisation de l' JavaScript API avec des politiques de sécurité du contenu](waf-javascript-api-csp.md)
+ [Utilisation de l' JavaScript API de gestion intelligente des menaces](waf-js-challenge-api.md)
+ [Utilisation de l'API CAPTCHA JavaScript](waf-js-captcha-api.md)

# Fournir des domaines à utiliser dans les jetons
<a name="waf-js-challenge-api-set-token-domain"></a>

Cette section explique comment fournir des domaines supplémentaires pour les jetons.

Par défaut, lors de AWS WAF la création d'un jeton, celui-ci utilise le domaine hôte de la ressource associée au pack de protection (ACL Web). Vous pouvez fournir des domaines supplémentaires pour les jetons AWS WAF créés pour le JavaScript APIs. Pour ce faire, configurez la variable `window.awsWafCookieDomainList` globale avec un ou plusieurs domaines de jetons. 

Lors AWS WAF de la création d'un jeton, il utilise le domaine le plus approprié et le plus court parmi la combinaison des domaines `window.awsWafCookieDomainList` et du domaine hôte de la ressource associée au pack de protection (ACL Web). 

Exemples de paramètres : 

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

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

Vous ne pouvez pas utiliser de suffixes publics dans cette liste. Par exemple, vous ne pouvez pas utiliser `gov.au` ou `co.uk` comme domaines symboliques dans la liste.

Les domaines que vous spécifiez dans cette liste doivent être compatibles avec vos autres domaines et configurations de domaines : 
+ Les domaines doivent être ceux qui AWS WAF seront acceptés, en fonction du domaine hôte protégé et de la liste de domaines de jetons configurée pour le pack de protection (ACL Web). Pour de plus amples informations, veuillez consulter [AWS WAF configuration de la liste de domaines de jetons du pack de protection (ACL Web)](waf-tokens-domains.md#waf-tokens-domain-lists). 
+ Si vous utilisez l'API JavaScript CAPTCHA, au moins un domaine de votre clé d'API CAPTCHA doit correspondre exactement à l'un des domaines de jetons `window.awsWafCookieDomainList` ou il doit être le domaine apex de l'un de ces domaines de jetons. 

  Par exemple, pour le domaine de jeton`mySubdomain.myApex.com`, la clé `mySubdomain.myApex.com` d'API correspond exactement et la clé d'API `myApex.com` est le domaine apex. L'une ou l'autre des clés correspond au domaine du jeton. 

  Pour plus d'informations sur les clés d'API, consultez[Gestion des clés d'API pour l'API JS CAPTCHA](waf-js-captcha-api-key.md). 

Si vous utilisez le groupe de règles `AWSManagedRulesACFPRuleSet` géré, vous pouvez configurer un domaine qui correspond à celui indiqué dans le chemin de création de compte que vous avez indiqué dans la configuration du groupe de règles. Pour en savoir plus sur cette configuration, consultez [Ajouter le groupe de règles géré par l'ACFP à votre ACL Web](waf-acfp-rg-using.md).

Si vous utilisez le groupe de règles `AWSManagedRulesATPRuleSet` géré, vous pouvez configurer un domaine qui correspond à celui indiqué dans le chemin de connexion que vous avez indiqué pour la configuration du groupe de règles. Pour en savoir plus sur cette configuration, consultez [Ajouter le groupe de règles géré par ATP à votre pack de protection (ACL Web)](waf-atp-rg-using.md).

# Utilisation de l' JavaScript API avec des politiques de sécurité du contenu
<a name="waf-javascript-api-csp"></a>

Cette section fournit un exemple de configuration pour autoriser le domaine AWS WAF apex à être répertorié.

Si vous appliquez des politiques de sécurité du contenu (CSP) à vos ressources, pour que votre JavaScript implémentation fonctionne, vous devez autoriser le domaine AWS WAF apex sur la liste. `awswaf.com` Ils JavaScript SDKs font des appels à différents AWS WAF points de terminaison, donc allowlisting ce domaine fournit les autorisations dont ils SDKs ont besoin pour fonctionner.

Voici un exemple de configuration permettant d'autoriser le domaine AWS WAF apex à être répertorié : 

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

Si vous essayez d'utiliser le JavaScript SDKs avec des ressources qui utilisent le CSP et que vous n'avez pas autorisé le AWS WAF domaine dans la liste, vous recevrez des erreurs du type suivant : 

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

# Utilisation de l' JavaScript API de gestion intelligente des menaces
<a name="waf-js-challenge-api"></a>

Cette section fournit des instructions relatives à l'utilisation de l' JavaScript API de menace intelligente dans votre application cliente.

La menace intelligente APIs fournit des opérations permettant d'exécuter des défis silencieux contre le navigateur de l'utilisateur et de gérer les AWS WAF jetons qui prouvent le succès des réponses aux défis et aux CAPTCHA. 

Implémentez l' JavaScript intégration d'abord dans un environnement de test, puis en production. Pour obtenir des conseils supplémentaires sur le codage, consultez les sections suivantes. 

 

**Pour utiliser la menace intelligente APIs**

1. **Installez le APIs** 

   Si vous utilisez l'API CAPTCHA, vous pouvez ignorer cette étape. Lorsque vous installez l'API CAPTCHA, le script installe automatiquement la menace intelligente. APIs

   1. Connectez-vous à la AWS WAF console AWS Management Console et ouvrez-la sur [https://console.aws.amazon.com/wafv2/homev2](https://console.aws.amazon.com/wafv2/homev2). 

   1. Dans le panneau de navigation, choisissez **Intégration d'applications**. Sur la page **d'intégration des applications**, vous pouvez voir les options sous forme d'onglets. 

   1. Sélectionnez **Intégration intelligente des menaces**

   1. Dans l'onglet, sélectionnez le pack de protection (ACL Web) que vous souhaitez intégrer. La liste des packs de protection (ACL Web) inclut uniquement les packs de protection (Web ACLs) qui utilisent le groupe de règles `AWSManagedRulesACFPRuleSet` `AWSManagedRulesATPRuleSet` géré, le groupe de règles géré ou le niveau de protection ciblé du groupe de règles `AWSManagedRulesBotControlRuleSet` géré. 

   1. Ouvrez le volet **JavaScript SDK** et copiez la balise de script à utiliser dans votre intégration. 

   1. Dans le code de page de votre application, dans la `<head>` section, insérez la balise de script que vous avez copiée pour le pack de protection (ACL Web). Cette inclusion permet à votre application cliente de récupérer automatiquement un jeton en arrière-plan lors du chargement de la page. 

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

      Cette `<script>` liste est configurée avec l'`defer`attribut, mais vous pouvez modifier le paramètre `async` si vous souhaitez un comportement différent pour votre page. 

1. **(Facultatif) Ajoutez une configuration de domaine pour les jetons du client** : par défaut, AWS WAF lors de la création d'un jeton, celui-ci utilise le domaine hôte de la ressource associée au pack de protection (ACL Web). Pour fournir des domaines supplémentaires pour le JavaScript APIs, suivez les instructions sur[Fournir des domaines à utiliser dans les jetons](waf-js-challenge-api-set-token-domain.md). 

1. **Codez votre intégration intelligente des menaces** : écrivez votre code pour vous assurer que la récupération des jetons est terminée avant que le client n'envoie ses demandes à vos points de terminaison protégés. Si vous utilisez déjà l'`fetch`API pour effectuer votre appel, vous pouvez remplacer le `fetch` wrapper AWS WAF d'intégration. Si vous n'utilisez pas l'`fetch`API, vous pouvez utiliser l'`getToken`opération AWS WAF d'intégration à la place. Pour obtenir des conseils de codage, consultez les sections suivantes. 

1. **Ajoutez la vérification par jeton dans votre pack de protection (ACL Web)** : ajoutez au moins une règle à votre pack de protection (ACL Web) qui vérifie la validité d'un jeton de défi dans les requêtes Web envoyées par votre client. Vous pouvez utiliser des groupes de règles qui vérifient et surveillent les jetons de défi, comme le niveau cible du groupe de règles géré par Bot Control, et vous pouvez utiliser l'action de Challenge règle pour vérifier, comme décrit dans[CAPTCHAet Challenge dans AWS WAF](waf-captcha-and-challenge.md). 

   Les ajouts au pack de protection (ACL Web) vérifient que les demandes adressées à vos points de terminaison protégés incluent le jeton que vous avez acquis lors de l'intégration de votre client. Les demandes qui incluent un jeton valide et non expiré passent l'Challengeinspection et ne constituent pas un autre défi silencieux pour votre client. 

1. **(Facultatif) Bloquer les demandes pour lesquelles il manque des jetons** — Si vous utilisez le APIs groupe de règles géré par l'ACFP, le groupe de règles géré ATP ou les règles ciblées du groupe de règles Bot Control, ces règles ne bloquent pas les demandes contenant des jetons manquants. Pour bloquer les demandes auxquelles il manque des jetons, suivez les instructions sur[Blocage des demandes dont le AWS WAF jeton n'est pas valide](waf-tokens-block-missing-tokens.md). 

**Topics**
+ [Spécification de l'API de menace intelligente](waf-js-challenge-api-specification.md)
+ [Comment utiliser le `fetch` wrapper d'intégration](waf-js-challenge-api-fetch-wrapper.md)
+ [Comment utiliser l'intégration `getToken`](waf-js-challenge-api-get-token.md)

# Spécification de l'API de menace intelligente
<a name="waf-js-challenge-api-specification"></a>

Cette section répertorie les spécifications relatives aux méthodes et aux propriétés de l'atténuation intelligente des menaces JavaScript APIs. Utilisez-les APIs pour les intégrations intelligentes des menaces et des CAPTCHA.

**`AwsWafIntegration.fetch()`**  
Envoie la `fetch` requête HTTP au serveur à l'aide de l'implémentation AWS WAF d'intégration. 

**`AwsWafIntegration.getToken()`**  
Récupère le AWS WAF jeton stocké et le stocke dans un cookie sur la page en cours avec un nom `aws-waf-token` et une valeur définie sur la valeur du jeton. 

**`AwsWafIntegration.hasToken()`**  
Renvoie une valeur booléenne indiquant si le `aws-waf-token` cookie contient actuellement un jeton non expiré. 

Si vous utilisez également l'intégration CAPTCHA, consultez les spécifications correspondantes à l'adresse. [Spécification de l'API CAPTCHA JavaScript](waf-js-captcha-api-specification.md)

# Comment utiliser le `fetch` wrapper d'intégration
<a name="waf-js-challenge-api-fetch-wrapper"></a>

Cette section fournit des instructions pour utiliser le `fetch` wrapper d'intégration.

Vous pouvez utiliser le AWS WAF `fetch` wrapper en modifiant vos `fetch` appels habituels à l'`fetch`API sous l'espace de `AwsWafIntegration` noms. Le AWS WAF wrapper prend en charge les mêmes options que l'appel d' JavaScript `fetch`API standard et ajoute la gestion des jetons pour l'intégration. Cette approche est généralement la méthode la plus simple pour intégrer votre application. 

**Avant l'implémentation du wrapper**  
La liste d'exemples suivante montre le code standard avant d'implémenter le `AwsWafIntegration` `fetch` wrapper.

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

**Après l'implémentation du wrapper**  
La liste suivante montre le même code avec l'implémentation du `AwsWafIntegration` `fetch` wrapper.

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

# Comment utiliser l'intégration `getToken`
<a name="waf-js-challenge-api-get-token"></a>

Cette section explique comment utiliser cette `getToken` opération.

AWS WAF nécessite que vos demandes adressées aux points de terminaison protégés incluent le cookie nommé `aws-waf-token` avec la valeur de votre jeton actuel. 

L'`getToken`opération est un appel d'API asynchrone qui récupère le AWS WAF jeton et le stocke dans un cookie sur la page en cours avec un nom `aws-waf-token` et une valeur définie sur la valeur du jeton. Vous pouvez utiliser ce cookie symbolique selon vos besoins sur votre page. 

Lorsque vous appelez`getToken`, il effectue les opérations suivantes : 
+ Si un jeton non expiré est déjà disponible, l'appel le renvoie immédiatement.
+ Dans le cas contraire, l'appel récupère un nouveau jeton auprès du fournisseur de jetons, en attendant jusqu'à 2 secondes que le flux de travail d'acquisition de jetons soit terminé avant l'expiration du délai imparti. Si l'opération expire, elle génère une erreur que votre code d'appel doit gérer. 

L'`getToken`opération est accompagnée d'une `hasToken` opération qui indique si le `aws-waf-token` cookie contient actuellement un jeton non expiré. 

`AwsWafIntegration.getToken()`récupère un jeton valide et le stocke sous forme de cookie. La plupart des appels clients joignent automatiquement ce cookie, mais ce n'est pas le cas pour certains. Par exemple, les appels passés entre des domaines hôtes ne joignent pas le cookie. Dans les détails de mise en œuvre qui suivent, nous montrons comment travailler avec les deux types d'appels clients. 

**`getToken`Implémentation de base, pour les appels qui joignent le `aws-waf-token` cookie**  
L'exemple de liste suivant montre le code standard pour implémenter l'`getToken`opération avec une demande de connexion.

```
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
	}
```

**Soumettre le formulaire uniquement une fois que le jeton sera disponible auprès de `getToken`**  
La liste suivante indique comment enregistrer un écouteur d'événements pour intercepter les soumissions de formulaires jusqu'à ce qu'un jeton valide soit disponible pour utilisation. 

```
<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>
```

**Joindre le jeton lorsque votre client n'attache pas le `aws-waf-token` cookie par défaut**  
`AwsWafIntegration.getToken()`récupère un jeton valide et le stocke sous forme de cookie, mais tous les appels clients ne joignent pas ce cookie par défaut. Par exemple, les appels passés entre des domaines hôtes ne joignent pas le cookie. 

Le `fetch` wrapper gère ces cas automatiquement, mais si vous n'êtes pas en mesure d'utiliser le `fetch` wrapper, vous pouvez le faire en utilisant un en-tête personnalisé`x-aws-waf-token`. AWS WAF lit les jetons depuis cet en-tête, en plus de les lire depuis le `aws-waf-token` cookie. Le code suivant montre un exemple de définition de l'en-tête. 

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

Par défaut, AWS WAF n'accepte que les jetons contenant le même domaine que le domaine hôte demandé. Tous les jetons interdomaines nécessitent des entrées correspondantes dans la liste des domaines des jetons du pack de protection (ACL Web). Pour de plus amples informations, veuillez consulter [AWS WAF configuration de la liste de domaines de jetons du pack de protection (ACL Web)](waf-tokens-domains.md#waf-tokens-domain-lists). 

Pour plus d'informations sur l'utilisation de jetons entre domaines, consultez [aws-waf-bot-controlaws-samples/](https://github.com/aws-samples/aws-waf-bot-control-api-protection-with-captcha) -. api-protection-with-captcha

# Utilisation de l'API CAPTCHA JavaScript
<a name="waf-js-captcha-api"></a>

Cette section fournit des instructions pour utiliser l'API d'intégration CAPTCHA.

L' JavaScript API CAPTCHA vous permet de configurer le puzzle CAPTCHA et de le placer où vous le souhaitez dans votre application cliente. Cette API exploite les fonctionnalités de la menace intelligente JavaScript APIs pour acquérir et utiliser des AWS WAF jetons une fois qu'un utilisateur final a réussi à résoudre un casse-tête CAPTCHA. 

Implémentez l' JavaScript intégration d'abord dans un environnement de test, puis en production. Pour obtenir des conseils supplémentaires sur le codage, consultez les sections suivantes. 

**Pour utiliser l'API d'intégration CAPTCHA**

1. **Installation de l'API**

   1. Connectez-vous à la AWS WAF console AWS Management Console et ouvrez-la sur [https://console.aws.amazon.com/wafv2/homev2](https://console.aws.amazon.com/wafv2/homev2). 

   1. Dans le panneau de navigation, choisissez **Intégration d'applications**. Sur la page **d'intégration des applications**, vous pouvez voir les options sous forme d'onglets. 

   1. Sélectionnez l'**intégration CAPTCHA**.

   1. Copiez la balise de script JavaScript d'intégration répertoriée pour l'utiliser dans votre intégration.

   1. Dans le code de page de votre application, dans la `<head>` section, insérez la balise de script que vous avez copiée. Cette inclusion rend le puzzle CAPTCHA disponible pour la configuration et l'utilisation. 

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

      Cette `<script>` liste est configurée avec l'`defer`attribut, mais vous pouvez modifier le paramètre `async` si vous souhaitez un comportement différent pour votre page. 

      Le script CAPTCHA charge également automatiquement le script d'intégration intelligente des menaces s'il n'est pas déjà présent. Le script intelligent d'intégration des menaces permet à votre application cliente de récupérer automatiquement un jeton en arrière-plan lors du chargement de la page et fournit d'autres fonctionnalités de gestion des jetons dont vous avez besoin pour utiliser l'API CAPTCHA. 

1. **(Facultatif) Ajoutez une configuration de domaine pour les jetons du client** : par défaut, AWS WAF lors de la création d'un jeton, celui-ci utilise le domaine hôte de la ressource associée au pack de protection (ACL Web). Pour fournir des domaines supplémentaires pour le JavaScript APIs, suivez les instructions sur[Fournir des domaines à utiliser dans les jetons](waf-js-challenge-api-set-token-domain.md). 

1. **Obtenir la clé d'API cryptée pour le client** — L'API CAPTCHA nécessite une clé d'API cryptée contenant une liste de domaines clients valides. AWS WAF utilise cette clé pour vérifier que le domaine client que vous utilisez avec l'intégration est approuvé pour utiliser le AWS WAF CAPTCHA. Pour générer votre clé d'API, suivez les instructions sur[Gestion des clés d'API pour l'API JS CAPTCHA](waf-js-captcha-api-key.md).

1. **Codez l'implémentation de votre widget CAPTCHA** : implémentez l'appel d'`renderCaptcha()`API sur votre page, à l'endroit où vous souhaitez l'utiliser. Pour plus d'informations sur la configuration et l'utilisation de cette fonction, consultez les sections suivantes, [Spécification de l'API CAPTCHA JavaScript](waf-js-captcha-api-specification.md) et[Comment afficher le casse-tête CAPTCHA](waf-js-captcha-api-render.md). 

   L'implémentation du CAPTCHA s'intègre à l'intégration intelligente des menaces APIs pour la gestion des jetons et pour exécuter des appels de récupération utilisant les jetons. AWS WAF Pour obtenir des conseils sur leur utilisation APIs, voir[Utilisation de l' JavaScript API de gestion intelligente des menaces](waf-js-challenge-api.md).

1. **Ajoutez la vérification par jeton dans votre pack de protection (ACL Web)** : ajoutez au moins une règle à votre pack de protection (ACL Web) qui vérifie la validité d'un jeton CAPTCHA dans les requêtes Web envoyées par votre client. Vous pouvez utiliser l'action de la CAPTCHA règle pour vérifier, comme décrit dans[CAPTCHAet Challenge dans AWS WAF](waf-captcha-and-challenge.md). 

   Les ajouts au pack de protection (ACL Web) vérifient que les demandes envoyées à vos points de terminaison protégés incluent le jeton que vous avez acquis lors de l'intégration de votre client. Les demandes qui incluent un jeton CAPTCHA valide et non expiré passent l'inspection des CAPTCHA règles et ne présentent aucun autre casse-tête CAPTCHA à votre utilisateur final. 

Après avoir implémenté l' JavaScript API, vous pouvez consulter les CloudWatch statistiques relatives aux tentatives et aux solutions de casse-tête CAPTCHA. Pour les statistiques et les détails relatifs aux dimensions, voir[Mesures et dimensions du compte](waf-metrics.md#waf-metrics-account).

**Topics**
+ [Spécification de l'API CAPTCHA JavaScript](waf-js-captcha-api-specification.md)
+ [Comment afficher le casse-tête CAPTCHA](waf-js-captcha-api-render.md)
+ [Gestion d'une réponse CAPTCHA depuis AWS WAF](waf-js-captcha-api-conditional.md)
+ [Gestion des clés d'API pour l'API JS CAPTCHA](waf-js-captcha-api-key.md)

# Spécification de l'API CAPTCHA JavaScript
<a name="waf-js-captcha-api-specification"></a>

Cette section répertorie les spécifications des méthodes et des propriétés du CAPTCHA JavaScript APIs. Utilisez le CAPTCHA JavaScript APIs pour exécuter des puzzles CAPTCHA personnalisés dans vos applications clientes. 

Cette API s'appuie sur la menace intelligente APIs, que vous utilisez pour configurer et gérer l'acquisition et l'utilisation de AWS WAF jetons. Voir[Spécification de l'API de menace intelligente](waf-js-challenge-api-specification.md).

**`AwsWafCaptcha.renderCaptcha(container, configuration)`**  
Présente un casse-tête AWS WAF CAPTCHA à l'utilisateur final et, en cas de succès, met à jour le jeton client avec la validation CAPTCHA. Ceci n'est disponible qu'avec l'intégration CAPTCHA. Utilisez cet appel ainsi que la menace intelligente APIs pour gérer la récupération des jetons et pour fournir le jeton dans vos `fetch` appels. Découvrez la menace intelligente APIs sur[Spécification de l'API de menace intelligente](waf-js-challenge-api-specification.md).  
Contrairement à l'interstitiel CAPTCHA qui AWS WAF envoie, le puzzle CAPTCHA rendu par cette méthode affiche le puzzle immédiatement, sans écran de titre initial.     
**`container`**  
L'`Element`objet de l'élément conteneur cible sur la page. Ceci est généralement récupéré en appelant `document.getElementById()` ou`document.querySelector()`.  
Obligatoire : oui  
Type : `Element`  
**configuration**  
Un objet contenant les paramètres de configuration CAPTCHA, comme suit : ****    
**`apiKey`**   
La clé API cryptée qui autorise les autorisations pour le domaine du client. Utilisez la AWS WAF console pour générer vos clés d'API pour les domaines de vos clients. Vous pouvez utiliser une clé pour un maximum de cinq domaines. Pour plus d'informations, consultez [Gestion des clés d'API pour l'API JS CAPTCHA](waf-js-captcha-api-key.md).   
Obligatoire : oui  
Type : `string`  
**`onSuccess: (wafToken: string) => void;`**   
Appelé avec un AWS WAF jeton valide lorsque l'utilisateur final termine avec succès un casse-tête CAPTCHA. Utilisez le jeton dans les demandes que vous envoyez aux points de terminaison que vous protégez à l'aide d'un pack de AWS WAF protection (ACL Web). Le jeton fournit la preuve et l'horodatage de la dernière réalisation réussie du puzzle.   
Obligatoire : oui  
**`onError?: (error: CaptchaError) => void;`**   
Appelé avec un objet d'erreur lorsqu'une erreur survient lors de l'opération CAPTCHA.   
Obligatoire : non  
**`CaptchaError`définition de classe** — Le `onError` gestionnaire fournit un type d'erreur avec la définition de classe suivante.   

```
CaptchaError extends Error {
    kind: "internal_error" | "network_error" | "token_error" | "client_error";
    statusCode?: number;
}
```
+ `kind`— Le type d'erreur renvoyé. 
+ `statusCode`— Le code d'état HTTP, s'il est disponible. Ceci est utilisé `network_error` si l'erreur est due à une erreur HTTP.  
**`onLoad?: () => void;`**   
Appelé lors du chargement d'un nouveau casse-tête CAPTCHA.  
Obligatoire : non  
**`onPuzzleTimeout?: () => void;`**   
Appelé lorsqu'un casse-tête CAPTCHA n'est pas terminé avant son expiration.  
Obligatoire : non  
**`onPuzzleCorrect?: () => void;`**   
Appelé lorsqu'une réponse correcte est fournie à un casse-tête CAPTCHA.  
Obligatoire : non  
**`onPuzzleIncorrect?: () => void;`**   
Appelé lorsqu'une réponse incorrecte est fournie à un casse-tête CAPTCHA.  
Obligatoire : non  
**`defaultLocale`**   
La localisation par défaut à utiliser pour le puzzle CAPTCHA. Les instructions écrites pour les puzzles CAPTCHA sont disponibles en arabe (ar-SA), chinois simplifié (zh-CN), néerlandais (nl-NL), anglais (en-US), français (fr-FR), allemand (de-DE), italien (it-IT), japonais (ja-JP), portugais brésilien (pT-BR), espagnol (es-ES) et turc (tr-TR). Les instructions audio sont disponibles pour toutes les langues écrites, à l'exception du chinois et du japonais, qui sont par défaut l'anglais. Pour modifier la langue par défaut, fournissez la langue internationale et le code local, par exemple,`ar-SA`.  
Par défaut : langue actuellement utilisée dans le navigateur de l'utilisateur final  
Obligatoire : non  
Type : `string`  
**`disableLanguageSelector`**   
S'il est défini sur`true`, le casse-tête CAPTCHA masque le sélecteur de langue.   
Par défaut: `false`  
Obligatoire : non  
Type : `boolean`  
**`dynamicWidth`**   
S'il est défini sur`true`, le puzzle CAPTCHA change de largeur pour être compatible avec la largeur de la fenêtre du navigateur.   
Par défaut: `false`  
Obligatoire : non  
Type : `boolean`  
**`skipTitle`**   
S'il est défini sur`true`, le casse-tête CAPTCHA n'affiche pas le titre du puzzle intitulé **Résoudre le** puzzle.   
Par défaut: `false`  
Obligatoire : non  
Type : `boolean`

# Comment afficher le casse-tête CAPTCHA
<a name="waf-js-captcha-api-render"></a>

Cette section fournit un exemple de `renderCaptcha` mise en œuvre.

Vous pouvez utiliser l' AWS WAF `renderCaptcha`appel où vous le souhaitez dans votre interface client. L'appel permet de récupérer un casse-tête CAPTCHA AWS WAF, de le restituer et d'envoyer les résultats à des fins de vérification. AWS WAF Lorsque vous passez l'appel, vous indiquez la configuration du rendu du puzzle et les rappels que vous souhaitez exécuter lorsque vos utilisateurs finaux auront terminé le puzzle. Pour plus de détails sur les options, reportez-vous à la section précédente,[Spécification de l'API CAPTCHA JavaScript](waf-js-captcha-api-specification.md).

Utilisez cet appel conjointement avec la fonctionnalité de gestion des jetons de l'intégration intelligente des menaces APIs. Cet appel fournit à votre client un jeton qui vérifie la réussite du casse-tête CAPTCHA. Utilisez l'intégration intelligente des menaces APIs pour gérer le jeton et pour fournir le jeton dans les appels de votre client aux points de terminaison protégés par des packs de AWS WAF protection (Web ACLs). Pour plus d'informations sur la menace intelligente APIs, consultez[Utilisation de l' JavaScript API de gestion intelligente des menaces](waf-js-challenge-api.md).

**Exemples d’implémentation**  
La liste d'exemples suivante montre une implémentation CAPTCHA standard, y compris le placement de l'URL d' AWS WAF intégration dans la `<head>` section. 

Cette liste configure la `renderCaptcha` fonction avec un rappel de réussite qui utilise le `AwsWafIntegration.fetch` wrapper de l'intégration intelligente des menaces. APIs Pour plus d'informations sur cette fonction, consultez[Comment utiliser le `fetch` wrapper d'intégration](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>
```

**Exemples de paramètres de configuration**  
L'exemple de liste suivant montre les `renderCaptcha` paramètres autres que ceux par défaut pour les options de largeur et de titre. 

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

Pour obtenir des informations complètes sur les options de configuration, consultez[Spécification de l'API CAPTCHA JavaScript](waf-js-captcha-api-specification.md).

# Gestion d'une réponse CAPTCHA depuis AWS WAF
<a name="waf-js-captcha-api-conditional"></a>

Cette section fournit un exemple de gestion d'une réponse CAPTCHA.

Une AWS WAF règle comportant une CAPTCHA action met fin à l'évaluation d'une requête Web correspondante si celle-ci ne contient pas de jeton avec un horodatage CAPTCHA valide. Si la demande est un `GET` text/html appel, l'CAPTCHAaction fournit alors au client un interstitiel avec un casse-tête CAPTCHA. Lorsque vous n'intégrez pas l' JavaScript API CAPTCHA, l'interstitiel exécute le puzzle et, si l'utilisateur final le résout avec succès, soumet automatiquement à nouveau la demande. 

Lorsque vous intégrez l' JavaScript API CAPTCHA et que vous personnalisez votre gestion des CAPTCHA, vous devez détecter la réponse CAPTCHA finale, fournir votre CAPTCHA personnalisé, puis si l'utilisateur final résout le casse-tête avec succès, soumettre à nouveau la demande Web du client. 

L'exemple de code suivant montre comment procéder : 

**Note**  
La réponse à l' AWS WAF CAPTCHAaction possède un code d'état HTTP 405, que nous utilisons pour reconnaître la CAPTCHA réponse dans ce code. Si votre point de terminaison protégé utilise un code d'état HTTP 405 pour communiquer tout autre type de réponse pour le même appel, cet exemple de code affichera également un casse-tête CAPTCHA pour ces réponses. 

```
<!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>
```

# Gestion des clés d'API pour l'API JS CAPTCHA
<a name="waf-js-captcha-api-key"></a>

Cette section fournit des instructions pour générer et supprimer des clés d'API.

Pour intégrer le AWS WAF CAPTCHA dans une application cliente avec l' JavaScript API, vous avez besoin de la balise d'intégration d' JavaScript API et de la clé d'API cryptée pour le domaine client dans lequel vous souhaitez exécuter votre puzzle CAPTCHA. 

L'intégration de l'application CAPTCHA JavaScript utilise les clés d'API cryptées pour vérifier que le domaine de l'application client est autorisé à utiliser l'API AWS WAF CAPTCHA. Lorsque vous appelez l'API CAPTCHA depuis votre JavaScript client, vous fournissez une clé d'API avec une liste de domaines qui inclut un domaine pour le client actuel. Vous pouvez répertorier jusqu'à 5 domaines dans une seule clé cryptée. 

**Exigences clés de l'API**  
La clé d'API que vous utilisez dans votre intégration CAPTCHA doit contenir un domaine qui s'applique au client sur lequel vous utilisez la clé. 
+ Si vous spécifiez un `window.awsWafCookieDomainList` dans l'intégration intelligente des menaces de votre client, au moins un domaine de votre clé d'API doit correspondre exactement à l'un des domaines de jetons `window.awsWafCookieDomainList` ou doit être le domaine apex de l'un de ces domaines de jetons. 

  Par exemple, pour le domaine de jeton`mySubdomain.myApex.com`, la clé `mySubdomain.myApex.com` d'API correspond exactement et la clé d'API `myApex.com` est le domaine apex. L'une ou l'autre des clés correspond au domaine du jeton. 

  Pour plus d'informations sur le paramétrage de la liste des domaines de jetons, consultez[Fournir des domaines à utiliser dans les jetons](waf-js-challenge-api-set-token-domain.md).
+ Dans le cas contraire, le domaine actuel doit être contenu dans la clé d'API. Le domaine actuel est celui que vous pouvez voir dans la barre d'adresse du navigateur. 

Les domaines que vous utilisez doivent être ceux qui AWS WAF seront acceptés, en fonction du domaine hôte protégé et de la liste de domaines de jetons configurée pour l'ACL Web. Pour de plus amples informations, veuillez consulter [AWS WAF configuration de la liste de domaines de jetons du pack de protection (ACL Web)](waf-tokens-domains.md#waf-tokens-domain-lists).

**Comment choisir la région pour votre clé d'API**  
AWS WAF peut générer des clés d'API CAPTCHA dans toutes les régions où elles AWS WAF sont disponibles. 

En règle générale, vous devez utiliser la même région pour votre clé d'API CAPTCHA que celle que vous utilisez pour votre pack de protection (ACL Web). Toutefois, si vous vous attendez à ce qu'un pack de protection régional (ACL Web) attire un public mondial, vous pouvez obtenir une balise d' JavaScript intégration CAPTCHA limitée CloudFront et une clé d'API limitée CloudFront, et les utiliser avec un pack de protection régional (ACL Web). Cette approche permet aux clients de charger un casse-tête CAPTCHA depuis la région la plus proche d'eux, ce qui réduit le temps de latence. 

Les clés d'API CAPTCHA qui sont limitées à des régions autres que ne CloudFront sont pas prises en charge pour une utilisation dans plusieurs régions. Ils ne peuvent être utilisés que dans la région à laquelle ils sont destinés. 

**Pour générer une clé d'API pour les domaines de vos clients**  
Pour obtenir l'URL d'intégration et générer et récupérer les clés d'API via la console. 

1. Connectez-vous à la AWS WAF console AWS Management Console et ouvrez-la sur [https://console.aws.amazon.com/wafv2/homev2](https://console.aws.amazon.com/wafv2/homev2). 

1. Dans le panneau de navigation, choisissez **Intégration d'applications**. 

1. Dans le volet des **packs de protection (Web ACLs) activés pour l'intégration des applications**, sélectionnez la région que vous souhaitez utiliser pour votre clé d'API. Vous pouvez également sélectionner la région dans le volet des **clés d'API** de l'onglet d'**intégration CAPTCHA**.

1. Choisissez l'onglet Intégration **CAPTCHA**. Cet onglet fournit la balise d' JavaScript intégration CAPTCHA, que vous pouvez utiliser dans votre intégration, ainsi que la liste des clés d'API. Les deux sont limités à la région sélectionnée.

1. Dans le volet **des clés d'API**, choisissez **Generate key**. Le dialogue de génération de clés apparaît. 

1. Entrez les domaines clients que vous souhaitez inclure dans la clé. Vous pouvez saisir jusqu'à 5. Lorsque vous avez terminé, choisissez **Generate key**. L'interface revient à l'onglet d'intégration CAPTCHA, où votre nouvelle clé est répertoriée. 

   Une fois créée, une clé d'API est immuable. Si vous devez apporter des modifications à une clé, générez une nouvelle clé et utilisez-la à la place. 

1. (Facultatif) Copiez la clé nouvellement générée pour l'utiliser dans votre intégration. 

Vous pouvez également utiliser le REST APIs ou l'un des langages spécifiques AWS SDKs pour ce travail. Les appels d'API REST sont [Create APIKey](https://docs.aws.amazon.com/waf/latest/APIReference/API_CreateAPIKey.html) et [List APIKeys](https://docs.aws.amazon.com/waf/latest/APIReference/API_ListAPIKeys.html). 

**Pour supprimer une clé d’API**  
Pour supprimer une clé d'API, vous devez utiliser l'API REST ou l'une des langues spécifiques AWS SDKs. L'appel de l'API REST est [Delete APIKey](https://docs.aws.amazon.com/waf/latest/APIReference/API_DeleteAPIKey.html). Vous ne pouvez pas utiliser la console pour supprimer une clé. 

Une fois que vous avez supprimé une clé, cela peut prendre jusqu' AWS WAF à 24 heures pour interdire son utilisation dans toutes les régions. 

# AWS WAF intégration d'applications mobiles
<a name="waf-mobile-sdk"></a>

Cette section aborde le sujet de l'utilisation du AWS WAF mobile SDKs pour implémenter l'intégration AWS WAF intelligente des menaces SDKs pour les applications mobiles et TV Android et iOS. Pour les applications TV, SDKs elles sont compatibles avec les principales plateformes de télévision intelligente, notamment Android TV et Apple TV.
+ Pour les applications mobiles et TV Android, elles SDKs fonctionnent pour l'API Android version 23 (Android version 6) et versions ultérieures. Pour plus d'informations sur les versions d'Android, consultez les [notes de mise à jour de SDK Platform](https://developer.android.com/tools/releases/platforms).
+ Pour les applications mobiles iOS, elles SDKs fonctionnent pour iOS version 13 et versions ultérieures. Pour plus d'informations sur les versions d'iOS, consultez les [notes de mise à jour pour iOS et iPadOS](https://developer.apple.com/documentation/ios-ipados-release-notes).
+ Pour les applications Apple TV, elles SDKs fonctionnent pour tvOS version 14 ou ultérieure. Pour plus d'informations sur les versions de tvOS, consultez les notes de [mise à jour de tvOS](https://developer.apple.com/documentation/tvos-release-notes).

Avec le AWS WAF SDK mobile, vous pouvez gérer l'autorisation des jetons et inclure les jetons dans les demandes que vous envoyez à vos ressources protégées. En utilisant le SDKs, vous vous assurez que ces appels de procédure à distance effectués par votre client contiennent un jeton valide. En outre, lorsque cette intégration est en place sur les pages de votre application, vous pouvez implémenter des règles d'atténuation dans votre pack de protection (ACL Web), telles que le blocage des demandes qui ne contiennent pas de jeton valide.

Pour accéder au mobile SDKs, contactez l'assistance via [Contact AWS](https://aws.amazon.com/contact-us).

**Note**  
Le AWS WAF mobile SDKs n'est pas disponible pour la personnalisation du CAPTCHA.

L'approche de base pour utiliser le SDK consiste à créer un fournisseur de jetons à l'aide d'un objet de configuration, puis à utiliser le fournisseur de jetons pour récupérer des AWS WAF jetons. Par défaut, le fournisseur de jetons inclut les jetons récupérés dans vos requêtes Web adressées à votre ressource protégée. 

Voici une liste partielle d'une implémentation du SDK, qui montre les principaux composants. Pour obtenir des exemples détaillés, consultez [Exemples de code pour le SDK AWS WAF mobile](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();
```

------

# Installation du SDK AWS WAF mobile
<a name="waf-mobile-sdk-installing"></a>

Cette section fournit des instructions pour installer le SDK AWS WAF mobile.

Pour accéder au mobile SDKs, contactez l'assistance via [Contact AWS](https://aws.amazon.com/contact-us).

Implémentez le SDK mobile d'abord dans un environnement de test, puis en production.

**Pour installer le SDK AWS WAF mobile**

1. Connectez-vous à la AWS WAF console AWS Management Console et ouvrez-la sur [https://console.aws.amazon.com/wafv2/homev2](https://console.aws.amazon.com/wafv2/homev2). 

1. Dans le panneau de navigation, choisissez **Intégration d'applications**. 

1. Dans l'onglet **Intégrations intelligentes des menaces**, procédez comme suit : 

   1. Dans le volet **Packs de protection (Web ACLs) activés pour l'intégration des applications**, localisez le pack de protection (ACL Web) auquel vous souhaitez procéder à l'intégration. Copiez et enregistrez l'URL d'intégration du pack de protection (ACL Web) à utiliser dans votre implémentation. Vous pouvez également obtenir cette URL via l'appel d'API`GetWebACL`.

   1. Choisissez le type et la version de l'appareil mobile, puis choisissez **Télécharger**. Vous pouvez choisir la version de votre choix, mais nous vous recommandons d'utiliser la dernière version. AWS WAF télécharge le `zip` fichier pour votre appareil sur votre emplacement de téléchargement standard.

1. Dans l'environnement de développement de votre application, décompressez le fichier sur l'emplacement de travail de votre choix. Dans le répertoire de premier niveau du fichier zip, recherchez et ouvrez le`README`. Suivez les instructions du `README` fichier pour installer le SDK AWS WAF mobile à utiliser dans le code de votre application mobile. 

1. Programmez votre application conformément aux instructions des sections suivantes.

# AWS WAF spécification du SDK mobile
<a name="waf-mobile-sdk-specification"></a>

Cette section répertorie les objets du SDK, les opérations et les paramètres de configuration de la dernière version disponible du SDK AWS WAF mobile. Pour des informations détaillées sur le fonctionnement du fournisseur de jetons et des opérations pour les différentes combinaisons de paramètres de configuration, consultez[Fonctionnement du SDK AWS WAF mobile](waf-mobile-sdk-how-it-works.md). 

**`WAFToken`**  
Détient un AWS WAF jeton.    
**`getValue()`**  
Récupère la `String` représentation du. `WAFToken` 

**`WAFTokenProvider`**  
Gère les jetons dans votre application mobile. Implémentez cela à l'aide d'un `WAFConfiguration` objet.    
**`getToken()`**  
Si l'actualisation en arrière-plan est activée, le jeton mis en cache est renvoyé. Si l'actualisation en arrière-plan est désactivée, un appel synchrone bloquant est lancé AWS WAF pour récupérer un nouveau jeton.   
**`loadTokenIntoProvider(WAFToken)`**  
Charge le jeton spécifié dans le`WAFTokenProvider`, en remplaçant tout jeton géré par le fournisseur. Le fournisseur de jetons s'approprie le nouveau jeton et s'occupe de son actualisation à l'avenir. Cette opération met également à jour le jeton dans le magasin de cookies, s'`setTokenCookie`il est activé dans le`WAFConfiguration`.  
**`onTokenReady(WAFTokenResultCallback)`**  
Demande au fournisseur de jetons d'actualiser le jeton et d'invoquer le rappel fourni lorsqu'un jeton actif est prêt. Le fournisseur de jetons invoquera votre rappel dans un fil d'arrière-plan lorsque le jeton sera mis en cache et prêt. Appelez cela lorsque votre application se charge pour la première fois et également lorsqu'elle revient à un état actif. Pour plus d'informations sur le retour à un état actif, consultez[Récupération d'un jeton suite à l'inactivité d'une application](waf-mobile-sdk-how-it-works.md#waf-mobile-sdk-how-back-from-inactive).   
Pour les applications Android ou iOS, vous pouvez `WAFTokenResultCallback` définir l'opération que vous souhaitez que le fournisseur de jetons appelle lorsqu'un jeton demandé est prêt. Votre implémentation de `WAFTokenResultCallback` doit prendre les paramètres`WAFToken`,`SdkError`. Pour les applications iOS, vous pouvez également créer une fonction intégrée.   
**`storeTokenInCookieStorage(WAFToken)`**  
Indique au `WAFTokenProvider` de stocker le AWS WAF jeton spécifié dans le gestionnaire de cookies du SDK. Par défaut, le jeton n'est ajouté au magasin de cookies que lorsqu'il est acquis pour la première fois et lorsqu'il est actualisé. Si l'application efface le magasin de cookies partagé pour une raison quelconque, le SDK n'ajoute pas automatiquement le AWS WAF jeton avant la prochaine actualisation. 

**`WAFConfiguration`**  
Détient la configuration pour la mise en œuvre du`WAFTokenProvider`. Lorsque vous implémentez cela, vous fournissez l'URL d'intégration de votre pack de protection (ACL Web), le nom de domaine à utiliser dans le jeton et tous les paramètres autres que ceux par défaut que vous souhaitez que le fournisseur de jetons utilise.   
La liste suivante indique les paramètres de configuration que vous pouvez gérer dans l'`WAFConfiguration`objet.    
**`applicationIntegrationUrl`**   
URL d'intégration de l'application. Obtenez-le depuis la AWS WAF console ou via l'appel `getWebACL` d'API.  
Obligatoire : oui  
Type : URL spécifique à l'application. Pour iOS, voir [URL iOS](https://developer.apple.com/documentation/foundation/url). Pour Android, consultez l'URL [java.net.](https://docs.oracle.com/javase/7/docs/api/java/net/URL.html)   
**`backgroundRefreshEnabled`**   
Indique si vous souhaitez que le fournisseur de jetons actualise le jeton en arrière-plan. Si vous définissez cette option, le fournisseur de jetons actualise vos jetons en arrière-plan conformément aux paramètres de configuration qui régissent les activités d'actualisation automatique des jetons.   
Obligatoire : non  
Type : `Boolean`  
Valeur par défaut : `TRUE`  
**`domainName`**   
Le domaine à utiliser dans le jeton, qui est utilisé pour l'acquisition de jetons et le stockage des cookies. Par exemple, `example.com` ou `aws.amazon.com`. Il s'agit généralement du domaine hôte de votre ressource associé au pack de protection (ACL Web), dans lequel vous allez envoyer des requêtes Web. Pour le groupe de règles géré par l'ACFP`AWSManagedRulesACFPRuleSet`, il s'agit généralement d'un domaine unique correspondant au domaine indiqué dans le chemin de création de compte que vous avez indiqué dans la configuration du groupe de règles. Pour le groupe de règles géré par ATP`AWSManagedRulesATPRuleSet`, il s'agit généralement d'un domaine unique correspondant au domaine indiqué dans le chemin de connexion que vous avez indiqué dans la configuration du groupe de règles.   
Les suffixes publics ne sont pas autorisés. Par exemple, vous ne pouvez pas utiliser `gov.au` ou `co.uk` comme domaine de jeton.  
Le domaine doit être accepté, en fonction du domaine hôte protégé et de la liste des domaines de jetons du pack de protection (ACL Web). AWS WAF Pour de plus amples informations, veuillez consulter [AWS WAF configuration de la liste de domaines de jetons du pack de protection (ACL Web)](waf-tokens-domains.md#waf-tokens-domain-lists).  
Obligatoire : oui  
Type : `String`   
**`maxErrorTokenRefreshDelayMsec`**   
Durée maximale en millisecondes d'attente avant de répéter l'actualisation d'un jeton après une tentative infructueuse. Pour chaque nouvelle tentative automatique suite à une tentative infructueuse, cela ajoutera un retard exponentiel jusqu'au délai d'entrée indiqué. Cette valeur est utilisée après l'échec de la récupération du jeton et après plusieurs tentatives`maxRetryCount`.   
Obligatoire : non  
Type : `Integer`  
Valeur par défaut : `5000` (5 secondes)  
Valeur minimale autorisée : `1` (1 milliseconde)  
Valeur maximale autorisée : `30000` (30 secondes)  
**`maxRetryCount`**   
Nombre maximal de tentatives à effectuer avec un retard exponentiel lorsqu'un jeton est demandé.   
Obligatoire : non  
Type : `Integer`  
Valeur par défaut : `Infinity`  
Valeur minimale autorisée : `0`  
Valeur maximale autorisée : `100`  
**`setTokenCookie`**   
Indique si vous souhaitez que le gestionnaire de cookies du SDK ajoute un cookie jeton dans les demandes et dans d'autres domaines.   
Avec une `TRUE` valeur :   
+ Le gestionnaire de cookies ajoute un cookie jeton à toutes les demandes dont le chemin est inférieur au chemin spécifié dans`tokenCookiePath`. 
+ L'`WAFTokenProvider`opération `loadTokenIntoProvider()` met à jour le jeton dans le magasin de cookies, en plus de le charger dans le fournisseur de jetons.
Obligatoire : non  
Type : `Boolean`  
Valeur par défaut : `TRUE`  
**`tokenCookiePath`**   
Utilisé quand `setTokenCookie` c'est le cas`TRUE`. Indique le chemin de niveau supérieur où vous souhaitez que le gestionnaire de cookies du SDK ajoute un cookie jeton. Le gestionnaire ajoute un cookie symbolique à toutes les demandes que vous envoyez à ce chemin et à tous les chemins enfants.   
Par exemple, si vous définissez ce paramètre sur`/web/login`, le gestionnaire inclut le cookie jeton pour tout ce qui est envoyé `/web/login` et pour tous ses chemins enfants, par exemple`/web/login/help`. Il n'inclut pas le jeton pour les demandes envoyées vers d'autres chemins`/`, comme`/web`, ou`/web/order`.   
Obligatoire : non  
Type : `String`  
Valeur par défaut : `/`  
**`tokenRefreshDelaySec`**   
Utilisé pour rafraîchir l'arrière-plan. Durée maximale en secondes entre les actualisations du jeton d'arrière-plan.  
Obligatoire : non  
Type : `Integer`  
Valeur par défaut : `88`  
Valeur minimale autorisée : `88`  
Valeur maximale autorisée : `300` (5 minutes)

## AWS WAF erreurs du SDK mobile
<a name="waf-mobile-sdk-errors"></a>

Cette section répertorie les erreurs possibles pour la version actuelle du SDK AWS WAF mobile.

**`SdkError`**  
Type d'erreur renvoyé lorsque vous ne parvenez pas à récupérer un jeton. Les SDK Android et iOS présentent les mêmes types d'erreurs.  
Le SDK AWS WAF mobile présente les types d'erreur suivants :    
**`invalidChallenge`**  
Cette erreur est renvoyée lorsque le serveur de jetons renvoie des données de défi non valides ou lorsque le blob de réponse est muté par un attaquant.  
**`errorInvokingGetChallengeEndpoint`**  
Cette erreur est renvoyée lorsque le serveur de jetons renvoie un code de réponse infructueux au client ou lorsqu'une erreur réseau se produit.  
**`invalidVerifyChallengeResponse`**  
Cette erreur est renvoyée en cas d'erreur lors de la récupération `aws-waf-token` de la réponse de vérification AWS WAF du serveur ou lorsque la réponse du serveur a été falsifiée.  
**`errorInvokingVerifyEndpoint`**  
Cette erreur est renvoyée lorsque le client reçoit une mauvaise réponse du AWS WAF serveur ou une erreur réseau lors de la vérification du défi résolu.  
**`internalError`**  
Cette erreur est renvoyée pour toutes les autres erreurs susceptibles de se produire dans le SDK lui-même.

**`socketTimeoutException`**  
Cette erreur est souvent renvoyée en cas d'erreur réseau lors de la récupération du jeton.  
Cette erreur peut être due à ce qui suit :  
+ Faible bande passante réseau : confirmez vos paramètres de connectivité réseau
+ URL d'intégration de l'application modifiée : vérifiez que l'URL d'intégration n'est pas modifiée par rapport à ce qui apparaît sur la console AWS WAF 

# Fonctionnement du SDK AWS WAF mobile
<a name="waf-mobile-sdk-how-it-works"></a>

Cette section explique comment les classes, les propriétés et les opérations du SDK AWS WAF mobile fonctionnent ensemble.

Le mobile vous SDKs fournit un fournisseur de jetons configurable que vous pouvez utiliser pour récupérer et utiliser des jetons. Le fournisseur de jetons vérifie que les demandes que vous autorisez proviennent de clients légitimes. Lorsque vous envoyez des demandes aux AWS ressources que vous protégez AWS WAF, vous incluez le jeton dans un cookie afin de valider la demande. Vous pouvez gérer le cookie de jeton manuellement ou demander au fournisseur de jetons de le faire pour vous.

Cette section couvre les interactions entre les classes, les propriétés et les méthodes incluses dans le SDK mobile. Pour les spécifications du SDK, voir[AWS WAF spécification du SDK mobile](waf-mobile-sdk-specification.md). 

## Récupération et mise en cache des jetons
<a name="waf-mobile-sdk-how-token-basics"></a>

Lorsque vous créez l'instance du fournisseur de jetons dans votre application mobile, vous configurez la manière dont vous souhaitez qu'elle gère les jetons et leur récupération. Votre principal choix est de savoir comment conserver des jetons valides et non expirés à utiliser dans les requêtes Web de votre application :
+ **Actualisation de l'arrière-plan activée** : il s'agit de la valeur par défaut. Le fournisseur de jetons actualise automatiquement le jeton en arrière-plan et le met en cache. Lorsque l'actualisation en arrière-plan est activée, lorsque vous appelez`getToken()`, l'opération récupère le jeton mis en cache. 

  Le fournisseur de jetons effectue l'actualisation du jeton à des intervalles configurables, de sorte qu'un jeton non expiré soit toujours disponible dans le cache lorsque l'application est active. L'actualisation en arrière-plan est suspendue lorsque votre application est inactive. Pour plus d'informations à ce sujet, consultez[Récupération d'un jeton suite à l'inactivité d'une application](#waf-mobile-sdk-how-back-from-inactive).
+ **Actualisation en arrière-plan désactivée** : vous pouvez désactiver l'actualisation des jetons en arrière-plan, puis récupérer les jetons uniquement sur demande. Les jetons récupérés à la demande ne sont pas mis en cache et vous pouvez en récupérer plusieurs si vous le souhaitez. Chaque jeton est indépendant des autres que vous récupérez, et chacun possède son propre horodatage utilisé pour calculer l'expiration.

  Les options suivantes s'offrent à vous pour récupérer les jetons lorsque l'actualisation en arrière-plan est désactivée : 
  + **`getToken()`**— Lorsque vous appelez alors que l'actualisation `getToken()` en arrière-plan est désactivée, l'appel récupère de manière synchrone un nouveau jeton depuis. AWS WAF Il s'agit d'un appel potentiellement bloquant qui peut affecter la réactivité de l'application si vous l'invoquez sur le thread principal. 
  + **`onTokenReady(WAFTokenResultCallback)`**— Cet appel récupère un nouveau jeton de manière asynchrone, puis invoque le rappel du résultat fourni dans un thread d'arrière-plan lorsqu'un jeton est prêt. 

### Comment le fournisseur de jetons tente à nouveau de récupérer un jeton qui a échoué
<a name="waf-mobile-sdk-how-token-retrieval-retries"></a>

Le fournisseur de jetons réessaie automatiquement de récupérer le jeton en cas d'échec de la récupération. Les nouvelles tentatives sont initialement effectuées à l'aide d'une temporisation exponentielle avec un temps d'attente de départ de 100 ms. Pour plus d'informations sur les tentatives exponentielles, reportez-vous à la section [Rétentatives d'erreur et recul exponentiel](https://docs.aws.amazon.com/general/latest/gr/api-retries.html) dans. AWS

Lorsque le nombre de tentatives atteint le nombre configuré`maxRetryCount`, le fournisseur de jetons arrête d'essayer ou passe à essayer toutes les `maxErrorTokenRefreshDelayMsec` millisecondes, selon le type de récupération du jeton : 
+ **`onTokenReady()`**— Le fournisseur de jetons passe à l'attente de quelques `maxErrorTokenRefreshDelayMsec` millisecondes entre les tentatives et continue d'essayer de récupérer le jeton. 
+ **Actualisation en arrière-plan** : le fournisseur de jetons passe à l'attente de quelques `maxErrorTokenRefreshDelayMsec` millisecondes entre les tentatives et continue d'essayer de récupérer le jeton. 
+ **`getToken()`Appels à la demande, lorsque l'actualisation en arrière-plan est désactivée** : le fournisseur de jetons arrête d'essayer de récupérer un jeton et renvoie la valeur du jeton précédent, ou une valeur nulle s'il n'existe aucun jeton précédent. 

## Scénarios de nouvelle tentative de récupération de jetons
<a name="waf-mobile-sdk-how-token-retrieval-retry-scenarios"></a>

Lorsque le fournisseur de jetons essaie de récupérer un jeton, cela peut entraîner de nouvelles tentatives automatiques en fonction de l'endroit où la récupération du jeton échoue dans le flux d'acquisition de jetons. Cette section répertorie les endroits où une nouvelle tentative automatique est susceptible de s'afficher.
+ **Obtenir ou vérifier le AWS WAF défi via /inputs ou /verify :**
  + Lorsqu'une demande d'obtention et de vérification d'un AWS WAF défi est faite et échoue, cela peut entraîner une nouvelle tentative automatique.
  + Il se peut que vous observiez de nouvelles tentatives automatiques accompagnées d'une `socketTimeoutException` erreur. Cela peut avoir plusieurs causes, notamment :
    + Faible bande passante réseau : confirmez vos paramètres de connectivité réseau
    + URL d'intégration de l'application modifiée : vérifiez que l'URL d'intégration n'est pas modifiée par rapport à ce qui apparaît sur la console AWS WAF 
  + Le nombre de tentatives automatiques est configurable avec la fonction `maxRetryCount()`
+ **Actualisation du jeton :**
  + Lorsqu'une demande d'actualisation du jeton est faite via le gestionnaire de jetons, cela peut entraîner une nouvelle tentative automatique.
  + Le nombre de tentatives automatiques ici est configurable avec la `maxRetryCount()` fonction.

Une configuration sans nouvelles tentatives automatiques est possible en configurant. `maxRetryCount(0)`

## Durée d'immunité des jetons et actualisation de l'arrière-plan
<a name="waf-mobile-sdk-how-token-immunity"></a>

La durée d'immunité des jetons que vous configurez dans l'ACL Web est indépendante de l'intervalle d'actualisation des jetons que vous avez défini dans le SDK AWS WAF mobile. Lorsque vous activez l'actualisation en arrière-plan, le SDK actualise le jeton à l'intervalle que vous spécifiez. `tokenRefreshDelaySec()` Cela peut entraîner l'existence simultanée de plusieurs jetons valides, en fonction de la durée d'immunité que vous avez configurée.

Pour empêcher la validité de plusieurs jetons, vous pouvez désactiver l'actualisation en arrière-plan et utiliser cette `getToken()` fonction pour gérer le cycle de vie des jetons dans votre application mobile.

## Récupération d'un jeton suite à l'inactivité d'une application
<a name="waf-mobile-sdk-how-back-from-inactive"></a>

L'actualisation en arrière-plan n'est effectuée que lorsque votre application est considérée comme active pour votre type d'application : 
+ **iOS** — L'actualisation de l'arrière-plan est effectuée lorsque l'application est au premier plan.
+ **Android** — L'actualisation de l'arrière-plan est effectuée lorsque l'application n'est pas fermée, qu'elle soit au premier plan ou en arrière-plan.

Si votre application reste dans un état qui ne prend pas en charge l'actualisation en arrière-plan pendant plus de `tokenRefreshDelaySec` quelques secondes que vous avez configurées, le fournisseur de jetons interrompt l'actualisation en arrière-plan. Par exemple, pour une application iOS, si la valeur `tokenRefreshDelaySec` est 300 et que l'application se ferme ou passe en arrière-plan pendant plus de 300 secondes, le fournisseur de jetons arrête d'actualiser le jeton. Lorsque l'application revient à un état actif, le fournisseur de jetons redémarre automatiquement l'actualisation en arrière-plan. 

Lorsque votre application revient à un état actif, appelez `onTokenReady()` pour être averti lorsque le fournisseur de jetons a récupéré et mis en cache un nouveau jeton. Ne vous contentez pas d'appeler`getToken()`, car le cache ne contient peut-être pas encore de jeton valide et actuel. 

## URL d'intégration de l'application
<a name="waf-mobile-sdk-application-integration-url"></a>

L'URL d'intégration de l'application du SDK AWS WAF mobile pointe vers une ACL Web que vous avez activée pour l'intégration des applications. Cette URL achemine les demandes vers le serveur principal approprié et les associe à votre client. Il ne s'agit pas d'un contrôle de sécurité strict. L'exposition d'une URL d'intégration ne présente donc aucun risque de sécurité.

Vous pouvez modifier techniquement l'URL d'intégration fournie tout en obtenant un jeton. Toutefois, nous ne le recommandons pas, car vous risquez de perdre de la visibilité sur les taux de résolution des problèmes ou de rencontrer des échecs de récupération de jetons accompagnés d'`socketTimeoutException`erreurs.

## Dépendances
<a name="waf-mobile-sdk-dependencies"></a>

Chaque SDK AWS WAF mobile téléchargeable inclut un fichier README répertoriant les dépendances de sa version spécifique du SDK. Reportez-vous au fichier README pour connaître les dépendances de votre version du SDK mobile.

## Obfuscation/ ProGuard (SDK Android uniquement)
<a name="waf-mobile-sdk-obfuscation"></a>

Si vous utilisez un produit d'obfuscation ou de minification tel que ProGuard, vous devrez peut-être exclure certains espaces de noms pour garantir le bon fonctionnement du SDK mobile. Consultez le fichier README correspondant à votre version du SDK mobile pour trouver la liste des espaces de noms et des règles d'exclusion.

# Exemples de code pour le SDK AWS WAF mobile
<a name="waf-mobile-sdk-coding-examples"></a>

Cette section fournit des exemples de code pour l'utilisation du SDK mobile. 

## Initialisation du fournisseur de jetons et obtention de jetons
<a name="waf-mobile-sdk-coding-basic"></a>

Vous lancez votre instance de fournisseur de jetons à l'aide d'un objet de configuration. Vous pouvez ensuite récupérer des jetons en utilisant les opérations disponibles. Les éléments de base du code requis sont présentés ci-dessous.

------
#### [ 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 ]

Exemple 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();
```

Exemple en 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)
		}
	}
}
```

------

## Autoriser le SDK à fournir le cookie jeton dans vos requêtes HTTP
<a name="waf-mobile-sdk-coding-auto-token-cookie"></a>

Si `setTokenCookie` tel est le cas`TRUE`, le fournisseur de jetons inclut le cookie jeton pour vous dans vos requêtes Web adressées à tous les emplacements situés sous le chemin spécifié dans`tokenCookiePath`. Par défaut, `setTokenCookie` est `TRUE` et `tokenCookiePath` est`/`. 

Vous pouvez réduire la portée des demandes qui incluent un cookie jeton en spécifiant le chemin du cookie jeton, par exemple,`/web/login`. Dans ce cas, vérifiez que vos AWS WAF règles ne détectent pas la présence de jetons dans les demandes que vous envoyez à d'autres chemins. Lorsque vous utilisez le groupe de `AWSManagedRulesACFPRuleSet` règles, vous configurez les chemins d'enregistrement et de création du compte, et le groupe de règles vérifie la présence de jetons dans les demandes envoyées à ces chemins. Pour de plus amples informations, veuillez consulter [Ajouter le groupe de règles géré par l'ACFP à votre ACL Web](waf-acfp-rg-using.md). De même, lorsque vous utilisez le groupe de `AWSManagedRulesATPRuleSet` règles, vous configurez le chemin de connexion, et le groupe de règles vérifie la présence de jetons dans les demandes envoyées vers ce chemin. Pour de plus amples informations, veuillez consulter [Ajouter le groupe de règles géré par ATP à votre pack de protection (ACL Web)](waf-atp-rg-using.md). 

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

Dans `setTokenCookie` ce cas`TRUE`, le fournisseur de jetons stocke le AWS WAF jeton dans un `HTTPCookieStorage.shared` et inclut automatiquement le cookie dans les demandes adressées au domaine que vous avez spécifié`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 ]

Dans `setTokenCookie` ce cas`TRUE`, le fournisseur de jetons stocke le AWS WAF jeton dans une `CookieHandler` instance partagée à l'échelle de l'application. Le fournisseur de jetons inclut automatiquement le cookie dans les demandes adressées au domaine que vous avez spécifié`WAFConfiguration`.

Exemple Java :

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

Exemple en Kotlin :

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

Si l'instance `CookieHandler` par défaut est déjà initialisée, le fournisseur de jetons l'utilisera pour gérer les cookies. Dans le cas contraire, le fournisseur de jetons initialisera une nouvelle `CookieManager` instance avec le AWS WAF jeton, `CookiePolicy.ACCEPT_ORIGINAL_SERVER` puis définira cette nouvelle instance comme instance par défaut dans`CookieHandler`.

Le code suivant montre comment le SDK initialise le gestionnaire de cookies et le gestionnaire de cookies lorsqu'ils ne sont pas disponibles dans votre application. 

Exemple Java :

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

Exemple en Kotlin :

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

------

## Fournir manuellement le cookie jeton dans vos requêtes HTTP
<a name="waf-mobile-sdk-coding-manual-token-cookie"></a>

Si vous définissez cette `setTokenCookie` option`FALSE`, vous devez fournir le cookie jeton manuellement, sous forme d'en-tête de requête HTTP Cookie, dans vos demandes adressées à votre point de terminaison protégé. Le code suivant montre comment procéder.

------
#### [ 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 ]

Exemple 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();
```

Exemple en 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
```

------