User API

Übersicht

Die User API ist eine REST API zur Verwaltung von Fess-Benutzerkonten. Sie können Benutzer erstellen, abrufen, aktualisieren und löschen sowie Rollen und Gruppen zuweisen.

Dies ist eine Admin-API; der Zugriff erfordert eine Authentifizierung mit einem Admin-Zugriffstoken. Informationen zur Authentifizierungsmethode und zu den gemeinsamen Spezifikationen finden Sie unter Admin API Übersicht.

Jede Antwort ist in ein response-Objekt eingebettet und enthält die folgenden gemeinsamen Felder:

  • version : Der Fess-Produktversionsstring.

  • status : Der Ergebnisstatuscode (0 =Erfolg, 1 =Ungültige Anfrage, 2 =Systemfehler, 3 =Nicht autorisiert, 9 =Fehlgeschlagen).

Basis-URL

/api/admin/user

Endpunktliste

Methode Pfad Beschreibung
GET /settings Benutzerliste abrufen
GET /setting/{id} Benutzer abrufen
POST /setting Benutzer erstellen
PUT /setting Benutzer aktualisieren
DELETE /setting/{id} Benutzer löschen

Benutzerliste abrufen

Anfrage

GET /api/admin/user/settings

Parameter

Parameter Typ Erforderlich Beschreibung
size Integer Nein Anzahl der Einträge pro Seite. Der Standardwert ist der konfigurierte Wert paging.page.size (Standard: 25).
page Integer Nein Seitennummer (beginnt bei 1). Der Standardwert ist 1.

Bemerkung

In der aktuellen Implementierung berücksichtigt der Endpunkt für die Benutzerliste die Parameter size und page nicht. Es wird immer die erste Seite zurückgegeben, mit der durch die Servereinstellung paging.page.size (Standard: 25) festgelegten Anzahl von Einträgen, sortiert nach Benutzername (name) in aufsteigender Reihenfolge. Die Gesamtanzahl der übereinstimmenden Benutzer ist in response.total verfügbar.

Antwort

{
  "response": {
    "version": "15.9",
    "status": 0,
    "settings": [
      {
        "id": "YWRtaW4=",
        "name": "admin",
        "attributes": {
          "surname": "Administrator",
          "givenName": "System",
          "mail": "admin@example.com"
        },
        "roles": ["YWRtaW4=", "Z3Vlc3Q="],
        "groups": [],
        "version_no": 1
      }
    ],
    "total": 10
  }
}

  • settings : Das Array der Benutzer auf der aktuellen Seite.

  • total : Die Gesamtanzahl der übereinstimmenden Benutzer.

Benutzer abrufen

Anfrage

GET /api/admin/user/setting/{id}

Geben Sie in {id} die Dokument-ID des Zielbenutzers an.

Antwort

{
  "response": {
    "version": "15.9",
    "status": 0,
    "setting": {
      "id": "YWRtaW4=",
      "name": "admin",
      "attributes": {
        "surname": "Administrator",
        "givenName": "System",
        "mail": "admin@example.com",
        "telephoneNumber": "",
        "uidNumber": "",
        "gidNumber": "",
        "homeDirectory": ""
      },
      "roles": ["YWRtaW4=", "Z3Vlc3Q="],
      "groups": [],
      "version_no": 1
    }
  }
}

Bemerkung

attributes enthält alle für den Benutzer gespeicherten Attribute, mit Ausnahme von name, password, roles und groups. password ist nicht in der Antwort enthalten.

Benutzer erstellen

Anfrage

POST /api/admin/user/setting
Content-Type: application/json

Anfrage-Body

{
  "name": "testuser",
  "password": "securepassword",
  "confirm_password": "securepassword",
  "attributes": {
    "surname": "Test",
    "givenName": "User",
    "mail": "testuser@example.com"
  },
  "roles": ["Z3Vlc3Q="],
  "groups": ["group_id_1"]
}

Feldbeschreibungen

Feld Erforderlich Beschreibung
name Ja Benutzername (Login-ID)
password Ja Passwort
confirm_password Nein Bestätigungspasswort
attributes Nein Attribut-Map (siehe unten)
roles Nein Array von Rollen-IDs
groups Nein Array von Gruppen-IDs

Bemerkung

Geben Sie in roles und groups die ID der Rolle bzw. Gruppe an, nicht deren Namen. Eine nicht vorhandene ID (auch ein Rollen- oder Gruppenname) wird mit 400 abgelehnt. Die IDs finden Sie im id der Antworten von GET /api/admin/role/settings und GET /api/admin/group/settings. Die ID einer in der Admin-Oberfläche oder über die API angelegten Rolle oder Gruppe ist ihr Name im Base64-URL-Format (zum Beispiel YWRtaW4= für die standardmäßig vorhandene Rolle admin und Z3Vlc3Q= für guest).

Bemerkung

Für das Passwort gelten dieselben Prüfungen wie in der Admin-Oberfläche. Eine Anlage ohne password, ein confirm_password, das von password abweicht (confirm_password selbst kann entfallen), und ein Passwort, das die Passwortrichtlinie verletzt (password.min.length (Standard 8), password.max.length, password.require.* und password.invalid.admin.passwords in fess_config.properties), werden jeweils mit 400 abgelehnt.

Die Schlüssel von attributes sind die Attributnamen der Benutzerentität (die aus LDAP abgeleiteten Schemaelementnamen). Die häufigsten Schlüssel sind:

  • surname, givenName, displayName, mail

  • telephoneNumber, mobile, homePhone

  • employeeNumber, title, description, homeDirectory

  • uidNumber, gidNumber

uidNumber und gidNumber müssen numerische Werte sein (der Typ wird bei der Aktualisierung validiert). Viele weitere LDAP-Attributschlüssel können ebenfalls angegeben werden.

Bemerkung

Bei der Erstellung wird die Benutzer-ID (Dokument-ID) automatisch als Base64-URL-kodierter Wert des Benutzernamens generiert (zum Beispiel wird der Benutzername admin zu YWRtaW4=).

Antwort

{
  "response": {
    "version": "15.9",
    "status": 0,
    "id": "new_user_id",
    "created": true
  }
}

  • id : Die Dokument-ID des erstellten Benutzers.

  • created : true bei erfolgreicher Erstellung.

Benutzer aktualisieren

Anfrage

PUT /api/admin/user/setting
Content-Type: application/json

Anfrage-Body

{
  "id": "existing_user_id",
  "name": "testuser",
  "password": "newpassword",
  "confirm_password": "newpassword",
  "attributes": {
    "surname": "Test",
    "givenName": "User Updated",
    "mail": "testuser.updated@example.com"
  },
  "roles": ["Z3Vlc3Q=", "YWRtaW4="],
  "groups": ["group_id_1", "group_id_2"],
  "version_no": 1
}

Feldbeschreibungen

Feld Erforderlich Beschreibung
id Ja Die Dokument-ID des zu aktualisierenden Benutzers.
name Ja Benutzername (Login-ID)
version_no Ja Versionsnummer (für optimistisches Sperren)
password Nein Neues Passwort (wird nur aktualisiert, wenn angegeben)
confirm_password Nein Bestätigungspasswort
attributes Nein Attribut-Map (siehe „Benutzer erstellen“)
roles Nein Array von Rollen-IDs
groups Nein Array von Gruppen-IDs

Bemerkung

Bei der Aktualisierung sind id, name und version_no erforderlich. version_no ist der Wert, der beim Abrufen des Zielbenutzers (GET) zurückgegeben wird, und entspricht der OpenSearch-Dokumentversion. Stimmt er nicht mit der aktuellen Version überein, wird die Anfrage als Konflikt behandelt und die Aktualisierung abgelehnt.

Antwort

{
  "response": {
    "version": "15.9",
    "status": 0,
    "id": "existing_user_id",
    "created": false
  }
}

  • created : false bei einer Aktualisierung.

Benutzer löschen

Anfrage

DELETE /api/admin/user/setting/{id}

Geben Sie in {id} die Dokument-ID des zu löschenden Benutzers an.

Bemerkung

Der aktuell angemeldete Benutzer kann nicht gelöscht werden.

Antwort

{
  "response": {
    "version": "15.9",
    "status": 0,
    "id": "deleted_user_id",
    "created": false
  }
}

  • id : Die Dokument-ID des gelöschten Benutzers.

Verwendungsbeispiele

Neuen Benutzer erstellen

curl -X POST "http://localhost:8080/api/admin/user/setting" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "john.doe",
       "password": "SecureP@ss123",
       "confirm_password": "SecureP@ss123",
       "attributes": {
         "surname": "Doe",
         "givenName": "John",
         "mail": "john.doe@example.com"
       },
       "roles": ["Z3Vlc3Q="],
       "groups": []
     }'

Benutzerrollen ändern

curl -X PUT "http://localhost:8080/api/admin/user/setting" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "id": "user_id_123",
       "name": "john.doe",
       "roles": ["Z3Vlc3Q=", "YWRtaW4="],
       "version_no": 1
     }'

Referenzinformationen