Authentifizierungs- und Sitzungs-API

Übersicht

Die v2-API verwendet sitzungsbasierte Authentifizierung. Die Anmeldung erfolgt über POST /auth/login. Bei Erfolg wird eine Sitzung aufgebaut und ein CSRF-Token ausgestellt.

Für zustandsändernde Anfragen (POST) ist der X-Fess-CSRF-Token-Header erforderlich. Informationen zum Abrufen und Rotieren des CSRF-Tokens sowie zum gemeinsamen Antwort-Envelope und Fehlermodell finden Sie unter API-Übersicht.

Diese Seite beschreibt die folgenden vier Endpunkte:

Endpunktübersicht

Endpunkt	Methode	Beschreibung
/auth/me	GET	Ruft den aktuell authentifizierten Benutzer ab.
/auth/login	POST	Meldet den Benutzer mit Benutzername und Passwort an.
/auth/logout	POST	Meldet den Benutzer ab (idempotent).
/auth/password	POST	Ändert das Passwort des aktuellen Benutzers.

Gemeinsame Benutzerinformationen (UserPayload)

Die in den Antworten von GET /auth/me und POST /auth/login enthaltenen Benutzerinformationen werden in einer gemeinsamen UserPayload-Struktur zurückgegeben. Alle Array-Felder sind nicht-null; bei fehlenden Werten wird ein leeres Array zurückgegeben.

UserPayload

Feld	Typ	Beschreibung
user_id	string	Benutzer-ID. (Pflichtfeld)
username	string	Angezeigter Benutzername für das Kontomenü der SPA. Derzeit identisch mit user_id, kann aber künftig vom Backend unabhängig bereitgestellt werden. (Pflichtfeld)
name	string	Angezeigter Name für das Kontomenü der SPA. Derzeit identisch mit user_id. (Pflichtfeld)
roles	string[]	Array der Benutzerrollen. (Pflichtfeld)
groups	string[]	Array der Benutzergruppen. (Pflichtfeld)
permissions	string[]	Array der Benutzerberechtigungen. (Pflichtfeld)
editable	boolean	Gibt an, ob die Benutzerinformationen bearbeitbar sind. (Pflichtfeld)
admin	boolean	Wird true, wenn der Benutzer eine der konfigurierten authentication.admin.roles besitzt. Steuert die Anzeige des Menüpunkts „Verwaltung“ in der SPA. (Pflichtfeld)

Authentifizierungsstatus abrufen

Anfrage

HTTP-Methode	GET
Endpunkt	/api/v2/auth/me

Ruft den aktuell authentifizierten Benutzer ab. Bei anonymen Aufrufen wird kein Fehler zurückgegeben, sondern authenticated: false. Bei authentifizierten Aufrufen enthält user eine UserPayload.

Antwort

Bei Erfolg (HTTP 200) wird eine Antwort im gemeinsamen Envelope-Format zurückgegeben (Beispiel für authentifizierten Benutzer):

{
  "response": {
    "status": 0,
    "authenticated": true,
    "user": {
      "user_id": "taro",
      "username": "taro",
      "name": "taro",
      "roles": ["admin"],
      "groups": [],
      "permissions": ["1taro"],
      "editable": true,
      "admin": true
    }
  }
}

Die einzelnen Elemente von response sind wie folgt beschrieben:

Antwortinformationen

Feld	Typ	Beschreibung
authenticated	boolean	Gibt an, ob der Benutzer authentifiziert ist. (Pflichtfeld)
user	object	UserPayload. Ist nur vorhanden, wenn authenticated true ist.

Fehlerantwort

Fehlerantwort

Statuscode	Beschreibung
405 Method Not Allowed	Wenn eine nicht unterstützte HTTP-Methode angegeben wurde.
500 Internal Server Error	Wenn ein interner Serverfehler auftritt.

Anmelden

Anfrage

HTTP-Methode	POST
Endpunkt	/api/v2/auth/login

Meldet den Benutzer mit Benutzername und Passwort an. Bei erfolgreicher Anmeldung wird die Servlet-Sitzungs-ID rotiert, ein neues CSRF-Token ausgestellt und die Rate-Limit-Buckets der aufrufenden IP und des Zielbenutzers geleert. Bei Überschreitung des Rate-Limits wird ein Retry-After-Header (in Sekunden) beigefügt.

Auch bei bereits authentifizierten Sitzungen wird kein Kurzschluss durchgeführt; die übermittelten Anmeldedaten werden stets überprüft.

return_to muss ein relativer Pfad sein, der dem Muster ^/[A-Za-z0-9_\-/.?&=%:@+~#*!,;]*$ entspricht. Außerdem werden protokollrelative Pfade (führendes //) und Pfade mit ASCII-Steuerzeichen abgelehnt und stillschweigend aus der Echo-Antwort entfernt.

Bemerkung

Dieser Endpunkt ist von der CSRF-Überprüfung ausgenommen (da vor der Anmeldung kein Token vorhanden ist).

Bemerkung

Anders als bei anderen zustandsändernden Endpunkten fasst dieser Endpunkt übermäßig große Request-Bodys und nicht unterstützte Content-Type-Werte zu 400 invalid_request zusammen (andere Endpunkte geben 413 bzw. 415 zurück).

Anfrage-Body (LoginRequest)

Content-Type ist application/json.

LoginRequest

Feld	Typ	Pflicht	Beschreibung
username	string	Ja	Benutzername. minLength ist 1.
password	string	Ja	Passwort. minLength ist 1.
return_to	string	Nein	Weiterleitungsziel nach der Anmeldung. Muss ein relativer Pfad sein, der dem oben genannten Muster entspricht.

Anfrage-Beispiel:

{
  "username": "taro",
  "password": "secret",
  "return_to": "/search"
}

Antwort

Bei Erfolg (HTTP 200, LoginResponse) wird eine Antwort im gemeinsamen Envelope-Format zurückgegeben:

{
  "response": {
    "status": 0,
    "user": {
      "user_id": "taro",
      "username": "taro",
      "name": "taro",
      "roles": ["admin"],
      "groups": [],
      "permissions": ["1taro"],
      "editable": true,
      "admin": true
    },
    "csrf_token": "0c1f2e3d4a5b6c7d8e9f",
    "return_to": "/search"
  }
}

Die einzelnen Elemente von response sind wie folgt beschrieben:

Antwortinformationen

Feld	Typ	Beschreibung
user	object	UserPayload.
csrf_token	string	Neues CSRF-Token, das mit der neuen Sitzung verknüpft ist. (Pflichtfeld)
return_to	string	Wird nur zurückgegeben, wenn der Anfragewert die Zulässigkeitsprüfung bestanden hat.

Fehlerantwort

Fehlerantwort

Statuscode	Beschreibung
400 Bad Request	Wenn die Anfrage ungültig ist (einschließlich übermäßig großer Request-Bodys und nicht unterstützter Content-Type-Werte).
401 Unauthorized	Wenn die Anmeldedaten ungültig sind.
405 Method Not Allowed	Wenn eine nicht unterstützte HTTP-Methode angegeben wurde.
429 Too Many Requests	Wenn das Rate-Limit überschritten wurde. Der Retry-After-Header gibt die Wartezeit in Sekunden an.
500 Internal Server Error	Wenn ein interner Serverfehler auftritt.

Abmelden

Anfrage

HTTP-Methode	POST
Endpunkt	/api/v2/auth/logout

Meldet den Benutzer ab. Diese Operation ist idempotent; auch wenn keine aktive Sitzung vorhanden ist, wird sie als No-op behandelt und kein Fehler zurückgegeben. Es wird stets ok: true zurückgegeben.

Der X-Fess-CSRF-Token-Header ist erforderlich.

Antwort

Bei Erfolg (HTTP 200, OkResponse) wird eine Antwort im gemeinsamen Envelope-Format zurückgegeben:

{
  "response": {
    "status": 0,
    "ok": true
  }
}

Die einzelnen Elemente von response sind wie folgt beschrieben:

Antwortinformationen

Feld	Typ	Beschreibung
ok	boolean	Stets true. (Pflichtfeld)

Fehlerantwort

Fehlerantwort

Statuscode	Beschreibung
403 Forbidden	Wenn der CSRF-Token fehlt oder abgelaufen ist.
405 Method Not Allowed	Wenn eine andere Methode als POST angegeben wurde. Es wird ein Allow: POST-Header beigefügt.

Passwort ändern

Anfrage

HTTP-Methode	POST
Endpunkt	/api/v2/auth/password

Ändert das Passwort des aktuellen Benutzers. Überprüft current_password, wendet die konfigurierte Passwortrichtlinie auf new_password an, invalidiert die aktuelle Sitzung und fordert die SPA durch re_login_required: true zur Weiterleitung zur Anmeldeseite auf.

Da die Sitzung serverseitig zerstört wird, wird kein csrf_token zurückgegeben. Die SPA muss nach erneuter Authentifizierung ein neues Token abrufen.

Der X-Fess-CSRF-Token-Header ist erforderlich.

Anfrage-Body (PasswordChangeRequest)

Content-Type ist application/json.

PasswordChangeRequest

Feld	Typ	Pflicht	Beschreibung
current_password	string	Ja	Aktuelles Passwort. minLength ist 1.
new_password	string	Ja	Neues Passwort. Muss die konfigurierte Passwortrichtlinie erfüllen. minLength ist 1.
confirm_password	string	Ja	Bestätigungspasswort. Muss mit new_password übereinstimmen. minLength ist 1.

Antwort

Bei Erfolg (HTTP 200) wird eine Antwort im gemeinsamen Envelope-Format zurückgegeben:

{
  "response": {
    "status": 0,
    "ok": true,
    "re_login_required": true
  }
}

Die einzelnen Elemente von response sind wie folgt beschrieben:

Antwortinformationen

Feld	Typ	Beschreibung
ok	boolean	Stets true. (Pflichtfeld)
re_login_required	boolean	Stets true. Die aktuelle Sitzung wurde serverseitig invalidiert. Die SPA muss zur Anmeldeseite weiterleiten, um eine neue Sitzung und ein neues CSRF-Token zu erhalten. (Pflichtfeld)

Fehlerantwort

Fehlerantwort

Statuscode	Beschreibung
400 Bad Request	Wenn die Anfrage ungültig ist.
401 Unauthorized	Wenn Authentifizierung erforderlich ist oder current_password ungültig ist.
403 Forbidden	Wenn der CSRF-Token fehlt oder abgelaufen ist.
405 Method Not Allowed	Wenn eine nicht unterstützte HTTP-Methode angegeben wurde.
413 Payload Too Large	Wenn der Request-Body die Größenbegrenzung überschreitet.
415 Unsupported Media Type	Wenn ein nicht unterstützter Content-Type angegeben wurde.
429 Too Many Requests	Wenn das Rate-Limit überschritten wurde.
500 Internal Server Error	Wenn ein interner Serverfehler auftritt.