Conectar o LabEx à sua conta da Cloudflare

Introdução

Antes de começar este laboratório ou iniciar sua VM, leia Prepare sua conta de aprendizagem Cloudflare e prepare a conta no navegador. Essa preparação obrigatória não precisa de uma VM LabEx. Continue somente quando seu e-mail de acesso estiver verificado, você puder selecionar sua própria conta dedicada à aprendizagem, Workers Free for o plano atual e você conseguir abrir Workers & Pages nessa conta. Tenha o nome em mãos; LabEx Learning é uma sugestão. Se a conta já estiver pronta, leia o guia e confirme esses pontos antes de continuar.

Você preparou uma conta de aprendizagem da Cloudflare. Agora, conectará um ambiente Linux do LabEx a ela usando o Wrangler, a ferramenta de linha de comando da Cloudflare. O navegador confirma sua identidade, enquanto o Wrangler salva a autorização dentro desta VM. Fazer login apenas no Dashboard não conecta o terminal.

Use uma conta que pertença a você, com um endereço de e-mail verificado e o plano Workers Free, conforme preparado em Preparar sua conta de aprendizagem da Cloudflare. Deixe o nome dela à mão; recomendamos LabEx Learning. Este laboratório solicita acesso de leitura às informações do seu usuário e da sua conta. Ele não implanta aplicações, não exige um domínio e não adiciona serviços pagos.

O laboratório instala automaticamente o Node.js 22.22.0 e o Wrangler 4.131.1. Você usará comandos padrão do Wrangler e a configuração de projeto dele, que também funcionam no seu próprio computador. Você autorizará a conexão, verificará o resultado e encerrará a sessão no final. Cada VM nova precisa de uma nova autorização.

Autorizar o Wrangler pelo navegador

Nesta etapa, você autorizará o Wrangler na sua VM do LabEx usando seu próprio login da Cloudflare.

Abra o Terminal do LabEx e entre no diretório do projeto preparado. O comando cd altera o diretório de trabalho; os comandos seguintes serão executados nesse diretório.

cd /home/labex/project/cloudflare-connect

O Wrangler está instalado localmente neste projeto como uma dependência de desenvolvimento. npx wrangler executa essa versão instalada. A configuração já instalou o Node.js e as dependências do projeto, portanto você não precisa instalá-los novamente. Verifique a versão:

npx wrangler --version

A versão esperada é 4.131.1. O arquivo package.json do projeto fixa exatamente essa versão, enquanto package-lock.json registra as versões resolvidas das dependências. No seu próprio computador, depois de instalar o Node.js, você pode adicionar o Wrangler a um projeto usando npm install --save-dev --save-exact wrangler@4.131.1. Isso é apenas uma explicação, não um comando adicional para executar no laboratório preparado. Use npm ci ao reproduzir um projeto existente com o arquivo de bloqueio versionado.

A instalação local no projeto mantém a versão da ferramenta independente em cada projeto. Consulte as orientações de instalação da Cloudflare.

Agora inicie a autorização do dispositivo. --device conecta a aprovação feita no navegador a este terminal remoto sem usar um callback localhost. --browser=false impede que o Wrangler tente abrir um navegador dentro da VM. Os dois escopos solicitam acesso de leitura à conta e ao usuário para este exercício de conexão. A Cloudflare também inclui o acesso obrigatório Background Access para que o Wrangler possa manter a autorização. Nenhuma permissão de gravação em Workers é solicitada.

npx wrangler login --device --browser=false --scopes account:read user:read

O Wrangler exibirá uma URL de verificação e um código curto. Mantenha este comando em execução. Abra a URL da Cloudflare exibida no seu próprio navegador, informe o código mostrado no seu terminal atual e continue. Se a URL já incluir o código, confira se ele corresponde ao código do terminal. Não use um código de uma captura de tela ou da sessão de outra pessoa.

Formulário de autorização de dispositivo da Cloudflare com o campo de código vazio

Copie o código diretamente do terminal para evitar confundir caracteres semelhantes. Selecione Continue. Se a Cloudflare não conseguir verificar o código, confira os caracteres exatos e se o comando de login atual ainda está aguardando.

Faça login, se solicitado. Na página de consentimento, confirme que a aplicação é o Wrangler, revise as permissões solicitadas e selecione apenas sua conta de aprendizagem, caso a seleção de conta seja oferecida. A página de consentimento agrupa Account Read em Account & Billing; expanda esse grupo para inspecioná-lo. User Read e Background Access aparecem em Required.

Permissões de consentimento do Wrangler mostrando User Read, Background Access e Account Read

Confira o nome da conta ao lado de Edit. Se não for sua conta de aprendizagem, selecione Edit e escolha a conta pretendida antes de retornar ao consentimento. A captura de tela recortada abaixo mostra a conta selecionada e o botão Authorize; sua identidade de login aparece acima desta área na página completa.

Conta LabEx Learning selecionada com os controles Edit e Authorize

Revise as informações de privacidade exibidas e selecione Authorize depois de conferir esses detalhes. Volte ao Terminal e aguarde a mensagem Successfully logged in. antes de continuar. A aprovação no navegador e a conclusão no terminal são etapas de verificação separadas.

Cloudflare confirma que a autorização do Wrangler foi concedida

A página de sucesso inclui sugestões gerais de desenvolvimento. Você não precisa instalar ferramentas de agentes nem copiar o prompt sugerido. A mensagem genérica de implantação não amplia as permissões de leitura deste laboratório.

O código expira após um curto período. Se ele expirar ou você negar a solicitação, deixe o comando terminar ou pressione Ctrl+C e execute o mesmo comando para obter um novo código. Se você iniciar acidentalmente o login comum e vir uma página localhost inacessível, interrompa esse comando e use o comando de dispositivo acima.

Confirme o login armazenado usando o próprio Wrangler:

npx wrangler whoami --json

Procure por "loggedIn": true, "authType": "OAuth Token" e uma matriz accounts que contenha sua conta de aprendizagem. Cada objeto de conta tem um name e um id. A opção --json retorna dados estruturados em vez do relatório legível; você não precisa entender as outras configurações da conta. Uma página de sucesso no navegador, sozinha, não é suficiente se a VM não tiver recebido a autorização. Se o Wrangler informar que você não está autenticado, repita a autorização do dispositivo.

Use o botão de verificação da etapa. O LabEx verifica independentemente se o login OAuth armazenado nesta VM consegue ler as contas acessíveis.

O Wrangler armazena as credenciais na configuração do usuário da VM. Não imprima nem copie arquivos de credenciais e não execute comandos que exibam tokens. A documentação oficial de login do Wrangler descreve o fluxo de dispositivo.

Selecionar e verificar sua conta de aprendizagem

Nesta etapa, você identificará sua conta de aprendizagem e salvará o ID dela na configuração padrão do projeto do Wrangler.

Um único login pode acessar várias contas. Execute o mesmo comando de identidade para ver os nomes e IDs delas na matriz accounts:

npx wrangler whoami --json

Encontre o objeto cujo name identifica sua conta de aprendizagem. Se aparecer apenas uma conta, ainda confira o nome dela. Se aparecerem várias, use o seletor de contas do Dashboard para confirmar qual é sua conta de aprendizagem. Não selecione uma conta apenas porque ela aparece primeiro. Se a conta pretendida não estiver presente, repita a autorização e selecione-a no navegador.

Copie o id de 32 caracteres desse mesmo objeto de conta. O nome da conta é um rótulo de exibição; o ID identifica a conta real. A configuração account_id do Wrangler torna explícito o destino do projeto, inclusive quando seu login pode acessar várias contas.

Crie wrangler.jsonc. Substitua YOUR_ACCOUNT_ID abaixo pelo ID que você acabou de copiar antes de executar o bloco. Mantenha as aspas. O here-document grava no arquivo tudo o que estiver entre os delimitadores CONFIG; > substitui o conteúdo existente.

cat > wrangler.jsonc <<'CONFIG'
{
  "account_id": "YOUR_ACCOUNT_ID"
}
CONFIG

Inspecione a configuração salva:

cat wrangler.jsonc

Confirme que account_id corresponde ao objeto da conta de aprendizagem em whoami --json e que o marcador de posição foi removido. Este arquivo contém um identificador, não uma senha nem um token OAuth. JSON sem comentários é um JSONC válido; use o formato mostrado neste laboratório. Laboratórios posteriores adicionarão configurações de Worker ao mesmo arquivo de configuração padrão. Consulte Configuração do Wrangler.

Use o botão de verificação desta etapa antes de encerrar a sessão. O backend lê sua configuração e faz uma solicitação autenticada de leitura à conta. Ele verifica se a Cloudflare confirma o acesso exatamente àquela conta; salvar o arquivo, por si só, não é suficiente. Se houver falha, confira o ID copiado, a autorização e a conectividade. Nenhum comando personalizado é necessário no seu terminal.

Isso verifica o acesso de leitura à conta. Laboratórios posteriores solicitarão permissões adicionais para implantação.

Desconectar esta VM

Nesta etapa, você removerá o login do Wrangler desta VM e verificará se ela não está mais autenticada.

Conclua primeiro a verificação da etapa anterior. Encerrar a sessão remove a autorização necessária para a verificação da API em tempo real. Nenhum recurso de nuvem foi criado neste laboratório, portanto não há aplicações nem contas para excluir.

Execute o comando de logout do Wrangler:

npx wrangler logout

Em seguida, confirme o estado explícito de não autenticado:

npx wrangler whoami --json

Procure por "loggedIn": false na saída estruturada. Nesta versão do Wrangler, o comando também termina com um código diferente de zero quando a sessão está encerrada; isso é esperado aqui. Um erro de rede sem esse estado explícito não comprova que o logout ocorreu. Use o botão de verificação da etapa para confirmar o resultado de forma independente.

Você também pode revisar a concessão da aplicação no Dashboard, em My Profile → Access Management → Connected Applications, conforme o link da página de consentimento. É nesse local que a Cloudflare permite gerenciar ou revogar o acesso de uma aplicação. Revogue apenas a concessão que você pretende remover; outro ambiente pode usar a mesma aplicação.

Encerrar a sessão do Wrangler não exclui sua conta de aprendizagem da Cloudflare nem encerra a sessão do navegador no Dashboard. Mantenha a conta para as próximas aulas. O arquivo wrangler.jsonc contém um identificador, não credenciais, mas não autoriza uma VM nova. O próximo laboratório começará com um ambiente novo e suas próprias etapas de conexão.

Se você executar novamente uma verificação anterior depois deste ponto, a falha de autenticação será esperada. Autorize novamente apenas se quiser repetir o exercício e encerre a sessão outra vez ao terminar.

Resumo

Você autorizou uma VM remota do LabEx usando o fluxo de dispositivo da Cloudflare, selecionou sua própria conta de aprendizagem e verificou o acesso à conta em tempo real a partir de um processo independente. Em seguida, encerrou a sessão do Wrangler e confirmou o estado explícito de não autenticado.

Sua conta de aprendizagem continua disponível para o curso. O login no navegador, a autorização da VM e a conta selecionada são partes separadas da conexão; verifique as três sempre que iniciar um ambiente novo.