Autenticazione OAuth 2.0

This page is not available in the language you requested. You have been redirected to the English version of the page.
Link to this page copied to clipboard
Not for use with personal data

Panoramica

OAuth 2.0 è un'alternativa all'autenticazione con chiave API disponibile per tutti gli utenti del server axe MCP. Utilizza il flusso Authorization Code con PKCE e conserva i token in modo sicuro nel portachiavi del tuo sistema operativo, quindi ti autentichi una volta sola e la CLI gestisce automaticamente il rinnovo del token.

L'autenticazione è gestita da @deque/axe-auth, una CLI standalone che installi separatamente sulla tua macchina host.

Prerequisiti

  • Node.js 22 LTS o successivo
  • Docker installato e funzionante

Fase 1: Autenticazione

Esegui il comando di accesso:

npx @deque/axe-auth login

La CLI:

  1. Apre il tuo browser predefinito sulla pagina di accesso
  2. Ti chiede di accedere con le credenziali del tuo account axe
  3. Conserva i token risultanti in modo sicuro nel portachiavi del tuo sistema
note

Il tuo sistema operativo potrebbe chiederti di concedere l'accesso al portachiavi la prima volta che i token vengono memorizzati.

Quando completo, il terminale conferma:

✓ Authenticated.

Devi eseguire login solo una volta per macchina. Alle invocazioni successive, npx @deque/axe-auth token rinnova il tuo token di accesso in modo silenzioso utilizzando il token di aggiornamento memorizzato.

Cloud privato, regioni non-USA o installazioni on-premises

Se la tua organizzazione utilizza un cloud privato o un'istanza axe on-premises, passa l'URL della tua istanza con --server (o imposta la AXE_SERVER_URL variabile di ambiente):

npx @deque/axe-auth login --server https://your-axe-instance.example.com

Fase 2: Configura il tuo IDE

Usa @deque/axe-auth token nella configurazione del tuo cliente MCP per iniettare un token di accesso valido nel contenitore Docker ogni volta che il server si avvia. Avvolgi il comando Docker con sh -c in modo che la shell possa sostituire il token — i file di configurazione MCP sono JSON e non espandono $(...) direttamente:

note

Imposta o AXE_API_KEY o AXE_ACCESS_TOKEN — non entrambi. Il server fallirà all'avvio se entrambe le variabili sono impostate.

Scegli il tuo IDE per istruzioni di configurazione specifiche:

Ogni pagina di configurazione include una sezione di configurazione OAuth insieme alle istruzioni per la chiave API.

Gestione delle sessioni

Durata del token

I token di accesso OAuth hanno una durata breve. Se una sessione dura più a lungo della durata del token, il server restituirà errori di autenticazione.

Soluzione: Riavvia la connessione del server MCP nel tuo IDE. La configurazione esegue di nuovo @deque/axe-auth token a ogni avvio del server, ottenendo automaticamente un token fresco.

Disconnessione

Per revocare i tuoi token sul server e cancellarli dal portachiavi di sistema:

npx @deque/axe-auth logout

Se la revoca lato server fallisce (ad esempio, a causa di un errore di rete), i token locali vengono comunque cancellati e viene stampato un avviso.

Ri-autenticazione

Se il tuo token di aggiornamento è scaduto o è stato revocato, @deque/axe-auth token si chiude con codice 1 e ti chiede di accedere di nuovo. Esegui npx @deque/axe-auth login di nuovo. Passa --force per saltare la richiesta di conferma della ri-autenticazione:

npx @deque/axe-auth login --force

Riferimento ai Comandi

login

Apre un browser, completa il flusso di Autorizzazione del Codice OAuth 2.0 + PKCE, e conserva i token nel portachiavi del sistema operativo.

npx @deque/axe-auth login [options]
Flag Descrizione
--server <url> URL di base della tua istanza di axe. Di default è https://axe.deque.com. Necessario solo per cloud privati, regioni non USA, o installazioni on-premise.
--force Salta la conferma di ri-autenticazione quando sei già loggato.
--allow-insecure-issuer Permetti URL http non loopback (il default è solo https; http loopback è sempre permesso). Si applica solo a login ; token e logout usano la policy persista al login.
--no-allow-insecure-issuer Forza allowInsecureIssuer=false per il nuovo login (e l'elemento che conserva). Mutuamente esclusivo con --allow-insecure-issuer. token e logout ignorano questo flag.

token

Stampa un token di accesso valido attualmente su stdout. Si aggiorna silenziosamente se il token memorizzato è scaduto. Esce con il codice 1 se non autenticato.

npx @deque/axe-auth token

logout

Revoca il token di refresh memorizzato sul server e cancella l'elemento nel portachiavi locale.

npx @deque/axe-auth logout

--help

Mostra informazioni di aiuto per @deque/axe-auth e i suoi comandi.

npx @deque/axe-auth --help
npx @deque/axe-auth <command> --help

Supporto della Piattaforma

Piattaforma Conservazione Token
macOS Portachiavi macOS
Windows Gestore Credenziali Windows
Linux D-Bus Secret Service (GNOME Keyring, KWallet, ecc.)
caution

**Linux:** @deque/axe-auth richiede un servizio D-Bus Secret funzionante. Gli ambienti headless o con desktop minimale potrebbero non averlo disponibile. Se vedi un errore come:

System keychain load failed: <details>. On Linux this usually means no D-Bus Secret Service is running (e.g. GNOME Keyring or KWallet).

chiedi all'amministratore del sistema di configurare GNOME Keyring o un provider di Secret Service compatibile.

Risoluzione dei Problemi

Il browser non si apre automaticamente

Se login non può aprire un browser, stampa l'URL di autorizzazione nel terminale. Copia l'URL e aprilo manualmente per completare l'autenticazione.

Scadenza del token durante sessioni lunghe

Vedi durata del token sopra. Riavvia la connessione al server MCP nel tuo IDE per ottenere un nuovo token.

Errore "Non autenticato" da token

La tua sessione è scaduta o i token sono stati cancellati. Esegui di nuovo npx @deque/axe-auth login per ri-autenticarti.

Errori di autenticazione del server MCP

  • Conferma solo che AXE_ACCESS_TOKEN è impostato (non AXE_API_KEY)
  • Conferma che AXE_SERVER_URL corrisponde al tuo URL dell'istanza axe — questo dovrebbe essere lo stesso URL usato con --server durante l'accesso (o https://axe.deque.com se hai usato il predefinito)
  • Esegui npx @deque/axe-auth token direttamente nel tuo terminale per confermare che hai un token valido
  • Se esce con codice 1, ri-autentica con npx @deque/axe-auth login

Keychain Linux non disponibile

Vedi la sezione Supporto Piattaforma sopra.

Is this page helpful?

Help us improve this page

Still need help?