API d’authentification et de session

Vue d’ensemble

L’API v2 utilise une authentification basée sur les sessions. La connexion s’effectue via POST /auth/login ; en cas de succès, une session est établie et un jeton CSRF est émis.

Les requêtes modifiant l’état (POST) nécessitent l’en-tête X-Fess-CSRF-Token. Pour les détails sur l’obtention et le renouvellement du jeton CSRF, ainsi que pour l’enveloppe de réponse commune et le modèle d’erreur, voir Vue d’ensemble de l’API.

Cette page décrit les quatre points de terminaison suivants.

Liste des points de terminaison

Point de terminaison	Méthode	Description
/auth/me	GET	Récupère l’utilisateur authentifié courant.
/auth/login	POST	Se connecte avec un nom d’utilisateur et un mot de passe.
/auth/logout	POST	Se déconnecte (idempotent).
/auth/password	POST	Modifie le mot de passe de l’utilisateur courant.

Informations utilisateur communes (UserPayload)

Les informations utilisateur incluses dans les réponses de GET /auth/me et POST /auth/login sont retournées dans la structure commune UserPayload. Tous les champs de type tableau sont non-nuls ; un tableau vide est retourné s’il n’y a pas de valeur.

UserPayload

Champ	Type	Description
user_id	string	Identifiant de l’utilisateur. (Obligatoire)
username	string	Nom d’utilisateur affiché dans le menu de compte de la SPA. Actuellement identique à user_id, mais peut être fourni indépendamment par le backend à l’avenir. (Obligatoire)
name	string	Nom d’affichage pour le menu de compte de la SPA. Actuellement identique à user_id. (Obligatoire)
roles	string[]	Tableau des rôles de l’utilisateur. (Obligatoire)
groups	string[]	Tableau des groupes de l’utilisateur. (Obligatoire)
permissions	string[]	Tableau des permissions de l’utilisateur. (Obligatoire)
editable	boolean	Indique si les informations utilisateur sont modifiables. (Obligatoire)
admin	boolean	Vaut true lorsque l’utilisateur possède l’un des rôles configurés dans authentication.admin.roles. Contrôle l’affichage de l’élément « Administration » dans la SPA. (Obligatoire)

Récupération de l’état d’authentification

Requête

Méthode HTTP	GET
Point de terminaison	/api/v2/auth/me

Récupère l’utilisateur authentifié courant. Pour les appels anonymes, aucune erreur n’est retournée : authenticated: false est renvoyé. Lorsque l’utilisateur est authentifié, user contient un UserPayload.

Réponse

En cas de succès (HTTP 200), une réponse au format d’enveloppe commune est retournée (exemple d’utilisateur authentifié).

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

Les détails de chaque élément de response sont les suivants.

Informations de réponse

Champ	Type	Description
authenticated	boolean	Indique si l’utilisateur est authentifié. (Obligatoire)
user	object	UserPayload. Présent uniquement si authenticated vaut true.

Réponse d’erreur

Réponses d’erreur

Code de statut	Description
405 Method Not Allowed	Une méthode HTTP non prise en charge a été spécifiée.
500 Internal Server Error	Une erreur interne s’est produite sur le serveur.

Connexion

Requête

Méthode HTTP	POST
Point de terminaison	/api/v2/auth/login

Se connecte avec un nom d’utilisateur et un mot de passe. En cas de succès, l’identifiant de session du servlet est renouvelé, un nouveau jeton CSRF est émis, et les buckets de limite de débit de l’IP appelante et de l’utilisateur cible sont réinitialisés. En cas de dépassement de la limite de débit, un en-tête Retry-After (en secondes) est ajouté.

Même pour une session déjà authentifiée, aucun court-circuit n’est appliqué : les informations d’authentification transmises sont toujours vérifiées.

return_to doit être un chemin relatif correspondant à ^/[A-Za-z0-9_\-/.?&=%:@+~#*!,;]*$. De plus, les chemins relatifs aux protocoles (commençant par //) et les chemins contenant des caractères de contrôle ASCII sont rejetés et silencieusement supprimés de la réponse.

Note

Ce point de terminaison est exclu de la vérification CSRF (car aucun jeton n’existe avant la connexion).

Note

Contrairement aux autres points de terminaison de modification d’état, ce point de terminaison regroupe les corps de requête trop grands et les Content-Type non pris en charge dans 400 invalid_request (les autres points de terminaison retournent 413 / 415).

Corps de la requête (LoginRequest)

Le Content-Type est application/json.

LoginRequest

Champ	Type	Obligatoire	Description
username	string	Oui	Nom d’utilisateur. minLength : 1.
password	string	Oui	Mot de passe. minLength : 1.
return_to	string	Non	Chemin de redirection après connexion. Doit être un chemin relatif correspondant au motif ci-dessus.

Exemple de requête :

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

Réponse

En cas de succès (HTTP 200, LoginResponse), une réponse au format d’enveloppe commune est retournée.

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

Les détails de chaque élément de response sont les suivants.

Informations de réponse

Champ	Type	Description
user	object	UserPayload.
csrf_token	string	Nouveau jeton CSRF associé à la nouvelle session. (Obligatoire)
return_to	string	Renvoyé uniquement si la valeur de la requête a passé la liste d’autorisation.

Réponse d’erreur

Réponses d’erreur

Code de statut	Description
400 Bad Request	La requête est incorrecte (corps trop grand ou Content-Type non pris en charge inclus).
401 Unauthorized	Les informations d’authentification sont incorrectes.
405 Method Not Allowed	Une méthode HTTP non prise en charge a été spécifiée.
429 Too Many Requests	Limite de débit dépassée. L’en-tête Retry-After indique le nombre de secondes d’attente.
500 Internal Server Error	Une erreur interne s’est produite sur le serveur.

Déconnexion

Requête

Méthode HTTP	POST
Point de terminaison	/api/v2/auth/logout

Déconnecte l’utilisateur. Cette opération est idempotente : en l’absence de session active, elle ne fait rien et ne retourne pas d’erreur. Retourne toujours ok: true.

L’en-tête X-Fess-CSRF-Token est requis.

Réponse

En cas de succès (HTTP 200, OkResponse), une réponse au format d’enveloppe commune est retournée.

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

Les détails de chaque élément de response sont les suivants.

Informations de réponse

Champ	Type	Description
ok	boolean	Toujours true. (Obligatoire)

Réponse d’erreur

Réponses d’erreur

Code de statut	Description
403 Forbidden	Jeton CSRF manquant ou expiré.
405 Method Not Allowed	Une méthode autre que POST a été spécifiée. Un en-tête Allow: POST est ajouté.

Changement de mot de passe

Requête

Méthode HTTP	POST
Point de terminaison	/api/v2/auth/password

Modifie le mot de passe de l’utilisateur courant. Valide current_password, applique la politique de mot de passe configurée à new_password, invalide la session courante et invite la SPA à rediriger vers la page de connexion via re_login_required: true.

Comme la session est détruite côté serveur, csrf_token n’est pas retourné. La SPA doit obtenir un nouveau jeton après une nouvelle authentification.

L’en-tête X-Fess-CSRF-Token est requis.

Corps de la requête (PasswordChangeRequest)

Le Content-Type est application/json.

PasswordChangeRequest

Champ	Type	Obligatoire	Description
current_password	string	Oui	Mot de passe actuel. minLength : 1.
new_password	string	Oui	Nouveau mot de passe. Doit satisfaire la politique de mot de passe configurée. minLength : 1.
confirm_password	string	Oui	Mot de passe de confirmation. Doit être identique à new_password. minLength : 1.

Réponse

En cas de succès (HTTP 200), une réponse au format d’enveloppe commune est retournée.

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

Les détails de chaque élément de response sont les suivants.

Informations de réponse

Champ	Type	Description
ok	boolean	Toujours true. (Obligatoire)
re_login_required	boolean	Toujours true. La session courante a été invalidée côté serveur. La SPA doit rediriger vers la page de connexion pour obtenir une nouvelle session et un nouveau jeton CSRF. (Obligatoire)

Réponse d’erreur

Réponses d’erreur

Code de statut	Description
400 Bad Request	La requête est incorrecte.
401 Unauthorized	Authentification requise ou current_password incorrect.
403 Forbidden	Jeton CSRF manquant ou expiré.
405 Method Not Allowed	Une méthode HTTP non prise en charge a été spécifiée.
413 Payload Too Large	Le corps de la requête dépasse la limite de taille.
415 Unsupported Media Type	Content-Type non pris en charge.
429 Too Many Requests	Limite de débit dépassée.
500 Internal Server Error	Une erreur interne s’est produite sur le serveur.