**Ti presentiamo una nuova esperienza di console per AWS WAF**

Ora puoi utilizzare l'esperienza aggiornata per accedere alle AWS WAF funzionalità da qualsiasi punto della console. Per ulteriori dettagli, consulta [Lavorare con la console](https://docs.aws.amazon.com/waf/latest/developerguide/working-with-console.html). 

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

# Integrazioni di applicazioni client in AWS WAF
<a name="waf-application-integration"></a>

Questa sezione spiega come utilizzare l'API di integrazione intelligente delle minacce APIs e JavaScript CAPTCHA con le tue funzionalità. AWS WAF 

Utilizza l'integrazione delle applicazioni AWS WAF client APIs per abbinare le protezioni lato client alle protezioni del pacchetto di protezione AWS lato server (Web ACL), per verificare che le applicazioni client che inviano richieste Web alle risorse protette siano i client previsti e che gli utenti finali siano esseri umani. 

Utilizza le integrazioni client per gestire le sfide silenziose del browser e i puzzle CAPTCHA, ottenere token con prove del successo del browser e delle risposte degli utenti finali e includere questi token nelle richieste agli endpoint protetti. Per informazioni generali sui token, consulta. AWS WAF [Uso dei token nella mitigazione AWS WAF intelligente delle minacce](waf-tokens.md) 

Combina le integrazioni dei client con le protezioni del Protection Pack (Web ACL) che richiedono token validi per l'accesso alle tue risorse. Puoi utilizzare gruppi di regole che controllano e monitorano i token di sfida, come quelli elencati nella sezione successiva, all'indirizzo[Integrazione intelligente delle minacce e regole AWS gestite](waf-application-integration-with-AMRs.md), e puoi utilizzare le azioni e le Challenge regole per controllare, come descritto in. CAPTCHA [CAPTCHAe Challenge in AWS WAF](waf-captcha-and-challenge.md) 

AWS WAF offre due livelli di integrazione per JavaScript le applicazioni e uno per le applicazioni mobili: 
+ **Integrazione intelligente delle minacce**: verifica l'applicazione client e fornisci l'acquisizione e la gestione dei AWS token. Questa funzionalità è simile alla funzionalità fornita dall'azione della AWS WAF Challenge regola. Questa funzionalità integra completamente l'applicazione client con il gruppo di regole `AWSManagedRulesACFPRuleSet` gestito, il gruppo di regole `AWSManagedRulesATPRuleSet` gestito e il livello di protezione mirato del gruppo di regole `AWSManagedRulesBotControlRuleSet` gestito. 

  L'integrazione intelligente delle minacce APIs utilizza la AWS WAF Silent Browser Challenge per garantire che i tentativi di accesso e le altre chiamate alla risorsa protetta siano consentiti solo dopo che il client ha acquisito un token valido. APIs Gestisce l'autorizzazione tramite token per le sessioni dell'applicazione client e raccoglie informazioni sul client per determinare se è gestito da un bot o da un essere umano. 
**Nota**  
È disponibile per JavaScript e per le applicazioni mobili Android e iOS. 
+ **Integrazione CAPTCHA**: verifica gli utenti finali con un puzzle CAPTCHA personalizzato che gestisci nella tua applicazione. È simile alla funzionalità fornita dall'azione della AWS WAF CAPTCHA regola, ma con un maggiore controllo sul posizionamento e sul comportamento del puzzle. 

  Questa integrazione sfrutta l'integrazione JavaScript intelligente delle minacce per eseguire sfide silenziose e fornire AWS WAF token alla pagina del cliente. 
**Nota**  
È disponibile per JavaScript le applicazioni. 

**Topics**
+ [Integrazione intelligente delle minacce e regole AWS gestite](waf-application-integration-with-AMRs.md)
+ [Accesso all'integrazione dell'applicazione AWS WAF client APIs](waf-application-integration-location-in-console.md)
+ [AWS WAF JavaScript integrazioni](waf-javascript-api.md)
+ [AWS WAF integrazione di applicazioni mobili](waf-mobile-sdk.md)

# Integrazione intelligente delle minacce e regole AWS gestite
<a name="waf-application-integration-with-AMRs"></a>

Questa sezione spiega come funziona l'integrazione APIs intelligente delle minacce con i gruppi di regole AWS Managed Rules.

L'integrazione intelligente delle minacce APIs funziona con pacchetti di protezione (web ACLs) che utilizzano i gruppi di regole intelligenti sulle minacce per abilitare la piena funzionalità di questi gruppi di regole gestiti avanzati. 
+ AWS WAF Gruppo di regole gestito per la prevenzione delle frodi (ACFP) per la creazione di account Fraud Control. `AWSManagedRulesACFPRuleSet` 

  La frode nella creazione di account è un'attività illegale online in cui un utente malintenzionato crea account non validi nell'applicazione per scopi quali ricevere bonus di iscrizione o spacciarsi per qualcuno. Il gruppo di regole gestito da ACFP fornisce regole per bloccare, etichettare e gestire le richieste che potrebbero far parte di tentativi fraudolenti di creazione di account. APIs Abilita la verifica del browser client e le informazioni sull'interattività umana ottimizzate che le regole ACFP utilizzano per separare il traffico client valido dal traffico dannoso.

  Per ulteriori informazioni, consultare [AWS WAF Gruppo di regole per la prevenzione delle frodi (ACFP) per la creazione di account Fraud Control](aws-managed-rule-groups-acfp.md) e [AWS WAF Fraud Control creazione di account e prevenzione delle frodi (ACFP)](waf-acfp.md).
+ AWS WAF Gruppo di regole gestito per la prevenzione dell'acquisizione di account (ATP) Fraud Control. `AWSManagedRulesATPRuleSet` 

  L'acquisizione di un account è un'attività illegale online in cui un utente malintenzionato ottiene l'accesso non autorizzato all'account di una persona. Il gruppo di regole gestito dall'ATP fornisce regole per bloccare, etichettare e gestire le richieste che potrebbero far parte di tentativi malevoli di acquisizione di account. APIs Consentono la verifica dei client e l'aggregazione del comportamento ottimizzate che le regole ATP utilizzano per separare il traffico client valido dal traffico dannoso.

  Per ulteriori informazioni, consultare [AWS WAF Gruppo di regole per la prevenzione delle acquisizioni di account (ATP) per il controllo delle frodi](aws-managed-rule-groups-atp.md) e [AWS WAF Controllo delle frodi e prevenzione delle acquisizioni di conti (ATP)](waf-atp.md).
+ Livello di protezione mirato del gruppo di regole gestito da AWS WAF Bot Control. `AWSManagedRulesBotControlRuleSet` 

  I bot vanno da quelli utili e che si identificano da soli, come la maggior parte dei motori di ricerca e dei crawler, ai bot dannosi che agiscono contro il tuo sito web e non si identificano da soli. Il gruppo di regole gestito da Bot Control fornisce regole per monitorare, etichettare e gestire l'attività dei bot nel traffico web. Quando si utilizza il livello di protezione mirato di questo gruppo di regole, le regole mirate utilizzano le informazioni sulla sessione client APIs fornite per rilevare meglio i bot dannosi. 

  Per ulteriori informazioni, consultare [AWS WAF Gruppo di regole Bot Control](aws-managed-rule-groups-bot.md) e [AWS WAF Controllo dei bot](waf-bot-control.md).

Per aggiungere uno di questi gruppi di regole gestiti al tuo pacchetto di protezione (ACL web), consulta le procedure [Aggiungere il gruppo di regole gestite ACFP all'ACL Web](waf-acfp-rg-using.md) e. [Aggiungere il gruppo di regole gestite ATP al pacchetto di protezione (Web ACL)](waf-atp-rg-using.md) [Aggiungere il gruppo di regole gestito da AWS WAF Bot Control all'ACL web](waf-bot-control-rg-using.md)

**Nota**  
I gruppi di regole gestiti attualmente non bloccano le richieste con token mancanti. Per bloccare le richieste che contengono token mancanti, dopo aver implementato l'integrazione dell'applicazione APIs, segui le istruzioni riportate all'indirizzo. [Bloccare le richieste che non hanno un AWS WAF token valido](waf-tokens-block-missing-tokens.md) 

# Accesso all'integrazione dell'applicazione AWS WAF client APIs
<a name="waf-application-integration-location-in-console"></a>

Questa sezione spiega dove trovare l'integrazione dell'applicazione APIs nella AWS WAF console.

Le JavaScript integrazioni APIs sono generalmente disponibili e puoi utilizzarle per i tuoi browser e altri dispositivi che eseguono JavaScript. 

AWS WAF offre un'integrazione intelligente delle minacce personalizzata SDKs per app mobili Android e iOS. 
+ Per le app Android per dispositivi mobili e TV, SDKs funziona per l'API Android versione 23 (Android versione 6) e successive. Per informazioni sulle versioni di Android, consulta le [note di rilascio della piattaforma SDK](https://developer.android.com/tools/releases/platforms).
+ Per le app mobili iOS, SDKs funziona per iOS versione 13 e successive. Per informazioni sulle versioni di iOS, consulta le [note di rilascio di iOS e iPadOS](https://developer.apple.com/documentation/ios-ipados-release-notes).
+ Per le app Apple TV, SDKs funzionano con la versione 14 o successiva di tvOS. Per informazioni sulle versioni di tvOS, consulta le note di rilascio di [tvOS](https://developer.apple.com/documentation/tvos-release-notes).

**Per accedere all'integrazione APIs tramite la console**

1. Accedi a Console di gestione AWS e apri la AWS WAF console all'indirizzo [https://console.aws.amazon.com/wafv2/homev2](https://console.aws.amazon.com/wafv2/homev2). 

1. Scegli **Integrazione delle applicazioni** nel riquadro di navigazione, quindi scegli la scheda che ti interessa.
   + **L'integrazione intelligente delle minacce** è disponibile per JavaScript tutte le applicazioni mobili. 

     La scheda contiene quanto segue:
     + Un elenco dei pacchetti di protezione (web ACLs) abilitati per l'integrazione intelligente delle applicazioni contro le minacce. L'elenco include ogni pacchetto di protezione (ACL web) che utilizza il gruppo di regole `AWSManagedRulesACFPRuleSet` gestito, il gruppo di regole `AWSManagedRulesATPRuleSet` gestito o il livello di protezione mirato del gruppo di regole `AWSManagedRulesBotControlRuleSet` gestito. Quando si implementa la minaccia intelligente APIs, si utilizza l'URL di integrazione per il pacchetto di protezione (ACL Web) con cui si desidera effettuare l'integrazione.
     + A APIs cui hai accesso. JavaScript APIs Sono sempre disponibili. Per accedere al cellulare SDKs, contatta l'assistenza all'indirizzo [Contact AWS](https://aws.amazon.com/contact-us).
   + **L'integrazione CAPTCHA** è disponibile per le JavaScript applicazioni. 

     La scheda contiene quanto segue: 
     + L'URL di integrazione da utilizzare nella tua integrazione. 
     + Le chiavi API che hai creato per i domini delle tue applicazioni client. L'utilizzo dell'API CAPTCHA richiede una chiave API crittografata che dia ai clienti il diritto di accedere al AWS WAF CAPTCHA dai loro domini. Per ogni client con cui effettui l'integrazione, utilizza una chiave API che contenga il dominio del client. Per ulteriori informazioni su questi requisiti e sulla gestione di queste chiavi, consulta[Gestione delle chiavi API per l'API JS CAPTCHA](waf-js-captcha-api-key.md).

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

Questa sezione spiega come utilizzare le AWS WAF JavaScript integrazioni.

Puoi utilizzare l' JavaScript integrazione APIs per implementare integrazioni di AWS WAF applicazioni nei tuoi browser e in altri dispositivi che eseguono. JavaScript 

I puzzle CAPTCHA e le sfide silenziose possono essere eseguiti solo quando i browser accedono agli endpoint HTTPS. I browser client devono funzionare in contesti sicuri per acquisire i token. 
+ Questa minaccia intelligente APIs consente di gestire l'autorizzazione dei token mediante una sfida silenziosa sul browser lato client e di includere i token nelle richieste inviate alle risorse protette. 
+ L'API di integrazione CAPTCHA si aggiunge alla minaccia APIs intelligente e consente di personalizzare il posizionamento e le caratteristiche del puzzle CAPTCHA nelle applicazioni client. Questa API sfrutta la minaccia intelligente APIs per acquisire AWS WAF token da utilizzare nella pagina dopo che l'utente finale ha completato con successo il puzzle CAPTCHA. 

Utilizzando queste integrazioni, ti assicuri che le chiamate di procedura remota del tuo client contengano un token valido. Quando queste integrazioni APIs sono presenti nelle pagine dell'applicazione, è possibile implementare regole di mitigazione nel pacchetto di protezione (Web ACL), ad esempio bloccare le richieste che non contengono un token valido. Puoi anche implementare regole che impongono l'uso dei token ottenuti dalle tue applicazioni client, utilizzando le CAPTCHA azioni Challenge o nelle tue regole. 

**Esempio di implementazione di una minaccia intelligente APIs**  
L'elenco seguente mostra i componenti di base di un'implementazione tipica della minaccia intelligente APIs in una pagina di applicazione 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>
```

**Esempio di implementazione dell'API CAPTCHA JavaScript**  
L'API di integrazione CAPTCHA ti consente di personalizzare l'esperienza con i puzzle CAPTCHA degli utenti finali. L'integrazione CAPTCHA sfrutta l'integrazione JavaScript intelligente delle minacce, per la verifica del browser e la gestione dei token, e aggiunge una funzione per la configurazione e il rendering del puzzle CAPTCHA. 

L'elenco seguente mostra i componenti di base di un'implementazione tipica dell'API JavaScript CAPTCHA in una pagina di applicazione 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**
+ [Fornire domini da utilizzare nei token](waf-js-challenge-api-set-token-domain.md)
+ [Utilizzo dell' JavaScript API con politiche di sicurezza dei contenuti](waf-javascript-api-csp.md)
+ [Utilizzo dell' JavaScript API per le minacce intelligenti](waf-js-challenge-api.md)
+ [Utilizzo dell'API CAPTCHA JavaScript](waf-js-captcha-api.md)

# Fornire domini da utilizzare nei token
<a name="waf-js-challenge-api-set-token-domain"></a>

Questa sezione spiega come fornire domini aggiuntivi per i token.

Per impostazione predefinita, quando AWS WAF crea un token, utilizza il dominio host della risorsa associata al protection pack (web ACL). È possibile fornire domini aggiuntivi per i token AWS WAF creati per. JavaScript APIs Per fare ciò, configura la variabile globale`window.awsWafCookieDomainList`, con uno o più domini token. 

Quando AWS WAF crea un token, utilizza il dominio più appropriato e più breve tra la combinazione dei domini in `window.awsWafCookieDomainList` e del dominio host della risorsa associata al protection pack (ACL web). 

Impostazioni di esempio: 

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

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

Non puoi usare suffissi pubblici in questo elenco. Ad esempio, non puoi utilizzare `gov.au` or `co.uk` come domini token nell'elenco.

I domini specificati in questo elenco devono essere compatibili con gli altri domini e configurazioni di dominio: 
+ I domini devono essere accettabili, in base al dominio host protetto e all'elenco di domini token configurato per il pacchetto di protezione (Web ACL). AWS WAF Per ulteriori informazioni, consulta [AWS WAF configurazione dell'elenco di domini con token protection pack (Web ACL)](waf-tokens-domains.md#waf-tokens-domain-lists). 
+ Se utilizzi l'API JavaScript CAPTCHA, almeno un dominio nella tua chiave API CAPTCHA deve corrispondere esattamente a uno dei domini token di `window.awsWafCookieDomainList` o deve essere il dominio apex di uno di quei domini token. 

  Ad esempio, per il dominio token`mySubdomain.myApex.com`, la chiave API corrisponde esattamente e la chiave API `mySubdomain.myApex.com` è il dominio apex. `myApex.com` Entrambe le chiavi corrispondono al dominio del token. 

  Per ulteriori informazioni sulle chiavi API, consulta[Gestione delle chiavi API per l'API JS CAPTCHA](waf-js-captcha-api-key.md). 

Se utilizzi il gruppo di regole `AWSManagedRulesACFPRuleSet` gestito, potresti configurare un dominio che corrisponda a quello nel percorso di creazione dell'account che hai fornito per la configurazione del gruppo di regole. Per ulteriori informazioni su questa configurazione, consulta [Aggiungere il gruppo di regole gestite ACFP all'ACL Web](waf-acfp-rg-using.md).

Se utilizzi il gruppo di regole `AWSManagedRulesATPRuleSet` gestito, potresti configurare un dominio che corrisponda a quello nel percorso di accesso che hai fornito alla configurazione del gruppo di regole. Per ulteriori informazioni su questa configurazione, consulta [Aggiungere il gruppo di regole gestite ATP al pacchetto di protezione (Web ACL)](waf-atp-rg-using.md).

# Utilizzo dell' JavaScript API con politiche di sicurezza dei contenuti
<a name="waf-javascript-api-csp"></a>

Questa sezione fornisce un esempio di configurazione per inserire nella lista consentita il dominio AWS WAF apex.

Se applichi politiche di sicurezza dei contenuti (CSP) alle tue risorse, affinché JavaScript l'implementazione funzioni, devi inserire nella lista consentita il dominio apex. AWS WAF `awswaf.com` JavaScript SDKs Effettua chiamate a diversi AWS WAF endpoint, quindi Allowlist questo dominio fornisce le autorizzazioni necessarie per funzionare. SDKs 

Di seguito viene mostrato un esempio di configurazione per inserire nella lista consentita il dominio apex: AWS WAF 

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

Se provi a utilizzare il JavaScript SDKs con risorse che utilizzano CSP e non hai inserito il AWS WAF dominio nella lista consentita, riceverai errori come i seguenti: 

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

# Utilizzo dell' JavaScript API per le minacce intelligenti
<a name="waf-js-challenge-api"></a>

Questa sezione fornisce istruzioni per l'utilizzo dell' JavaScript API per le minacce intelligenti nell'applicazione client.

La minaccia intelligente APIs fornisce operazioni per eseguire sfide silenziose contro il browser dell'utente e per gestire i AWS WAF token che forniscono la prova dell'avvenuta sfida e le risposte CAPTCHA. 

Implementa l' JavaScript integrazione prima in un ambiente di test, poi in produzione. Per ulteriori indicazioni sulla codifica, consulta le sezioni seguenti. 

 

**Per usare la minaccia intelligente APIs**

1. **Installa il APIs** 

   Se utilizzi l'API CAPTCHA, puoi saltare questo passaggio. Quando installi l'API CAPTCHA, lo script installa automaticamente la minaccia intelligente. APIs

   1. [Accedi Console di gestione AWS e apri la AWS WAF console all'indirizzo homev2. https://console.aws.amazon.com/wafv2/](https://console.aws.amazon.com/wafv2/homev2) 

   1. Nel riquadro di navigazione, scegliere **Application integration (Integrazione di applicazioni)**. Nella pagina di **integrazione dell'applicazione**, puoi vedere le opzioni a schede. 

   1. Seleziona Integrazione **intelligente** delle minacce

   1. Nella scheda, seleziona il pacchetto di protezione (Web ACL) con cui desideri effettuare l'integrazione. L'elenco dei pacchetti di protezione (Web ACL) include solo i pacchetti di protezione (Web ACLs) che utilizzano il gruppo di regole `AWSManagedRulesACFPRuleSet` gestito, il gruppo di regole `AWSManagedRulesATPRuleSet` gestito o il livello di protezione mirato del gruppo di regole `AWSManagedRulesBotControlRuleSet` gestito. 

   1. Apri il riquadro **JavaScript SDK** e copia il tag dello script da utilizzare nella tua integrazione. 

   1. Nel codice della pagina dell'applicazione, nella `<head>` sezione, inserisci il tag script che hai copiato per il protection pack (web ACL). Questa inclusione fa sì che l'applicazione client recuperi automaticamente un token in background al caricamento della pagina. 

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

      Questo `<script>` elenco è configurato con l'`defer`attributo, ma puoi modificare l'impostazione `async` se desideri un comportamento diverso per la tua pagina. 

1. **(Facoltativo) Aggiungi la configurazione del dominio per i token del client**: per impostazione predefinita, quando AWS WAF crea un token, utilizza il dominio host della risorsa associata al pacchetto di protezione (ACL web). Per fornire domini aggiuntivi per il JavaScript APIs, segui le istruzioni all'indirizzo. [Fornire domini da utilizzare nei token](waf-js-challenge-api-set-token-domain.md) 

1. **Codifica la tua integrazione intelligente contro le minacce**: scrivi il codice per assicurarti che il recupero dei token venga completato prima che il client invii le sue richieste agli endpoint protetti. Se stai già utilizzando l'`fetch`API per effettuare la chiamata, puoi sostituire il wrapper di integrazione. AWS WAF `fetch` Se non utilizzi l'`fetch`API, puoi invece utilizzare l'operazione di AWS WAF integrazione`getToken`. Per indicazioni sulla codifica, consulta le seguenti sezioni. 

1. **Aggiungi la verifica tramite token nel tuo pacchetto di protezione (Web ACL)**: aggiungi almeno una regola al tuo pacchetto di protezione (Web ACL) per verificare la presenza di un token di sfida valido nelle richieste Web inviate dal client. Puoi utilizzare gruppi di regole che controllano e monitorano i token di sfida, come il livello mirato del gruppo di regole gestito da Bot Control, e puoi utilizzare l'azione delle Challenge regole per verificare, come descritto in. [CAPTCHAe Challenge in AWS WAF](waf-captcha-and-challenge.md) 

   Le aggiunte al pacchetto di protezione (Web ACL) verificano che le richieste agli endpoint protetti includano il token che hai acquisito nell'integrazione con il client. Le richieste che includono un token valido e non scaduto superano l'Challengeispezione e non inviano un'altra contestazione silenziosa al cliente. 

1. **(Facoltativo) Blocca le richieste APIs con token mancanti**: se utilizzi il gruppo di regole gestite ACFP, il gruppo di regole gestito ATP o le regole mirate del gruppo di regole Bot Control, queste regole non bloccano le richieste che contengono token mancanti. Per bloccare le richieste che contengono token mancanti, segui le istruzioni riportate all'indirizzo. [Bloccare le richieste che non hanno un AWS WAF token valido](waf-tokens-block-missing-tokens.md) 

**Topics**
+ [Specifiche dell'API per le minacce intelligenti](waf-js-challenge-api-specification.md)
+ [Come usare il `fetch` wrapper di integrazione](waf-js-challenge-api-fetch-wrapper.md)
+ [Come usare l'integrazione `getToken`](waf-js-challenge-api-get-token.md)

# Specifiche dell'API per le minacce intelligenti
<a name="waf-js-challenge-api-specification"></a>

Questa sezione elenca le specifiche dei metodi e delle proprietà della JavaScript APIs mitigazione intelligente delle minacce. Utilizzali APIs per le integrazioni intelligenti di minacce e CAPTCHA.

**`AwsWafIntegration.fetch()`**  
Invia la `fetch` richiesta HTTP al server utilizzando l'implementazione dell' AWS WAF integrazione. 

**`AwsWafIntegration.getToken()`**  
Recupera il AWS WAF token memorizzato e lo memorizza in un cookie nella pagina corrente con il nome `aws-waf-token` e il valore impostato sul valore del token. 

**`AwsWafIntegration.hasToken()`**  
Restituisce un valore booleano che indica se il `aws-waf-token` cookie contiene attualmente un token non scaduto. 

Se utilizzi anche l'integrazione CAPTCHA, consulta le relative specifiche all'indirizzo. [Specifiche dell'API CAPTCHA JavaScript](waf-js-captcha-api-specification.md)

# Come usare il `fetch` wrapper di integrazione
<a name="waf-js-challenge-api-fetch-wrapper"></a>

Questa sezione fornisce istruzioni per l'uso del wrapper di integrazione`fetch`.

È possibile utilizzare il AWS WAF `fetch` wrapper modificando le normali `fetch` chiamate all'`fetch`API nel namespace. `AwsWafIntegration` Il AWS WAF wrapper supporta tutte le stesse opzioni della chiamata JavaScript `fetch` API standard e aggiunge la gestione dei token per l'integrazione. Questo approccio è generalmente il modo più semplice per integrare l'applicazione. 

**Prima dell'implementazione del wrapper**  
L'elenco di esempio seguente mostra il codice standard prima di implementare il `AwsWafIntegration` `fetch` wrapper.

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

**Dopo l'implementazione del wrapper**  
L'elenco seguente mostra lo stesso codice con l'implementazione del `AwsWafIntegration` `fetch` wrapper.

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

# Come usare l'integrazione `getToken`
<a name="waf-js-challenge-api-get-token"></a>

Questa sezione spiega come utilizzare l'`getToken`operazione.

AWS WAF richiede che le richieste agli endpoint protetti includano il cookie denominato `aws-waf-token` con il valore del token corrente. 

L'`getToken`operazione è una chiamata API asincrona che recupera il AWS WAF token e lo memorizza in un cookie nella pagina corrente con il nome `aws-waf-token` e il valore impostato sul valore del token. Puoi utilizzare questo cookie token in base alle tue esigenze nella tua pagina. 

Quando chiami`getToken`, esegue le seguenti operazioni: 
+ Se un token non scaduto è già disponibile, la chiamata lo restituisce immediatamente.
+ In caso contrario, la chiamata recupera un nuovo token dal fornitore del token e attende il completamento del flusso di lavoro di acquisizione del token fino a 2 secondi prima che scada il timeout. Se l'operazione scade, viene generato un errore, che deve essere gestito dal codice di chiamata. 

L'`getToken`operazione è accompagnata da un'`hasToken`operazione che indica se il `aws-waf-token` cookie contiene attualmente un token non scaduto. 

`AwsWafIntegration.getToken()`recupera un token valido e lo memorizza come cookie. La maggior parte delle chiamate client allega automaticamente questo cookie, ma alcune no. Ad esempio, le chiamate effettuate tra domini host non allegano il cookie. Nei dettagli di implementazione che seguono, mostriamo come lavorare con entrambi i tipi di chiamate client. 

**`getToken`Implementazione di base, per le chiamate che allegano il `aws-waf-token` cookie**  
L'elenco di esempio seguente mostra il codice standard per l'implementazione dell'`getToken`operazione con una richiesta di accesso.

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

**Invia il modulo solo dopo che il token è disponibile da `getToken`**  
L'elenco seguente mostra come registrare un listener di eventi per intercettare gli invii di moduli fino a quando non sarà disponibile un token valido per l'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>
```

**Allegare il token quando il client non allega il cookie per impostazione predefinita `aws-waf-token`**  
`AwsWafIntegration.getToken()`recupera un token valido e lo memorizza come cookie, ma non tutte le chiamate client associano questo cookie per impostazione predefinita. Ad esempio, le chiamate effettuate tra domini host non allegano il cookie. 

Il `fetch` wrapper gestisce questi casi automaticamente, ma se non riesci a utilizzare il `fetch` wrapper, puoi gestirlo utilizzando un'intestazione personalizzata. `x-aws-waf-token` AWS WAF legge i token da questa intestazione, oltre a leggerli dal cookie. `aws-waf-token` Il codice seguente mostra un esempio di impostazione dell'intestazione. 

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

Per impostazione predefinita, accetta AWS WAF solo token che contengono lo stesso dominio del dominio host richiesto. Qualsiasi token interdominio richiede le voci corrispondenti nell'elenco dei domini del token Protection Pack (Web ACL). Per ulteriori informazioni, consulta [AWS WAF configurazione dell'elenco di domini con token protection pack (Web ACL)](waf-tokens-domains.md#waf-tokens-domain-lists). 

[Per ulteriori informazioni sull'uso dei token tra domini, consulta aws-samples/ -. aws-waf-bot-control api-protection-with-captcha](https://github.com/aws-samples/aws-waf-bot-control-api-protection-with-captcha)

# Utilizzo dell'API CAPTCHA JavaScript
<a name="waf-js-captcha-api"></a>

Questa sezione fornisce istruzioni per l'utilizzo dell'API di integrazione CAPTCHA.

L' JavaScript API CAPTCHA ti consente di configurare il puzzle CAPTCHA e posizionarlo dove vuoi nell'applicazione client. Questa API sfrutta le funzionalità della minaccia intelligente JavaScript APIs per acquisire e utilizzare i AWS WAF token dopo che un utente finale ha completato con successo un puzzle CAPTCHA. 

Implementa l' JavaScript integrazione prima in un ambiente di test, poi in produzione. Per ulteriori indicazioni sulla codifica, consulta le sezioni seguenti. 

**Per utilizzare l'API di integrazione CAPTCHA**

1. **Installa l'API**

   1. Accedi a Console di gestione AWS e apri la AWS WAF console all'indirizzo [https://console.aws.amazon.com/wafv2/homev2](https://console.aws.amazon.com/wafv2/homev2). 

   1. Nel riquadro di navigazione, scegliere **Application integration (Integrazione di applicazioni)**. Nella pagina di **integrazione dell'applicazione**, puoi vedere le opzioni a schede. 

   1. Seleziona Integrazione **CAPTCHA**.

   1. Copia il tag dello script di JavaScript integrazione elencato per utilizzarlo nella tua integrazione.

   1. Nel codice della pagina dell'applicazione, nella `<head>` sezione, inserisci il tag script che hai copiato. Questa inclusione rende il puzzle CAPTCHA disponibile per la configurazione e l'uso. 

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

      Questo `<script>` elenco è configurato con l'`defer`attributo, ma puoi modificare l'impostazione `async` se desideri un comportamento diverso per la tua pagina. 

      Lo script CAPTCHA carica automaticamente anche lo script di integrazione intelligente delle minacce se non è già presente. Lo script di integrazione intelligente delle minacce consente all'applicazione client di recuperare automaticamente un token in background al caricamento della pagina e fornisce altre funzionalità di gestione dei token necessarie per l'utilizzo dell'API CAPTCHA. 

1. **(Facoltativo) Aggiungi la configurazione del dominio per i token del client**: per impostazione predefinita, quando AWS WAF crea un token, utilizza il dominio host della risorsa associata al protection pack (Web ACL). Per fornire domini aggiuntivi per il JavaScript APIs, segui le istruzioni all'indirizzo. [Fornire domini da utilizzare nei token](waf-js-challenge-api-set-token-domain.md) 

1. **Ottieni la chiave API crittografata per il client**: l'API CAPTCHA richiede una chiave API crittografata che contenga un elenco di domini client validi. AWS WAF utilizza questa chiave per verificare che il dominio client che stai utilizzando con l'integrazione sia approvato per l'uso di CAPTCHA. AWS WAF Per generare la tua chiave API, segui le istruzioni all'indirizzo. [Gestione delle chiavi API per l'API JS CAPTCHA](waf-js-captcha-api-key.md)

1. **Codifica l'implementazione del widget CAPTCHA**: implementa la chiamata `renderCaptcha()` API nella tua pagina, nel luogo in cui desideri utilizzarla. Per informazioni sulla configurazione e l'uso di questa funzione, consulta le seguenti sezioni e. [Specifiche dell'API CAPTCHA JavaScript](waf-js-captcha-api-specification.md) [Come renderizzare il puzzle CAPTCHA](waf-js-captcha-api-render.md) 

   L'implementazione CAPTCHA si integra con l'integrazione intelligente delle minacce per la gestione dei token e APIs per l'esecuzione di chiamate di recupero che utilizzano i token. AWS WAF Per indicazioni sull'utilizzo di questi, consulta. APIs [Utilizzo dell' JavaScript API per le minacce intelligenti](waf-js-challenge-api.md)

1. **Aggiungi la verifica tramite token nel tuo pacchetto di protezione (Web ACL)**: aggiungi almeno una regola al tuo pacchetto di protezione (Web ACL) per verificare la presenza di un token CAPTCHA valido nelle richieste Web inviate dal client. È possibile utilizzare l'azione della CAPTCHA regola per verificare, come descritto in. [CAPTCHAe Challenge in AWS WAF](waf-captcha-and-challenge.md) 

   Le aggiunte al pacchetto di protezione (Web ACL) verificano che le richieste che arrivano agli endpoint protetti includano il token che hai acquisito nell'integrazione del client. Le richieste che includono un token CAPTCHA valido e non scaduto superano l'ispezione delle CAPTCHA regole e non presentano all'utente finale un altro puzzle CAPTCHA. 

Dopo aver implementato l' JavaScript API, puoi esaminare le CloudWatch metriche relative ai tentativi e alle soluzioni dei puzzle CAPTCHA. Per i dettagli sulle metriche e sulle dimensioni, consulta. [Metriche e dimensioni dell'account](waf-metrics.md#waf-metrics-account)

**Topics**
+ [Specifiche dell'API CAPTCHA JavaScript](waf-js-captcha-api-specification.md)
+ [Come renderizzare il puzzle CAPTCHA](waf-js-captcha-api-render.md)
+ [Gestione di una risposta CAPTCHA da AWS WAF](waf-js-captcha-api-conditional.md)
+ [Gestione delle chiavi API per l'API JS CAPTCHA](waf-js-captcha-api-key.md)

# Specifiche dell'API CAPTCHA JavaScript
<a name="waf-js-captcha-api-specification"></a>

Questa sezione elenca le specifiche dei metodi e delle proprietà del CAPTCHA. JavaScript APIs Usa il CAPTCHA JavaScript APIs per eseguire puzzle CAPTCHA personalizzati nelle tue applicazioni client. 

Questa API si basa sulla minaccia intelligente APIs, che utilizzi per configurare e gestire l'acquisizione e l'utilizzo dei token. AWS WAF Vedi[Specifiche dell'API per le minacce intelligenti](waf-js-challenge-api-specification.md).

**`AwsWafCaptcha.renderCaptcha(container, configuration)`**  
Presenta un puzzle AWS WAF CAPTCHA all'utente finale e, in caso di successo, aggiorna il token client con la convalida CAPTCHA. Questo è disponibile solo con l'integrazione CAPTCHA. Utilizzate questa chiamata insieme alla minaccia intelligente APIs per gestire il recupero dei token e fornire il token nelle chiamate. `fetch` Vedi la minaccia APIs intelligente su. [Specifiche dell'API per le minacce intelligenti](waf-js-challenge-api-specification.md)  
A differenza del CAPTCHA interstitial che AWS WAF invia, il puzzle CAPTCHA reso con questo metodo visualizza il puzzle immediatamente, senza una schermata iniziale del titolo.     
**`container`**  
L'`Element`oggetto per l'elemento contenitore di destinazione sulla pagina. Questo viene in genere recuperato chiamando `document.getElementById()` o`document.querySelector()`.  
Obbligatorio: sì  
Tipo: `Element`  
**configurazione**  
Un oggetto contenente le impostazioni di configurazione CAPTCHA, come segue: ****    
**`apiKey`**   
La chiave API crittografata che abilita le autorizzazioni per il dominio del client. Usa la AWS WAF console per generare le tue chiavi API per i domini dei tuoi clienti. Puoi utilizzare una chiave per un massimo di cinque domini. Per informazioni, consulta [Gestione delle chiavi API per l'API JS CAPTCHA](waf-js-captcha-api-key.md).   
Obbligatorio: sì  
Tipo: `string`  
**`onSuccess: (wafToken: string) => void;`**   
Chiamato con un AWS WAF token valido quando l'utente finale completa con successo un puzzle CAPTCHA. Utilizza il token nelle richieste inviate agli endpoint che proteggi con un pacchetto di AWS WAF protezione (Web ACL). Il token fornisce la prova e l'ora dell'ultimo completamento riuscito del puzzle.   
Obbligatorio: sì  
**`onError?: (error: CaptchaError) => void;`**   
Chiamato con un oggetto error quando si verifica un errore durante l'operazione CAPTCHA.   
Obbligatorio: no  
**`CaptchaError`definizione della classe** — Il `onError` gestore fornisce un tipo di errore con la seguente definizione di classe.   

```
CaptchaError extends Error {
    kind: "internal_error" | "network_error" | "token_error" | "client_error";
    statusCode?: number;
}
```
+ `kind`— Il tipo di errore restituito. 
+ `statusCode`— Il codice di stato HTTP, se disponibile. Viene utilizzato da `network_error` se l'errore è dovuto a un errore HTTP.  
**`onLoad?: () => void;`**   
Chiamato quando viene caricato un nuovo puzzle CAPTCHA.  
Obbligatorio: no  
**`onPuzzleTimeout?: () => void;`**   
Chiamato quando un puzzle CAPTCHA non viene completato prima della scadenza.  
Obbligatorio: no  
**`onPuzzleCorrect?: () => void;`**   
Chiamato quando viene fornita una risposta corretta a un puzzle CAPTCHA.  
Obbligatorio: no  
**`onPuzzleIncorrect?: () => void;`**   
Chiamato quando viene fornita una risposta errata a un puzzle CAPTCHA.  
Obbligatorio: no  
**`defaultLocale`**   
La localizzazione predefinita da usare per il puzzle CAPTCHA. Le istruzioni scritte per i puzzle CAPTCHA sono disponibili in arabo (ar-SA), cinese semplificato (zh-CN), olandese (nl-NL), inglese (en-US), francese (fr-FR), tedesco (de-DE), italiano (it-IT), giapponese (ja-JP), portoghese brasiliano (pt-BR), spagnolo (es-ES) e turco (tr-TR). Le istruzioni audio sono disponibili per tutte le lingue scritte tranne il cinese e il giapponese, che per impostazione predefinita è l'inglese. Per cambiare la lingua predefinita, fornisci la lingua internazionale e il codice locale, ad esempio`ar-SA`.  
Predefinita: la lingua attualmente in uso nel browser dell'utente finale  
Obbligatorio: no  
Tipo: `string`  
**`disableLanguageSelector`**   
Se impostato su`true`, il puzzle CAPTCHA nasconde il selettore della lingua.   
Impostazione predefinita: `false`  
Obbligatorio: no  
Tipo: `boolean`  
**`dynamicWidth`**   
Se impostato su`true`, il puzzle CAPTCHA cambia larghezza per compatibilità con la larghezza della finestra del browser.   
Impostazione predefinita: `false`  
Obbligatorio: no  
Tipo: `boolean`  
**`skipTitle`**   
**Se impostato su`true`, il puzzle CAPTCHA non visualizza il titolo del puzzle Risolvi il puzzle.**   
Impostazione predefinita: `false`  
Obbligatorio: no  
Tipo: `boolean`

# Come renderizzare il puzzle CAPTCHA
<a name="waf-js-captcha-api-render"></a>

Questa sezione fornisce un esempio `renderCaptcha` di implementazione.

È possibile utilizzare la AWS WAF `renderCaptcha` chiamata dove si desidera nell'interfaccia client. La chiamata recupera un puzzle CAPTCHA da AWS WAF, lo esegue il rendering e invia i risultati per la verifica. AWS WAF Quando effettui la chiamata, fornisci la configurazione di rendering del puzzle e i callback che desideri eseguire quando gli utenti finali completano il puzzle. Per informazioni dettagliate sulle opzioni, consultate la sezione precedente,. [Specifiche dell'API CAPTCHA JavaScript](waf-js-captcha-api-specification.md)

Utilizzate questa chiamata insieme alla funzionalità di gestione dei token dell'integrazione intelligente delle minacce. APIs Questa chiamata fornisce al cliente un token che verifica il completamento con successo del puzzle CAPTCHA. Utilizzate l'integrazione intelligente delle minacce APIs per gestire il token e per fornire il token nelle chiamate del cliente agli endpoint protetti con pacchetti di AWS WAF protezione (web). ACLs Per informazioni sulla minaccia intelligente APIs, consulta[Utilizzo dell' JavaScript API per le minacce intelligenti](waf-js-challenge-api.md).

**Implementazione di esempio**  
L'elenco di esempio seguente mostra un'implementazione CAPTCHA standard, incluso il posizionamento dell'URL di AWS WAF integrazione nella `<head>` sezione. 

Questo elenco configura la `renderCaptcha` funzione con un callback di successo che utilizza il `AwsWafIntegration.fetch` wrapper dell'integrazione intelligente delle minacce. APIs Per informazioni su questa funzione, vedere. [Come usare il `fetch` wrapper di integrazione](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>
```

**Impostazioni di configurazione di esempio**  
L'elenco di esempio seguente mostra le opzioni `renderCaptcha` con impostazioni non predefinite per la larghezza e il titolo. 

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

Per informazioni complete sulle opzioni di configurazione, vedere[Specifiche dell'API CAPTCHA JavaScript](waf-js-captcha-api-specification.md).

# Gestione di una risposta CAPTCHA da AWS WAF
<a name="waf-js-captcha-api-conditional"></a>

Questa sezione fornisce un esempio di gestione di una risposta CAPTCHA.

Una AWS WAF regola con un'CAPTCHAazione termina la valutazione di una richiesta web corrispondente se la richiesta non ha un token con un timestamp CAPTCHA valido. Se la richiesta è una `GET` text/html chiamata, l'CAPTCHAazione invia al client un messaggio interstiziale con un puzzle CAPTCHA. Quando non integri l' JavaScript API CAPTCHA, l'interstitial esegue il puzzle e, se l'utente finale lo risolve con successo, invia nuovamente la richiesta automaticamente. 

Quando integri l' JavaScript API CAPTCHA e personalizzi la gestione del CAPTCHA, devi rilevare la risposta CAPTCHA di terminazione, fornire il CAPTCHA personalizzato e, se l'utente finale risolve con successo il puzzle, inviare nuovamente la richiesta web del cliente. 

L'esempio di codice seguente mostra come eseguire tale operazione. 

**Nota**  
La risposta AWS WAF CAPTCHA all'azione ha un codice di stato HTTP 405, che utilizziamo per riconoscere la risposta in questo codice. CAPTCHA Se l'endpoint protetto utilizza un codice di stato HTTP 405 per comunicare qualsiasi altro tipo di risposta per la stessa chiamata, questo codice di esempio genererà anche un puzzle CAPTCHA per quelle risposte. 

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

# Gestione delle chiavi API per l'API JS CAPTCHA
<a name="waf-js-captcha-api-key"></a>

Questa sezione fornisce istruzioni per la generazione e l'eliminazione delle chiavi API.

Per integrare AWS WAF CAPTCHA in un'applicazione client con l' JavaScript API, sono necessari il tag di integrazione JavaScript API e la chiave API crittografata per il dominio client in cui desideri eseguire il puzzle CAPTCHA. 

L'integrazione dell'applicazione CAPTCHA JavaScript utilizza le chiavi API crittografate per verificare che il dominio dell'applicazione client sia autorizzato a utilizzare l'API CAPTCHA. AWS WAF Quando richiami l'API CAPTCHA dal tuo JavaScript client, fornisci una chiave API con un elenco di domini che include un dominio per il client corrente. Puoi elencare fino a 5 domini in un'unica chiave crittografata. 

**Requisiti delle chiavi API**  
La chiave API che utilizzi nell'integrazione CAPTCHA deve contenere un dominio applicabile al client in cui utilizzi la chiave. 
+ Se specifichi una `window.awsWafCookieDomainList` nell'integrazione intelligente delle minacce del tuo client, almeno un dominio nella tua chiave API deve corrispondere esattamente a uno dei domini token in `window.awsWafCookieDomainList` o deve essere il dominio apex di uno di quei domini token. 

  Ad esempio, per il dominio token`mySubdomain.myApex.com`, la chiave `mySubdomain.myApex.com` API corrisponde esattamente e la chiave API `myApex.com` è il dominio apex. Entrambe le chiavi corrispondono al dominio del token. 

  Per informazioni sull'impostazione dell'elenco dei domini dei token, vedere[Fornire domini da utilizzare nei token](waf-js-challenge-api-set-token-domain.md).
+ Altrimenti, il dominio corrente deve essere contenuto nella chiave API. Il dominio corrente è il dominio che puoi vedere nella barra degli indirizzi del browser. 

I domini che utilizzi devono essere accettati, in base al dominio host protetto e all'elenco di domini token configurato per l'ACL web. AWS WAF Per ulteriori informazioni, consulta [AWS WAF configurazione dell'elenco di domini con token protection pack (Web ACL)](waf-tokens-domains.md#waf-tokens-domain-lists).

**Come scegliere la regione per la tua chiave API**  
AWS WAF può generare chiavi API CAPTCHA in qualsiasi regione in cui AWS WAF sia disponibile. 

Come regola generale, è necessario utilizzare la stessa regione per la chiave API CAPTCHA utilizzata per il pacchetto di protezione (Web ACL). Se ti aspetti un pubblico globale per un pacchetto di protezione regionale (ACL web), tuttavia, puoi ottenere un tag di JavaScript integrazione CAPTCHA con ambito e una chiave API con ambito a CloudFront, CloudFront e utilizzarli con un pacchetto di protezione regionale (ACL web). Questo approccio consente ai clienti di caricare un puzzle CAPTCHA dalla regione più vicina a loro, il che riduce la latenza. 

Le chiavi API CAPTCHA destinate a regioni diverse da quelle non CloudFront sono supportate per l'uso in più regioni. Possono essere utilizzate solo nella regione a cui sono destinate. 

**Per generare una chiave API per i domini dei tuoi clienti**  
Per ottenere l'URL di integrazione e generare e recuperare le chiavi API tramite la console. 

1. Accedi a Console di gestione AWS e apri la AWS WAF console all'indirizzo [https://console.aws.amazon.com/wafv2/homev2](https://console.aws.amazon.com/wafv2/homev2). 

1. Nel riquadro di navigazione, scegliere **Application integration (Integrazione di applicazioni)**. 

1. Nel riquadro, contenente i **protection pack (web ACLs) abilitati per l'integrazione delle applicazioni**, seleziona la regione che desideri utilizzare per la tua chiave API. Puoi anche selezionare la regione nel riquadro delle **chiavi API** della scheda di **integrazione CAPTCHA**.

1. Scegli la scheda Integrazione **CAPTCHA**. Questa scheda fornisce il tag di JavaScript integrazione CAPTCHA, che puoi utilizzare nella tua integrazione, e l'elenco delle chiavi API. Entrambi si riferiscono alla regione selezionata.

1. Nel riquadro **Chiavi API**, scegli **Genera chiave**. Viene visualizzata la finestra di dialogo per la generazione delle chiavi. 

1. Inserisci i domini client che desideri includere nella chiave. Puoi inserire fino a 5. Quando hai finito, scegli **Genera chiave**. L'interfaccia torna alla scheda di integrazione CAPTCHA, dove è elencata la tua nuova chiave. 

   Una volta creata, una chiave API è immutabile. Se devi apportare modifiche a una chiave, genera una nuova chiave e usala al suo posto. 

1. (Facoltativo) Copia la chiave appena generata per utilizzarla nella tua integrazione. 

Puoi anche usare il REST APIs o uno dei linguaggi specifici AWS SDKs per questo lavoro. [Le chiamate API REST sono [APIKeyCreate](https://docs.aws.amazon.com/waf/latest/APIReference/API_CreateAPIKey.html) e List. APIKeys](https://docs.aws.amazon.com/waf/latest/APIReference/API_ListAPIKeys.html) 

**Come eliminare una chiave API**  
Per eliminare una chiave API, è necessario utilizzare l'API REST o una delle lingue specifiche AWS SDKs. La chiamata all'API REST è [Delete APIKey](https://docs.aws.amazon.com/waf/latest/APIReference/API_DeleteAPIKey.html). Non puoi utilizzare la console per eliminare una chiave. 

Dopo aver eliminato una chiave, possono essere necessarie fino a 24 ore prima che non AWS WAF venga consentita l'utilizzo della chiave in tutte le aree geografiche. 

# AWS WAF integrazione di applicazioni mobili
<a name="waf-mobile-sdk"></a>

Questa sezione introduce l'argomento dell'utilizzo dei AWS WAF dispositivi mobili SDKs per implementare l'integrazione AWS WAF intelligente delle minacce SDKs per app mobili e TV Android e iOS. Per quanto riguarda le app TV, SDKs sono compatibili con le principali piattaforme di smart TV, tra cui Android TV e Apple TV.
+ Per le app Android per dispositivi mobili e TV, SDKs funziona per l'API Android versione 23 (Android versione 6) e successive. Per informazioni sulle versioni di Android, consulta le [note di rilascio della piattaforma SDK](https://developer.android.com/tools/releases/platforms).
+ Per le app mobili iOS, SDKs funziona per iOS versione 13 e successive. Per informazioni sulle versioni di iOS, consulta le [note di rilascio di iOS e iPadOS](https://developer.apple.com/documentation/ios-ipados-release-notes).
+ Per le app Apple TV, SDKs funzionano con la versione 14 o successiva di tvOS. Per informazioni sulle versioni di tvOS, consulta le note di rilascio di [tvOS](https://developer.apple.com/documentation/tvos-release-notes).

Con l' AWS WAF SDK per dispositivi mobili, puoi gestire l'autorizzazione dei token e includerli nelle richieste inviate alle tue risorse protette. Utilizzando SDKs, ti assicuri che queste chiamate di procedura remota effettuate dal tuo client contengano un token valido. Inoltre, quando questa integrazione è attiva nelle pagine dell'applicazione, è possibile implementare regole di mitigazione nel pacchetto di protezione (Web ACL), come il blocco delle richieste che non contengono un token valido.

[Per accedere al cellulare SDKs, contatta l'assistenza all'indirizzo Contact. AWS](https://aws.amazon.com/contact-us)

**Nota**  
Il AWS WAF cellulare SDKs non è disponibile per la personalizzazione del CAPTCHA.

L'approccio di base per l'utilizzo dell'SDK consiste nel creare un provider di token utilizzando un oggetto di configurazione, quindi utilizzare il provider di token da cui recuperare i token. AWS WAF Per impostazione predefinita, il provider di token include i token recuperati nelle richieste web alla risorsa protetta. 

Di seguito è riportato un elenco parziale di un'implementazione SDK, che mostra i componenti principali. Per esempi più dettagliati, consulta [Esempi di codice per l'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();
```

------

# Installazione dell'SDK AWS WAF per dispositivi mobili
<a name="waf-mobile-sdk-installing"></a>

Questa sezione fornisce istruzioni per l'installazione dell'SDK per AWS WAF dispositivi mobili.

Per accedere al cellulare SDKs, contatta l'assistenza all'indirizzo [Contact AWS](https://aws.amazon.com/contact-us).

Implementa l'SDK mobile prima in un ambiente di test, poi in produzione.

**Per installare l'SDK AWS WAF mobile**

1. Accedi a Console di gestione AWS e apri la AWS WAF console all'indirizzo [https://console.aws.amazon.com/wafv2/homev2](https://console.aws.amazon.com/wafv2/homev2). 

1. Nel riquadro di navigazione, scegliere **Application integration (Integrazione di applicazioni)**. 

1. Nella scheda **Integrazioni intelligenti contro le minacce**, procedi come segue: 

   1. Nel riquadro **Protection Pack (web ACLs) abilitati per l'integrazione delle applicazioni**, individua il pacchetto di protezione (Web ACL) con cui stai effettuando l'integrazione. Copia e salva l'URL di integrazione del Protection Pack (Web ACL) per utilizzarlo nell'implementazione. È inoltre possibile ottenere questo URL tramite la chiamata `GetWebACL` API.

   1. Scegli il tipo e la versione del dispositivo mobile, quindi scegli **Scarica**. Puoi scegliere la versione che preferisci, ma ti consigliamo di utilizzare la versione più recente. AWS WAF scarica il `zip` file per il tuo dispositivo nella posizione di download standard.

1. Nell'ambiente di sviluppo dell'app, decomprimi il file in una posizione di lavoro a tua scelta. Nella directory di primo livello del file zip, individua e apri il. `README` Segui le istruzioni contenute nel `README` file per installare l'SDK per AWS WAF dispositivi mobili da utilizzare nel codice dell'app per dispositivi mobili. 

1. Programma la tua app in base alle indicazioni riportate nelle sezioni seguenti.

# AWS WAF specifiche SDK per dispositivi mobili
<a name="waf-mobile-sdk-specification"></a>

Questa sezione elenca gli oggetti SDK, le operazioni e le impostazioni di configurazione per l'ultima versione disponibile dell'SDK AWS WAF mobile. Per informazioni dettagliate su come funzionano il provider di token e le operazioni per le varie combinazioni di impostazioni di configurazione, consulta. [Come funziona l'SDK AWS WAF per dispositivi mobili](waf-mobile-sdk-how-it-works.md) 

**`WAFToken`**  
Detiene un AWS WAF token.    
**`getValue()`**  
Recupera la `String` rappresentazione di. `WAFToken` 

**`WAFTokenProvider`**  
Gestisce i token nella tua app mobile. Implementalo usando un `WAFConfiguration` oggetto.    
**`getToken()`**  
Se l'aggiornamento in background è abilitato, restituisce il token memorizzato nella cache. Se l'aggiornamento in background è disabilitato, viene effettuata una chiamata sincrona e bloccante AWS WAF a per recuperare un nuovo token.   
**`loadTokenIntoProvider(WAFToken)`**  
Carica il token specificato in`WAFTokenProvider`, sostituendo qualsiasi token gestito dal provider. Il fornitore di token assume la proprietà del nuovo token e ne gestisce l'aggiornamento in futuro. Questa operazione aggiorna anche il token nel cookie store, se `setTokenCookie` abilitata in. `WAFConfiguration`  
**`onTokenReady(WAFTokenResultCallback)`**  
Indica al fornitore del token di aggiornare il token e di richiamare il callback fornito quando un token attivo è pronto. Il fornitore del token invocherà il callback in un thread in background quando il token è memorizzato nella cache e pronto. Chiamalo quando l'app viene caricata per la prima volta e anche quando torna allo stato attivo. Per ulteriori informazioni sul ritorno a uno stato attivo, consulta[Recupero di un token dopo l'inattività dell'app](waf-mobile-sdk-how-it-works.md#waf-mobile-sdk-how-back-from-inactive).   
Per le app Android o iOS, puoi `WAFTokenResultCallback` impostare l'operazione che desideri venga richiamata dal provider del token quando un token richiesto è pronto. La tua implementazione di `WAFTokenResultCallback` deve accettare i parametri`WAFToken`,`SdkError`. Per le app iOS, puoi creare alternativamente una funzione in linea.   
**`storeTokenInCookieStorage(WAFToken)`**  
Indica `WAFTokenProvider` a memorizzare il AWS WAF token specificato nel gestore dei cookie dell'SDK. Per impostazione predefinita, il token viene aggiunto all'archivio dei cookie solo quando viene acquisito per la prima volta e quando viene aggiornato. Se l'applicazione cancella l'archivio di cookie condiviso per qualsiasi motivo, l'SDK non aggiunge automaticamente il AWS WAF token fino al prossimo aggiornamento. 

**`WAFConfiguration`**  
Contiene la configurazione per l'implementazione di. `WAFTokenProvider` Quando lo implementate, fornite l'URL di integrazione del pacchetto di protezione (Web ACL), il nome di dominio da utilizzare nel token e tutte le impostazioni non predefinite che desiderate che il provider del token utilizzi.   
L'elenco seguente specifica le impostazioni di configurazione che è possibile gestire nell'oggetto. `WAFConfiguration`    
**`applicationIntegrationUrl`**   
L'URL di integrazione dell'applicazione. Scaricalo dalla AWS WAF console o tramite la chiamata `getWebACL` API.  
Obbligatorio: sì  
Tipo: URL specifico dell'app. Per iOS, vedi [URL iOS](https://developer.apple.com/documentation/foundation/url). Per Android, vedi l'URL [java.net.](https://docs.oracle.com/javase/7/docs/api/java/net/URL.html)   
**`backgroundRefreshEnabled`**   
Indica se desideri che il fornitore del token aggiorni il token in background. Se si imposta questa impostazione, il provider di token aggiorna i token in background in base alle impostazioni di configurazione che regolano le attività di aggiornamento automatico dei token.   
Obbligatorio: no  
Tipo: `Boolean`  
Valore predefinito: `TRUE`  
**`domainName`**   
Il dominio da utilizzare nel token, utilizzato per l'acquisizione dei token e l'archiviazione dei cookie. Ad esempio `example.com` o `aws.amazon.com`. Di solito si tratta del dominio host della risorsa associato al pacchetto di protezione (web ACL), a cui invierai le richieste web. Per il gruppo di regole gestito ACFP`AWSManagedRulesACFPRuleSet`, in genere si tratta di un singolo dominio che corrisponde al dominio nel percorso di creazione dell'account fornito nella configurazione del gruppo di regole. Per il gruppo di regole gestito ATP`AWSManagedRulesATPRuleSet`, in genere si tratta di un singolo dominio che corrisponde al dominio nel percorso di accesso fornito nella configurazione del gruppo di regole.   
I suffissi pubblici non sono consentiti. Ad esempio, non puoi usare `gov.au` or `co.uk` come dominio del token.  
Il dominio deve essere accettato, in base al dominio host protetto e all'elenco di domini token del Protection Pack (Web ACL). AWS WAF Per ulteriori informazioni, consulta [AWS WAF configurazione dell'elenco di domini con token protection pack (Web ACL)](waf-tokens-domains.md#waf-tokens-domain-lists).  
Obbligatorio: sì  
Tipo: `String`   
**`maxErrorTokenRefreshDelayMsec`**   
Il tempo massimo di attesa in millisecondi prima di ripetere un aggiornamento del token dopo un tentativo fallito. Per ogni tentativo automatico per un tentativo fallito, aggiungerà un backup esponenziale fino al tempo di ritardo di input specificato. Questo valore viene utilizzato dopo che il recupero del token non è riuscito ed è stato ripetuto più volte. `maxRetryCount`   
Obbligatorio: no  
Tipo: `Integer`  
Valore predefinito: `5000` (5 secondi)  
Valore minimo consentito: `1` (1 millisecondo)  
Valore massimo consentito: `30000` (30 secondi)  
**`maxRetryCount`**   
Il numero massimo di tentativi da eseguire con backoff esponenziale quando viene richiesto un token.   
Obbligatorio: no  
Tipo: `Integer`  
Valore predefinito: `Infinity`  
Valore minimo consentito: `0`  
Valore massimo consentito: `100`  
**`setTokenCookie`**   
Indica se desideri che il gestore dei cookie dell'SDK aggiunga un cookie token nelle richieste e in altre aree.   
Con un `TRUE` valore:   
+ Il gestore dei cookie aggiunge un cookie token a tutte le richieste il cui percorso si trova nel percorso specificato in`tokenCookiePath`. 
+ L'`WAFTokenProvider`operazione `loadTokenIntoProvider()` aggiorna il token nell'archivio dei cookie, oltre a caricarlo nel fornitore del token.
Obbligatorio: no  
Tipo: `Boolean`  
Valore predefinito: `TRUE`  
**`tokenCookiePath`**   
Usato quando `setTokenCookie` è`TRUE`. Indica il percorso di primo livello in cui desideri che il gestore dei cookie dell'SDK aggiunga un cookie token. Il gestore aggiunge un cookie token a tutte le richieste inviate a questo percorso e a tutti i percorsi secondari.   
Ad esempio, se lo imposti su`/web/login`, il gestore include il cookie token per tutto ciò che viene inviato `/web/login` e per tutti i relativi percorsi secondari, ad esempio`/web/login/help`. Non include il token per le richieste inviate ad altri percorsi, come `/``/web`, o`/web/order`.   
Obbligatorio: no  
Tipo: `String`  
Valore predefinito: `/`  
**`tokenRefreshDelaySec`**   
Utilizzato per l'aggiornamento dello sfondo. La quantità massima di tempo in secondi tra gli aggiornamenti dei token in background.  
Obbligatorio: no  
Tipo: `Integer`  
Valore predefinito: `88`  
Valore minimo consentito: `88`  
Valore massimo consentito: `300` (5 minuti)

## AWS WAF errori SDK per dispositivi mobili
<a name="waf-mobile-sdk-errors"></a>

Questa sezione elenca i possibili errori per la AWS WAF versione corrente dell'SDK per dispositivi mobili.

**`SdkError`**  
Il tipo di errore restituito quando non si riesce a recuperare un token. L'SDK per Android e iOS presenta gli stessi tipi di errore.  
L'SDK AWS WAF per dispositivi mobili presenta i seguenti tipi di errore:    
**`invalidChallenge`**  
Questo errore viene restituito quando il token server restituisce dati di sfida non validi o il blob di risposta viene modificato da un utente malintenzionato.  
**`errorInvokingGetChallengeEndpoint`**  
Questo errore viene restituito quando il token server invia al client un codice di risposta non riuscito o quando si verifica un errore di rete.  
**`invalidVerifyChallengeResponse`**  
Questo errore viene restituito quando si verifica un errore durante il `aws-waf-token` recupero della risposta di verifica del AWS WAF server o se la risposta del server è stata manomessa.  
**`errorInvokingVerifyEndpoint`**  
Questo errore viene restituito quando il client riceve una risposta errata dal AWS WAF server o un errore di rete durante la verifica della sfida risolta.  
**`internalError`**  
Questo errore viene restituito per tutti gli altri errori che potrebbero verificarsi all'interno dell'SDK stesso.

**`socketTimeoutException`**  
Questo errore viene spesso restituito quando si verificano errori di rete durante il recupero del token.  
Questo errore potrebbe essere causato da quanto segue:  
+ Larghezza di banda di rete ridotta: conferma le impostazioni di connettività di rete
+ URL di integrazione dell'applicazione mutato: verifica che l'URL di integrazione non sia stato modificato rispetto a quanto visualizzato sulla console AWS WAF 

# Come funziona l'SDK AWS WAF per dispositivi mobili
<a name="waf-mobile-sdk-how-it-works"></a>

Questa sezione spiega come interagiscono le classi, le proprietà e le operazioni dell'SDK AWS WAF mobile.

Il dispositivo mobile SDKs offre un provider di token configurabile che è possibile utilizzare per il recupero e l'utilizzo dei token. Il fornitore di token verifica che le richieste consentite provengano da clienti legittimi. Quando invii richieste alle AWS risorse con cui proteggi AWS WAF, includi il token in un cookie per convalidare la richiesta. Puoi gestire il cookie del token manualmente o lasciare che sia il fornitore del token a farlo per te.

Questa sezione tratta le interazioni tra le classi, le proprietà e i metodi inclusi nell'SDK per dispositivi mobili. Per le specifiche SDK, consulta. [AWS WAF specifiche SDK per dispositivi mobili](waf-mobile-sdk-specification.md) 

## Recupero e memorizzazione nella cache dei token
<a name="waf-mobile-sdk-how-token-basics"></a>

Quando crei l'istanza del fornitore di token nella tua app per dispositivi mobili, configuri come desideri che gestisca i token e il recupero dei token. La tua scelta principale è come mantenere i token validi e non scaduti da utilizzare nelle richieste web dell'app:
+ **Aggiornamento in background abilitato**: questa è l'impostazione predefinita. Il provider del token aggiorna automaticamente il token in background e lo memorizza nella cache. Con l'aggiornamento in background abilitato, quando si chiama`getToken()`, l'operazione recupera il token memorizzato nella cache. 

  Il provider del token esegue l'aggiornamento del token a intervalli configurabili, in modo che un token non scaduto sia sempre disponibile nella cache mentre l'applicazione è attiva. L'aggiornamento in background viene sospeso mentre l'applicazione è in uno stato inattivo. Per informazioni su questo argomento, vedere. [Recupero di un token dopo l'inattività dell'app](#waf-mobile-sdk-how-back-from-inactive)
+ **Aggiornamento in background disabilitato**: è possibile disabilitare l'aggiornamento dei token in background e quindi recuperare i token solo su richiesta. I token recuperati su richiesta non vengono memorizzati nella cache e, se lo desideri, puoi recuperarne più di uno. Ogni token è indipendente dagli altri che recuperi e ognuno ha il proprio timestamp che viene utilizzato per calcolare la scadenza.

  Hai le seguenti scelte per il recupero dei token quando l'aggiornamento in background è disabilitato: 
  + **`getToken()`**— Quando si chiama `getToken()` con l'aggiornamento in background disabilitato, la chiamata recupera in modo sincrono un nuovo token da. AWS WAF Si tratta di una chiamata potenzialmente bloccante che potrebbe influire sulla reattività dell'app se viene richiamata nel thread principale. 
  + **`onTokenReady(WAFTokenResultCallback)`**— Questa chiamata recupera in modo asincrono un nuovo token e quindi richiama il callback dei risultati fornito in un thread in background quando un token è pronto. 

### In che modo il fornitore del token tenta di ripetere i recuperi di token non riusciti
<a name="waf-mobile-sdk-how-token-retrieval-retries"></a>

Il fornitore di token riprova automaticamente il recupero del token quando il recupero fallisce. I nuovi tentativi vengono inizialmente eseguiti utilizzando il backoff esponenziale con un tempo di attesa iniziale di 100 ms. [Per informazioni sui tentativi esponenziali, vedere Tentativi di errore e backoff esponenziale in. AWS](https://docs.aws.amazon.com/general/latest/gr/api-retries.html)

Quando il numero di tentativi raggiunge il valore configurato`maxRetryCount`, il fornitore del token smette di provare o passa a provare ogni `maxErrorTokenRefreshDelayMsec` millisecondo, a seconda del tipo di recupero del token: 
+ **`onTokenReady()`**— Il fornitore del token passa ad attendere `maxErrorTokenRefreshDelayMsec` millisecondi tra un tentativo e l'altro e continua a cercare di recuperare il token. 
+ **Aggiornamento in background**: il fornitore del token passa ad attendere `maxErrorTokenRefreshDelayMsec` millisecondi tra un tentativo e l'altro e continua a cercare di recuperare il token. 
+ **`getToken()`Chiamate su richiesta, quando l'aggiornamento in background è disabilitato**: il provider di token interrompe il tentativo di recuperare un token e restituisce il valore del token precedente o un valore nullo se non esiste un token precedente. 

## Scenari di nuovo tentativo di recupero del token
<a name="waf-mobile-sdk-how-token-retrieval-retry-scenarios"></a>

Quando il fornitore del token tenta di recuperare un token, potrebbero verificarsi tentativi automatici a seconda del punto in cui il recupero del token non riesce nel flusso di acquisizione del token. Questa sezione elenca i possibili punti in cui potresti vedere un nuovo tentativo automatico.
+ **Ottenere o verificare la AWS WAF Challenge tramite /inputs o /verify:**
  + Quando una richiesta di ottenimento e verifica di una AWS WAF sfida viene effettuata e fallisce, può comportare un nuovo tentativo automatico.
  + Potresti notare che qui si verificano nuovi tentativi automatici insieme a un `socketTimeoutException` errore. Ciò può avere diverse cause, tra cui:
    + Larghezza di banda di rete ridotta: conferma le impostazioni di connettività di rete
    + URL di integrazione dell'applicazione mutato: verifica che l'URL di integrazione non sia stato modificato rispetto a quanto visualizzato sulla console AWS WAF 
  + Il conteggio dei tentativi automatici è configurabile con la funzione `maxRetryCount()`
+ **Aggiornamento del token:**
  + Quando viene effettuata una richiesta di aggiornamento del token tramite il gestore del token, potrebbe comportare un nuovo tentativo automatico.
  + Il conteggio dei tentativi automatici qui è configurabile con la funzione. `maxRetryCount()`

Una configurazione senza tentativi automatici è possibile impostando. `maxRetryCount(0)`

## Tempo di immunità dei token e aggiornamento in background
<a name="waf-mobile-sdk-how-token-immunity"></a>

Il tempo di immunità dei token configurato nell'ACL Web è indipendente dall'intervallo di aggiornamento dei token impostato nell'SDK mobile. AWS WAF Quando abiliti l'aggiornamento in background, l'SDK aggiorna il token all'intervallo specificato utilizzando. `tokenRefreshDelaySec()` Ciò può comportare la presenza simultanea di più token validi, a seconda del tempo di immunità configurato.

Per evitare più token validi, puoi disabilitare l'aggiornamento in background e utilizzare la `getToken()` funzione per gestire il ciclo di vita del token nell'app mobile.

## Recupero di un token dopo l'inattività dell'app
<a name="waf-mobile-sdk-how-back-from-inactive"></a>

L'aggiornamento in background viene eseguito solo quando l'app è considerata attiva per il tipo di app in uso: 
+ **iOS**: l'aggiornamento in background viene eseguito quando l'app è in primo piano.
+ **Android**: l'aggiornamento in background viene eseguito quando l'app non è chiusa, indipendentemente dal fatto che sia in primo piano o in background.

Se l'app rimane in uno stato che non supporta l'aggiornamento in background per un periodo superiore ai `tokenRefreshDelaySec` secondi configurati, il fornitore del token sospende l'aggiornamento in background. Ad esempio, per un'app iOS, se `tokenRefreshDelaySec` è 300 e l'app si chiude o passa in background per più di 300 secondi, il fornitore del token interrompe l'aggiornamento del token. Quando l'app torna a uno stato attivo, il provider del token riavvia automaticamente l'aggiornamento in background. 

Quando l'app torna allo stato attivo, chiama `onTokenReady()` per ricevere una notifica quando il fornitore del token ha recuperato e memorizzato nella cache un nuovo token. Non limitarti a chiamare`getToken()`, perché la cache potrebbe non contenere ancora un token attuale e valido. 

## URL di integrazione dell'applicazione
<a name="waf-mobile-sdk-application-integration-url"></a>

L'URL di integrazione dell'applicazione SDK per AWS WAF dispositivi mobili rimanda a un ACL Web che hai abilitato per l'integrazione delle applicazioni. Questo URL indirizza le richieste al server di backend corretto e le associa al cliente. Non funge da controllo di sicurezza rigido, quindi l'esposizione di un URL di integrazione non rappresenta un rischio per la sicurezza.

Puoi modificare tecnicamente l'URL di integrazione fornito e ottenere comunque un token. Tuttavia, non lo consigliamo perché potresti perdere la visibilità sulle percentuali di risoluzione delle sfide o riscontrare errori nel recupero dei token con errori. `socketTimeoutException`

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

Ogni SDK AWS WAF mobile scaricabile include un file README che elenca le dipendenze per la versione specifica dell'SDK. Fai riferimento al README per le dipendenze per la tua versione dell'SDK mobile.

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

Se utilizzi un prodotto di offuscamento o minificazione come ProGuard, potrebbe essere necessario escludere determinati namespace per garantire il corretto funzionamento dell'SDK per dispositivi mobili. Controlla il README della tua versione dell'SDK per dispositivi mobili per trovare l'elenco dei namespace e delle regole di esclusione.

# Esempi di codice per l'SDK AWS WAF mobile
<a name="waf-mobile-sdk-coding-examples"></a>

Questa sezione fornisce esempi di codice per l'utilizzo dell'SDK per dispositivi mobili. 

## Inizializzazione del fornitore di token e ottenimento dei token
<a name="waf-mobile-sdk-coding-basic"></a>

Si avvia l'istanza del provider di token utilizzando un oggetto di configurazione. Quindi puoi recuperare i token utilizzando le operazioni disponibili. Di seguito vengono illustrati i componenti di base del codice richiesto.

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

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

Esempio di 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)
		}
	}
}
```

------

## Consentire all'SDK di fornire il cookie del token nelle richieste HTTP
<a name="waf-mobile-sdk-coding-auto-token-cookie"></a>

In caso `setTokenCookie` affermativo`TRUE`, il fornitore del token include il cookie del token nelle richieste web a tutte le località nel percorso specificato in`tokenCookiePath`. Per impostazione predefinita, `setTokenCookie` è `TRUE` ed `tokenCookiePath` è`/`. 

È possibile restringere l'ambito delle richieste che includono un cookie token specificando il percorso del cookie del token, `/web/login` ad esempio. Se lo fai, controlla che AWS WAF le tue regole non controllino la presenza di token nelle richieste che invii ad altri percorsi. Quando utilizzi il gruppo di `AWSManagedRulesACFPRuleSet` regole, configuri i percorsi di registrazione e creazione dell'account e il gruppo di regole verifica la presenza di token nelle richieste inviate a tali percorsi. Per ulteriori informazioni, consulta [Aggiungere il gruppo di regole gestite ACFP all'ACL Web](waf-acfp-rg-using.md). Allo stesso modo, quando si utilizza il gruppo di `AWSManagedRulesATPRuleSet` regole, si configura il percorso di accesso e il gruppo di regole verifica la presenza di token nelle richieste inviate a quel percorso. Per ulteriori informazioni, consulta [Aggiungere il gruppo di regole gestite ATP al pacchetto di protezione (Web ACL)](waf-atp-rg-using.md). 

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

In caso `setTokenCookie` `TRUE` affermativo, il fornitore del AWS WAF token memorizza il token in un file `HTTPCookieStorage.shared` e lo include automaticamente nelle richieste al dominio specificato in`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 ]

In caso `setTokenCookie` `TRUE` affermativo, il provider del token archivia il AWS WAF token in un'`CookieHandler`istanza condivisa a livello di applicazione. Il provider di token include automaticamente il cookie nelle richieste al dominio specificato dall'utente`WAFConfiguration`.

Esempio di Java:

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

Esempio di Kotlin:

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

Se hai già inizializzato l'istanza `CookieHandler` predefinita, il fornitore del token la utilizzerà per gestire i cookie. In caso contrario, il fornitore del token inizializzerà una nuova `CookieManager` istanza con il AWS WAF token `CookiePolicy.ACCEPT_ORIGINAL_SERVER` e quindi imposterà questa nuova istanza come istanza predefinita in. `CookieHandler`

Il codice seguente mostra come l'SDK inizializza il gestore dei cookie e il gestore dei cookie quando non sono disponibili nell'app. 

Esempio di Java:

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

Esempio di Kotlin:

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

------

## Fornitura manuale del cookie token nelle richieste HTTP
<a name="waf-mobile-sdk-coding-manual-token-cookie"></a>

Se lo `setTokenCookie` imposti`FALSE`, devi fornire il cookie token manualmente, come intestazione della richiesta Cookie HTTP, nelle tue richieste all'endpoint protetto. Il codice seguente mostra come eseguire questa operazione.

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

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

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

------