OAuth2 / OIDC — connecter un service à Omniscol

Ce que fait Omniscol comme serveur OAuth2

Un service extérieur — un agent IA, un connecteur, un tableau de bord — devient un client déclaré dans votre compte ; un utilisateur de l'école approuve son accès via un écran de consentement ; le service reçoit alors un jeton d'accès à durée de vie courte, dont le périmètre est borné aux scopes accordés et aux droits de l'utilisateur.

Ce mécanisme est distinct du SSO utilisateur décrit sur OIDC / SSO, où Omniscol est au contraire client de votre fournisseur d'identité pour connecter vos utilisateurs. Ici, Omniscol est du côté serveur : ce sont des services qui se connectent à lui.

Deux intégrations Omniscol consomment ce serveur :

• MCP — l'authentification standard d'un agent IA passe par ce serveur OAuth2 (voir MCP — connecter un agent IA externe) ;
• OneRoster — le producteur OneRoster s'authentifie par un jeton OAuth2 de machine à machine émis par ce même serveur (voir OneRoster).

Tout autre service conforme OAuth2 / OIDC peut s'y connecter de la même manière.

Découverte et points d'accès du protocole

Omniscol publie ses métadonnées de découverte aux adresses standard .well-known, servies à la racine du domaine de votre compte (par exemple https://votre-ecole.omniscol.com). Un client conforme y trouve seul tous les points d'accès, sans configuration manuelle :

• /.well-known/oauth-authorization-server — métadonnées du serveur d'autorisation (RFC 8414) ;
• /.well-known/openid-configuration — métadonnées OpenID Connect (contenu identique au précédent) ;
• /.well-known/jwks.json — clés publiques de vérification (JWKS), qui permettent de vérifier la signature des id_token ;
• /.well-known/oauth-protected-resource — métadonnées de ressource protégée (RFC 9728).

Ces métadonnées annoncent les points d'accès du protocole :

• /oauth/authorize — demande d'autorisation (écran de connexion puis de consentement) ;
• /oauth/token — échange du code contre un jeton, et rafraîchissement ;
• /oauth/register — enregistrement dynamique de clients (RFC 7591) ;
• /oidc/userinfo — informations sur l'utilisateur connecté (OIDC) ;
• /oauth/revoke — révocation d'un jeton (RFC 7009).

Ces points d'accès du protocole sont publics : ils ne sont pas réservés aux comptes Premium et n'ont pas à être ouverts manuellement. Seul l'écran de gestion des clients décrit plus bas relève du Premium.

Les flux d'autorisation

Omniscol prend en charge trois flux OAuth2 :

• Code d'autorisation avec PKCE — le flux par défaut pour un service agissant au nom d'un utilisateur. Le service redirige l'utilisateur vers /oauth/authorize ; après connexion et consentement, Omniscol renvoie un code d'autorisation (valable 5 minutes) que le service échange sur /oauth/token. La méthode PKCE retenue est S256, et le seul response_type accepté est code.
• Rafraîchissement (refresh_token) — pour prolonger un accès délégué sans repasser par le consentement.
• Client credentials — flux de machine à machine, sans utilisateur, utilisé notamment par les consommateurs OneRoster. Le client s'authentifie directement et reçoit un jeton d'accès.

À l'échange, le serveur émet un jeton d'accès (Bearer, valable 1 heure) et, pour les flux utilisateur, un jeton de rafraîchissement (valable 30 jours). Lorsque le scope openid est demandé, un id_token OIDC signé est également émis ; sa signature se vérifie via /.well-known/jwks.json. Le flux client_credentials n'émet qu'un jeton d'accès, sans rafraîchissement ni id_token.

Le jeton d'accès se présente ensuite en en-tête HTTP Authorization: Bearer <jeton>. À chaque appel, Omniscol vérifie sa signature, contrôle que le client est toujours actif, que l'utilisateur existe toujours et possède le rôle requis, et que les scopes du jeton couvrent bien le point d'accès appelé — faute de quoi l'appel est refusé.

Les scopes et le consentement

Les scopes que vous gérez sur un client sont :

• read:basic — lecture des emplois du temps, tableaux de bord et consultations (modules Accueil, EDT, Tableau de bord, Gestion des EDT) ;
• read:user — lecture de la liste des utilisateurs ;
• write:data — écriture sur ces mêmes modules de consultation ;
• admin — accès d'administration (modules Administration, Gestion des absences, Gestion des EDT).

Le serveur connaît aussi les scopes OIDC (openid, email, profile) et les scopes OneRoster en lecture seule (préfixe imsglobal.org). Ces derniers sont privilégiés : un client ne peut pas se les auto-attribuer par l'enregistrement dynamique ; ils doivent être provisionnés par un administrateur sur la fiche du client.

Le scope effectivement accordé est l'intersection de ce que le client demande et de ce qui lui est enregistré : un client n'obtient jamais plus que ce qui figure sur sa fiche. Lors du flux utilisateur, l'écran de consentement (/oauth/consent) affiche le nom et le logo du service demandeur ainsi que la liste lisible des scopes demandés, avec les boutons Accepter et Refuser. Approuver émet le code d'autorisation et renvoie l'utilisateur vers le service ; refuser le renvoie avec une erreur access_denied.

L'enregistrement dynamique de clients

Le point d'accès /oauth/register met en œuvre l'enregistrement dynamique (Dynamic Client Registration, RFC 7591) : un service conforme peut se déclarer seul comme client, sans intervention manuelle préalable. C'est ce qui permet à un agent MCP de se configurer à partir de la seule URL du serveur.

L'enregistrement dynamique ne peut pas s'attribuer de scope privilégié (les scopes OneRoster) : ceux-ci sont silencieusement écartés, et si aucun scope valide ne subsiste, read:basic est accordé par défaut. Les scopes privilégiés restent réservés à un provisionnement par un administrateur.

L'écran de gestion des clients OAuth2

Sur les comptes Premium, vous administrez les clients depuis Administration → Import/Export, section OAuth2, avec le bouton OAuth2. L'accès demande d'abord le mot de passe administrateur — une confirmation supplémentaire avant d'ouvrir l'écran.

L'écran liste les clients enregistrés et, pour chacun, affiche son état (actif / inactif), son nom, ses scopes, ses contacts et ses URIs (site, logo, URIs de redirection). Vous pouvez :

• Enregistrer un client — renseignez le nom, un software_id facultatif, les scopes, les contacts, le site, le logo et les URIs de redirection. À la création, Omniscol affiche une seule fois le client_id et le client_secret.
• Modifier un client — seuls des champs sûrs sont modifiables : nom, scopes, contacts, site et logo. Les URIs de redirection, le software_id et le secret ne se modifient pas ici.
• Activer ou désactiver un client — un client désactivé voit ses jetons refusés dès l'appel suivant.
• Supprimer un client — la suppression est définitive.

Le secret du client

Le client_secret est affiché une seule fois, à l'enregistrement. Omniscol ne conserve à ses côtés qu'une empreinte du secret, jamais le secret en clair : il ne peut pas être ré-affiché ni récupéré ensuite. Copiez-le immédiatement dans un gestionnaire de secrets.

Le client_id, lui, est déterministe : il dérive du nom du compte, du nom du client et d'une empreinte de ses métadonnées techniques. Deux enregistrements strictement identiques retombent ainsi sur le même identifiant.

Renouveler le secret (rotation)

La rotation du secret existe : elle émet un nouveau secret, n'en conserve que la nouvelle empreinte, et ne renvoie ce nouveau secret qu'une fois. Elle s'effectue via le point d'accès de gestion de l'enregistrement dynamique (/oauth/register/<client_id>/rotation) et suppose de présenter le jeton d'enregistrement remis au client lors de son enregistrement dynamique. Elle n'est donc pas déclenchée depuis l'écran de gestion ci-dessus, qui ne manipule pas ce jeton.

OAuth2 ou clé d'API : lequel choisir

Omniscol propose deux mécanismes d'accès machine, aux modèles de confiance différents :

• OAuth2 (cette page) — un tiers enregistré obtient, après consentement d'un utilisateur, un jeton à durée de vie courte (1 h), borné aux scopes accordés, rafraîchissable et révocable (en désactivant le client). Le flux client_credentials couvre en outre la machine à machine sans utilisateur. C'est le mode adapté à un service tiers identifié, à MCP et à OneRoster.
• Clé d'API (voir API Omniscol) — un jeton autonome signé par le serveur, qui embarque une liste de points d'accès autorisés et que vous remettez vous-même au système externe : pas de tiers enregistré, pas d'écran de consentement, pas de rafraîchissement. C'est une délégation, par l'administrateur, de ses propres droits à un système qu'il maîtrise.

En résumé : la clé d'API convient quand vous remettez vous-même un accès à un système que vous contrôlez ; OAuth2 convient quand un service tiers identifié doit obtenir un accès délégué, scopé et révocable, ou quand le protocole l'impose (MCP, OneRoster).