Faça a integração com o Google Cloud Armor para aplicações para dispositivos móveis

Este documento mostra como integrar as funcionalidades do reCAPTCHA com o Cloud Armor em aplicações para dispositivos móveis.

Para concluir a integração, tem de implementar uma ou mais funcionalidades do reCAPTCHA e configurar as políticas de segurança do Cloud Armor. No entanto, só pode implementar tokens de ação do reCAPTCHA para integração com o Cloud Armor em aplicações para dispositivos móveis.

Antes de começar

  1. Ative a 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

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

Implemente tokens de ação do reCAPTCHA

Tem de ter o reCAPTCHA em execução na sua aplicação para dispositivos móveis para gerar tokens de ação. Depois de o reCAPTCHA gerar um token de ação, anexa o token de ação a um cabeçalho de pedido predefinido sempre que precisar de proteger uma ação do utilizador, como checkout. Por predefinição, os tokens de ação são válidos durante 30 minutos, mas podem variar consoante o tráfego. Tem de anexar o token de ação a um cabeçalho de pedido predefinido antes de o token expirar, para que o Cloud Armor possa avaliar os atributos do token.

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

  1. Crie uma chave action-token para a sua aplicação para dispositivos móveis.

    Consola

    1. Na Google Cloud consola, aceda à página reCAPTCHA.

      Aceder ao reCAPTCHA

    2. Verifique se o nome do seu projeto é apresentado no seletor de recursos na parte superior da página.

      Se não vir o nome do seu projeto, clique no seletor de recursos e, de seguida, selecione o seu projeto.

    3. Clique em Criar chave.
    4. No campo Nome a apresentar, introduza um nome a apresentar para a chave.
    5. Consoante o tipo de aplicação para a qual quer criar as chaves reCAPTCHA para o WAF, execute a ação adequada:

      6. Crie chaves reCAPTCHA para o WAF para aplicações iOS

      Recomendamos que crie uma chave do reCAPTCHA por aplicação iOS.

      1. Para o Tipo de aplicação, selecione iOS.
        1. Na secção Lista de IDs de pacotes iOS, clique em Adicionar ID de pacote iOS.

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

        3. Opcional: para adicionar um ID do pacote adicional, clique em Adicionar ID do pacote iOS e introduza o nome do ID do pacote iOS no campo ID do pacote.
        4. Para proteger a chave do reCAPTCHA para os seus IDs de pacote, certifique-se de que o botão Desativar validação do ID de pacote está desativado.

        5. Opcional: faculte as definições de programador da Apple.

          Recomendamos que forneça estes dados, uma vez que permitem que o reCAPTCHA forneça pontuações de risco mais precisas para o seu tráfego.

          Introduza as seguintes informações:

          • Chave privada (.p8): esta é gerada no Apple Developer Center em Certificates, Identifiers & Profiles.
          • Identificador da chave: o identificador da chave de programador da Apple (string de 10 carateres).
          • ID da equipa: o ID da equipa da Apple (string de 10 carateres) proprietária do perfil de aprovisionamento usado para criar a sua aplicação.
        6. Opcional: clique em Passo seguinte (opcional).
          1. Para criar uma chave reCAPTCHA para o WAF, faça o seguinte:
            1. Em Definições adicionais, ative a opção
            2. Em Definições adicionais, ative/desative o botão Vai implementar esta chave numa firewall de aplicações Web (WAF)?.
            3. Nas opções de Serviço, selecione Cloud Armor.
            4. Nas opções de Funcionalidade, selecione Ação.

          2. Para o seu ambiente de não produção, se quiser especificar uma pontuação que a chave devolva quando forem criadas avaliações para a mesma, faça o seguinte:

            1. Em Definições adicionais, clique no botão Está a criar esta chave apenas para fins de teste?.
            2. Use o controlo de deslize Definir pontuação para especificar uma pontuação entre 0 e 1,0.
        7. Clique em Criar chave.

          8. A chave criada recentemente é apresentada na página Chaves do reCAPTCHA.

      Crie chaves reCAPTCHA para o WAF para aplicações Android

      1. Para o Tipo de aplicação, selecione Android.
      2. Na secção Lista de pacotes Android, clique em Adicionar pacote Android.
      3. No campo Pacote Android, introduza o nome do seu pacote Android.
      4. Opcional: para adicionar outro pacote, clique em Adicionar pacote Android e introduza o nome de outro pacote Android no campo Pacote Android.
      5. Para aplicar que a chave do reCAPTCHA seja usada apenas na sua app, desative o botão de ativação/desativação Desativar validação do nome do pacote.
      6. Se quiser criar uma chave para uma aplicação que esteja disponível noutras lojas de apps além da Google Play Store, ative a opção Suportar aplicações distribuídas fora da Google Play Store.
      7. Opcional: clique em Passo seguinte (opcional).
        1. Para criar uma chave reCAPTCHA para o WAF, faça o seguinte:
          1. Em Definições adicionais, ative a opção
          2. Em Definições adicionais, ative/desative o botão Vai implementar esta chave numa firewall de aplicações Web (WAF)?.
          3. Nas opções de Serviço, selecione Cloud Armor.
          4. Nas opções de Funcionalidade, selecione Ação.

        2. Para o seu ambiente de não produção, se quiser especificar uma pontuação que a chave devolva quando forem criadas avaliações para a mesma, faça o seguinte:

          1. Em Definições adicionais, clique no botão Está a criar esta chave apenas para fins de teste?.
          2. Use o controlo de deslize Definir pontuação para especificar uma pontuação entre 0 e 1,0.
      8. Clique em Criar chave.

        9. A chave criada recentemente é apresentada na página Chaves do reCAPTCHA.

    gcloud (iOS)

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

    Antes de usar qualquer um dos dados de comandos abaixo, faça as seguintes substituições:

    • DISPLAY_NAME: nome da chave. Normalmente, um nome do site.
    • BUNDLE_IDs: IDs de pacotes iOS de apps autorizadas a usar a chave. Especifique vários IDs de pacote como uma lista separada por vírgulas.
    • WAF_FEATURE: nome da funcionalidade da WAF. Especifique action-token.
    • WAF_SERVICE: nome do fornecedor de serviços do WAF. Especifique CA para o 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 do reCAPTCHA, use o comando gcloud recaptcha keys create.

    Antes de usar qualquer um dos dados de comandos abaixo, faça as seguintes substituições:

    • DISPLAY_NAME: nome da chave. Normalmente, um nome do site.
    • PACKAGE_NAMES: nomes de pacotes Android de apps autorizadas a usar a chave. Especifique vários nomes de pacotes como uma lista separada por vírgulas.
    • WAF_FEATURE: nome da funcionalidade da WAF. Especifique action-token.
    • WAF_SERVICE: nome do fornecedor de serviços do WAF. Especifique CA para o Cloud Armor.

    Execute o comando gcloud recaptcha keys create:

    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 qualquer um dos dados do pedido, faça as seguintes substituições:

    • DISPLAY_NAME: nome da chave. Normalmente, o nome de uma app.
    • BUNDLE_IDs: IDs de pacotes iOS de apps autorizadas a usar a chave. Especifique vários IDs de pacote como uma lista separada por vírgulas.
    • WAF_FEATURE: nome da funcionalidade da WAF. Especifique action-token.
    • WAF_SERVICE: nome do fornecedor de serviços do WAF. Especifique CA para o Cloud Armor.

    Método HTTP e URL: 

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

    Corpo JSON do pedido: 

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

    Para enviar o seu pedido, escolha uma destas opções:

    curl

    Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte 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

    Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte 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

    Deve receber uma resposta JSON semelhante à seguinte:

    
{
  "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 qualquer um dos dados do pedido, faça as seguintes substituições:

    • DISPLAY_NAME: nome da chave. Normalmente, o nome de uma app.
    • PACKAGE_NAMES: nomes de pacotes Android de apps autorizadas a usar a chave. Especifique vários nomes de pacotes como uma lista separada por vírgulas.
    • WAF_FEATURE: nome da funcionalidade da WAF. Especifique action-token.
    • WAF_SERVICE: nome do fornecedor de serviços do WAF. Especifique CA para o Cloud Armor.

    Método HTTP e URL: 

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

    Corpo JSON do pedido: 

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

    Para enviar o seu pedido, escolha uma destas opções:

    curl

    Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte 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

    Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte 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

    Deve receber uma resposta JSON semelhante à seguinte:

    
{
  "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 para dispositivos móveis do reCAPTCHA nas suas aplicações para dispositivos móveis com a chave action-token que criou. Para ver instruções, consulte o documento que corresponde ao tipo da sua aplicação para dispositivos móveis.

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

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

    O seguinte exemplo de código 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)
 }

Configure políticas de segurança do Cloud Armor

Depois de implementar as funcionalidades do reCAPTCHA para WAF, tem de configurar políticas de segurança do Cloud Armor que avaliam os tokens do reCAPTCHA para gestão de bots.

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

Obtenha pontuações do reCAPTCHA

Para tokens de ação do reCAPTCHA, pode obter pontuações do reCAPTCHA a partir do cabeçalho X-Recaptcha-Wafdata. Com base nestas classificações, pode configurar qualquer ação personalizada que tenha de ser tomada para pedidos de utilizadores.

O exemplo seguinte mostra um cabeçalho X-Recaptcha-Wafdata de exemplo:

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

Também pode ver as pontuações do reCAPTCHA nos registos do Google Cloud Armor.

O que se segue?