User API

Vue d’ensemble

L’API User est une API REST pour gérer les comptes utilisateurs de Fess. Vous pouvez créer, récupérer, mettre à jour et supprimer des utilisateurs, et leur attribuer des rôles et des groupes.

Il s’agit d’une API d’administration ; son accès requiert une authentification par jeton d’accès administrateur. Consultez Vue d’ensemble de l’API Admin pour la méthode d’authentification et les spécifications communes.

Chaque réponse est encapsulée dans un objet response et contient les champs communs suivants :

• version : La chaîne de version du produit Fess.

• status : Le code de statut du résultat (0 = succès, 1 = requête invalide, 2 = erreur système, 3 = non autorisé, 9 = échec).

URL de base

/api/admin/user

Liste des endpoints

Méthode	Chemin	Description
GET	/settings	Lister les utilisateurs
GET	/setting/{id}	Récupérer un utilisateur
POST	/setting	Créer un utilisateur
PUT	/setting	Mettre à jour un utilisateur
DELETE	/setting/{id}	Supprimer un utilisateur

Lister les utilisateurs

Requête

GET /api/admin/user/settings

Paramètres

Paramètre	Type	Requis	Description
size	Integer	Non	Nombre d’éléments par page. La valeur par défaut est la valeur configurée paging.page.size (par défaut : 25).
page	Integer	Non	Numéro de page (commence à 1). La valeur par défaut est 1.

Note

Dans l’implémentation actuelle, l’endpoint de liste des utilisateurs n’applique pas les paramètres size et page. Il retourne toujours la première page, avec le nombre d’éléments défini par le paramètre serveur paging.page.size (par défaut : 25), trié par nom d’utilisateur (name) en ordre croissant. Le nombre total d’utilisateurs correspondants est disponible dans response.total.

Réponse

{
  "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 : Le tableau des utilisateurs de la page courante.

• total : Le nombre total d’utilisateurs correspondants.

Récupérer un utilisateur

Requête

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

Spécifiez l’identifiant de document de l’utilisateur cible dans {id}.

Réponse

{
  "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
    }
  }
}

Note

attributes contient tous les attributs enregistrés pour l’utilisateur, à l’exception de name, password, roles et groups. password n’est pas inclus dans la réponse.

Créer un utilisateur

Requête

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

Corps de la requête

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

Description des champs

Champ	Requis	Description
name	Oui	Nom d’utilisateur (identifiant de connexion)
password	Oui	Mot de passe
confirm_password	Non	Mot de passe de confirmation
attributes	Non	Map d’attributs (voir ci-dessous)
roles	Non	Tableau des identifiants de rôles
groups	Non	Tableau des identifiants de groupes

Note

Indiquez dans roles et groups l’ID du rôle ou du groupe, et non son nom. Un ID qui n’existe pas (y compris un nom de rôle ou de groupe) est refusé avec 400. Les ID figurent dans le id renvoyé par GET /api/admin/role/settings et GET /api/admin/group/settings. L’ID d’un rôle ou d’un groupe créé dans l’interface d’administration ou via l’API est son nom encodé en Base64 URL (par exemple YWRtaW4= pour le rôle admin et Z3Vlc3Q= pour guest, présents par défaut).

Note

Les mêmes vérifications du mot de passe que dans l’interface d’administration s’appliquent. Sont refusés avec 400 : une création sans password, un confirm_password différent de password (confirm_password peut être omis) et un mot de passe qui enfreint la politique de mot de passe (password.min.length (8 par défaut), password.max.length, password.require.* et password.invalid.admin.passwords de fess_config.properties).

Les clés de attributes sont les noms d’attributs de l’entité utilisateur (les noms d’éléments dérivés du schéma LDAP). Les clés les plus courantes sont :

• surname, givenName, displayName, mail

• telephoneNumber, mobile, homePhone

• employeeNumber, title, description, homeDirectory

• uidNumber, gidNumber

uidNumber et gidNumber doivent être numériques (leur type est validé lors de la mise à jour). De nombreuses autres clés d’attributs LDAP peuvent également être spécifiées.

Note

Lors de la création, l’identifiant de l’utilisateur (identifiant de document) est automatiquement généré comme la valeur encodée en Base64 URL du nom d’utilisateur (par exemple, le nom d’utilisateur admin devient YWRtaW4=).

Réponse

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

• id : L’identifiant de document de l’utilisateur créé.

• created : true lors de la création.

Mettre à jour un utilisateur

Requête

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

Corps de la requête

{
  "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
}

Description des champs

Champ	Requis	Description
id	Oui	L’identifiant de document de l’utilisateur à mettre à jour.
name	Oui	Nom d’utilisateur (identifiant de connexion)
version_no	Oui	Numéro de version (pour le verrouillage optimiste)
password	Non	Nouveau mot de passe (mis à jour uniquement si spécifié)
confirm_password	Non	Mot de passe de confirmation
attributes	Non	Map d’attributs (voir « Créer un utilisateur »)
roles	Non	Tableau des identifiants de rôles
groups	Non	Tableau des identifiants de groupes

Note

Lors de la mise à jour, id, name et version_no sont obligatoires. version_no est la valeur retournée lors de la récupération de l’utilisateur cible (GET), et correspond à la version du document OpenSearch. Si elle ne correspond pas à la version actuelle, la requête est traitée comme un conflit et la mise à jour est rejetée.

Réponse

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

• created : false pour une mise à jour.

Supprimer un utilisateur

Requête

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

Spécifiez l’identifiant de document de l’utilisateur à supprimer dans {id}.

Note

Vous ne pouvez pas supprimer l’utilisateur actuellement connecté.

Réponse

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

• id : L’identifiant de document de l’utilisateur supprimé.

Exemples d’utilisation

Créer un nouvel utilisateur

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": []
     }'

Modifier les rôles d’un utilisateur

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
     }'

Références

• Vue d’ensemble de l’API Admin - Vue d’ensemble de l’API Admin

• API Role - API de gestion des rôles

• API Group - API de gestion des groupes

• Utilisateur - Guide de gestion des utilisateurs