Skip to content

Authentification

Jump to bottom
Louis DEVIE edited this page May 10, 2025 · 9 revisions

Schémas

Avec un nom d'utilisateur et un mot de passe

Pour se connecter au service avec un compte utilisateur, il faut envoyer une requête POST /login avec la clé d'API de l'application, le nom d'utilisateur et le mot de passe. Il y a deux moyens de transmettre ces informations :

  1. Avec l'en-tête Authorization : la requête n'a pas de corps, elle est juste accompagnée des deux en-têtes X-API-Key qui contient la clé d'API et Authorization qui contient le nom d'utilisateur et le mot de passe, encodé avec le schéma d'authentification standard Basic.

    Exemple en pseudocode 
    credentials := "Basic " + base64(username + ':' + password)

response := http.post(
  "https://gallium.etiq-dijon.fr/api/login",
  headers: {
    "Authorization": credentials,
    "X-API-Key": API_KEY
  }
)

  2. En envoyant le nom d'utilisateur et le mot de passe dans le corps de la requête. L'objet envoyé doit contenir deux champs, username et password, et toujours être accompagné de l'en-tête X-API-Key.

    Exemple en pseudocode 
    credentials := json({ username, password })

response := http.post(
  "https://gallium.etiq-dijon.fr/api/login",
  body: credentials,
  headers: {
    "X-API-Key": API_KEY
  }
)

Pour les applications et les bots

Les applications se connectent en envoyant une requête POST /connect sans corps, avec les en-têtes X-API-Key contenant la clé d'API de l'application et Authorization contenant sa clé secrète (la valeur de l'en-tête doit être structurée comme Secret XXXXXXXX-XXXXXXXXXXXX-XXXXXXXX)

Exemple en pseudocode 
response := http.post(
"https://gallium.etiq-dijon.fr/api/connect",
  headers: {
    "X-API-Key": API_KEY,
    "Authorization": "Secret " + SECRET_KEY
  }
)

Pour les application utilisant le service de Same Sign-On

Une application qui ne se connecte pas directement à l'API va renvoyer l'utilisateur sur la page de connexion de Gallium+ avec sa clé d'API (l'URL doit être par exemple https://gallium.etiq-dijon.fr/login?service=[CLÉ D'API]). Une fois l'utilisateur authentifié, il sera redirigé ers la page de connexion de l'application avec un JWT contenant ses informations en paramètre de la requête (par exemple https://ma-super-appli.fr/login?token=[JWT]). L'application peut alors vérifier l'authenticité des données avec sa clé secrète et procéder.

Pour plus de détails, voir la page dédiée au Same Sign-On.

Une fois connecté

Une fois l'application connectée (c-à-d, en posession d'un jeton de session valide), elle peut utiliser ce dernier pour authentifier ses requêtes sans renvoyer d'identifiants et sa clé d'API à chaque fois. Le jeton doit être passé dans l'en-tête Authorization avec le schéma Bearer.

Une session obtenue par /login se termine dans trois conditions :

  • Quand l'utilisateur se déconnecte explicitement;
  • Quand aucune requête n'a été effectuée depuis 20 minutes;
  • Ou quand la session a été ouverte depuis plus de 12h.

Une session obtenue par /connect se termine dans deux conditions :

  • Quand l'utilisateur se déconnecte explicitement;
  • Ou 72h après ouverture.

Réponse à une demande de connexion

Voici la réponse à une requête de connexion (/login ou /connect) :

{
  "token": "OF5R5jdJJV1rV2sstQGA",
  "expiration": "2023-07-13T14:05:46.2198296Z",
  "user": { },
  "permissions": 0
}
  • token est le jeton de session
  • expiration est la date et l'heure d'expiration
  • user contient les informations de l'utilisateur connecté (ou null pour les bots)
  • permissions sont les permissions associées à cette session

Processus

Pour les clients directs

  • L'application se connecte à l'API avec nom d'utilisateur et mot de passe (2).
  • Si tout est correct, elle reçoit un jeton de session (3).
  • Ce jeton de session peut ensuite être utilisé pour effectuer différentes requêtes (8).
sequenceDiagram
    autonumber
    actor U as Utilisateur
    participant A as Application
    participant S as Serveur

    activate U

    U ->>+ A : connexion
    A ->>+ S : connexion avec clé d'API + identifiants utilisateur

    alt OK
    S -->>- A : jeton de session
    A -->>- U : connecté
    else
    activate S
    activate A
    S -->>- A : erreur
    A -->>- U : identifiants invalides
    end

    U ->>+ A : action
    A ->>+ S : action avec jeton de session

    alt OK
    S -->>- A : ok
    A -->>- U : ok
    else
    activate S
    activate A
    S -->>- A : session expirée
    A -->>- U : déconnecté
    end

    deactivate U
Loading

Pour les bots

  • Si il n'est pas connecté, le bot peut se (re)connecter en envoyant sa clé d'API et sa clé secrète (1).
  • Il obtient alors un (nouveau) jeton de session qui peut être utilisé pour effectuer d'autres requêtes (4).
sequenceDiagram
    autonumber
    participant B as Bot
    participant S as Serveur

    activate B

    B ->>+ S : (re)connexion avec clé d'API + secret

    alt OK
    S -->>- B : jeton de session
    else
    activate S
    S -->>- B : erreur
    end

    B ->>+ S : action avec jeton de session

    alt OK
    S -->>- B : ok
    else
    activate S
    S -->>- B : déconnecté
    end

    deactivate B
Loading

Pour les applications utilisant le same sign-on

  • Quand l'utilisateur choisit de se connecter via Gallium+, il est redirigé vers la page de connexion (2).
  • L'utilisateur se connecte sur la page de connexion de Gallium+.
  • Si ses identifiants sont corrects, il est redirigé vers l'application avec un ticket contenant ses informations et, pour les applications utilisant aussi l'API, un jeton de session.
sequenceDiagram
    autonumber
    actor U as Utilisateur
    participant A as Application
    participant W as SSO Gallium+
    participant S as Serveur

    activate U

    U ->>+ A : connexion avec Gallium+
    A ->>- W : redirection vers Gallium+ avec clé d'API

    activate W

    U ->> W : connexion
    W ->>+ S : connexion avec clé d'API + identitifiants utilisateur

    alt mauvais identifiants
    S -->>- W : erreur
    W -->>- U : identifiants invalides
    else OK
    activate S
    activate W
    S -->>- W : ticket (infos sur l'utilisateur)
    W -->> U : ok, redirection
    W ->>- A : redirection vers l'Application avec ticket

    activate A

    A ->> A : Vérification du ticket

    opt ticket valide
    A -->>- U : connecté
    end    
    
    end

    deactivate U
Loading

Clone this wiki locally