Authentification

Présentation

Le processus d'authentification est le même que celui implémenté dans l'application mobile. Ce processus est réalisé par le mécanisme OpenID Connect (basé sur OAuth 2.0). À l'issue de cette authentification, l'utilisateur récupère deux jetons : un Access Token et un Refresh Token (cf. mécanisme OAuth 2.0).

Chaque ENT possède son propre service d'authentification SSO (Single Sign-On) compatible OpenID Connect. Il est donc nécessaire de déterminer l'adresse de ce serveur avant d'entamer le processus d'authentification. C'est pourquoi l'application mobile demande à l'utilisateur son établissement scolaire de rattachement.

S'authentifier

Pour obtenir vos jetons, il vous est possible d'utiliser scolengo-token. Des exécutables pour systèmes Windows et Linux sont disponibles dans la dernière Release. Il est à noter que vous pouvez aussi récupérer ces jetons sans cet outil, en effectuant les requêtes adéquates.

Si l'authentification a réussi, scolengo-token vous renvoie un objet JSON contenant tout ce dont vous avez besoin pour de futures requêtes à l'API :

{
  "tokenSet": {
    "access_token": "<access_token_here>",
    "id_token": "<id_token_here>",
    "refresh_token": "RT-<refresh_token_here>",
    "token_type": "bearer",
    "expires_at": 1234567890,
    "scope": "openid"
  },
  "school": {
    "id": "SKO-E-<school_id>",
    "name": "<school_name>",
    "addressLine1": "<school_address>",
    "addressLine2": null,
    "addressLine3": null,
    "zipCode": "<school_zip_code>",
    "city": "<school_city>",
    "country": "France",
    "homePageUrl": "<cas_login_url>",
    "emsCode": "<school_ems_code>",
    "emsOIDCWellKnownUrl": "<school_ems_oidc_well_known_url>"
  }
}

L'objet tokenSet contient les jetons Access Token et Refresh Token. Il renseigne aussi sur la date d'expiration de l'Access Token. Celui-ci devra être renouvelé en utilisant le Refresh Token.

Pour que l'API sache pour quel ENT la requête est destinée, il est nécessaire de préciser l'en-tête HTTP X-Skolengo-Ems-Code. C'est la raison pour laquelle l'objet school est aussi présent dans cet objet JSON. Pour certaines requêtes, l'identifiant de l'établissement doit aussi être présent dans l'en-tête HTTP X-Skolengo-School-Id.

Pour chaque requête nécessitant une authentification, le jeton Access Token est présent dans l'en-tête Authorization. (Bearer authentication).

Rafraichissement

Les applications utilisant ces jetons à la longue rencontreront un problème : le Access Token possède une durée de validité de 24 heures.

Cependant, il est possible d'en obtenir un nouveau à partir du Refresh Token. Le Refresh Token possède une validité de 21 jours.

scolengo_api possède un mécanisme permettant de facilement rafraichir l'Access Token une fois qu'il expire. Cependant, le nouveau Access Token n'est pas conservé et l'ancien sera utilisé au redémarrage de l'application. Il est possible de conserver le nouvel Access Token après son rafraichissement en utilisant le callback onTokenRefresh :

const { Skolengo } = require("scolengo-api");
const config = require("./tokenset.json");
const { writeFileSync } = require("node:fs");

// ...

const sko = await Skolengo.fromConfigObject(config, { onTokenRefresh: (tokenSet) => {
    config.tokenSet = tokenSet
    writeFileSync("./tokenset.json", JSON.stringify(config))
}});

Dans cet exemple, l'objet de tokenSet est enregistré dans le fichier tokenSet.json. Une fois l'Access Token rafraichi, la fonction spécifiée a onTokenRefresh est appelée, ici, elle réécrit le fichier tokenSet.json avec le nouvel Access Token, le permettant d'être réutilisé au redémarrage de l'application.

Cet exemple fonctionnera pour la majorité des applications, mais pour d'autre, il sera préférable d'enregistrer les tokenSet par d'autres moyens, par exemple une base de données SQL.

---

Spécification OpenID Connect