Integrar com o Google Cloud Armor para aplicativos móveis

Este documento mostra como integrar os recursos WAF do reCAPTCHA com o Google Cloud Armor em aplicativos para dispositivos móveis.

Para concluir a integração, implemente um ou mais recursos do reCAPTCHA para WAF e configure as políticas de segurança do Google Cloud Armor. No entanto, só é possível implementar tokens de ação reCAPTCHA para integração com o Google Cloud Armor em aplicativos para dispositivos móveis.

Antes de começar

  1. Ative a API reCAPTCHA Enterprise.

    Enable the API

  2. Identifique as ações que você quer proteger.

Implementar tokens de ação do reCAPTCHA

Você precisa ter o reCAPTCHA em execução no seu aplicativo para dispositivos móveis para gerar tokens de ação. Depois que o reCAPTCHA gerar um token de ação, anexe-o a um cabeçalho de solicitação predefinido sempre que precisar proteger qualquer ação do usuário, como checkout. Por padrão, os tokens de ação são válidos por 30 minutos, mas podem variar dependendo do tráfego. É necessário anexar o token de ação a um cabeçalho de solicitação predefinido antes que o token expire para que o Google Cloud Armor pode avaliar os atributos de token.

Para implementar um token de ação reCAPTCHA, faça o seguinte:

  1. Crie uma chave de token de ação para seu aplicativo para dispositivos móveis.

    Console

    1. No console do Google Cloud, acesse a página do reCAPTCHA.

      Acessar o reCAPTCHA

    2. Verifique se o nome do projeto aparece no seletor de recursos, na parte superior da página.

      Se você não vir o nome do projeto, clique no seletor de recursos para selecioná-lo.

    3. Clique em Criar chave.
    4. No campo Nome de exibição, insira um nome de exibição para a chave.
    5. Dependendo do tipo de aplicativo para o qual você quer criar as chaves reCAPTCHA para WAF, faça a ação adequada:

      6. Criar chaves reCAPTCHA para o WAF para aplicativos iOS

      Recomendamos criar uma chave reCAPTCHA por app iOS.

      1. No menu Escolher o tipo de plataforma, selecione App iOS.
        1. Na seção Lista de ID do pacote do iOS, clique em Adicionar ID do pacote do iOS.

        2. No campo ID do pacote, insira o nome do ID do pacote do iOS.

        3. Opcional: para adicionar outro ID do pacote, clique em Adicionar ID do pacote iOS. e insira o nome do ID do pacote iOS no campo ID do pacote.

        4. Opcional: forneça as configurações do desenvolvedor da Apple.

          Recomendamos o envio desses dados porque eles permitem que o reCAPTCHA forneça pontuações de risco mais precisas para seu tráfego.

          Digite as seguintes informações:

          • Chave privada (.p8): é gerada no serviço da Centro para Desenvolvedores, em "Certificates, Identifiers &" Perfis.
          • Identificador de chave: o identificador de chave do desenvolvedor da Apple (string de 10 caracteres).
          • ID da equipe: o ID da equipe da Apple (string de 10 caracteres) que possui o perfil de provisionamento usado para criar seu aplicativo.
        5. Expanda Verificação de ID do pacote e tipo de chave.
          1. Para criar uma chave reCAPTCHA para o WAF, faça o seguinte:
            1. Ative a opção Firewall de aplicativos da Web (WAF).
            2. No menu Serviço, selecione Cloud Armor.
            3. No menu Feature, selecione Action token.
          2. Para proteger a chave reCAPTCHA dos seus IDs de pacote, verifique se a opção Desativar verificação do ID do pacote está desativada.

          3. Para o ambiente que não é de produção, se você quiser especificar uma pontuação que a chave deve retornar quando as avaliações forem criadas, faça o seguinte:

            1. Clique no botão Esta é uma chave de teste.
            2. Na caixa Pontuação, especifique uma pontuação entre 0 e 1,0.
        6. Clique em Criar chave.

          7. A chave recém-criada é listada na página Chaves reCAPTCHA.

      Criar chaves reCAPTCHA para WAF em apps Android

      1. No menu Escolher o tipo de plataforma, selecione App Android.
      2. Na seção Lista de pacote do Android, clique em Adicionar pacote do Android.
      3. No campo pacote do Android, insira o nome do pacote do Android.
      4. (Opcional) Para incluir outro pacote, clique em Adicionar pacote do Android e digite o nome de outro pacote no campo Pacote do Android.
      5. Expanda Verificação do nome do pacote, distribuição de apps e chaves de teste.
        1. Para criar uma chave reCAPTCHA para o WAF, faça o seguinte:
          1. Ative a opção Firewall de aplicativos da Web (WAF).
          2. No menu Serviço, selecione Cloud Armor.
          3. No menu Recurso, selecione Token de ação.
        2. Para garantir que a chave reCAPTCHA seja usada apenas no seu app, desative a opção Botão Desativar a verificação do nome do pacote.
        3. Se você quiser criar uma chave para um aplicativo disponível em outras app stores, além da Google Play Store, ative a opção Suporte a aplicativos distribuídos fora da Google Play Store.

        4. Para o ambiente que não é de produção, se você quiser especificar uma pontuação que a chave deve retornar quando as avaliações forem criadas, faça o seguinte:

          1. Clique no botão Esta é uma chave de teste.
          2. Na caixa Pontuação, especifique uma pontuação entre 0 e 1,0.
      6. Clique em Criar chave.

        7. A chave recém-criada é listada na página Chaves reCAPTCHA.

    gcloud (iOS)

    Para criar chaves reCAPTCHA, use o comando gcloud recaptcha keys create.

    Antes de usar os dados do comando abaixo, faça estas substituições:

    • DISPLAY_NAME: nome da chave. Geralmente, um nome de site.
    • BUNDLE_IDs: os IDs do pacote de apps iOS autorizados a usar a chave. Para especificar vários IDs de pacote, use um formato de lista separada por vírgulas.
    • WAF_FEATURE: nome do recurso WAF. Especifique action-token.
    • WAF_SERVICE: nome do Provedor de serviços WAF. Especifique CA para o Google Cloud Armor.

    Execute o comando gcloud recaptcha keys create:

    Linux, macOS ou 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

    A resposta contém a chave reCAPTCHA recém-criada.

    gcloud (Android)

    Para criar chaves reCAPTCHA, use o comando gcloud recaptcha keys create.

    Antes de usar os dados do comando abaixo, faça estas substituições:

    • DISPLAY_NAME: o nome da chave. Geralmente, um nome de site.
    • PACKAGE_NAMES: nomes de pacotes de apps Android autorizados a usar a chave. Para especificar vários nomes de pacotes, use um formato de lista separada por vírgulas.
    • WAF_FEATURE: nome do recurso WAF. Especifique action-token.
    • WAF_SERVICE: nome do provedor de serviço do WAF. Especifique CA para o Google Cloud Armor.

    Execute o gcloud recaptcha keys create (link em inglês) comando:

    Linux, macOS ou 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

    A resposta contém a chave reCAPTCHA recém-criada.

    REST (iOS)

    Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

    • DISPLAY_NAME: o nome da chave. Geralmente, o nome de um app.
    • BUNDLE_IDs: os IDs do pacote de apps iOS autorizados a usar a chave. Para especificar vários IDs de pacote, use um formato de lista separada por vírgulas.
    • WAF_FEATURE: nome do recurso WAF. Especifique action-token.
    • WAF_SERVICE: nome do provedor de serviço do WAF. Especifique CA para o Google Cloud Armor.

    Método HTTP e URL: 

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

    Corpo JSON da solicitação:

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

    Para enviar a solicitação, escolha uma destas opções:

    curl

    Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir: 

    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

    Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir: 

    $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

    Você receberá uma resposta JSON semelhante a esta:

    
{
  "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)

    Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

    • DISPLAY_NAME: nome da chave. Geralmente, o nome de um app.
    • PACKAGE_NAMES: nomes de pacotes Android de apps com permissão para use a chave. Para especificar vários nomes de pacotes, use um formato de lista separada por vírgulas.
    • WAF_FEATURE: nome do recurso WAF. Especifique action-token.
    • WAF_SERVICE: nome do provedor de serviço do WAF. Especifique CA para o Google Cloud Armor.

    Método HTTP e URL: 

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

    Corpo JSON da solicitação:

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

    Para enviar a solicitação, escolha uma destas opções:

    curl

    Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir: 

    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

    Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir: 

    $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

    Você receberá uma resposta JSON semelhante a esta:

    
{
  "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. Integre o SDK reCAPTCHA para dispositivos móveis aos seus aplicativos para dispositivos móveis com a chave do token de ação que você criou. Para instruções, consulte o documento que corresponde ao tipo do seu aplicativo para dispositivos móveis.

  3. Depois de receber o token do reCAPTCHA, anexe-o a um cabeçalho de solicitação predefinido no seguinte formato:

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

    O exemplo de código abaixo mostra como anexar o token:

    Android

    Exemplo de código em 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

    Exemplo de código em 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)
 }

Configurar políticas de segurança do Google Cloud Armor

Depois de implementar os recursos do reCAPTCHA para WAF, configure as políticas de segurança do Google Cloud Armor que avaliam os tokens do reCAPTCHA para gerenciamento de bots.

Para saber como configurar políticas de segurança do Google Cloud Armor e usar as chaves de token de ação com elas, consulte Configurar regras para gerenciamento de bots.

A seguir