**Presentamos una nueva experiencia de consola para AWS WAF**

Ahora puede usar la experiencia actualizada para acceder a las AWS WAF funciones desde cualquier parte de la consola. Para obtener más información, consulte [Trabajar con la consola](https://docs.aws.amazon.com/waf/latest/developerguide/working-with-console.html). 

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

# Integraciones de aplicaciones cliente en AWS WAF
<a name="waf-application-integration"></a>

En esta sección, se explica cómo utilizar la API de integración de amenazas inteligentes APIs y JavaScript CAPTCHA con sus funciones. AWS WAF 

Utilice la integración de aplicaciones AWS WAF cliente APIs para combinar las protecciones del lado del cliente con las protecciones del paquete de protección del AWS lado del servidor (ACL web), a fin de comprobar que las aplicaciones cliente que envían solicitudes web a sus recursos protegidos son los clientes previstos y que sus usuarios finales son seres humanos. 

Utilice las integraciones de cliente para administrar los desafíos silenciosos al navegador y los rompecabezas de CAPTCHA, obtener tokens que demuestren que el navegador y los usuarios finales han respondido satisfactoriamente, e incluir estos tokens en las solicitudes a sus puntos de conexión protegidos. Para obtener información general sobre los tokens, consulte AWS WAF . [Uso de tokens en la mitigación AWS WAF inteligente de amenazas](waf-tokens.md) 

Combine las integraciones de sus clientes con protecciones del paquete de protección (ACL web) que requieren tokens válidos para acceder a sus recursos. Puede usar grupos de reglas que comprueben y supervisen los tokens de desafíos, como los que se muestran en la siguiente sección, en [Integración inteligente de amenazas y reglas AWS gestionadas](waf-application-integration-with-AMRs.md), y puede usar las acciones de regla CAPTCHA y Challenge para verificarlos, tal y como se describe en [CAPTCHAy Challenge en AWS WAF](waf-captcha-and-challenge.md). 

AWS WAF proporciona dos niveles de integración para JavaScript las aplicaciones y uno para las aplicaciones móviles: 
+ **Integración inteligente de amenazas**: verifique la aplicación cliente y proporcione la adquisición y administración de los AWS tokens. Es similar a la funcionalidad que proporciona la acción de la AWS WAF Challenge regla. Esta funcionalidad integra completamente la aplicación cliente con el grupo de reglas administradas `AWSManagedRulesACFPRuleSet`, el grupo de reglas administradas `AWSManagedRulesATPRuleSet` y el nivel de protección objetivo del grupo de reglas administradas `AWSManagedRulesBotControlRuleSet`. 

  La integración de amenazas inteligentes APIs utiliza el desafío del navegador AWS WAF silencioso para garantizar que los intentos de inicio de sesión y otras llamadas al recurso protegido solo se permitan después de que el cliente haya adquirido un token válido. APIs Gestiona la autorización mediante token para las sesiones de las aplicaciones de tu cliente y recopila información sobre el cliente para ayudar a determinar si está siendo operado por un bot o por un ser humano. 
**nota**  
Está disponible para JavaScript y para aplicaciones móviles de Android e iOS. 
+ **Integración de CAPTCHA**: verifique a los usuarios finales con un rompecabezas de CAPTCHA personalizado que gestiona en su aplicación. Es similar a la funcionalidad que proporciona la acción de la AWS WAF CAPTCHA regla, pero con un control adicional sobre la ubicación y el comportamiento del rompecabezas. 

  Esta integración aprovecha la integración JavaScript inteligente de amenazas para ejecutar desafíos silenciosos y proporcionar AWS WAF fichas a la página del cliente. 
**nota**  
Está disponible para JavaScript las aplicaciones. 

**Topics**
+ [Integración inteligente de amenazas y reglas AWS gestionadas](waf-application-integration-with-AMRs.md)
+ [Acceso a la integración de aplicaciones AWS WAF cliente APIs](waf-application-integration-location-in-console.md)
+ [AWS WAF JavaScript integraciones](waf-javascript-api.md)
+ [AWS WAF integración de aplicaciones móviles](waf-mobile-sdk.md)

# Integración inteligente de amenazas y reglas AWS gestionadas
<a name="waf-application-integration-with-AMRs"></a>

En esta sección se explica cómo APIs funciona la integración inteligente de amenazas con los grupos de reglas de reglas AWS administradas.

La integración de amenazas inteligentes APIs funciona con paquetes de protección (web ACLs) que utilizan los grupos de reglas de amenazas inteligentes para habilitar todas las funciones de estos grupos de reglas gestionados avanzados. 
+ AWS WAF Grupo `AWSManagedRulesACFPRuleSet` de reglas gestionado por la prevención del fraude (ACFP) para la creación de cuentas de Fraud Control. 

  El fraude en la creación de cuentas es una actividad ilegal en Internet en la que un atacante crea cuentas no válidas en su solicitud para, por ejemplo, recibir bonificaciones de registro o hacerse pasar por otra persona. El grupo de reglas administradas de ACFP proporciona reglas para bloquear, etiquetar y administrar las solicitudes que podrían formar parte de intentos malintencionados de creación de cuentas. APIs Permiten ajustar con precisión la verificación del navegador del cliente y la información sobre la interactividad humana que las reglas de la ACFP utilizan para separar el tráfico de clientes válido del tráfico malicioso.

  Para obtener más información, consulte [AWS WAF Grupo de reglas de prevención del fraude (ACFP) para la creación de cuentas de Control de Fraude](aws-managed-rule-groups-acfp.md) y [AWS WAF Control de fraude: creación de cuentas y prevención del fraude (ACFP)](waf-acfp.md).
+ AWS WAF Grupo de reglas gestionado para la prevención de apropiación de cuentas (ATP) para el control del fraude. `AWSManagedRulesATPRuleSet` 

  La apropiación de cuentas es una actividad ilegal en línea en la que un atacante obtiene acceso no autorizado a la cuenta de una persona. El grupo de reglas administradas de la ATP proporciona reglas para bloquear, etiquetar y administrar las solicitudes que puedan formar parte de intentos malintencionados de apropiación de cuentas. APIs Permiten la verificación precisa de los clientes y la agregación del comportamiento que utilizan las reglas de la ATP para separar el tráfico de clientes válido del tráfico malicioso.

  Para obtener más información, consulte [AWS WAF Grupo de reglas de prevención de apropiación de cuentas (ATP) para el control del fraude](aws-managed-rule-groups-atp.md) y [AWS WAF Control de fraudes y prevención de apropiación de cuentas (ATP)](waf-atp.md).
+ Nivel de protección específico del grupo de reglas gestionado por AWS WAF Bot Control. `AWSManagedRulesBotControlRuleSet` 

  Los bots van desde los que se identifican a sí mismos y son útiles, como la mayoría de los motores de búsqueda y rastreadores, hasta los bots maliciosos que actúan contra su sitio web y no se identifican a sí mismos. El grupo de reglas administradas de control de bots proporciona reglas para supervisar, etiquetar y administrar la actividad de los bots en el tráfico web. Cuando se utiliza el nivel de protección específico de este grupo de reglas, las reglas objetivo utilizan la información de sesión del cliente que APIs proporcionan para detectar mejor los bots malintencionados. 

  Para obtener más información, consulte [AWS WAF Grupo de reglas de control de bots](aws-managed-rule-groups-bot.md) y [AWS WAF Control de bots](waf-bot-control.md).

Para agregar uno de estos grupos de reglas administradas a su paquete de protección (ACL web), consulte los procedimientos [Adición del grupo de reglas administradas por ACFP a la nueva ACL web](waf-acfp-rg-using.md), [Adición del grupo de reglas administradas por ATP al paquete de protección (ACL web)](waf-atp-rg-using.md) y [Añadir el grupo de reglas gestionado por AWS WAF Bot Control a su ACL web](waf-bot-control-rg-using.md).

**nota**  
Los grupos de reglas administradas actualmente no bloquean las solicitudes a las que les faltan tokens. Para bloquear las solicitudes a las que les falten tokens, después de implementar la integración de la aplicación APIs, sigue las instrucciones que se indican en[Bloquear solicitudes que no tienen un AWS WAF token válido](waf-tokens-block-missing-tokens.md). 

# Acceso a la integración de aplicaciones AWS WAF cliente APIs
<a name="waf-application-integration-location-in-console"></a>

En esta sección se explica dónde encontrar la integración de aplicaciones APIs en la AWS WAF consola.

La JavaScript integración APIs está disponible de forma general y puede utilizarla en sus navegadores y otros dispositivos que se ejecuten JavaScript. 

AWS WAF ofrece una integración personalizada de amenazas inteligentes SDKs para aplicaciones móviles Android e iOS. 
+ En el caso de las aplicaciones móviles y de TV de Android, SDKs funcionan para la versión 23 de la API de Android (versión 6 de Android) y versiones posteriores. Para obtener información sobre las versiones de Android, consulte las [Notas de versión de la plataforma SDK](https://developer.android.com/tools/releases/platforms).
+ Para las aplicaciones móviles de iOS, SDKs funcionan para la versión 13 de iOS y versiones posteriores. Para obtener información sobre las versiones de iOS, consulte las [notas de la versión de iOS y iPadOS](https://developer.apple.com/documentation/ios-ipados-release-notes).
+ Para las aplicaciones de Apple TV, SDKs funcionan para tvOS versión 14 o posterior. Para obtener información sobre las versiones de tvOS, consulte [Notas de lanzamiento de tvOS](https://developer.apple.com/documentation/tvos-release-notes).

**Para acceder a la integración APIs a través de la consola**

1. Inicie sesión en la AWS WAF consola Consola de administración de AWS y ábrala en [https://console.aws.amazon.com/wafv2/homev2](https://console.aws.amazon.com/wafv2/homev2). 

1. Elija **Integración de aplicaciones** en el panel de navegación y, a continuación, elija la pestaña que le interese.
   + La **integración inteligente de amenazas** está disponible para JavaScript aplicaciones móviles. 

     La pestaña contiene lo siguiente:
     + Una lista de los paquetes de protección (web ACLs) que están habilitados para la integración de aplicaciones contra amenazas inteligentes. La lista incluye cada paquete de protección (ACL web) que utiliza el grupo de reglas administradas de `AWSManagedRulesACFPRuleSet`, el grupo de reglas administradas de `AWSManagedRulesATPRuleSet` o el nivel de protección específica del grupo de reglas administradas de `AWSManagedRulesBotControlRuleSet`. Cuando implementa la amenaza inteligente APIs, utiliza la URL de integración del paquete de protección (ACL web) con el que desea realizar la integración.
     + Aquel al APIs que tiene acceso. JavaScript APIs Están siempre disponibles. Para acceder al móvil SDKs, ponte en contacto con el servicio de asistencia en [Contact AWS](https://aws.amazon.com/contact-us).
   + La **integración con CAPTCHA** está disponible para JavaScript las aplicaciones. 

     La pestaña contiene lo siguiente: 
     + La URL de integración que se utilizará en la integración. 
     + Las claves de API que ha creado para los dominios de las aplicaciones de sus clientes. El uso de la API de CAPTCHA requiere una clave de API cifrada que dé a los clientes el derecho a acceder a la API de AWS WAF CAPTCHA desde sus dominios. Para cada cliente con el que se integre, use una clave de API que contenga el dominio del cliente. Para obtener más información sobre estos requisitos y sobre la administración de estas claves, consulte [Administración de las claves de API para la API de JS CAPTCHA](waf-js-captcha-api-key.md).

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

En esta sección se explica cómo utilizar las AWS WAF JavaScript integraciones.

Puede usar la JavaScript integración APIs para implementar integraciones de AWS WAF aplicaciones en sus navegadores y otros dispositivos que se ejecuten. JavaScript 

Los rompecabezas de CAPTCHA y los desafíos silenciosos solo se pueden ejecutar cuando los navegadores acceden a los puntos de conexión HTTPS. Los clientes del navegador deben ejecutarse en contextos seguros para poder adquirir los tókenes. 
+ La amenaza inteligente le APIs permite gestionar la autorización de los tokens mediante un desafío silencioso desde el lado del navegador desde el lado del cliente e incluir los tokens en las solicitudes que envía a sus recursos protegidos. 
+ La API de integración de CAPTCHA se suma a la amenaza APIs inteligente y le permite personalizar la ubicación y las características del rompecabezas del CAPTCHA en las aplicaciones de sus clientes. Esta API aprovecha la amenaza inteligente APIs para adquirir AWS WAF fichas para utilizarlas en la página una vez que el usuario final haya completado correctamente el rompecabezas del CAPTCHA. 

Al utilizar estas integraciones, se asegura de que las llamadas a procedimientos remotos de su cliente contengan un token válido. Cuando estas integraciones APIs estén implementadas en las páginas de su aplicación, podrá implementar reglas atenuantes en su paquete de protección (ACL web), como bloquear las solicitudes que no contengan un token válido. También puede implementar reglas que impongan el uso de los tokens que obtienen las aplicaciones cliente utilizando las acciones Challenge o CAPTCHA en sus reglas. 

**Ejemplo de implementación de una amenaza inteligente APIs**  
La siguiente lista muestra los componentes básicos de una implementación típica de la amenaza inteligente APIs en una página de aplicaciones 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>
```

**Ejemplo de implementación de la API CAPTCHA JavaScript**  
La API de integración de CAPTCHA le permite personalizar la experiencia de los usuarios finales con los rompecabezas de CAPTCHA. La integración con CAPTCHA aprovecha la integración JavaScript inteligente de amenazas para la verificación del navegador y la gestión de los tokens, y añade una función para configurar y renderizar el rompecabezas del CAPTCHA. 

La siguiente lista muestra los componentes básicos de una implementación típica de la API CAPTCHA JavaScript en una página de aplicación 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**
+ [Suministro de dominios para su uso en los tokens](waf-js-challenge-api-set-token-domain.md)
+ [Uso de la JavaScript API con políticas de seguridad de contenido](waf-javascript-api-csp.md)
+ [Uso de la JavaScript API de amenazas inteligentes](waf-js-challenge-api.md)
+ [Uso de la API CAPTCHA JavaScript](waf-js-captcha-api.md)

# Suministro de dominios para su uso en los tokens
<a name="waf-js-challenge-api-set-token-domain"></a>

En esta sección se explica cómo proporcionar dominios adicionales para los tókenes.

De forma predeterminada, cuando AWS WAF crea un token, utiliza el dominio host del recurso asociado al paquete de protección (ACL web). Puede proporcionar dominios adicionales para los tokens que AWS WAF crea para el JavaScript APIs. Para ello, configure la `window.awsWafCookieDomainList` variable global con uno o más dominios de token. 

Al AWS WAF crear un token, utiliza el dominio más adecuado y más corto de entre la combinación de los dominios del recurso `window.awsWafCookieDomainList` y el dominio host del recurso asociado al paquete de protección (ACL web). 

Ejemplo de configuración: 

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

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

No puede usar sufijos públicos en esta lista. Por ejemplo, no puede usar `gov.au` o `co.uk` como dominios de token en la lista.

Los dominios que especifique en esta lista deben ser compatibles con los demás dominios y configuraciones de dominio: 
+ Los dominios deben ser los que AWS WAF acepten, según el dominio host protegido y la lista de dominios token configurada para el paquete de protección (ACL web). Para obtener más información, consulte [AWS WAF configuración de la lista de dominios simbólicos del paquete de protección (ACL web)](waf-tokens-domains.md#waf-tokens-domain-lists). 
+ Si utilizas la API de JavaScript CAPTCHA, al menos un dominio de tu clave de API de CAPTCHA debe coincidir exactamente con uno de los dominios de token `window.awsWafCookieDomainList` o debe ser el dominio principal de uno de esos dominios de token. 

  Por ejemplo, para el dominio de token `mySubdomain.myApex.com`, la clave de API `mySubdomain.myApex.com` coincide exactamente y la clave de API `myApex.com` es el dominio de ápex. Cualquiera de las claves coincide con el dominio de token. 

  Para obtener más información sobre las claves de API, consulte [Administración de las claves de API para la API de JS CAPTCHA](waf-js-captcha-api-key.md). 

Si usa el grupo de reglas administradas de `AWSManagedRulesACFPRuleSet`, puede configurar un dominio que coincida con el de la ruta de creación de cuentas que proporcionó a la configuración del grupo de reglas. Para obtener más información acerca de esta configuración, consulte [Adición del grupo de reglas administradas por ACFP a la nueva ACL web](waf-acfp-rg-using.md).

Si usa el grupo de reglas administradas de `AWSManagedRulesATPRuleSet`, debería un dominio que coincida con el de la ruta de regustri que proporcionó en la configuración del grupo de reglas. Para obtener más información acerca de esta configuración, consulte [Adición del grupo de reglas administradas por ATP al paquete de protección (ACL web)](waf-atp-rg-using.md).

# Uso de la JavaScript API con políticas de seguridad de contenido
<a name="waf-javascript-api-csp"></a>

En esta sección se proporciona un ejemplo de configuración para incluir en la lista de permisos el dominio de AWS WAF Apex.

Si aplica políticas de seguridad de contenido (CSP) a sus recursos, para que la JavaScript implementación funcione, debe incluir en la lista de permisos el dominio apex. AWS WAF `awswaf.com` JavaScript SDKs Hacen llamadas a distintos AWS WAF puntos de conexión, por lo que permitir incluir este dominio en la lista proporciona los permisos necesarios para funcionar. SDKs 

A continuación se muestra un ejemplo de configuración para incluir en la lista de permisos el AWS WAF dominio de Apex: 

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

Si intentas usarlo JavaScript SDKs con recursos que usan CSP y no has incluido el AWS WAF dominio en la lista de permitidos, recibirás errores como los siguientes: 

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

# Uso de la JavaScript API de amenazas inteligentes
<a name="waf-js-challenge-api"></a>

En esta sección se proporcionan instrucciones para usar la JavaScript API de amenazas inteligentes en su aplicación cliente.

La amenaza inteligente APIs proporciona operaciones para ejecutar desafíos silenciosos contra el navegador del usuario y gestionar los AWS WAF símbolos que demuestran que el desafío ha respondido satisfactoriamente y mediante CAPTCHA. 

Implemente la JavaScript integración primero en un entorno de prueba y, después, en producción. Para obtener más información sobre la guía de codificación, consulta las secciones siguientes. 

 

**Para utilizar la amenaza inteligente APIs**

1. **Instale el APIs** 

   Si utiliza la API de CAPTCHA, puede omitir este paso. Al instalar la API CAPTCHA, el script instala automáticamente la amenaza inteligente. APIs

   1. [Inicie sesión Consola de administración de AWS y abra la AWS WAF consola en homev2. https://console.aws.amazon.com/wafv2/](https://console.aws.amazon.com/wafv2/homev2) 

   1. En el panel de navegación, elija **Integración de la aplicación**. En la página **Integración de aplicaciones**, puede ver las opciones agrupadas en pestañas. 

   1. Seleccione **Integración de amenazas inteligentes**

   1. En la pestaña, seleccione el paquete de protección (ACL web) con el que desea realizar la integración. La lista de paquetes de protección (ACL web) incluye solo los paquetes de protección (web ACLs) que utilizan el grupo de reglas `AWSManagedRulesACFPRuleSet` `AWSManagedRulesATPRuleSet` administrado, el grupo de reglas administrado o el nivel de protección objetivo del grupo de reglas `AWSManagedRulesBotControlRuleSet` administrado. 

   1. Abra el panel **JavaScript SDK** y copie la etiqueta del script para usarla en la integración. 

   1. En el código de la página de la aplicación, en la sección `<head>`, inserte la etiqueta de script que copió para el paquete de protección (ACL web). Esta inclusión hace que la aplicación cliente recupere automáticamente un token en segundo plano al cargar la página. 

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

      Esta lista de `<script>` está configurada con el atributo `defer`, pero puede cambiarlo por otro `async` si desea un comportamiento diferente para su página. 

1. **(Opcional) Agrega una configuración de dominio para los tokens del cliente**: de forma predeterminada, cuando AWS WAF crea un token, utiliza el dominio host del recurso asociado al paquete de protección (ACL web). Para proporcionar dominios adicionales para el JavaScript APIs, sigue las instrucciones que aparecen en[Suministro de dominios para su uso en los tokens](waf-js-challenge-api-set-token-domain.md). 

1. **Codifique su integración de amenazas inteligentes**: escriba el código para asegurarse de que la recuperación del token se complete antes de que el cliente envíe sus solicitudes a los puntos de conexión protegidos. Si ya utiliza la API `fetch` para realizar la llamada, puede sustituirla por el contenedor `fetch` de integración de AWS WAF . Si no usas la `fetch` API, puedes usar la `getToken` operación de AWS WAF integración en su lugar. Para obtener orientación sobre el código, consulte las siguientes secciones: 

1. **Agregue la verificación mediante token a su paquete de protección (ACL web)**: agregue al menos una regla a su paquete de protección (ACL web) que compruebe si hay un token de desafío válido en las solicitudes web que envíe su cliente. Puede utilizar grupos de reglas que comprueben y supervisen los tokens de desafío, como el nivel objetivo del grupo de reglas administradas de control de bots, y puede utilizar la acción de regla Challenge para comprobarlos, tal y como se describe en [CAPTCHAy Challenge en AWS WAF](waf-captcha-and-challenge.md). 

   Las incorporaciones de paquetes de protección (ACL web) comprueban que las solicitudes a sus puntos de conexión protegidos incluyan el token que adquirió en la integración del cliente. Las solicitudes que incluyan un token válido y vigente pasan la inspección de Challenge y no envían otro desafío silencioso a su cliente. 

1. **(Opcional) Bloquee las solicitudes a las que les falten tokens**: si las usa APIs con el grupo de reglas administrado por la ACFP, el grupo de reglas administrado por la ATP o las reglas específicas del grupo de reglas del control de bots, estas reglas no bloquean las solicitudes a las que les faltan tokens. Para bloquear las solicitudes a las que les faltan tokens, siga las instrucciones que se indican en [Bloquear solicitudes que no tienen un AWS WAF token válido](waf-tokens-block-missing-tokens.md). 

**Topics**
+ [Especificación de la API de amenazas inteligentes](waf-js-challenge-api-specification.md)
+ [Cómo utilizar el contenedor `fetch` de integración](waf-js-challenge-api-fetch-wrapper.md)
+ [Cómo utilizar la integración de `getToken`](waf-js-challenge-api-get-token.md)

# Especificación de la API de amenazas inteligentes
<a name="waf-js-challenge-api-specification"></a>

En esta sección se enumeran las especificaciones de los métodos y propiedades de la mitigación inteligente de amenazas JavaScript APIs. Úselos APIs para integraciones inteligentes de amenazas y CAPTCHA.

**`AwsWafIntegration.fetch()`**  
Envía la `fetch` solicitud HTTP al servidor mediante la implementación de integración. AWS WAF 

**`AwsWafIntegration.getToken()`**  
Recupera el AWS WAF token almacenado y lo almacena en una cookie en la página actual con su nombre `aws-waf-token` y el valor establecido en el valor del token. 

**`AwsWafIntegration.hasToken()`**  
Devuelve un booleano que indica si la cookie `aws-waf-token` contiene actualmente un token vigente. 

Si también utiliza la integración de CAPTCHA, consulte las especificaciones correspondientes en [Especificación de la API CAPTCHA JavaScript](waf-js-captcha-api-specification.md).

# Cómo utilizar el contenedor `fetch` de integración
<a name="waf-js-challenge-api-fetch-wrapper"></a>

En esta sección se incluyen las instrucciones para utilizar el contenedor `fetch` de integración.

Puedes usar el AWS WAF `fetch` contenedor cambiando tus `fetch` llamadas normales a la `fetch` API en el espacio de `AwsWafIntegration` nombres. El AWS WAF contenedor admite todas las mismas opciones que la llamada a la JavaScript `fetch` API estándar y añade la gestión de los tokens para la integración. Por lo general, este enfoque es la forma más sencilla de integrar su aplicación. 

**Antes de la implementación del contenedor**  
La siguiente lista de ejemplos muestra el código estándar antes de implementar el contenedor `AwsWafIntegration` `fetch`.

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

**Después de la implementación del contenedor**  
La siguiente lista muestra el mismo código con la implementación del contenedor `AwsWafIntegration` `fetch`.

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

# Cómo utilizar la integración de `getToken`
<a name="waf-js-challenge-api-get-token"></a>

En esta sección, se explica cómo usar la operación `getToken`.

AWS WAF requiere que sus solicitudes a los puntos finales protegidos incluyan la cookie nombrada `aws-waf-token` con el valor de su token actual. 

La operación de `getToken` es una llamada a la API asíncrona que recupera el token de AWS WAF y lo almacena en una cookie en la página actual con el nombre `aws-waf-token`, y el valor establecido al valor del token. Puede usar esta cookie de token en su página según sea necesario. 

Cuando se llama a `getToken`, hace lo siguiente: 
+ Si un token vigente ya está disponible, la llamada lo devuelve inmediatamente.
+ De lo contrario, la llamada recupera un nuevo token del proveedor de tokens y espera hasta 2 segundos a que se complete el flujo de trabajo de adquisición del token antes de que se agote el tiempo de espera. Si se agota el tiempo de espera de la operación, se generará un error que deberá gestionar su código de llamada. 

La operación `getToken` viene acompañada de una operación `hasToken` que indica si la cookie `aws-waf-token` contiene actualmente un token que no ha caducado. 

`AwsWafIntegration.getToken()` recupera un token válido y lo almacena como una cookie. La mayoría de las llamadas de los clientes adjuntan automáticamente esta cookie, pero algunas no. Por ejemplo, las llamadas realizadas entre dominios host no adjuntan la cookie. En los detalles de implementación que aparecen a continuación, mostramos cómo trabajar con ambos tipos de llamadas de clientes. 

**Implementación `getToken` básica para llamadas que adjuntan la cookie `aws-waf-token`**  
La siguiente lista de ejemplos muestra el código estándar para implementar la operación `getToken` con una solicitud de inicio de sesión.

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

**Envío del formulario solo después de que el token esté disponible en `getToken`**  
La siguiente lista muestra cómo registrar un oyente de eventos para interceptar los envíos de formularios hasta que haya un token válido disponible para su uso. 

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

**Cómo adjuntar el token cuando el cliente no adjunta la cookie `aws-waf-token` de forma predeterminada**  
`AwsWafIntegration.getToken()` recupera un token válido y lo almacena como una cookie, pero no todas las llamadas de los clientes adjuntan esta cookie de forma predeterminada. Por ejemplo, las llamadas realizadas entre dominios host no adjuntan la cookie. 

El `fetch` contenedor maneja estos casos automáticamente, pero si no puedes usar el `fetch` contenedor, puedes hacerlo usando un encabezado personalizado. `x-aws-waf-token` AWS WAF lee los símbolos de este encabezado, además de leerlos de la `aws-waf-token` cookie. En el siguiente código, se muestra un ejemplo de cómo configurar el encabezado. 

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

De forma predeterminada, AWS WAF solo acepta los tokens que contienen el mismo dominio que el dominio anfitrión solicitado. Cualquier token que abarque varios dominios requiere las entradas correspondientes en la lista de dominios del token de paquete de protección (ACL web). Para obtener más información, consulte [AWS WAF configuración de la lista de dominios simbólicos del paquete de protección (ACL web)](waf-tokens-domains.md#waf-tokens-domain-lists). 

Para obtener información adicional sobre el uso de los tokens entre dominios, consulte [aws-waf-bot-controlaws-samples/](https://github.com/aws-samples/aws-waf-bot-control-api-protection-with-captcha) -. api-protection-with-captcha

# Uso de la API CAPTCHA JavaScript
<a name="waf-js-captcha-api"></a>

En esta sección se incluyen instrucciones para utilizar la API de integración de CAPTCHA.

La JavaScript API de CAPTCHA le permite configurar el rompecabezas de CAPTCHA y colocarlo donde desee en su aplicación cliente. Esta API aprovecha las características de la amenaza inteligente JavaScript APIs para adquirir y utilizar los AWS WAF tokens una vez que el usuario final haya completado satisfactoriamente un rompecabezas de CAPTCHA. 

Implemente la JavaScript integración primero en un entorno de prueba y, después, en producción. Para obtener más información sobre la guía de codificación, consulta las secciones siguientes. 

**Uso de la API de integración de CAPTCHA**

1. **Instalación de la API**

   1. Inicie sesión Consola de administración de AWS y abra la AWS WAF consola en [https://console.aws.amazon.com/wafv2/homev2](https://console.aws.amazon.com/wafv2/homev2). 

   1. En el panel de navegación, elija **Integración de la aplicación**. En la página **Integración de aplicaciones**, puede ver las opciones agrupadas en pestañas. 

   1. Seleccione la **Integración de CAPTCHA**.

   1. Copia la etiqueta del script de JavaScript integración que aparece en la lista para utilizarla en tu integración.

   1. En el código de la página de la aplicación, en la sección `<head>`, inserte la etiqueta de script que copió. Esta inclusión hace que el rompecabezas de CAPTCHA esté disponible para su configuración y uso. 

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

      Esta lista de `<script>` está configurada con el atributo `defer`, pero puede cambiarlo por otro `async` si desea un comportamiento diferente para su página. 

      El script de CAPTCHA también carga automáticamente el script de integración de amenazas inteligentes si aún no está presente. El script de integración de amenazas inteligentes hace que la aplicación cliente recupere automáticamente un token en segundo plano al cargar la página y proporciona otras funciones de administración de tokens que necesita para usar la API de CAPTCHA. 

1. **(Opcional) Agregue una configuración de dominio para los tokens del cliente**: de forma predeterminada, cuando AWS WAF crea un token, utiliza el dominio host del recurso asociado al paquete de protección (ACL web). Para proporcionar dominios adicionales para el JavaScript APIs, sigue las instrucciones que aparecen en[Suministro de dominios para su uso en los tokens](waf-js-challenge-api-set-token-domain.md). 

1. **Obtenga la clave de API cifrada del cliente**: la API de CAPTCHA requiere una clave de API cifrada que contenga una lista de dominios de cliente válidos. AWS WAF usa esta clave para comprobar que el dominio de cliente que utilizas con la integración está aprobado para usar AWS WAF CAPTCHA. Para generar su clave de API, siga las instrucciones que se indican en [Administración de las claves de API para la API de JS CAPTCHA](waf-js-captcha-api-key.md).

1. **Codifique la implementación del widget de CAPTCHA**: implemente la llamada a la API `renderCaptcha()` en su página, en la ubicación en la que quiera usarla. Para obtener información acerca de cómo configurar y usar esta función, consulte las siguientes secciones, [Especificación de la API CAPTCHA JavaScript](waf-js-captcha-api-specification.md) y [Cómo renderizar el rompecabezas de CAPTCHA](waf-js-captcha-api-render.md). 

   La implementación del CAPTCHA se integra con la integración inteligente de amenazas APIs para gestionar los tokens y ejecutar llamadas de búsqueda que utilizan los tokens. AWS WAF Para obtener orientación sobre su uso, consulte. APIs [Uso de la JavaScript API de amenazas inteligentes](waf-js-challenge-api.md)

1. **Agregue la verificación mediante token a su paquete de protección (ACL web)**: agregue al menos una regla a su paquete de protección (ACL web) que compruebe si hay un token de CAPTCHA válido en las solicitudes web que envíe su cliente. Puede utilizar la acción de regla CAPTCHA para realizar la comprobación, tal y como se describe en [CAPTCHAy Challenge en AWS WAF](waf-captcha-and-challenge.md). 

   Las incorporaciones de los paquetes de protección (ACL web) comprueban que las solicitudes que van a sus puntos de conexión protegidos incluyen el token que adquirió en la integración con el cliente. Las solicitudes que incluyen un token de CAPTCHA válido y vigente pasan la inspección de acción de regla CAPTCHA y no presentan al usuario final otro rompecabezas de CAPTCHA. 

Una vez que hayas implementado la JavaScript API, puedes revisar las CloudWatch métricas de los intentos y las soluciones de los acertijos del CAPTCHA. Para obtener información acerca de las métricas y las dimensiones, consulte [Métricas y dimensiones de la cuenta](waf-metrics.md#waf-metrics-account).

**Topics**
+ [Especificación de la API CAPTCHA JavaScript](waf-js-captcha-api-specification.md)
+ [Cómo renderizar el rompecabezas de CAPTCHA](waf-js-captcha-api-render.md)
+ [Gestión de una respuesta CAPTCHA de AWS WAF](waf-js-captcha-api-conditional.md)
+ [Administración de las claves de API para la API de JS CAPTCHA](waf-js-captcha-api-key.md)

# Especificación de la API CAPTCHA JavaScript
<a name="waf-js-captcha-api-specification"></a>

En esta sección se enumeran las especificaciones de los métodos y propiedades del CAPTCHA. JavaScript APIs Utilice el CAPTCHA JavaScript APIs para ejecutar rompecabezas CAPTCHA personalizados en sus aplicaciones cliente. 

Esta API se basa en la amenaza inteligente APIs, que se utiliza para configurar y gestionar la adquisición y el uso de los AWS WAF tokens. Consulte [Especificación de la API de amenazas inteligentes](waf-js-challenge-api-specification.md).

**`AwsWafCaptcha.renderCaptcha(container, configuration)`**  
Presenta un rompecabezas de AWS WAF CAPTCHA al usuario final y, en caso de éxito, actualiza el token del cliente con la validación del CAPTCHA. Esto solo está disponible con la integración de CAPTCHA. Utilice esta llamada junto con la amenaza inteligente APIs para gestionar la recuperación del token e incluir el token en sus llamadas. `fetch` Vea la amenaza inteligente APIs en[Especificación de la API de amenazas inteligentes](waf-js-challenge-api-specification.md).  
A diferencia del CAPTCHA intersticial que se AWS WAF envía, el puzle CAPTCHA renderizado con este método muestra el puzle inmediatamente, sin pantalla de título inicial.     
**`container`**  
El objeto `Element` para el elemento contenedor objetivo de la página. Por lo general, se recupera llamando a `document.getElementById()` o `document.querySelector()`.  
Obligatorio: sí  
Tipo: `Element`  
**configuración**  
Un objeto que contiene los ajustes de configuración de CAPTCHA, de la siguiente manera****:    
**`apiKey`**   
La clave de API cifrada que habilita los permisos para el dominio del cliente. Utilice la consola AWS WAF para generar las claves de API para los dominios de los clientes. Puede utilizar una clave para hasta cinco dominios. Para obtener información, consulte [Administración de las claves de API para la API de JS CAPTCHA](waf-js-captcha-api-key.md).   
Obligatorio: sí  
Tipo: `string`  
**`onSuccess: (wafToken: string) => void;`**   
Se llama con un AWS WAF token válido cuando el usuario final completa correctamente un rompecabezas de CAPTCHA. Utilice el token en las solicitudes que envíe a los puntos finales que proteja con un paquete de AWS WAF protección (ACL web). El token proporciona la prueba y la marca de tiempo de la última vez que se ha completado con éxito el rompecabezas.   
Obligatorio: sí  
**`onError?: (error: CaptchaError) => void;`**   
Se llama con un objeto de error cuando se produce un error durante la operación de CAPTCHA.   
Obligatorio: no  
**Definición de clase `CaptchaError`**: el controlador `onError` proporciona un tipo de error con la siguiente definición de clase.   

```
CaptchaError extends Error {
    kind: "internal_error" | "network_error" | "token_error" | "client_error";
    statusCode?: number;
}
```
+ `kind`: el tipo de error devuelto. 
+ `statusCode`: el código de estado HTTP, si está disponible. Lo utiliza `network_error` si el error se debe a un error HTTP.  
**`onLoad?: () => void;`**   
Se llama cuando se carga un nuevo rompecabezas de CAPTCHA.  
Obligatorio: no  
**`onPuzzleTimeout?: () => void;`**   
Se llama cuando un rompecabezas de CAPTCHA no se completa antes de que caduque.  
Obligatorio: no  
**`onPuzzleCorrect?: () => void;`**   
Se llama cuando se proporciona una respuesta correcta a un rompecabezas de CAPTCHA.  
Obligatorio: no  
**`onPuzzleIncorrect?: () => void;`**   
Se llama cuando se proporciona una respuesta incorrecta a un rompecabezas de CAPTCHA.  
Obligatorio: no  
**`defaultLocale`**   
La configuración regional predeterminada que se utilizará en el rompecabezas de CAPTCHA. Las instrucciones escritas para los rompecabezas de CAPTCHA están disponibles en árabe (ar-SA), chino simplificado (zh-CN), holandés (nl-NL), inglés (en-US), francés (fr-FR), alemán (de-DE), italiano (it-IT), japonés (ja-JP), portugués brasileño (pt-BR), español (es-ES) y turco (tr-TR). Las instrucciones de audio están disponibles en todos los idiomas escritos, excepto en chino y japonés, que por defecto están en inglés. Para cambiar el idioma predeterminado, proporcione el idioma internacional y el código de configuración regional, por ejemplo, `ar-SA`.  
Predeterminado: el idioma que se utiliza actualmente en el navegador del usuario final  
Obligatorio: no  
Tipo: `string`  
**`disableLanguageSelector`**   
Si se establece en `true`, el rompecabezas de CAPTCHA oculta el selector de idioma.   
Valor predeterminado: `false`  
Obligatorio: no  
Tipo: `boolean`  
**`dynamicWidth`**   
Si se establece en `true`, el rompecabezas de CAPTCHA cambia de ancho para que sea compatible con el ancho de la ventana del navegador.   
Valor predeterminado: `false`  
Obligatorio: no  
Tipo: `boolean`  
**`skipTitle`**   
Si se establece en `true`, el rompecabezas de CAPTCHA no mostrará el título del rompecabezas **Resuelva el rompecabezas**.   
Valor predeterminado: `false`  
Obligatorio: no  
Tipo: `boolean`

# Cómo renderizar el rompecabezas de CAPTCHA
<a name="waf-js-captcha-api-render"></a>

En esta sección se incluye un ejemplo de la implementación de `renderCaptcha`.

Puede usar la AWS WAF `renderCaptcha` llamada donde desee en la interfaz de cliente. La llamada recupera un acertijo de CAPTCHA AWS WAF, lo renderiza y envía los resultados para su verificación. AWS WAF Al realizar la llamada, proporciona la configuración de renderización del rompecabezas y las devoluciones de llamadas que desea ejecutar cuando los usuarios finales completen el rompecabezas. Para obtener detalles sobre las opciones, consulte la sección anterior, [Especificación de la API CAPTCHA JavaScript](waf-js-captcha-api-specification.md).

Utilice esta llamada junto con la funcionalidad de administración de tokens de la integración inteligente de amenazas. APIs Esta llamada proporciona a su cliente un token que verifica que ha completado correctamente el rompecabezas de CAPTCHA. Utilice la integración inteligente contra amenazas APIs para gestionar el token y proporcionarlo en las llamadas de sus clientes a los puntos finales que están protegidos con paquetes de AWS WAF protección (web ACLs). Para obtener información sobre la amenaza inteligente APIs, consulte[Uso de la JavaScript API de amenazas inteligentes](waf-js-challenge-api.md).

**Despliegue de ejemplo**  
La siguiente lista de ejemplos muestra una implementación de CAPTCHA estándar, incluida la ubicación de la URL de AWS WAF integración en la `<head>` sección. 

Esta lista configura la `renderCaptcha` función con una llamada de respuesta correcta que utiliza el `AwsWafIntegration.fetch` contenedor de la integración de amenazas inteligentes. APIs Para obtener información acerca de esta función, consulte [Cómo utilizar el contenedor `fetch` de integración](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>
```

**Ejemplo de configuración**  
En la siguiente lista de ejemplos, se muestra la configuración no predeterminada de `renderCaptcha` para las opciones de ancho y título. 

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

Para obtener información completa acerca de las opciones de configuración, consulte [Especificación de la API CAPTCHA JavaScript](waf-js-captcha-api-specification.md).

# Gestión de una respuesta CAPTCHA de AWS WAF
<a name="waf-js-captcha-api-conditional"></a>

En esta sección se incluye un ejemplo de cómo administrar una respuesta de CAPTCHA.

Una AWS WAF regla con una CAPTCHA acción finaliza la evaluación de una solicitud web coincidente si la solicitud no tiene un token con una marca de tiempo de CAPTCHA válida. Si la solicitud es una `GET` text/html llamada, la CAPTCHA acción presenta al cliente un intersticial con un acertijo de CAPTCHA. Si no integras la JavaScript API de CAPTCHA, el intersticial resuelve el rompecabezas y, si el usuario final lo resuelve correctamente, vuelve a enviar la solicitud automáticamente. 

Al integrar la JavaScript API de CAPTCHA y personalizar el manejo del CAPTCHA, es necesario detectar la respuesta de CAPTCHA que termina, entregar el CAPTCHA personalizado y, a continuación, si el usuario final resuelve el acertijo con éxito, volver a enviar la solicitud web del cliente. 

El siguiente ejemplo de código muestra cómo hacerlo. 

**nota**  
La respuesta de AWS WAF CAPTCHA acción tiene un código de estado HTTP 405, que utilizamos para reconocer la respuesta en este código. CAPTCHA Si su punto de conexión protegido utiliza un código de estado HTTP 405 para comunicar cualquier otro tipo de respuesta para la misma llamada, este código de ejemplo también renderizará un rompecabezas de CAPTCHA para esas respuestas. 

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

# Administración de las claves de API para la API de JS CAPTCHA
<a name="waf-js-captcha-api-key"></a>

En esta sección, se proporcionan instrucciones para generar y eliminar claves de API.

Para integrar AWS WAF CAPTCHA en una aplicación cliente con la JavaScript API, necesitas la etiqueta de integración de la JavaScript API y la clave de API cifrada del dominio del cliente en el que quieres ejecutar el rompecabezas de CAPTCHA. 

La integración de la aplicación CAPTCHA JavaScript utiliza las claves de API cifradas para comprobar que el dominio de la aplicación cliente tiene permiso para utilizar la API de CAPTCHA. AWS WAF Cuando llamas a la API de CAPTCHA desde tu JavaScript cliente, proporcionas una clave de API con una lista de dominios que incluye un dominio para el cliente actual. Puede enumerar hasta 5 dominios en una sola clave cifrada. 

**Requisitos de la clave de API**  
La clave de API que utilices en su integración de CAPTCHA debe contener un dominio que se aplique al cliente en el que utilice la clave. 
+ Si especifica una `window.awsWafCookieDomainList` en la integración de amenazas inteligentes del cliente, al menos un dominio de la clave de API debe coincidir exactamente con uno de los dominios de token en `window.awsWafCookieDomainList` o debe ser el dominio de ápex de uno de esos dominios de token. 

  Por ejemplo, para el dominio de token `mySubdomain.myApex.com`, la clave de API `mySubdomain.myApex.com` coincide exactamente y la clave de API `myApex.com` es el dominio de ápex. Cualquiera de las claves coincide con el dominio de token. 

  Para obtener información sobre la configuración de la lista de dominios de tokens, consulte [Suministro de dominios para su uso en los tokens](waf-js-challenge-api-set-token-domain.md).
+ De lo contrario, el dominio actual debe estar incluido en la clave de API. El dominio actual es el dominio que puede ver en la barra de direcciones del navegador. 

Los dominios que utilices deben ser los que AWS WAF acepten, según el dominio host protegido y la lista de dominios simbólicos configurada para la ACL web. Para obtener más información, consulte [AWS WAF configuración de la lista de dominios simbólicos del paquete de protección (ACL web)](waf-tokens-domains.md#waf-tokens-domain-lists).

**Cómo elegir la región para la clave de API**  
AWS WAF puede generar claves de API de CAPTCHA en cualquier región en la que estén AWS WAF disponibles. 

Como regla general, debería usar la misma región para su clave de API de CAPTCHA que usa para su paquete de protección (ACL web). Sin embargo, si espera que un paquete de protección regional (ACL web) llegue a todo el mundo, puede obtener una etiqueta de JavaScript integración CAPTCHA específica CloudFront y una clave de API específica CloudFront, y utilizarlas con un paquete de protección regional (ACL web). Este enfoque permite a los clientes cargar una prueba CAPTCHA desde la región más cercana a ellos, lo que reduce la latencia. 

Las claves de API de CAPTCHA que están dirigidas a otras regiones no se admiten para su uso en CloudFront varias regiones. Solo se pueden usar en la región que las abarquen. 

**Cómo generar una clave de API para los dominios de sus clientes**  
Para obtener la URL de integración y generar y recuperar las claves de API a través de la consola. 

1. [Inicie sesión en la AWS WAF consola Consola de administración de AWS y ábrala en homev2. https://console.aws.amazon.com/wafv2/](https://console.aws.amazon.com/wafv2/homev2) 

1. En el panel de navegación, elija **Integración de la aplicación**. 

1. En el panel de **paquetes de protección (web ACLs) que están habilitados para la integración de aplicaciones**, seleccione la región que desee usar como clave de API. También puede seleccionar la región en el panel de **claves de API** de la pestaña de **integración con CAPTCHA**.

1. Seleccione la pestaña **Integración de CAPTCHA**. Esta pestaña proporciona la etiqueta de JavaScript integración CAPTCHA, que puede usar en la integración, y la lista de claves de API. Ambos los abarca la región seleccionada.

1. En el panel de **Claves de API**, seleccione **Generar claves**. Aparecerá el cuadro de diálogo de generación de claves. 

1. Introduzca los dominios de cliente que desee incluir en la clave. Puede especificar una máximo de 5. Cuando haya terminado, elija **Generar clave**. La interfaz vuelve a la pestaña de integración de CAPTCHA, donde aparece la nueva clave. 

   Una vez creada, la clave de API es inmutable. Si necesita realizar cambios en una clave, genere una nueva clave y úsela en su lugar. 

1. (Opcional) Copia la clave recién generada para usarla en la integración. 

También puedes usar el REST APIs o uno de los idiomas específicos para este trabajo AWS SDKs . [Las llamadas a la API REST son [Create APIKey y List](https://docs.aws.amazon.com/waf/latest/APIReference/API_CreateAPIKey.html). APIKeys](https://docs.aws.amazon.com/waf/latest/APIReference/API_ListAPIKeys.html) 

**Eliminación de una clave de API**  
Para eliminar una clave de API, debes usar la API REST o uno de los idiomas específicos AWS SDKs. La llamada a la API REST es [Eliminar APIKey](https://docs.aws.amazon.com/waf/latest/APIReference/API_DeleteAPIKey.html). No puede utilizar la consola para eliminar una clave. 

Después de eliminar una clave, pueden pasar hasta 24 horas AWS WAF hasta que no se permita su uso en todas las regiones. 

# AWS WAF integración de aplicaciones móviles
<a name="waf-mobile-sdk"></a>

En esta sección se presenta el tema del uso del AWS WAF dispositivo móvil SDKs para implementar la integración AWS WAF SDKs inteligente de amenazas en aplicaciones móviles y de TV de Android e iOS. En cuanto a las aplicaciones de TV, SDKs son compatibles con las principales plataformas de televisión inteligente, incluidas Android TV y Apple TV.
+ En el caso de las aplicaciones móviles y de TV con Android, SDKs funcionan con la API de Android versión 23 (Android versión 6) y versiones posteriores. Para obtener información sobre las versiones de Android, consulte las [Notas de versión de la plataforma SDK](https://developer.android.com/tools/releases/platforms).
+ En el caso de las aplicaciones móviles de iOS, SDKs funcionan para la versión 13 de iOS y versiones posteriores. Para obtener información sobre las versiones de iOS, consulte las [notas de la versión de iOS y iPadOS](https://developer.apple.com/documentation/ios-ipados-release-notes).
+ Para las aplicaciones de Apple TV, SDKs funcionan para tvOS versión 14 o posterior. Para obtener información sobre las versiones de tvOS, consulte [Notas de lanzamiento de tvOS](https://developer.apple.com/documentation/tvos-release-notes).

Con el AWS WAF SDK móvil, puedes gestionar la autorización de los tokens e incluir los tokens en las solicitudes que envíes a tus recursos protegidos. Al utilizar el SDKs, se asegura de que estas llamadas a procedimientos remotos realizadas por su cliente contengan un token válido. Además, cuando esta integración esté instalada en las páginas de su aplicación, podrá implementar reglas de mitigación en su paquete de protección (ACL web), como bloquear las solicitudes que no contengan un token válido.

Para acceder al móvil SDKs, póngase en contacto con el servicio de asistencia en [Contact AWS](https://aws.amazon.com/contact-us).

**nota**  
Los AWS WAF dispositivos móviles SDKs no están disponibles para la personalización de CAPTCHA.

El enfoque básico para usar el SDK consiste en crear un proveedor de fichas mediante un objeto de configuración y, a continuación, utilizar el proveedor de fichas para recuperar las fichas. AWS WAF De forma predeterminada, el proveedor de tokens incluye los tokens recuperados en sus solicitudes web para su recurso protegido. 

La siguiente es una lista parcial de la implementación de un SDK, en la que se muestran los componentes principales. Para obtener más ejemplos más detallados, consulte [Ejemplos de código para el SDK AWS WAF móvil](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();
```

------

# Instalación del SDK AWS WAF móvil
<a name="waf-mobile-sdk-installing"></a>

En esta sección se proporcionan instrucciones para instalar el SDK AWS WAF móvil.

Para acceder al dispositivo móvil SDKs, ponte en contacto con el servicio de asistencia en [Contact AWS](https://aws.amazon.com/contact-us).

Implemente SDK para móviles primero en un entorno de prueba y, después, en producción.

**Para instalar el SDK AWS WAF móvil**

1. Inicie sesión Consola de administración de AWS y abra la AWS WAF consola en [https://console.aws.amazon.com/wafv2/homev2](https://console.aws.amazon.com/wafv2/homev2). 

1. En el panel de navegación, elija **Integración de la aplicación**. 

1. En la pestaña **Integraciones de amenazas inteligentes**, haga lo siguiente: 

   1. En el panel de **paquetes de protección (web ACLs) que están habilitados para la integración de aplicaciones**, localice el paquete de protección (ACL web) con el que se está integrando. Copie y guarde la URL de integración del paquete de protección (ACL web) para utilizarla en la implementación. También puede obtener esta URL a través de la llamada a la API `GetWebACL`.

   1. Elija el tipo y la versión del dispositivo móvil y, a continuación, seleccione **Descargar**. Puede elegir la versión que desee, pero le recomendamos que utilice la versión más reciente. AWS WAF descarga el `zip` archivo para su dispositivo en su ubicación de descarga estándar.

1. En su entorno de desarrollo de aplicaciones, descomprima el archivo en la ubicación de trabajo que elija. En el directorio de nivel superior del archivo zip, busque y abra el `README`. Sigue las instrucciones del `README` archivo para instalar el SDK AWS WAF móvil y usarlo en el código de tu aplicación móvil. 

1. Programe la aplicación de acuerdo con las instrucciones que se detallan en las siguientes secciones.

# AWS WAF especificación de SDK móvil
<a name="waf-mobile-sdk-specification"></a>

En esta sección, se enumeran los objetos, las operaciones y los ajustes de configuración del SDK para la última versión disponible del SDK para móviles de AWS WAF . Para obtener información detallada sobre cómo funcionan el proveedor de tokens y las operaciones para las distintas combinaciones de ajustes de configuración, consulte [Cómo funciona el SDK AWS WAF móvil](waf-mobile-sdk-how-it-works.md). 

**`WAFToken`**  
Contiene un AWS WAF token.    
**`getValue()`**  
Recupera la representación `String` del valor `WAFToken`. 

**`WAFTokenProvider`**  
Administra los tokens en su aplicación para móviles. Implemente esto usando un objeto `WAFConfiguration`.    
**`getToken()`**  
Si la actualización en segundo plano está habilitada, devuelve el token almacenado en caché. Si la actualización en segundo plano está desactivada, se realiza una llamada síncrona y bloqueante AWS WAF a para recuperar un nuevo token.   
**`loadTokenIntoProvider(WAFToken)`**  
Carga el token especificado en el`WAFTokenProvider`, reemplazando cualquier token que el proveedor administraba. El proveedor de tokens toma posesión del token nuevo y continúa administrando su actualización. Esta operación también actualiza el token en el almacén de cookies si `setTokenCookie` está habilitado en el `WAFConfiguration`.  
**`onTokenReady(WAFTokenResultCallback)`**  
Indica al proveedor de tokens que actualice el token e invoque la devolución de llamada proporcionada cuando haya un token activo listo. El proveedor de tokens invocará la devolución de llamada en un hilo en segundo plano cuando el token esté en caché y esté listo. Llame a esto cuando la aplicación se cargue por primera vez y también cuando vuelva a un estado activo. Para obtener más información sobre cómo volver a un estado activo, consulte [Recuperación de un token tras la inactividad de la aplicación](waf-mobile-sdk-how-it-works.md#waf-mobile-sdk-how-back-from-inactive).   
Para las aplicaciones de Android o iOS, puede configurar `WAFTokenResultCallback` en la operación que desee que el proveedor de tokens invoque cuando el token solicitado esté listo. Su implementación de `WAFTokenResultCallback` debe tomar los parámetros `WAFToken`, `SdkError`. Para las aplicaciones de iOS, también puede crear una función en línea.   
**`storeTokenInCookieStorage(WAFToken)`**  
Le indica `WAFTokenProvider` que almacene el AWS WAF token especificado en el administrador de cookies del SDK. De forma predeterminada, el token solo se agrega al almacén de cookies cuando se adquiere por primera vez y cuando se actualiza. Si la aplicación borra el almacén de cookies compartido por cualquier motivo, el SDK no volverá a añadir el AWS WAF token automáticamente hasta la próxima actualización. 

**`WAFConfiguration`**  
Contiene la configuración para la implementación de `WAFTokenProvider`. Al implementar esto, debe proporcionar la URL de integración del paquete de protección (ACL web), el nombre de dominio que usará en el token y cualquier configuración no predeterminada que desee que use el proveedor de tokens.   
La siguiente lista especifica los ajustes de configuración que puede administrar en el objeto `WAFConfiguration`.    
**`applicationIntegrationUrl`**   
La URL de integración de aplicaciones. Consíguelo desde la AWS WAF consola o mediante una llamada a la `getWebACL` API.  
Obligatorio: sí  
Tipo: URL específica de la aplicación. Para iOS, consulte [URL de iOS](https://developer.apple.com/documentation/foundation/url). Para Android, consulte [URL java.net](https://docs.oracle.com/javase/7/docs/api/java/net/URL.html).   
**`backgroundRefreshEnabled`**   
Indica si desea que el proveedor de tokens actualice el token en segundo plano. Si lo establece, el proveedor de tokens los actualiza en segundo plano de acuerdo con los ajustes de configuración que rigen las actividades de actualización automática de los tokens.   
Obligatorio: no  
Tipo: `Boolean`  
Valor predeterminado: `TRUE`  
**`domainName`**   
El dominio que se utilizará en el token, que se utiliza para la adquisición de tokens y el almacenamiento de cookies. Por ejemplo, `example.com` o `aws.amazon.com`. Por lo general, este es el dominio host del recurso asociado con el paquete de protección (ACL web), hacia el cual enviará solicitudes web. En el caso del grupo de reglas administradas de la ACFP, `AWSManagedRulesACFPRuleSet`, este suele ser un dominio único que coincide con el dominio de la ruta de creación de cuentas que proporcionó en la configuración del grupo de reglas. En el caso del grupo de reglas administradas de ATP, `AWSManagedRulesATPRuleSet`, este suele ser un dominio único que coincide con el dominio de la ruta de inicio de sesión que proporcionó en la configuración del grupo de reglas.   
No se admiten sufijos públicos. Por ejemplo, no puede usar `gov.au` o `co.uk` como dominio de token.  
El dominio debe ser uno que AWS WAF lo acepte, según el dominio host protegido y la lista de dominios simbólicos del paquete de protección (ACL web). Para obtener más información, consulte [AWS WAF configuración de la lista de dominios simbólicos del paquete de protección (ACL web)](waf-tokens-domains.md#waf-tokens-domain-lists).  
Obligatorio: sí  
Tipo: `String`   
**`maxErrorTokenRefreshDelayMsec`**   
El tiempo máximo en milisegundos para esperar antes de repetir una actualización del token después de un intento fallido. En cada reintento automático tras un intento fallido, se añade un retroceso exponencial hasta alcanzar el tiempo de demora especificado. Este valor se utiliza cuando la recuperación del token ha fallado y se ha vuelto a intentar `maxRetryCount` veces.   
Obligatorio: no  
Tipo: `Integer`  
Valor predeterminado: `5000` (5 segundos)  
Valor mínimo permitido: `1` (1 milisegundo)  
Valor máximo permitido: `30000` (30 segundos)  
**`maxRetryCount`**   
El número máximo de reintentos que se pueden realizar con un retroceso exponencial cuando se solicita un token.   
Obligatorio: no  
Tipo: `Integer`  
Valor predeterminado: `Infinity`  
Valor mínimo permitido: `0`  
Valor máximo permitido: `100`  
**`setTokenCookie`**   
Indica si desea que el administrador de cookies del SDK agregue una cookie de token en las solicitudes y en otras áreas.   
Con un valor `TRUE`:   
+ El administrador de cookies agrega una cookie de token a todas las solicitudes cuya ruta esté bajo la ruta especificada en `tokenCookiePath`. 
+ La operación `WAFTokenProvider` `loadTokenIntoProvider()` actualiza el token en el almacén de cookies, además de cargarlo en el proveedor de tokens.
Obligatorio: no  
Tipo: `Boolean`  
Valor predeterminado: `TRUE`  
**`tokenCookiePath`**   
Se usa cuando `setTokenCookie` es `TRUE`. Indica la ruta de nivel superior en la que desea que el gestor de cookies del SDK añada una cookie de token. El administrador agrega una cookie de token a todas las solicitudes que envíe a esta ruta y a todas las rutas secundarias.   
Por ejemplo, si lo establece en `/web/login`, el administrador incluirá la cookie de token para todo lo que se envíe a `/web/login` y para cualquiera de sus rutas secundarias, como `/web/login/help`. No incluye el token para las solicitudes enviadas a otras rutas, como `/`, `/web` o `/web/order`.   
Obligatorio: no  
Tipo: `String`  
Valor predeterminado: `/`  
**`tokenRefreshDelaySec`**   
Se utiliza para la actualización en segundo plano. La cantidad máxima de tiempo en segundos entre las actualizaciones del token en segundo plano.  
Obligatorio: no  
Tipo: `Integer`  
Valor predeterminado: `88`  
Valor mínimo permitido: `88`  
Valor máximo permitido: `300` (5 minutos)

## AWS WAF errores del SDK móvil
<a name="waf-mobile-sdk-errors"></a>

En esta sección se enumeran los posibles errores de la versión actual del SDK AWS WAF móvil.

**`SdkError`**  
El tipo de error que se devuelve cuando falla la obtención de un token. Los SDK de Android y iOS tienen los mismos tipos de errores.  
El SDK AWS WAF móvil tiene los siguientes tipos de errores:    
**`invalidChallenge`**  
Este error se devuelve cuando el servidor de tokens devuelve datos de desafío no válidos o cuando un atacante altera la respuesta.  
**`errorInvokingGetChallengeEndpoint`**  
Este error se devuelve cuando el servidor de tokens envía un código de respuesta no exitoso al cliente o cuando ocurre un error de red.  
**`invalidVerifyChallengeResponse`**  
Este error se devuelve cuando se produce un error al recuperar la respuesta `aws-waf-token` de verificación del AWS WAF servidor o se ha manipulado la respuesta del servidor.  
**`errorInvokingVerifyEndpoint`**  
Este error se devuelve cuando el cliente recibe una mala respuesta del AWS WAF servidor o un error de red al verificar el problema resuelto.  
**`internalError`**  
Este error se devuelve ante cualquier otro error que pueda ocurrir dentro del propio SDK.

**`socketTimeoutException`**  
Este error se devuelve con frecuencia cuando ocurren errores de red durante la obtención del token.  
Este error puede deberse a lo siguiente:  
+ Bajo ancho de banda de la red: confirme la configuración de conectividad de red.
+ URL de integración de aplicaciones mutada: confirme que la URL de integración no se ha modificado con respecto a la que aparece en la consola AWS WAF 

# Cómo funciona el SDK AWS WAF móvil
<a name="waf-mobile-sdk-how-it-works"></a>

En esta sección se explica cómo funcionan juntas las clases, propiedades y operaciones del SDK AWS WAF móvil.

Los dispositivos móviles te SDKs proporcionan un proveedor de tokens configurable que puedes usar para recuperar y usar los tokens. El proveedor de los tokens verifica que las solicitudes que permita procedan de clientes legítimos. Cuando envías solicitudes a los AWS recursos con los que proteges AWS WAF, incluyes el token en una cookie para validar la solicitud. Puede gestionar la cookie de token manualmente o dejar que el proveedor de tokens lo haga por usted.

En esta sección se describen las interacciones entre las clases, las propiedades y los métodos que se incluyen en el SDK para móviles. Para obtener información sobre la especificación del SDK, consulte [AWS WAF especificación de SDK móvil](waf-mobile-sdk-specification.md). 

## Recuperación de tokens y almacenamiento en caché
<a name="waf-mobile-sdk-how-token-basics"></a>

Cuando crea la instancia del proveedor de tokens en su aplicación para móviles, configura la forma en que quiere que administre los tokens y su recuperación. Su principal opción es cómo mantener los tokens válidos y vigentes para usarlos en las solicitudes web de su aplicación:
+ **Actualización en segundo plano habilitada** Es el valor predeterminado. El proveedor del token actualiza automáticamente el token en segundo plano y lo guarda en caché. Con la actualización en segundo plano habilitada, cuando llama `getToken()`, la operación recupera el token almacenado en caché. 

  El proveedor de tokens actualiza el token a intervalos configurables, de modo que siempre haya un token vigente en la memoria caché mientras la aplicación esté activa. La actualización en segundo plano se detiene mientras la aplicación está inactiva. Para obtener información acerca de este tema, consulte [Recuperación de un token tras la inactividad de la aplicación](#waf-mobile-sdk-how-back-from-inactive).
+ **Actualización en segundo plano desactivada**: puede deshabilitar la actualización de los tokens en segundo plano y, a continuación, recuperarlos solo cuando lo solicite. Los tokens recuperados bajo demanda no se almacenan en caché y, si lo desea, puede recuperar más de uno. Cada token es independiente de los demás que recupere y cada uno tiene su propia marca de tiempo que se utiliza para calcular el vencimiento.

  Dispone de las siguientes opciones para recuperar el token cuando la actualización en segundo plano está desactivada: 
  + **`getToken()`**— Cuando llamas `getToken()` con la actualización en segundo plano desactivada, la llamada recupera un nuevo token de forma sincrónica. AWS WAF Se trata de una llamada que puede bloquear y que podría afectar a la capacidad de respuesta de la aplicación si se invoca en el subproceso principal. 
  + **`onTokenReady(WAFTokenResultCallback)`**: esta llamada recupera de forma asíncrona un nuevo token y, a continuación, invoca la devolución de llamada resultante proporcionada en un hilo en segundo plano cuando el token está listo. 

### Cómo reintenta el proveedor de tokens las recuperaciones de tokens fallidas
<a name="waf-mobile-sdk-how-token-retrieval-retries"></a>

El proveedor de tokens vuelve a intentar recuperar el token automáticamente cuando se produce un error en la recuperación. Los reintentos se realizan inicialmente mediante un retroceso exponencial con un tiempo de espera de reintento inicial de 100 ms. Para obtener información acerca de las recuperaciones exponenciales, consulte [Reintentos de error y retroceso exponencial en AWS](https://docs.aws.amazon.com/general/latest/gr/api-retries.html).

Cuando el número de reintentos alcanza el valor `maxRetryCount` configurado, el proveedor de tokens deja de intentarlo o pasa a intentarlo cada `maxErrorTokenRefreshDelayMsec` milisegundos, según el tipo de recuperación del token: 
+ **`onTokenReady()`**: el proveedor de tokens pasa a esperar `maxErrorTokenRefreshDelayMsec` milisegundos entre intentos y continúa intentando recuperar el token. 
+ **Actualización en segundo plano**: el proveedor del token pasa a esperar `maxErrorTokenRefreshDelayMsec` milisegundos entre intentos y continúa intentando recuperar el token. 
+ **Llamadas `getToken()` bajo demanda, cuando la actualización en segundo plano está desactivada**: el proveedor de tokens deja de intentar recuperar un token y devuelve el valor del token anterior o un valor nulo si no hay ningún token anterior. 

## Escenarios de reintento de recuperación de tokens
<a name="waf-mobile-sdk-how-token-retrieval-retry-scenarios"></a>

Cuando el proveedor de tokens intenta recuperar un token, puede producir reintentos automáticos según el punto del flujo de recuperación de tokens en el que falle la operación. En esta sección, se enumeran los posibles puntos donde podría ver un reintento automático.
+ **Obtener o verificar el AWS WAF desafío a través de /inputs o /verify:**
  + Cuando se realiza una solicitud para obtener y verificar una AWS WAF impugnación y no se cumple, puede producirse un reintento automático.
  + Puede ver reintentos automáticos junto con un erro `socketTimeoutException`. Esto puede deberse a causas como las siguientes:
    + Bajo ancho de banda de la red: confirme la configuración de conectividad de red.
    + URL de integración de aplicaciones mutada: confirme que la URL de integración no se ha modificado con respecto a la que aparece en la consola AWS WAF 
  + La cantidad de reintentos automáticos se puede configurar mediante la función `maxRetryCount()`
+ **Actualización del token:**
  + Cuando una solicitud para actualizar el token se realiza mediante el manejador de tokens, puede producir reintentos automáticos.
  + La cantidad de reintentos automáticos aquí también se configura mediante la función `maxRetryCount()`.

Es posible una configuración sin reintentos automáticos si establece `maxRetryCount(0)`.

## Tiempo de inmunidad del token y actualización en segundo plano
<a name="waf-mobile-sdk-how-token-immunity"></a>

El tiempo de inmunidad de los tokens que configure en la ACL web es independiente del intervalo de actualización del token que establezca en el SDK AWS WAF móvil. Cuando habilita la actualización en segundo plano, el SDK actualiza el token en el intervalo que especifique mediante `tokenRefreshDelaySec()`. Esto puede generar varios tokens válidos de forma simultánea, según su tiempo de inmunidad configurado.

Para evitar múltiples tokens válidos, puede deshabilitar la actualización en segundo plano y usar la función `getToken()` para administrar el ciclo de vida del token en su aplicación móvil.

## Recuperación de un token tras la inactividad de la aplicación
<a name="waf-mobile-sdk-how-back-from-inactive"></a>

La actualización en segundo plano solo se realiza mientras la aplicación se considera activa para el tipo de aplicación: 
+ **iOS**: la actualización en segundo plano se realiza cuando la aplicación está en primer plano.
+ **Android**: la actualización en segundo plano se realiza cuando la aplicación no está cerrada, ya sea en primer plano o en segundo plano.

Si la aplicación permanece en un estado que no admite la actualización en segundo plano durante más de los `tokenRefreshDelaySec` segundos configurados, el proveedor de tokens detiene la actualización en segundo plano. Por ejemplo, en el caso de una aplicación de iOS, si `tokenRefreshDelaySec` es 300 y la aplicación se cierra o pasa a segundo plano durante más de 300 segundos, el proveedor de tokens deja de actualizar el token. Cuando la aplicación vuelve a un estado activo, el proveedor de tokens reinicia automáticamente la actualización en segundo plano. 

Cuando su aplicación vuelva a estar activa, llame a `onTokenReady()` para recibir una notificación cuando el proveedor de tokens recupere y almacene en caché un nuevo token. No se limite a llamar a `getToken()`, porque la caché podría no contener un token actual y válido. 

## URL de integración de la aplicación
<a name="waf-mobile-sdk-application-integration-url"></a>

La URL de integración de aplicaciones del SDK AWS WAF móvil apunta a una ACL web que ha activado para la integración de aplicaciones. Esta URL enruta las solicitudes al servidor backend correcto y las asocia con su cliente. No funciona como un control de seguridad estricto, por lo que exponer una URL de integración no representa un riesgo de seguridad.

Puede modificar técnicamente la URL de integración proporcionada y aun así obtener un token. Sin embargo, no lo recomendamos porque podría perder visibilidad de las tasas de resolución de desafíos o encontrar fallas en la obtención de tokens con errores de `socketTimeoutException`.

## Dependencias
<a name="waf-mobile-sdk-dependencies"></a>

Cada SDK AWS WAF móvil descargable incluye un archivo README en el que se enumeran las dependencias de su versión específica del SDK. Consulte el README para conocer las dependencias de su versión del SDK móvil.

## ProGuard Ofuscation/ (solo para el SDK de Android)
<a name="waf-mobile-sdk-obfuscation"></a>

Si utilizas un producto de ofuscación o minificación ProGuard, es posible que tengas que excluir algunos espacios de nombres para garantizar que el SDK móvil funcione correctamente. Consulte el README de su versión del SDK móvil para ver la lista de espacios de nombres y reglas de exclusión.

# Ejemplos de código para el SDK AWS WAF móvil
<a name="waf-mobile-sdk-coding-examples"></a>

Esta sección se brinda ejemplos de códigos para usar el SDK para móviles. 

## Inicialización del proveedor de tokens y obtención de tokens
<a name="waf-mobile-sdk-coding-basic"></a>

La instancia del proveedor de tokens se inicia mediante un objeto de configuración. A continuación, puede recuperar los tokens mediante las operaciones disponibles. Se indican a continuación los componentes básicos del código exigido.

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

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

Ejemplo de 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)
		}
	}
}
```

------

## Permisión de que el SDK proporcione la cookie de token en sus solicitudes HTTP
<a name="waf-mobile-sdk-coding-auto-token-cookie"></a>

Si `setTokenCookie` es `TRUE`, el proveedor de tokens incluye la cookie de token para usted en sus solicitudes web en todas las ubicaciones de la ruta especificada en `tokenCookiePath`. De forma predeterminada, `setTokenCookie` es `TRUE` y `tokenCookiePath` es `/`. 

Puede limitar el alcance de las solicitudes que incluyen una cookie de token especificando la ruta de la cookie de token, por ejemplo, `/web/login`. Si lo haces, comprueba que tus AWS WAF reglas no inspeccionen los tokens en las solicitudes que envíes a otras rutas. Cuando usa el grupo de reglas de `AWSManagedRulesACFPRuleSet`, configura las rutas de registro y creación de cuentas, y el grupo de reglas comprueba si hay tokens en las solicitudes que se envían a esas rutas. Para obtener más información, consulte [Adición del grupo de reglas administradas por ACFP a la nueva ACL web](waf-acfp-rg-using.md). Igualmente, al usar el grupo de reglas de `AWSManagedRulesATPRuleSet`, configure la ruta de inicio de sesión, y el grupo de reglas comprueba si hay tokens en las solicitudes que se envían a esa ruta. Para obtener más información, consulte [Adición del grupo de reglas administradas por ATP al paquete de protección (ACL web)](waf-atp-rg-using.md). 

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

Cuando `setTokenCookie` es `TRUE` así, el proveedor del token almacena el AWS WAF token en un `HTTPCookieStorage.shared` e incluye automáticamente la cookie en las solicitudes al dominio que especificaste`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 ]

Cuando `setTokenCookie` es`TRUE`, el proveedor del token almacena el AWS WAF token en una `CookieHandler` instancia que se comparte en toda la aplicación. Cuando el proveedor de tokens incluye automáticamente la cookie en las solicitudes al dominio que especificó en `WAFConfiguration`.

Ejemplo de Java:

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

Ejemplo de Kotlin:

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

Si ya tiene inicializada la instancia predeterminada `CookieHandler`, el proveedor de tokens la usará para administrar las cookies. De lo contrario, el proveedor del token inicializará una nueva `CookieManager` instancia con el AWS WAF token `CookiePolicy.ACCEPT_ORIGINAL_SERVER` y, a continuación, establecerá esta nueva instancia como la instancia predeterminada en`CookieHandler`.

El siguiente código muestra cómo el SDK inicializa el administrador de cookies y el controlador de cookies cuando no están disponibles en su aplicación. 

Ejemplo de Java:

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

Ejemplo de Kotlin:

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

------

## Suministro manual de la cookie de token en sus solicitudes HTTP
<a name="waf-mobile-sdk-coding-manual-token-cookie"></a>

Si configura `setTokenCookie` en `FALSE`, tendrá que proporcionar la cookie de token manualmente, como encabezado de solicitud HTTP de cookie, en las solicitudes que envíe a su punto de conexión protegido. El siguiente código muestra cómo hacerlo.

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

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

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

------