Authentifizierung

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

Der Axe-MCP-Server unterstützt zwei Authentifizierungsmethoden. Beide stehen allen Nutzern zur Verfügung – wählen Sie diejenige, die zu Ihrem Workflow passt:

  • API-Schlüssel — ein langlebiger Schlüssel, der im axe Account-Portal generiert wird. Am einfachsten einzurichten.
  • OAuth 2.0 — browserbasierte Anmeldung über die @deque/axe-auth CLI, mit Tokens, die in Ihrem Betriebssystem-Schlüsselspeicher gespeichert und automatisch aktualisiert werden.

Sie konfigurieren das gewählte Anmeldeinformation in Ihrem Client-Einrichtungsleitfaden. Jede Einrichtungsseite zeigt sowohl API-Schlüssel- als auch OAuth-Konfigurationen nebeneinander an.

note

Setzen Sie entweder AXE_API_KEY oder AXE_ACCESS_TOKEN — nicht beide. Der Server wird beim Start fehlschlagen, wenn beide Variablen gesetzt sind.

API-Schlüssel

  1. Melden Sie sich beim Axe Account-Portal an
  2. Navigieren Sie zu dem API-Schlüssel-Seite
  3. Klicken Sie auf NEUEN API-SCHLÜSSEL HINZUFÜGEN
  4. Wählen Sie Axe MCP Server als Produkt aus
  5. Geben Sie einen beschreibenden Namen für Ihren API-Schlüssel ein
  6. Klicken Sie auf Speichern
  7. Kopieren Sie den generierten API-Schlüssel — Sie werden ihn als AXE_API_KEY-Umgebungsvariable an den Server übergeben

OAuth 2.0

OAuth 2.0 verwendet den Authorization Code Flow mit PKCE und speichert Tokens sicher in Ihrem Betriebssystem-Schlüsselbund, sodass Sie sich einmal authentifizieren und das CLI die Token-Aktualisierung automatisch übernimmt.

Die Authentifizierung wird von @deque/axe-auth verwaltet, einer eigenständigen CLI, die separat auf Ihrem Host-Computer installiert wird.

Voraussetzungen

  • Node.js 22.13.0 oder neuer, was @deque/axe-auth erfordert (die npm-Distribution des Servers selbst benötigt 22.19.0 oder neuer)
  • Ihre gewählte axe MCP Server-Distribution ist installiert — siehe Eine Distribution wählen

Schritt 1: Authentifizieren

Führen Sie den Login-Befehl aus:

npx @deque/axe-auth login

Das CLI wird:

  1. Ihren Standardbrowser zur Anmeldeseite öffnen
  2. Sie auffordern, sich mit Ihren Axe-Account-Anmeldeinformationen anzumelden
  3. Die resultierenden Tokens sicher in Ihrem System-Schlüsselbund speichern
note

Möglicherweise fordert Ihr Betriebssystem Sie beim ersten Speichern von Tokens dazu auf, den Zugriff auf den Schlüsselbund zu gewähren.

Nachdem dies abgeschlossen ist, bestätigt das Terminal:

✓ Authenticated.

Sie müssen login nur einmal pro Computer ausführen. Bei nachfolgenden Aufrufen erneuert npx @deque/axe-auth token Ihr Zugriffstoken stillschweigend mit dem gespeicherten Erneuerungstoken.

Private Cloud, Nicht-US-Regionen oder lokale Installationen

Wenn Ihre Organisation eine private Cloud oder eine firmeninterne axe-Instanz verwendet, übergeben Sie die URL Ihrer Instanz mit --server (oder legen Sie die Umgebungsvariable AXE_SERVER_URL fest):

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

Schritt 2: Konfigurieren Sie Ihren Client

Verwenden Sie @deque/axe-auth token in Ihrer MCP-Clientkonfiguration, um jedes Mal, wenn der Server startet, ein gültiges Zugriffstoken einzubinden. Wählen Sie Ihren Client für spezifische Einrichtungshinweise:

Jede Setup-Seite enthält einen OAuth-Konfigurationsabschnitt neben den API-Schlüssel-Anweisungen.

Sitzungen verwalten

Token-Lebensdauer

OAuth-Zugriffstoken sind nur von kurzer Dauer. Eine Konfiguration, die ein Token mit @deque/axe-auth token einbindet, erfasst es einmalig beim Serverstart — sodass eine Agentsitzung, die länger dauert als die Lebensdauer des Tokens, mit Authentifizierungsfehlern beginnt.

Es gibt zwei Möglichkeiten, dies zu handhaben:

  • Empfohlen — den Server unter @deque/axe-auth run betreiben, was das Token während der gesamten Sitzung automatisch aktuell hält.
  • Andernfalls — die MCP-Serververbindung in Ihrem Client neu starten. Die Konfiguration führt @deque/axe-auth token bei jedem Serverstart erneut aus, was ein neues Token holt.

Eine lange Sitzung aufrechterhalten

@deque/axe-auth run startet und überwacht den Axe-MCP-Server und aktualisiert sein Zugriffstoken, bevor es abläuft — so trifft eine Sitzung über Stunden nie auf Token-Ablauf, ohne Neustart und ohne manuelles Eingreifen.

Richten Sie Ihren MCP-Client auf run als Serverbefehl ein, anstatt auf den Server selbst, und leiten Sie den Startbefehl nach -- weiter. Es verwaltet die Lebensdauer des Serverprozesses wie bei jedem anderen stdio-Server.

npm-Distribution:

{
  "command": "npx",
  "args": ["-y", "@deque/axe-auth", "run", "--", "npx", "axe-mcp-server"],
  "env": {
    "AXE_TOKEN_REFRESH_PORT": "9223"
  }
}

Docker-Distribution — veröffentlichen Sie den Aktualisierungsport auf dem Host-Loopback, leiten Sie die Authentifizierungsvariablen in den Container weiter und binden Sie den Listener innerhalb von 0.0.0.0:

{
  "command": "npx",
  "args": [
    "-y",
    "@deque/axe-auth",
    "run",
    "--",
    "docker",
    "run",
    "-i",
    "--rm",
    "-p",
    "127.0.0.1:9223:9223",
    "-e",
    "AXE_ACCESS_TOKEN",
    "-e",
    "AXE_TOKEN_REFRESH_PORT",
    "-e",
    "AXE_TOKEN_REFRESH_SECRET",
    "-e",
    "AXE_TOKEN_REFRESH_HOST=0.0.0.0",
    "dequesystems/axe-mcp-server:latest"
  ],
  "env": {
    "AXE_TOKEN_REFRESH_PORT": "9223"
  }
}
important

AXE_TOKEN_REFRESH_HOST=0.0.0.0 ist unter Docker erforderlich. Ein veröffentlichter Port leitet an die Netzwerkschnittstelle des Containers weiter, nicht an sein Loopback, sodass die Standardeinstellung für Loopback-Bindungen nicht erreichbar wäre. Das Veröffentlichen als 127.0.0.1:9223:9223 hält den Endpunkt von den externen Schnittstellen Ihres Hosts fern, und das geteilte Geheimnis — nicht die Container-Isolation — schützt den Endpunkt selbst.

note

Ihr Aktualisierungstoken verlässt niemals Ihre Maschine. Nur kurzlebige Zugriffstoken werden über eine Loopback-Verbindung, die durch ein von run für die Sitzung generiertes gemeinsames Geheimnis authentifiziert ist, an den Server gesendet. Dies ist dieselbe Isolationseigenschaft, die das Aktualisierungstoken aus dem Container heraushält.

Siehe Token-Aktualisierungsvariablen für die serverseitigen Umgebungsvariablen, die beteiligt sind.

Abmelden

Um Ihre Tokens serverseitig zu widerrufen und aus dem System-Schlüsselbund zu löschen:

npx @deque/axe-auth logout

Wenn der serverseitige Widerruf fehlschlägt (z. B. aufgrund eines Netzwerkfehlers), werden lokale Tokens dennoch gelöscht und eine Warnung wird ausgegeben.

Erneutes Authentifizieren

Wenn Ihr Erneuerungstoken abgelaufen oder widerrufen wurde, beendet sich @deque/axe-auth token mit Code 1 und fordert Sie auf, sich erneut anzumelden. Führen Sie npx @deque/axe-auth login erneut aus. Übergeben Sie --force, um die Bestätigungsaufforderung zur erneuten Authentifizierung zu überspringen:

npx @deque/axe-auth login --force

Befehlsreferenz

login

Öffnet einen Browser, führt den OAuth 2.0 Authorization Code + PKCE Flow durch und speichert Tokens im Betriebssystem-Schlüsselbund.

npx @deque/axe-auth login [options]
Flag Beschreibung
--server <url> Basis-URL Ihrer axe-Instanz. Standardmäßig auf https://axe.deque.com. Nur erforderlich für Privat-Cloud, Nicht-US-Regionen oder firmeninterne Installationen.
--force Bestätigung der erneuten Authentifizierung überspringen, wenn bereits eingeloggt.
--allow-insecure-issuer Erlauben Sie nicht-Loopback-HTTP-URLs (Standard ist nur HTTPS; Loopback-HTTP ist immer erlaubt). Gilt nur für login; token und logout verwenden die bei der Anmeldung gespeicherte Richtlinie.
--no-allow-insecure-issuer Erzwingen Sie allowInsecureIssuer=false für das neue login (und den Eintrag, den es speichert). Kann nicht gleichzeitig mit --allow-insecure-issuer verwendet werden. token und logout ignorieren diese Option.

token

Gibt ein aktuell gültiges Zugriffstoken auf stdout aus. Aktualisiert stillschweigend, wenn das gespeicherte Token abgelaufen ist. Beendet sich mit Code 1, wenn nicht authentifiziert.

npx @deque/axe-auth token

logout

Widerruft das gespeicherte Auffrischungstoken serverseitig und löscht den lokalen Schlüsselbund-Eintrag.

npx @deque/axe-auth logout

run

Startet und überwacht den Axe-MCP-Server und hält dessen Zugriffstoken für die Dauer der Sitzung aktuell. Konfigurieren Sie es als MCP-Client-Serverbefehl anstelle einer manuellen Ausführung. Siehe Eine lange Sitzung aufrechterhalten.

npx @deque/axe-auth run [options] -- <server launch command>
Flag Beschreibung
--port <port> Loopback-Port, der verwendet wird, um aktualisierte Tokens an den Server zu senden. Entspricht AXE_TOKEN_REFRESH_PORT. Optional unter npm: ohne einen bestimmt run einen freien Port für die Sitzung. Erforderlich, wenn der umschlossene Befehl eine Containerumgebung ist (docker, podman oder nerdctl), die nur einen veröffentlichten Port erreichen kann — run lehnt solche ohne fixierten Port ab.
--secret <secret> Gemeinsames Geheimnis zur Authentifizierung jedes Pushs. Entspricht AXE_TOKEN_REFRESH_SECRET. Wird automatisch generiert, es sei denn, Sie setzen einen festen Wert.

Funktioniert mit beiden Distributionen, npm und Docker, auf macOS, Windows und Linux.

--help

Zeigt Hilfeinformationen für @deque/axe-auth und dessen Befehle an.

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

Plattformunterstützung

Plattform Token-Speicherung
macOS macOS-Schlüsselbund
Windows Windows-Anmeldeinformationsverwaltung
Linux D-Bus Secret Service (GNOME Keyring, KWallet, etc.)
caution

Linux: @deque/axe-auth erfordert einen funktionierenden D-Bus Secret Service. Kopflose oder minimale Desktop-Umgebungen haben möglicherweise keinen zur Verfügung. Wenn Sie einen Fehler wie diesen sehen:

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

bitten Sie Ihren Systemadministrator, GNOME Keyring oder einen kompatiblen Secret-Service-Anbieter zu konfigurieren.

OAuth-Fehlerbehebung

Browser öffnet sich nicht automatisch

Wenn login keinen Browser öffnen kann, wird die Autorisierungs-URL im Terminal angezeigt. Kopieren Sie die URL und öffnen Sie sie manuell, um die Authentifizierung abzuschließen.

Token-Ablauf bei langen Sitzungen

Betreiben Sie den Server unter @deque/axe-auth run, das das Token für Sie aktualisiert und das Problem vollständig beseitigt. Ohne dass dies geschieht, starten Sie die MCP-Serververbindung in Ihrem Client neu, um ein neues Token zu erhalten. Siehe Token-Lebensdauer oben.

„Nicht authentifiziert“-Fehler von token

Ihre Sitzung ist abgelaufen oder Tokens wurden gelöscht. Führen Sie npx @deque/axe-auth login erneut aus, um sich erneut zu authentifizieren.

MCP-Server-Authentifizierungsfehler

  • Bestätigen Sie, dass nur AXE_ACCESS_TOKEN gesetzt ist (nicht AXE_API_KEY)
  • Bestätigen Sie, dass AXE_SERVER_URL Ihrer axe-Instanz-URL entspricht — dies sollte die gleiche URL sein, die Sie während der Anmeldung mit --server verwendet haben (oder https://axe.deque.com, wenn Sie den Standard verwendet haben)
  • Führen Sie npx @deque/axe-auth token direkt in Ihrem Terminal aus, um zu bestätigen, dass Sie ein gültiges Token haben
  • Wenn es mit Code 1 beendet wird, authentifizieren Sie sich erneut mit npx @deque/axe-auth login

Linux-Schlüsselbund nicht verfügbar

Siehe den Plattformunterstützung-Hinweis oben.

Is this page helpful?

Help us improve this page

Still need help?