OAuth2 / OIDC — een dienst koppelen aan Omniscol

Wat Omniscol doet als OAuth2-server

Een externe dienst — een AI-agent, een connector, een dashboard — wordt een client die in uw account is geregistreerd; een gebruiker van de school keurt zijn toegang goed via een toestemmingsscherm; daarna ontvangt de dienst een toegangstoken met een korte levensduur, waarvan het bereik begrensd is door de toegekende scopes en door de rechten van de gebruiker.

Dit mechanisme staat los van de gebruikers-SSO die op OIDC / SSO wordt beschreven, waar Omniscol juist client is van uw identiteitsprovider om uw gebruikers aan te melden. Hier staat Omniscol aan de serverzijde: het zijn diensten die verbinding maken met Omniscol.

Twee Omniscol-integraties maken gebruik van deze server:

• MCP — de standaardauthenticatie van een AI-agent verloopt via deze OAuth2-server (zie MCP — een externe AI-agent aansluiten);
• OneRoster — de OneRoster-producer authenticeert zich met een OAuth2-token van machine tot machine dat door diezelfde server wordt uitgegeven (zie OneRoster).

Elke andere dienst die aan OAuth2 / OIDC voldoet, kan op dezelfde manier verbinding maken.

Discovery en endpoints van het protocol

Omniscol publiceert zijn discovery-metadata op de standaardadressen .well-known, die in de root van het domein van uw account worden aangeboden (bijvoorbeeld https://uw-school.omniscol.com). Een conforme client vindt daar zelf alle endpoints, zonder handmatige configuratie:

• /.well-known/oauth-authorization-server — metadata van de autorisatieserver (RFC 8414);
• /.well-known/openid-configuration — OpenID Connect-metadata (dezelfde inhoud als de vorige);
• /.well-known/jwks.json — publieke verificatiesleutels (JWKS), waarmee de handtekening van de id_token gecontroleerd kan worden;
• /.well-known/oauth-protected-resource — metadata van de beschermde resource (RFC 9728).

Deze metadata kondigen de endpoints van het protocol aan:

• /oauth/authorize — autorisatieverzoek (aanmeldscherm en vervolgens toestemmingsscherm);
• /oauth/token — de code inwisselen voor een token, en de vernieuwing;
• /oauth/register — dynamische registratie van clients (RFC 7591);
• /oidc/userinfo — informatie over de aangemelde gebruiker (OIDC);
• /oauth/revoke — intrekking van een token (RFC 7009).

Deze protocol-endpoints zijn openbaar: ze zijn niet voorbehouden aan Premium-accounts en hoeven niet handmatig te worden opengezet. Alleen het beheerscherm voor clients dat hieronder wordt beschreven, valt onder Premium.

De autorisatieflows

Omniscol ondersteunt drie OAuth2-flows:

• Autorisatiecode met PKCE — de standaardflow voor een dienst die namens een gebruiker handelt. De dienst stuurt de gebruiker door naar /oauth/authorize; na aanmelding en toestemming geeft Omniscol een autorisatiecode terug (5 minuten geldig) die de dienst op /oauth/token inwisselt. De gebruikte PKCE-methode is S256 en het enige aanvaarde response_type is code.
• Vernieuwing (refresh_token) — om gedelegeerde toegang te verlengen zonder opnieuw langs de toestemming te gaan.
• Client credentials — een flow van machine tot machine, zonder gebruiker, die met name door de OneRoster-consumers wordt gebruikt. De client authenticeert zich rechtstreeks en ontvangt een toegangstoken.

Bij de inwisseling geeft de server een toegangstoken uit (Bearer, 1 uur geldig) en, voor de gebruikersflows, een vernieuwingstoken (30 dagen geldig). Wanneer de scope openid wordt gevraagd, wordt ook een ondertekend OIDC-id_token uitgegeven; de handtekening daarvan controleert u via /.well-known/jwks.json. De flow client_credentials geeft alleen een toegangstoken uit, zonder vernieuwing en zonder id_token.

Het toegangstoken geeft u vervolgens mee in de HTTP-header Authorization: Bearer <token>. Bij elke aanroep controleert Omniscol de handtekening, gaat het na of de client nog actief is, of de gebruiker nog bestaat en de vereiste rol heeft, en of de scopes van het token het aangeroepen endpoint wel dekken — zo niet, dan wordt de aanroep geweigerd.

De scopes en de toestemming

De scopes die u op een client beheert, zijn:

• read:basic — het lezen van roosters, dashboards en overzichten (modules Home, Rooster, Dashboard, Roosterbeheer);
• read:user — het lezen van de gebruikerslijst;
• write:data — schrijven in diezelfde raadpleegmodules;
• admin — beheertoegang (modules Beheer, Afwezigheidsbeheer, Roosterbeheer).

De server kent ook de OIDC-scopes (openid, email, profile) en de OneRoster-scopes voor alleen lezen (voorvoegsel imsglobal.org). Die laatste zijn bevoorrecht: een client kan ze zichzelf niet toekennen via de dynamische registratie; ze moeten door een beheerder op de fiche van de client worden ingericht.

De scope die daadwerkelijk wordt toegekend, is de doorsnede van wat de client vraagt en wat voor hem is geregistreerd: een client krijgt nooit meer dan wat op zijn fiche staat. In de gebruikersflow toont het toestemmingsscherm (/oauth/consent) de naam en het logo van de vragende dienst, evenals de leesbare lijst van de gevraagde scopes, met de knoppen Accepteren en Weigeren. Goedkeuren geeft de autorisatiecode uit en stuurt de gebruiker terug naar de dienst; weigeren stuurt hem terug met een fout access_denied.

De dynamische registratie van clients

Het endpoint /oauth/register implementeert de dynamische registratie (Dynamic Client Registration, RFC 7591): een conforme dienst kan zichzelf registreren als client, zonder voorafgaande handmatige tussenkomst. Daardoor kan een MCP-agent zich configureren op basis van alleen de URL van de server.

De dynamische registratie kan zichzelf geen bevoorrechte scope toekennen (de OneRoster-scopes): die worden stilzwijgend terzijde gelegd, en als er geen geldige scope overblijft, wordt standaard read:basic toegekend. Bevoorrechte scopes blijven voorbehouden aan een inrichting door een beheerder.

Het beheerscherm voor OAuth2-clients

Op Premium-accounts beheert u de clients vanuit Beheer → Import/Export, sectie OAuth2, met de knop OAuth2. Voor de toegang is eerst het beheerderswachtwoord vereist — een extra bevestiging voordat het scherm opengaat.

Het scherm toont de geregistreerde clients en, voor elk daarvan, de status (actief / inactief), de naam, de scopes, de contactpersonen en de URI's (website, logo, redirect-URI's). U kunt:

• Een client registreren — vul de naam in, een optionele software_id, de scopes, de contactpersonen, de website, het logo en de redirect-URI's. Bij het aanmaken toont Omniscol één enkele keer de client_id en de client_secret.
• Een client wijzigen — alleen veilige velden zijn te wijzigen: naam, scopes, contactpersonen, website en logo. De redirect-URI's, de software_id en het geheim wijzigt u hier niet.
• Een client activeren of deactiveren — bij een gedeactiveerde client worden de tokens al bij de eerstvolgende aanroep geweigerd.
• Een client verwijderen — het verwijderen is definitief.

Het geheim van de client

De client_secret wordt één enkele keer getoond, bij de registratie. Omniscol bewaart aan zijn kant alleen een vingerafdruk van het geheim, nooit het geheim in leesbare vorm: het kan daarna niet opnieuw worden getoond of opgehaald. Kopieer het meteen naar een secretsmanager.

De client_id daarentegen is deterministisch: die wordt afgeleid van de naam van het account, de naam van de client en een vingerafdruk van zijn technische metadata. Twee volstrekt identieke registraties komen zo op dezelfde identificatie uit.

Het geheim vernieuwen (rotatie)

De rotatie van het geheim bestaat: ze geeft een nieuw geheim uit, bewaart daarvan alleen de nieuwe vingerafdruk en geeft dat nieuwe geheim maar één keer terug. Ze verloopt via het beheer-endpoint van de dynamische registratie (/oauth/register/<client_id>/rotation) en veronderstelt dat u het registratietoken meestuurt dat bij de dynamische registratie aan de client is verstrekt. Ze wordt dus niet gestart vanuit het beheerscherm hierboven, dat dit token niet gebruikt.

OAuth2 of API-sleutel: wat kiest u

Omniscol biedt twee mechanismen voor machinetoegang, met verschillende vertrouwensmodellen:

• OAuth2 (deze pagina) — een geregistreerde derde partij krijgt, na toestemming van een gebruiker, een token met een korte levensduur (1 uur), begrensd tot de toegekende scopes, vernieuwbaar en intrekbaar (door de client te deactiveren). De flow client_credentials dekt daarnaast machine tot machine zonder gebruiker. Dit is de werkwijze die past bij een geïdentificeerde externe dienst, bij MCP en bij OneRoster.
• API-sleutel (zie Omniscol-API) — een op zichzelf staand token dat door de server is ondertekend, dat een lijst met toegestane endpoints meedraagt en dat u zelf aan het externe systeem doorgeeft: geen geregistreerde derde partij, geen toestemmingsscherm, geen vernieuwing. Het is een delegatie, door de beheerder, van zijn eigen rechten aan een systeem dat hij zelf in de hand heeft.

Kortom: de API-sleutel past wanneer u zelf toegang verstrekt aan een systeem dat u beheert; OAuth2 past wanneer een geïdentificeerde externe dienst gedelegeerde toegang moet krijgen die tot bepaalde scopes beperkt en intrekbaar is, of wanneer het protocol dat oplegt (MCP, OneRoster).