Integrazione con Google Cloud Armor per applicazioni mobile

Questo documento mostra come integrare le funzionalità WAF di reCAPTCHA Enterprise con Google Cloud Armor su applicazioni mobile.

Per completare l'integrazione, devi implementare una o più funzionalità di reCAPTCHA Enterprise per il WAF e configurare i criteri di sicurezza di Google Cloud Armor. Tuttavia, puoi implementare solo i token di azione reCAPTCHA per l'integrazione con Google Cloud Armor su applicazioni mobile.

Prima di iniziare

  1. Abilita l'API reCAPTCHA Enterprise.

    Abilita l'API

  2. Identifica le azioni che vuoi proteggere.

Implementa i token di azione reCAPTCHA

Per generare token di azione, è necessario che reCAPTCHA Enterprise sia in esecuzione sull'applicazione mobile. Dopo che reCAPTCHA Enterprise ha generato un token di azione, lo colleghi a un'intestazione della richiesta predefinita ogni volta che devi proteggere qualsiasi azione dell'utente, ad esempio checkout. Per impostazione predefinita, i token di azione sono validi per 30 minuti, ma possono variare a seconda del traffico. Devi collegare il token di azione a un'intestazione della richiesta predefinita prima che scada, in modo che Google Cloud Armor possa valutare gli attributi del token.

Per implementare un token di azione reCAPTCHA:

  1. Crea una chiave token di azione per la tua applicazione mobile.

    Console

    1. Nella console Google Cloud, vai alla pagina reCAPTCHA Enterprise.

      Vai a reCAPTCHA Enterprise

    2. Verifica che il nome del progetto venga visualizzato nel selettore di risorse nella parte superiore della pagina.

      Se non vedi il nome del progetto, fai clic sul selettore di risorse e seleziona il progetto.

    3. Fai clic su Crea chiave.

    4. Nel campo Nome visualizzato, inserisci un nome visualizzato per la chiave.
    5. A seconda del tipo di applicazione per cui vuoi creare le chiavi reCAPTCHA per il WAF, esegui l'azione appropriata:

      6. Creare chiavi reCAPTCHA per le applicazioni WAF per iOS

      Ti consigliamo di creare una chiave reCAPTCHA per ogni applicazione iOS.

      1. Nel menu Scegli il tipo di piattaforma, seleziona App per iOS.
        1. Nella sezione Elenco degli ID pacchetto iOS, fai clic su Aggiungi ID pacchetto iOS.

        2. Nel campo ID pacchetto, inserisci il nome del tuo ID bundle iOS.

        3. (Facoltativo) Per aggiungere un ulteriore ID pacchetto, fai clic su Aggiungi ID pacchetto iOS e inserisci il nome dell'ID pacchetto iOS nel campo ID pacchetto.

        4. (Facoltativo) Fornisci le impostazioni di Apple Developer.

          Ti consigliamo di fornire questi dati perché consentono a reCAPTCHA Enterprise di fornire punteggi di rischio più accurati per il tuo traffico.

          Inserisci le seguenti informazioni:

          • Chiave privata (.p8): viene generata nell'Apple Developer Center in Certificati, identificatori e profili.
          • Identificatore chiave: l'identificatore della chiave sviluppatore Apple (stringa di 10 caratteri).
          • ID team: l'ID team Apple (stringa di 10 caratteri) proprietario del profilo di provisioning utilizzato per creare l'applicazione.
        5. Espandi Verifica dell'ID pacchetto e tipo di chiave.
          1. Per creare una chiave reCAPTCHA per WAF:
            1. Attiva l'opzione Web application firewall (WAF).
            2. Dal menu Servizio, seleziona Cloud Armor.
            3. Dal menu Funzionalità, seleziona Token azione.
          2. Per proteggere la chiave reCAPTCHA per gli ID pacchetto, assicurati che l'opzione Disattiva la verifica dell'ID pacchetto sia disattivata.

          3. Per l'ambiente non di produzione, se vuoi specificare un punteggio che vuoi che venga restituito dalla chiave al momento della creazione delle valutazioni, segui questi passaggi:

            1. Fai clic sul pulsante di attivazione/disattivazione Questa è una chiave di test.
            2. Nella casella Punteggio, specifica un punteggio compreso tra 0 e 1,0.
        6. Fai clic su Crea chiave.

          7. La chiave appena creata viene elencata nella pagina Chiavi reCAPTCHA.

      Creare chiavi reCAPTCHA per le app WAF per Android

      1. Nel menu Scegli il tipo di piattaforma, seleziona App Android.
      2. Nella sezione Elenco pacchetti Android, fai clic su Aggiungi pacchetto Android.

      3. Nel campo Pacchetto Android, inserisci il nome del tuo pacchetto Android.

      4. (Facoltativo) Per aggiungere un altro pacchetto, fai clic su Aggiungi pacchetto Android e inserisci il nome di un altro pacchetto Android nel campo Pacchetto Android.
      5. Espandi Verifica del nome del pacchetto, distribuzione delle app e chiavi di test.
        1. Per creare una chiave reCAPTCHA per WAF:
          1. Attiva l'opzione Web application firewall (WAF).
          2. Dal menu Servizio, seleziona Cloud Armor.
          3. Dal menu Funzionalità, seleziona Token azione.
        2. Per fare in modo che la chiave reCAPTCHA venga utilizzata solo all'interno della tua app, disattiva l'opzione Disabilita la verifica del nome del pacchetto.
        3. Se vuoi creare una chiave per un'applicazione che sia disponibile su altri store oltre che su Google Play Store, attiva Supporto per le applicazioni distribuite al di fuori del Google Play Store.

        4. Per l'ambiente non di produzione, se vuoi specificare un punteggio che vuoi che venga restituito dalla chiave al momento della creazione delle valutazioni, segui questi passaggi:

          1. Fai clic sul pulsante di attivazione/disattivazione Questa è una chiave di test.
          2. Nella casella Punteggio, specifica un punteggio compreso tra 0 e 1,0.
      6. Fai clic su Crea chiave.

        7. La chiave appena creata viene elencata nella pagina Chiavi reCAPTCHA.

    gcloud (iOS)

    Per creare chiavi reCAPTCHA, utilizza il comando gcloud recaptcha Keys create.

    Prima di utilizzare uno qualsiasi dei dati del comando riportati di seguito, apporta le seguenti sostituzioni:

    • DISPLAY_NAME: nome della chiave. In genere il nome di un sito.
    • BUNDLE_IDs: ID bundle iOS di app a cui è consentito utilizzare la chiave. Specifica più ID bundle sotto forma di elenco separato da virgole.
    • WAF_FEATURE: nome della funzionalità WAF. Specifica action-token.
    • WAF_SERVICE: nome del fornitore di servizi WAF. Specifica CA per Google Cloud Armor.

    Esegui il comando gcloud recaptcha Keys create:

    Linux, macOS o Cloud Shell

    
gcloud recaptcha keys create \
--display-name=DISPLAY_NAME  \
--ios --bundle-ids=BUNDLE_IDs \
--waf-feature=WAF_FEATURE \
--waf-service=WAF_SERVICE

    Windows (PowerShell)

    
gcloud recaptcha keys create `
--display-name=DISPLAY_NAME  `
--ios --bundle-ids=BUNDLE_IDs `
--waf-feature=WAF_FEATURE `
--waf-service=WAF_SERVICE

    Windows (cmd.exe)

    
gcloud recaptcha keys create ^
--display-name=DISPLAY_NAME  ^
--ios --bundle-ids=BUNDLE_IDs ^
--waf-feature=WAF_FEATURE ^
--waf-service=WAF_SERVICE

    La risposta contiene la chiave reCAPTCHA appena creata.

    gcloud (Android)

    Per creare chiavi reCAPTCHA, utilizza il comando gcloud recaptcha Keys create.

    Prima di utilizzare uno qualsiasi dei dati del comando riportati di seguito, apporta le seguenti sostituzioni:

    • DISPLAY_NAME: nome della chiave. In genere il nome di un sito.
    • PACKAGE_NAMES: nomi di pacchetti Android delle app autorizzate a utilizzare la chiave. Specifica più nomi di pacchetti sotto forma di elenco separato da virgole.
    • WAF_FEATURE: nome della funzionalità WAF. Specifica action-token.
    • WAF_SERVICE: nome del fornitore di servizi WAF. Specifica CA per Google Cloud Armor.

    Esegui il comando gcloud recaptcha Keys create:

    Linux, macOS o Cloud Shell

    
gcloud recaptcha keys create \
--display-name=DISPLAY_NAME  \
--android --package-names=PACKAGE_NAMES \
--waf-feature=WAF_FEATURE \
--waf-service=WAF_SERVICE

    Windows (PowerShell)

    
gcloud recaptcha keys create `
--display-name=DISPLAY_NAME  `
--android --package-names=PACKAGE_NAMES `
--waf-feature=WAF_FEATURE `
--waf-service=WAF_SERVICE

    Windows (cmd.exe)

    
gcloud recaptcha keys create ^
--display-name=DISPLAY_NAME  ^
--android --package-names=PACKAGE_NAMES ^
--waf-feature=WAF_FEATURE ^
--waf-service=WAF_SERVICE

    La risposta contiene la chiave reCAPTCHA appena creata.

    REST (iOS)

    Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:

    • DISPLAY_NAME: nome della chiave. In genere il nome di un'app.
    • BUNDLE_IDs: ID bundle iOS di app a cui è consentito utilizzare la chiave. Specifica più ID bundle sotto forma di elenco separato da virgole.
    • WAF_FEATURE: nome della funzionalità WAF. Specifica action-token.
    • WAF_SERVICE: nome del fornitore di servizi WAF. Specifica CA per Google Cloud Armor.

    Metodo HTTP e URL: 

    POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys

    Corpo JSON richiesta: 

    {
  "displayName": "DISPLAY_NAME",
  "iosSettings": {
 "allowedBundleIds": "BUNDLE_IDS"
 },
   'wafSettings': "  {
       "wafService": "CA",
 "wafFeature": "ACTION_TOKEN"
  }
 }

    Per inviare la richiesta, scegli una delle seguenti opzioni:

    arricciare

    Salva il corpo della richiesta in un file denominato request.json ed esegui questo comando: 

    curl -X POST \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json; charset=utf-8" \
        -d @request.json \
        "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys"

    PowerShell

    Salva il corpo della richiesta in un file denominato request.json ed esegui questo comando: 

    $cred = gcloud auth print-access-token
    $headers = @{ "Authorization" = "Bearer $cred" }

    Invoke-WebRequest `
        -Method POST `
        -Headers $headers `
        -ContentType: "application/json; charset=utf-8" `
        -InFile request.json `
        -Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys" | Select-Object -Expand Content

    Dovresti ricevere una risposta JSON simile alla seguente:

    
{
  "name": "projects/project-id/keys/6LfhtywnAAAAABY3sCS2duZ6A55kmDXz-PNEgKgT",
  "displayName": "DISPLAY_NAME",
  "iosSettings": {
    "allowAllBundleIds": false,
    "allowedBundleIds": [
        BUNDLE_IDS
    ]
  },
  "labels": {},
  "wafSettings": {
      "wafService": "CA",
      "wafFeature": "ACTION_TOKEN"
  }
}

    REST (Android)

    Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:

    • DISPLAY_NAME: nome della chiave. In genere il nome di un'app.
    • PACKAGE_NAMES: nomi di pacchetti Android delle app autorizzate a utilizzare la chiave. Specifica più nomi di pacchetti sotto forma di elenco separato da virgole.
    • WAF_FEATURE: nome della funzionalità WAF. Specifica action-token.
    • WAF_SERVICE: nome del fornitore di servizi WAF. Specifica CA per Google Cloud Armor.

    Metodo HTTP e URL: 

    POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys

    Corpo JSON richiesta: 

    {
  "displayName": "DISPLAY_NAME",
  "androidSettings": {
  "allowedPackageNames":"PACKAGE_NAMES"
 },
   'wafSettings': "  {
       "wafService": "CA",
 "wafFeature": "ACTION_TOKEN"
  }
 }

    Per inviare la richiesta, scegli una delle seguenti opzioni:

    arricciare

    Salva il corpo della richiesta in un file denominato request.json ed esegui questo comando: 

    curl -X POST \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json; charset=utf-8" \
        -d @request.json \
        "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys"

    PowerShell

    Salva il corpo della richiesta in un file denominato request.json ed esegui questo comando: 

    $cred = gcloud auth print-access-token
    $headers = @{ "Authorization" = "Bearer $cred" }

    Invoke-WebRequest `
        -Method POST `
        -Headers $headers `
        -ContentType: "application/json; charset=utf-8" `
        -InFile request.json `
        -Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys" | Select-Object -Expand Content

    Dovresti ricevere una risposta JSON simile alla seguente:

    
{
  "name": "projects/project-id/keys/6LcioSknAAAAABrjlMuZv2fjIGYMqwaAFC9izhoy",
  "displayName": "DISPLAY_NAME",
  "androidSettings": {
      "allowAllPackageNames": false,
      "allowedPackageNames": [
          PACKAGE_NAMES
      ],
      "supportNonGoogleAppStoreDistribution": false
  },
  "labels": {},
  "wafSettings": {
      "wafService": "CA",
      "wafFeature": "ACTION_TOKEN"
  }
}

  2. Integra l'SDK per dispositivi mobili reCAPTCHA Enterprise nelle tue applicazioni mobile con la chiave token di azione che hai creato. Per le istruzioni, consulta il documento corrispondente al tipo di applicazione mobile.

  3. Dopo aver ricevuto il token da reCAPTCHA Enterprise, collegalo a un'intestazione della richiesta predefinita nel seguente formato:

    X-Recaptcha-Token: value-of-your-action-token

    Il seguente codice campione mostra come collegare il token:

    Android

    Codice campione in Java

    
// This example shows how to send an HTTP request to the backend server
// attached with the reCAPTCHA token in the header.
//
// @param serverUrl: the URL of the backend server.
// @param rceToken: reCAPTCHA token that is attached to the header of the
// HTTP request.

public static void sendRequestToServerWithRceToken(
    String serverUrl, String rceToken) throws JSONException, IOException {
 URL url = new URL(String.format("http://%s/decryptcaptchacookie/accesswafserver", serverUrl));
 HttpURLConnection connection = (HttpURLConnection) url.openConnection();
 connection.setRequestProperty("X-Recaptcha-Token", rceToken);

 try {
    String requestBody = "['']";
    sendRequest(connection, requestBody, "AccessWithRceToken", "GET");
 } finally {
    connection.disconnect();
 }
}

private static void sendRequest(
    HttpURLConnection connection, String requestString, String requestName, String action)
    throws IOException {
 connection.setConnectTimeout(HTTP_CONNECT_TIMEOUT_MS);
 connection.setReadTimeout(HTTP_READ_TIMEOUT_MS);
 connection.setRequestProperty("Content-type", CONTENT_TYPE);
 connection.setRequestProperty(
    "Content-Length", Integer.toString(Utf8.encodedLength(requestString)));
 connection.setRequestMethod(action);
 connection.setDoOutput(true);
 connection.connect();
 try (OutputStream postStream = connection.getOutputStream()) {
    postStream.write(requestString.getBytes(UTF_8));
 }

 int responseCode = connection.getResponseCode();
 String response = connection.getResponseMessage();
 if (responseCode != HttpURLConnection.HTTP_OK) {
    throw new IOException(
       String.format(
          "Failed to complete request.\nResponse code:%s\nError Detail:\n%s",
          responseCode, response));
 }
}

    iOS

    Codice campione in Swift

    
// This example shows how to send an HTTP request to the backend server
// attached with the reCAPTCHA token in the header.
// @param serverUrl: the URL of the backend server.
// @param rceToken: reCAPTCHA token that is attached to the header of
// the HTTP request.

 public static func accessWafServer(rceToken: String, serverUrl: String)
    async throws -> String
 {
    let requestURL = try HttpHelper.createRequestURL(endpoint: serverUrl)
    var request = try HttpHelper.createRequest(requestURL: requestURL, action: "GET")
    request.setValue(rceToken, forHTTPHeaderField: "X-Recaptcha-Token")

    let data = try await HttpHelper.getDataFromServer(request)

    return String(decoding: data, as: UTF8.self)
 }

Configura i criteri di sicurezza di Google Cloud Armor

Dopo aver implementato le funzionalità di reCAPTCHA Enterprise per il WAF, devi configurare i criteri di sicurezza di Google Cloud Armor che valutano i token reCAPTCHA Enterprise per la gestione dei bot.

Per informazioni su come configurare i criteri di sicurezza di Google Cloud Armor e utilizzare le chiavi token di azione con i criteri di sicurezza, consulta Configurare le regole per la gestione dei bot.

Passaggi successivi