Autenticação OAuth 2.0
Visão Geral
OAuth 2.0 é uma alternativa à autenticação por chave de API disponível para todos os usuários do axe MCP Server. Ele utiliza o Authorization Code Flow com PKCE e armazena tokens de forma segura no seu keychain do sistema operacional, assim você se autentica uma vez e o CLI gerencia a renovação de tokens automaticamente.
A autenticação é gerenciada pelo @deque/axe-auth, um CLI independente que você instala separadamente na sua máquina host.
Pré-requisitos
- Node.js 22 LTS ou posterior
- Docker instalado e em execução
Passo 1: Autenticar
Execute o comando de login:
npx @deque/axe-auth loginO CLI irá:
- Abrir seu navegador padrão na página de login
- Solicitar que você inicie sessão com as credenciais da sua Conta axe
- Armazenar os tokens resultantes de forma segura no keychain do seu sistema
Seu sistema operacional pode solicitar que você conceda acesso ao keychain na primeira vez que os tokens forem armazenados.
Quando completar, o terminal confirma:
✓ Authenticated.Você só precisa executar login uma vez por máquina. Nas invocações subsequentes, npx @deque/axe-auth token renova seu token de acesso silenciosamente usando o token de atualização armazenado.
Nuvem privada, regiões fora dos EUA ou instalações locais
Se sua organização utiliza uma instância axe em nuvem privada ou local, passe a URL da sua instância com --server (ou defina a variável de ambiente AXE_SERVER_URL ):
npx @deque/axe-auth login --server https://your-axe-instance.example.comPasso 2: Configurar seu IDE
Use @deque/axe-auth token na configuração do cliente MCP para injetar um token de acesso válido no contêiner do Docker cada vez que o servidor for iniciado. Envolva o comando Docker com sh -c para que o shell possa substituir o token — arquivos de configuração MCP são JSON e não expandem $(...) diretamente:
Defina ou AXE_API_KEY ou AXE_ACCESS_TOKEN — não ambos. O servidor falhará na inicialização se ambas as variáveis estiverem definidas.
Escolha seu IDE para instruções específicas de configuração:
Cada página de configuração inclui uma seção de configuração OAuth junto com as instruções de chave de API.
Gerenciando Sessões
Tempo de vida do token
Os tokens de acesso OAuth têm vida curta. Se uma sessão durar mais do que o tempo de vida do token, o servidor retornará erros de autenticação.
Solução alternativa: Reinicie a conexão do servidor MCP no seu IDE. A configuração reexecuta @deque/axe-auth token a cada inicialização do servidor, o que busca um novo token automaticamente.
Finalizando sessão
Para revogar seus tokens do lado do servidor e removê-los do keychain do sistema:
npx @deque/axe-auth logoutSe a revogação do lado do servidor falhar (por exemplo, devido a um erro de rede), os tokens locais ainda serão removidos e um aviso será impresso.
Reautenticação
Se seu token de atualização expirou ou foi revogado, @deque/axe-auth token termina com o código 1 e direciona você a fazer login novamente. Execute npx @deque/axe-auth login novamente. Passe --force para pular o aviso de confirmação de re-autenticação:
npx @deque/axe-auth login --forceReferência de Comando
login
Abre um navegador, completa o fluxo OAuth 2.0 Authorization Code + PKCE e salva os tokens no chaveiro do sistema operacional.
npx @deque/axe-auth login [options]| Flag | Descrição |
|---|---|
--server <url> |
URL base da sua instância axe. O padrão é https://axe.deque.com. Apenas necessário para nuvem privada, regiões fora dos EUA, ou instalações locais. |
--force |
Pular confirmação de re-autenticação quando já estiver logado. |
--allow-insecure-issuer |
Permitir URLs http fora do loopback (o padrão é apenas https; http loopback é sempre permitido). Aplica-se a login apenas; token e logout usam a política persistida no login. |
--no-allow-insecure-issuer |
Forçar allowInsecureIssuer=false para o novo login (e a entrada que ele persiste). Mutuamente exclusivo com --allow-insecure-issuer. token e logout ignoram este flag. |
token
Imprime um token de acesso atualmente válido no stdout. Atualiza silenciosamente se o token armazenado estiver expirado. Sai com o código 1 se não estiver autenticado.
npx @deque/axe-auth tokenlogout
Revoga o token de atualização armazenado no lado do servidor e limpa a entrada do chaveiro local.
npx @deque/axe-auth logout--help
Exibe informações de ajuda para @deque/axe-auth e seus comandos.
npx @deque/axe-auth --help
npx @deque/axe-auth <command> --helpSuporte de Plataforma
| Plataforma | Armazenamento de Token |
|---|---|
| macOS | Chaveiro macOS |
| Windows | Gerenciador de Credenciais do Windows |
| Linux | Serviço Secreto D-Bus (GNOME Keyring, KWallet, etc.) |
**Linux:** @deque/axe-auth requer um Serviço Secreto D-Bus funcional. Ambientes sem interface gráfica ou com desktop minimalista podem não ter um disponível. Se você ver um erro como:
System keychain load failed: <details>. On Linux this usually means no D-Bus Secret Service is running (e.g. GNOME Keyring or KWallet).peça ao administrador do sistema para configurar o GNOME Keyring ou um provedor de Serviço Secreto compatível.
Solução de Problemas
Navegador não abre automaticamente
Se login não conseguir abrir um navegador, ele imprime a URL de autorização no terminal. Copie a URL e abra-a manualmente para completar a autenticação.
Expiração de token durante sessões longas
Veja Duração do token acima. Reinicie a conexão do servidor MCP no seu IDE para obter um novo token.
Erro "Não autenticado" do token
Sua sessão expirou ou os tokens foram limpos. Execute npx @deque/axe-auth login novamente para re-autenticar.
Erros de autenticação do servidor MCP
- Confirme que apenas
AXE_ACCESS_TOKENestá definido (nãoAXE_API_KEY) - Confirme
AXE_SERVER_URLque corresponde ao seu URL da instância do axe — este deve ser o mesmo URL usado com--serverdurante o login (ouhttps://axe.deque.comcaso tenha usado o padrão) - Execute
npx @deque/axe-auth tokendiretamente no seu terminal para confirmar que você tem um token válido - Se ele sair com o código
1, re-autentique-se comnpx @deque/axe-auth login
Cadeia de chaves do Linux indisponível
Veja o Suporte de Plataforma acima no destaque.