Instalar chaves universais em páginas da Web

Neste documento, descrevemos como instalar e integrar uma chave universal às suas páginas da Web.

Antes de começar

  1. Prepare seu ambiente para o Google Cloud Fraud Defense.

  2. Crie uma chave universal e configure domínios.

Instalar chaves universais no seu site

Para instalar a chave universal e proteger suas páginas da Web, use a configuração de execução automática, a instalação manual do JavaScript ou os dois métodos juntos em diferentes endpoints usando a mesma chave universal:

  • Configuração do AutoExecute (recomendado): intercepta automaticamente solicitações de rede assíncronas para caminhos de URL configurados e anexa o token do reCAPTCHA ao cabeçalho da solicitação.
  • Instalação manual: usa chamadas manuais de grecaptcha.enterprise.execute() ou atributos de botão HTML. É possível usar esse método sozinho ou com o AutoExecute para solicitações de rede que não são compatíveis com o AutoExecute, solicitações que exigem a inserção de tokens personalizados no payload ou durante migrações incrementais para o AutoExecute.

Dependendo da sua abordagem de integração, escolha a opção adequada:

Configuração do AutoExecute

O AutoExecute pode ajudar a simplificar a integração do JavaScript de front-end interceptando solicitações de rede nas suas páginas da Web e eliminando chamadas manuais de grecaptcha.enterprise.execute() para cada ação de front-end.

  • A execução automática só intercepta solicitações de rede assíncronas iniciadas com a API Fetch ou XMLHttpRequest, incluindo solicitações de frameworks como AJAX que usam essas APIs.
  • O AutoExecute não é compatível com recursos que são carregados automaticamente no tempo de carregamento da página. Em vez disso, aplique o AutoExecute a solicitações de rede acionadas por ações do usuário na página, como um botão de login.
  • Para evitar que os desafios do Fraud Defense causem tempos limite de rede, aplique tempos limite diretamente às solicitações. Use AbortSignal.timeout(n) para a API Fetch e a propriedade XMLHttpRequest.timeout para XMLHttpRequest.

Adicionar a tag script às suas páginas da Web

Para carregar a Fraud Defense na sua página da web, adicione a API JavaScript com sua chave universal ao elemento <head></head> da página:

<head>
  <script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID"></script>
  ...
</head>

A Fraud Defense usa o idioma do navegador por padrão. Se você quiser especificar um idioma diferente, use o atributo hl=LANG no script. Por exemplo, para usar o francês, especifique o seguinte:

<script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID&hl=fr"></script>

Para saber mais sobre os idiomas disponíveis, consulte os códigos de idioma para o Fraud Defense.

Configurar endpoints protegidos

O script do Fraud Defense se integra automaticamente às ações de rede definidas na configuração da política da sua chave universal. Esta seção define um mapeamento de caminhos de URL (path) para nomes de ação (action).

Se o script do Fraud Defense detectar uma solicitação de rede assíncrona para um caminho mapeado, ele vai interceptar a solicitação, acionar uma avaliação de risco e, possivelmente, mostrar um desafio CAPTCHA ao usuário antes que a solicitação original continue. O token de resposta gerado é anexado automaticamente ao cabeçalho X-Recaptcha-Token na solicitação.

gcloud

Para inspecionar a configuração atual da política da chave universal, use o comando gcloud alpha recaptcha policies describe:

gcloud alpha recaptcha policies describe --key=KEY_ID

Para atualizar a configuração da política com os endpoints protegidos, crie um arquivo YAML (por exemplo, POLICY.yaml) definindo os caminhos e as ações protegidos:

client_settings:
  allowedDomains:
    - example.com
  protected_endpoint_group:
    protected_endpoints:
      - path: "/login_api"
        action: login
      - path: "/register_api"
        action: register
      - path: "/cart_api/add/*"
        action: add_to_cart

Atualize a configuração da chave com o arquivo YAML usando o comando gcloud alpha recaptcha policies update:

gcloud alpha recaptcha policies update \
    --key=KEY_ID \
    --policy=POLICY.yaml

API REST

Para atualizar a configuração da política e definir endpoints protegidos usando a API REST, use o método projects.keys.updatePolicy.

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

  • PROJECT_ID: o ID do projeto do Google Cloud .
  • KEY_ID: o ID da chave universal

Método HTTP e URL: 

PATCH https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/KEY_ID/policy?updateMask=clientSettings.protectedEndpointGroup

Corpo JSON da solicitação:

{
"clientSettings": {
  "protectedEndpointGroup": {
    "protectedEndpoints": [
      {
        "path": "/login_api",
        "action": "login"
      },
      {
        "path": "/register_api",
        "action": "register"
      },
      {
        "path": "/cart_api/add/*",
        "action": "add_to_cart"
      }
    ]
  }
}
}

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

Se a solicitação for bem-sucedida, ela vai retornar a configuração atualizada da política.

É possível configurar até 25 endpoints protegidos por chave universal. Cada endpoint precisa atender aos seguintes requisitos:

  • action: o nome da ação precisa conter de 1 a 100 caracteres e usar apenas letras, números, barras (/) e sublinhados (_).
  • path (diferencia maiúsculas de minúsculas): o caminho precisa atender aos seguintes critérios:
    • Ser exclusivo, começar com / e conter de 1 a 200 caracteres sem barras consecutivas (//).
    • Inclua pelo menos um segmento que não seja curinga (por exemplo, não pode ser /, /*, /** ou /*/).
    • Os caracteres curinga precisam ocupar segmentos completos: * corresponde a um único segmento (por exemplo, /api/*/login ou /api/* são válidos; /api/login* é inválido) e ** corresponde a vários segmentos apenas como o segmento final (por exemplo, /api/** é válido; /api/**/login é inválido).
  • Solicitações de terceiros:se as ferramentas de terceiros em execução na sua página (como scripts de análise ou de parceiros) enviarem solicitações para caminhos que correspondem aos endpoints protegidos (por exemplo, https://analytics.example.net/login correspondendo a /login), o AutoExecute também vai interceptá-las. Isso pode causar latência de rede extra, métricas distorcidas ou desafios de CAPTCHA inesperados. Para evitar conflitos, verifique se os caminhos protegidos são distintos (por exemplo, /auth/v1/login) ou use a instalação manual se houver colisões de caminhos.
  • APIs de vários domínios:se a API de back-end estiver hospedada em um domínio diferente do seu site (por exemplo, examplecdn.net em vez de www.example.com), o AutoExecute vai funcionar automaticamente sem configuração de domínio extra.

Se a correspondência com domínios de destino específicos for importante para sua integração, envie uma solicitação de recurso.

No back-end, receba o token de resposta do cabeçalho da solicitação X-Recaptcha-Token e crie uma avaliação em até dois minutos.

Instalação manual

Recomendamos adicionar a verificação do Fraud Defense a uma interação do usuário que precisa ser verificada. Por exemplo, se você quiser verificar a ação de envio de um formulário, adicione a verificação do Fraud Defense à ação de envio.

Dependendo de onde você quer adicionar a verificação do Fraud Defense, escolha a opção apropriada:

Adicionar verificação em uma interação do usuário

  1. Para carregar o reCAPTCHA na sua página da Web, adicione a API JavaScript com sua chave universal ao elemento <head></head> da página:

    <head>
  <script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID"></script>
  ...
</head>

    A Fraud Defense usa o idioma do navegador por padrão. Se quiser especificar um idioma diferente, use o atributo hl=LANG no seu script. Por exemplo, para usar o francês, especifique o seguinte:

    <script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID&hl=fr"></script>

    Para saber mais sobre os idiomas disponíveis, consulte os códigos de idioma para o Fraud Defense.

    Se você quiser especificar um local para o selo, use badge=LOCATION como um parâmetro de consulta na tag script. Por exemplo, https://www.google.com/recaptcha/enterprise.js?render=KEY_ID&badge=bottomleft. Por padrão, o local é definido como bottomright. Outros valores possíveis são inline e bottomleft.

  2. Para adicionar a verificação do Fraud Defense a uma interação do usuário, faça o seguinte:

    1. Para garantir que grecaptcha.enterprise.execute() seja executado após o carregamento da biblioteca do Fraud Defense, use grecaptcha.enterprise.ready().

    2. Chame grecaptcha.enterprise.execute() em cada interação que você quer proteger com sua chave universal. Especifique um nome significativo para uma interação do usuário no parâmetro action. Para mais orientações, consulte Ações.

      O exemplo a seguir mostra como chamar grecaptcha.enterprise.execute() em uma ação de login:

      <script>
  // Use `requestSubmit()` for extra features like browser input
  // validation.
  function onClick(e) {
    e.preventDefault();
    grecaptcha.enterprise.ready(async () => {
      const token = await grecaptcha.enterprise.execute(
        'KEY_ID',
        {action: 'LOGIN'}
      );
      // IMPORTANT: The 'token' that results from execute is an
      // encrypted response sent by Fraud Defense to
      // the end user's browser.
      // This token must be validated by creating an assessment.
      // See https://cloud.google.com/recaptcha/docs/create-assessment
    });
  }
</script>

  3. Depois que o token for gerado, envie o token reCAPTCHA ao back-end e crie uma avaliação em até dois minutos.

Adicionar o Fraud Defense a um botão HTML

  1. Para carregar o reCAPTCHA na sua página da Web, adicione a API JavaScript com sua chave universal ao elemento <head></head> da página da Web:

    <head>
  <script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID"></script>
  ...
</head>

    A Fraud Defense usa o idioma do navegador por padrão. Se quiser especificar um idioma diferente, use o atributo hl=LANG no seu script. Por exemplo, para usar o francês, especifique o seguinte:

    <script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID&hl=fr"></script>

    Para saber mais sobre os idiomas disponíveis, consulte os códigos de idioma para o Fraud Defense.

  2. Para adicionar o Fraud Defense a um botão HTML, faça o seguinte:

    1. Defina uma função de callback para manipular o token.
    <script>
  function onSubmit(token) {
    document.getElementById("demo-form").submit();
  }
  // Use `requestSubmit()` for extra features like browser input
  // validation.
</script>

    Para mais informações, consulte o método requestSubmit().

    1. Adicione atributos ao botão HTML.
    <button class="g-recaptcha"
    data-sitekey="KEY_ID"
    data-callback="onSubmit"
    data-action="submit">Submit</button>

    Se você quiser especificar um local para o selo, use o atributo data-badge="LOCATION" no elemento que tem class="g-recaptcha". Por padrão, o local é definido como bottomright. Outros valores possíveis são inline e bottomleft.

    1. Quando esse botão é usado para enviar um formulário no site, o parâmetro POST g-recaptcha-response contém o token de resposta.

  3. Depois que o token for gerado, envie o token reCAPTCHA ao back-end e crie uma avaliação em até dois minutos.

A seguir