Questa pagina è stata tradotta dall'API Cloud Translation.

Eseguire l'integrazione con Google Cloud Armor per le applicazioni mobile

Questo documento mostra come integrare le funzionalità di reCAPTCHA con Cloud Armor nelle applicazioni mobile.

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

Prima di iniziare

Abilita l'API reCAPTCHA Enterprise.

Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.
Enable the API
Identifica le azioni che vuoi proteggere.

Implementare i token di azione reCAPTCHA

Per generare action-token, devi aver eseguito reCAPTCHA nella tua applicazione mobile. Dopo che reCAPTCHA genera un token di azione, lo colleghi a un'intestazione della richiesta predefinita ovunque tu debba proteggere un'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 allegare il token di azione a un'intestazione della richiesta predefinita prima della scadenza del token, in modo che Cloud Armor possa valutare gli attributi del token.

Per implementare un token di azione reCAPTCHA:

Crea una chiave action-token per la tua applicazione mobile.
Console
1. Nella console Google Cloud , vai alla pagina reCAPTCHA.
  
  Vai a reCAPTCHA
2. Verifica che il nome del tuo progetto venga visualizzato nel selettore di risorse nella parte superiore della pagina.
  
  Se non vedi il nome del tuo progetto, fai clic sul selettore di risorse, poi seleziona il tuo 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 WAF, esegui l'azione appropriata:
gcloud (iOS)

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

Nota:la creazione di chiavi reCAPTCHA per WAF sulle applicazioni mobile è supportata solo per l'integrazione con Cloud Armor. Per questa integrazione, puoi creare solo chiavi token azione per le applicazioni mobile.

Prima di utilizzare i dati dei comandi riportati di seguito, effettua le seguenti sostituzioni:
- DISPLAY_NAME: il nome della chiave. In genere il nome di un sito.
- BUNDLE_IDs: ID bundle iOS delle app autorizzate a utilizzare la chiave. Specifica più ID bundle come elenco separato da virgole.
- WAF_FEATURE: il nome della funzionalità WAF. Specifica action-token.
- WAF_SERVICE: Nome del fornitore di servizi WAF. Specifica CA per 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.

Nota:la creazione di chiavi reCAPTCHA per WAF sulle applicazioni mobile è supportata solo per l'integrazione con Cloud Armor. Per questa integrazione, puoi creare solo chiavi token azione per le applicazioni mobile.

Prima di utilizzare i dati dei comandi riportati di seguito, effettua le seguenti sostituzioni:
- DISPLAY_NAME: il nome della chiave. In genere il nome di un sito.
- PACKAGE_NAMES: i nomi dei pacchetti Android delle app autorizzate a utilizzare la chiave. Specifica più nomi di pacchetti come elenco separato da virgole.
- WAF_FEATURE: il nome della funzionalità WAF. Specifica action-token.
- WAF_SERVICE: Nome del fornitore di servizi WAF. Specifica CA per 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)

Nota:la creazione di chiavi reCAPTCHA per WAF sulle applicazioni mobile è supportata solo per l'integrazione con Cloud Armor. Per questa integrazione, puoi creare solo chiavi token azione per le applicazioni mobile.

Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:
- DISPLAY_NAME: il nome della chiave. In genere il nome di un'app.
- BUNDLE_IDs: ID bundle iOS delle app autorizzate a utilizzare la chiave. Specifica più ID bundle come elenco separato da virgole.
- WAF_FEATURE: il nome della funzionalità WAF. Specifica action-token.
- WAF_SERVICE: Nome del fornitore di servizi WAF. Specifica CA per Cloud Armor.
Metodo HTTP e URL:
POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys
Corpo JSON della richiesta:
{ "displayName": "DISPLAY_NAME", "iosSettings": { "allowedBundleIds": "BUNDLE_IDS" }, 'wafSettings': " { "wafService": "CA", "wafFeature": "ACTION_TOKEN" } }
Per inviare la richiesta, scegli una di queste opzioni:
curl

Nota: il seguente comando presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login oppure utilizzando Cloud Shell, che consente di accedere automaticamente all'interfaccia a riga di comando gcloud. Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

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

Nota: il comando seguente presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login . Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

$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)

Nota:la creazione di chiavi reCAPTCHA per WAF sulle applicazioni mobile è supportata solo per l'integrazione con Cloud Armor. Per questa integrazione, puoi creare solo chiavi token azione per le applicazioni mobile.

Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:
- DISPLAY_NAME: il nome della chiave. In genere il nome di un'app.
- PACKAGE_NAMES: i nomi dei pacchetti Android delle app autorizzate a utilizzare la chiave. Specifica più nomi di pacchetti come elenco separato da virgole.
- WAF_FEATURE: il nome della funzionalità WAF. Specifica action-token.
- WAF_SERVICE: Nome del fornitore di servizi WAF. Specifica CA per Cloud Armor.
Metodo HTTP e URL:
POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys
Corpo JSON della richiesta:
{ "displayName": "DISPLAY_NAME", "androidSettings": { "allowedPackageNames":"PACKAGE_NAMES" }, 'wafSettings': " { "wafService": "CA", "wafFeature": "ACTION_TOKEN" } }
Per inviare la richiesta, scegli una di queste opzioni:
curl

Nota: il seguente comando presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login oppure utilizzando Cloud Shell, che consente di accedere automaticamente all'interfaccia a riga di comando gcloud. Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

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

Nota: il comando seguente presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login . Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

$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" } }
Integra l'SDK mobile reCAPTCHA nelle tue applicazioni mobile con la chiave action-token che hai creato. Per istruzioni, consulta il documento corrispondente al tipo di applicazione mobile.
- Per Android, consulta Integrare le chiavi WAF con le applicazioni Android.
- Per iOS, consulta Integrare le chiavi WAF con le applicazioni per iOS.

Dopo aver ricevuto il token da reCAPTCHA, allegalo a un'intestazione della richiesta predefinita nel seguente formato:

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

Il seguente codice campione mostra come allegare il token:

Android

Codice di esempio 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 di esempio 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 Cloud Armor

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

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

Recupero dei punteggi reCAPTCHA

Per i token di azione reCAPTCHA, puoi ottenere i punteggi reCAPTCHA dall'intestazione X-Recaptcha-Wafdata. In base a questi punteggi, puoi configurare qualsiasi azione personalizzata da intraprendere per le richieste degli utenti.

L'esempio seguente mostra un'intestazione X-Recaptcha-Wafdata di esempio:

X-Recaptcha-Wafdata: waf_service="Google Cloud Armor", action_token;score=0.9\r\n

Puoi anche visualizzare i punteggi reCAPTCHA nei log di Google Cloud Armor.

Passaggi successivi

Configura le regole per la gestione dei bot.

Eseguire l'integrazione con Google Cloud Armor per le applicazioni mobile

Prima di iniziare

Implementare i token di azione reCAPTCHA

Console

Crea chiavi reCAPTCHA per WAF per applicazioni iOS

Crea chiavi reCAPTCHA per WAF per applicazioni Android

gcloud (iOS)

Linux, macOS o Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

gcloud (Android)