¶ Guia Completo: Integrando reCAPTCHA Enterprise no Backend PHP (Slim) e App Android (Kotlin)
Todo mundo sabe que sou das antigas, sou véio! Comecei no desenvolvimento há um bom tempo. Vi o Google lançar diversas ferramentas que ainda estão por aí (pelo menos algumas). O reCAPTCHA é uma delas. Acompanhei desde a versão 1, depois a v2, v3...
Quando migrei os serviços de uma empresa para o Google Cloud, tive meu primeiro contato com o reCAPTCHA Enterprise, bonito, robusto! Se não me engano, a versão geral foi lançada em 2022, e hoje em dia muita coisa já roda com ele.
Além de oferecer uma segurança muito maior no backend, ele dá um suporte essencial na proteção de APIs. Aí pensei:
“E se eu fizer um teste no Android com Kotlin e backend em PHP? Será que rola?”
Neste artigo, irei ilustrar passo a passo como integrar o reCAPTCHA Enterprise do Google em um projeto Android nativo (Kotlin) com backend em PHP (Slim Framework).
¶ 1. Criando uma Chave reCAPTCHA no Google Cloud para o backend
¶ Acesse o Console do Google Cloud
- Acesse o Console do Google Cloud.
- Certifique-se de estar no projeto correto.
¶ Ative a API reCAPTCHA Enterprise
- Ir em “APIs e serviços > Biblioteca” e pesquisar por “reCAPTCHA Enterprise API”, ao encontrá-lo ative-o.
¶ Criando conta de serviço
- Vá para “IAM e administrador > Contas de serviço”
- Clique em "Criar conta de serviço".
- Preencha os dados:
- Nome:
recaptcha-verifier - ID da conta de serviço: vai ser gerado automaticamente
- Clique em "Criar e continuar"
- Nome:
- Em “selecionar papel” procure por “Agente do reCAPTCHA Enterprise”
- Clique em "Continuar" e depois "Concluir".
¶ Gerar chave JSON
- Na lista de contas de serviço (“IAM e administrador > Contas de serviço”), clique nos 3 pontos ao lado da conta que nomeamos recaptcha-verifier e escolha "Gerenciar chaves"
- Clique em "Adicionar chave > Criar nova chave"
- Escolha o tipo da chave como “JSON”
- Clique em "Criar"
- Um arquivo .json será baixado automaticamente com algo parecido com isso:
{
"type": "service_account",
"project_id": "example-project",
"private_key_id": "123abc456def789ghi012jkl345mno678pqr901",
"private_key": "-----BEGIN PRIVATE KEY-----\nFAKEPRIVATEKEYFAKEPRIVATEKEYFAKEPRIVATEKEYFAKE\n-----END PRIVATE KEY-----\n",
"client_email": "[email protected]",
"client_id": "000000000000000000000",
"auth_uri": "https://accounts.google.com/o/oauth2/auth",
"token_uri": "https://oauth2.googleapis.com/token",
"auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
"client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/service-account%40example-project.iam.gserviceaccount.com",
"universe_domain": "googleapis.com"
}
- Guarde-o e tome cuidado pois trata-se de um arquivo com chaves de segurança.
¶ 2. Backend PHP (Slim Framework)
Utilizei a seguinte documentação para criar o código fonte deste tópico.
¶ Instale a dependência do Google:
composer require google/cloud-recaptcha-enterprise¶ Configuração (ex: config.php)
- O foco aqui está na chave “recaptcha_google_key” que recebe o .json gerado da Google. Pode-se usar o .env também e fazer as devidas alterações nos códigos à seguir, eu sou “bitolado” com segurança e com isso e normalmente prefiro embutir no código fonte… sim já me xingaram por isso… rsrsrsrs…
<?php
return [
"jwt_secret" => "mocked_jwt_secret_key_123456789",
"jwt_secret_refresh" => "mocked_refresh_secret_key_987654321",
"db_settings" => [
"host" => "mocked-db-host",
"database" => "mocked_database",
"username" => "mocked_user",
"password" => "mocked_password"
],
"recaptcha_google_key" => <<<'JSON'
{
"type": "service_account",
"project_id": "mocked-project-id",
"private_key_id": "mockedprivatekeyid1234567890abcdef",
"private_key": "-----BEGIN PRIVATE KEY-----\nMOCKEDPRIVATEKEYDATA1234567890ABCDEF\n-----END PRIVATE KEY-----\n",
"client_email": "[email protected]",
"client_id": "000000000000000000000",
"auth_uri": "https://accounts.google.com/o/oauth2/auth",
"token_uri": "https://oauth2.googleapis.com/token",
"auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
"client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/mocked-service-account%40mocked-project-id.iam.gserviceaccount.com",
"universe_domain": "googleapis.com"
}
JSON
];¶ Helper (ex: src/Helpers/RecaptchaHelper.php)
<?php
namespace Helpers;
use Google\Cloud\RecaptchaEnterprise\V1\Client\RecaptchaEnterpriseServiceClient;
use Google\Cloud\RecaptchaEnterprise\V1\CreateAssessmentRequest;
use Google\Cloud\RecaptchaEnterprise\V1\Event;
use Google\Cloud\RecaptchaEnterprise\V1\Assessment;
use Google\Cloud\RecaptchaEnterprise\V1\TokenProperties\InvalidReason;
use Exception;
class RecaptchaHelper
{
public static function isValid(string $token, string $siteKey): bool
{
global $config;
if (empty($config['recaptcha_google_key'])) {
error_log('[Recaptcha] Chave de conta de serviço não definida no config.');
return false;
}
// Cria um arquivo temporário com o conteúdo da chave
$tmpPath = tempnam(sys_get_temp_dir(), 'recaptcha_key_');
file_put_contents($tmpPath, $config['recaptcha_google_key']);
putenv("GOOGLE_APPLICATION_CREDENTIALS={$tmpPath}");
// Extrai project_id do JSON
$keyData = json_decode($config['recaptcha_google_key'], true);
$projectId = $keyData['project_id'] ?? null;
if (!$projectId) {
error_log('[Recaptcha] Project ID não encontrado no JSON.');
return false;
}
try {
$client = new RecaptchaEnterpriseServiceClient();
$projectName = $client->projectName($projectId);
$event = (new Event())
->setSiteKey($siteKey)
->setToken($token);
$assessment = (new Assessment())->setEvent($event);
$request = (new CreateAssessmentRequest())
->setParent($projectName)
->setAssessment($assessment);
$response = $client->createAssessment($request);
$props = $response->getTokenProperties();
if (!$props->getValid()) {
error_log('[Recaptcha] Token inválido: ' . InvalidReason::name($props->getInvalidReason()));
return false;
}
return $response->getRiskAnalysis()->getScore() >= 0.5;
} catch (Exception $e) {
error_log('[Recaptcha] Erro: ' . $e->getMessage());
return false;
}
}
}¶ Exemplo de uso
- Este código é compatível com qualquer reCAPTCHA configurado no seu projeto, desde que a chave JSON do backend (conta de serviço) correspondente tenha sido gerada corretamente.
- Com isso, sua API backend pode receber requisições contendo:
- O token gerado pelo reCAPTCHA no frontend (fornecido pela Google)
- O site key, que é a chave pública utilizada pelo frontend para solicitar esse token
- O site key é necessário para o Google emitir o token, e o backend utiliza o método isValid() da classe RecaptchaHelper para validar esse token com base na chave privada (JSON) do projeto.
- Caso seu endpoint esteja destinado a apenas uma aplicação específica, o envio do site key pelo frontend torna-se opcional, você pode fixá-lo diretamente no código. No entanto, essa abordagem que apresentei é mais flexível e permite abstrair essa dependência, tornando seu backend capaz de atender múltiplas aplicações com diferentes chaves.
if (!RecaptchaHelper::isValid($recaptchaToken, $recaptchaSiteKey)) {
//Não foi possível validar sua ação.
}
¶ 3. Criando uma Chave reCAPTCHA no Google Cloud para o frontend
¶ Acesse o Console do reCAPTCHA
- Acesse o Console do Google Cloud.
- Selecione o mesmo projeto que ativamos o reCAPTCHA para o backend.
- Acesse no menu “Segurança > reCAPTCHA”.
¶ Crie a Chave do reCAPTCHA
- Na tela que abriu clique em “Criar Chave”.
- Crie sua chave conforme sua necessidade, segui o padrão abaixo pois trata-se de um ambiente de desenvolvimento e testes, caso contrário se preocupe em preencher o pacote android se for gerar algo produtivo.
- Nome de exibição: app_example;
- Tipo de aplicativo: Android;
- Lista de pacote do Android: Desativar a verificação do nome do pacote;
- Suporte a aplicativos distribuídos fora da Google Play Store: sim.
- Clique em “Create Key”.
¶ Obtenha Site Key
- Copie o Site Key e salve-o para usarmos em nosso frontend.
¶ 4. App Android (Kotlin + Jetpack Compose)
- Para gerar o código abaixo, usei a seguinte documentação do Google.
¶ Dependência:
- libs.versions.toml
[versions]
...
recaptcha = "18.7.0-beta01"
[libraries]
...
recaptcha = { module = "com.google.android.recaptcha:recaptcha", version.ref = "recaptcha" }
- build.gradle.kts (Module :app)
dependencies {
...
implementation(libs.recaptcha)
}¶ Criar o Helper RecaptchaHelper.kt
package br.com.fbsantos.util
import android.app.Application
import android.util.Log
import com.google.android.recaptcha.*
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.launch
object RecaptchaHelper {
private const val SITE_KEY = "6MockT0kenAAAAAFakeRecaptcha4TestOnly!!"
private var recaptchaClient: RecaptchaClient? = null
private val recaptchaScope = CoroutineScope(Dispatchers.IO)
fun initialize(application: Application) {
recaptchaScope.launch {
try {
recaptchaClient = Recaptcha.fetchClient(application, SITE_KEY)
Log.d("reCAPTCHA", "Cliente inicializado")
} catch (e: RecaptchaException) {
Log.e("reCAPTCHA", "Erro ao inicializar: ${e.message}", e)
}
}
}
private fun executeLoginAction(onTokenReceived: (String?, String?) -> Unit) {
val client = recaptchaClient ?: return onTokenReceived(null, null)
recaptchaScope.launch {
try {
client.execute(RecaptchaAction.LOGIN)
.onSuccess { token ->
onTokenReceived(token, SITE_KEY)
}
.onFailure { exception ->
Log.e("reCAPTCHA", "Erro na execução: ${exception.message}", exception)
onTokenReceived(null, null)
}
} catch (e: Exception) {
Log.e("reCAPTCHA", "Exceção inesperada: ${e.message}", e)
onTokenReceived(null, null)
}
}
}
fun exec(
before: (() -> Unit)? = null,
after: (() -> Unit)? = null,
onSuccess: (String, String) -> Unit,
onError: (String) -> Unit
) {
before?.invoke()
executeLoginAction { token, siteKey ->
after?.invoke()
if (token != null && siteKey != null) {
onSuccess(token, siteKey)
} else {
onError("Falha ao validar reCAPTCHA. Tente novamente.")
}
}
}
}- Basicamente funciona assim:
- initialize: inicializa o cliente reCAPTCHA com a SITE_KEY chamaremos ele mais abaixo.
- executeLoginAction: executa a ação LOGIN do reCAPTCHA e retorna o token e site key, a ideia é que ele seja privado para minha utilização pois exec já trata tudo que preciso.
- exec: encapsula a execução do reCAPTCHA com callbacks para before/after/sucesso/erro. Este é o método que usarei…
¶ App Global (App.kt)
- É necessário criar essa classe App que estende Application para inicializar o cliente do reCAPTCHA Enterprise globalmente, assim que a aplicação for lançada. Assim consumimos o método initialize do RecaptchaHelper.
package br.com.fbsantos
import android.app.Application
import br.com.fbsantos.util.RecaptchaHelper
class App : Application() {
override fun onCreate() {
super.onCreate()
RecaptchaHelper.initialize(this)
}
}¶ Uso na tela de Login (Jetpack Compose):
Button(
onClick = {
RecaptchaHelper.exec(
before = { setFormEnabled(false) },
after = { setFormEnabled(true) },
onSuccess = { token, siteKey ->
onLoginClicked(token, siteKey)
},
onError = { erro ->
setError(erro)
}
)
},
modifier = Modifier.fillMaxWidth(),
shape = RoundedCornerShape(50),
colors = ButtonDefaults.buttonColors(
containerColor = MaterialTheme.colorScheme.primary,
contentColor = MaterialTheme.colorScheme.onPrimary
),
enabled = state.isFormEnabled
) {
Text("Entrar")
}- Agora é só alegria!
- Se reparar o código chama onLoginClicked que recebe agora o token e o siteKey publico. Basta o método onLoginClicked fazer uma request para o seu endpoint do backend enviando o token e o siteKey e tudo autenticará bonitinho!
¶ Conclusão
Implementando este processo, firmamos um backend mais seguro, dificultando os invasores com os seguintes pontos:
- Proteção avançada contra bots e fraudes: detecta com mais precisão interações maliciosas (bots, scraping, automações) com base em IA e análise comportamental;
- Personalização por risco e contexto: você pode configurar políticas de segurança específicas por tipo de ação (login, envio de formulário, etc.) e tomar decisões automatizadas com base na pontuação de risco;
- Integração com segurança corporativa (SIEM, IAM, etc.): pode ser integrado a sistemas de segurança empresarial para auditoria, monitoramento e resposta a incidentes;
- Sem fricção para o usuário: a maioria das interações ocorre sem desafios visuais, mantendo a experiência do usuário fluida e sem "clique aqui para provar que não é um robô";
- Suporte corporativo e SLA: ideal para aplicações críticas, pois o Enterprise oferece suporte técnico, garantias de disponibilidade e conformidade com normas de segurança;
- Escalabilidade e confiabilidade: projetado para grandes volumes de tráfego com alta disponibilidade e desempenho consistente.
Eu sei, eu sei, você vai falar que tem custo, que é caro e tudo mais… mas veja você tem até 10.000 avaliações gratuitas por mês!
Não da pra começar assim? Se pra você não dá, ok, tem outras plataformas gratuitas! Mas pra mim dá! E é isso que importa! kkkkkkk…
Valeu, falooow!