OAuth2 / OIDC — einen Dienst mit Omniscol verbinden

Was Omniscol als OAuth2-Server tut

Ein externer Dienst — ein KI-Agent, ein Konnektor, ein Dashboard — wird zu einem in Ihrem Konto deklarierten Client; ein Benutzer der Schule genehmigt seinen Zugang über einen Zustimmungsbildschirm; der Dienst erhält daraufhin einen kurzlebigen Zugriffstoken, dessen Reichweite durch die gewährten Scopes und die Rechte des Benutzers begrenzt ist.

Dieser Mechanismus ist verschieden vom Benutzer-SSO, das auf OIDC / SSO beschrieben ist, wo Omniscol umgekehrt Client Ihres Identitätsanbieters ist, um Ihre Benutzer anzumelden. Hier ist Omniscol auf der Server-Seite: Es sind Dienste, die sich mit ihm verbinden.

Zwei Omniscol-Integrationen nutzen diesen Server:

• MCP — die Standardauthentifizierung eines KI-Agenten läuft über diesen OAuth2-Server (siehe MCP — einen externen KI-Agenten verbinden);
• OneRoster — der OneRoster-Produzent authentifiziert sich über einen OAuth2-Token von Maschine zu Maschine, der von diesem selben Server ausgestellt wird (siehe OneRoster).

Jeder andere OAuth2- / OIDC-konforme Dienst kann sich auf dieselbe Weise damit verbinden.

Discovery und Protokoll-Zugangspunkte

Omniscol veröffentlicht seine Discovery-Metadaten unter den Standard-Adressen .well-known, die an der Wurzel der Domain Ihres Kontos ausgeliefert werden (zum Beispiel https://ihre-schule.omniscol.com). Ein konformer Client findet dort alle Zugangspunkte selbst, ohne manuelle Konfiguration:

• /.well-known/oauth-authorization-server — Metadaten des Autorisierungsservers (RFC 8414);
• /.well-known/openid-configuration — OpenID-Connect-Metadaten (inhaltlich identisch mit dem vorherigen);
• /.well-known/jwks.json — öffentliche Prüfschlüssel (JWKS), die es ermöglichen, die Signatur der id_token zu prüfen;
• /.well-known/oauth-protected-resource — Metadaten der geschützten Ressource (RFC 9728).

Diese Metadaten kündigen die Protokoll-Zugangspunkte an:

• /oauth/authorize — Autorisierungsanfrage (Anmeldebildschirm, dann Zustimmungsbildschirm);
• /oauth/token — Austausch des Codes gegen einen Token und Aktualisierung;
• /oauth/register — dynamische Registrierung von Clients (RFC 7591);
• /oidc/userinfo — Informationen über den angemeldeten Benutzer (OIDC);
• /oauth/revoke — Widerruf eines Tokens (RFC 7009).

Diese Protokoll-Zugangspunkte sind öffentlich: Sie sind nicht den Premium-Konten vorbehalten und müssen nicht manuell geöffnet werden. Nur der Bildschirm zur Verwaltung der Clients, der weiter unten beschrieben wird, gehört zu Premium.

Die Autorisierungsflüsse

Omniscol unterstützt drei OAuth2-Flüsse:

• Autorisierungscode mit PKCE — der Standardfluss für einen Dienst, der im Namen eines Benutzers handelt. Der Dienst leitet den Benutzer auf /oauth/authorize weiter; nach Anmeldung und Zustimmung gibt Omniscol einen Autorisierungscode zurück (5 Minuten gültig), den der Dienst auf /oauth/token austauscht. Die verwendete PKCE-Methode ist S256, und der einzige akzeptierte response_type ist code.
• Aktualisierung (refresh_token) — um einen delegierten Zugang zu verlängern, ohne die Zustimmung erneut zu durchlaufen.
• Client Credentials — Fluss von Maschine zu Maschine, ohne Benutzer, der insbesondere von den OneRoster-Konsumenten genutzt wird. Der Client authentifiziert sich direkt und erhält einen Zugriffstoken.

Beim Austausch stellt der Server einen Zugriffstoken (Bearer, gültig für 1 Stunde) aus und, für die Benutzerflüsse, einen Aktualisierungstoken (gültig für 30 Tage). Wenn der Scope openid angefordert wird, wird auch ein signierter OIDC-id_token ausgestellt; seine Signatur lässt sich über /.well-known/jwks.json prüfen. Der Fluss client_credentials stellt nur einen Zugriffstoken aus, ohne Aktualisierung und ohne id_token.

Der Zugriffstoken wird anschließend im HTTP-Header Authorization: Bearer <token> übermittelt. Bei jedem Aufruf prüft Omniscol seine Signatur, kontrolliert, dass der Client noch aktiv ist, dass der Benutzer noch existiert und die erforderliche Rolle besitzt, und dass die Scopes des Tokens den aufgerufenen Zugangspunkt tatsächlich abdecken — andernfalls wird der Aufruf abgelehnt.

Die Scopes und die Zustimmung

Die Scopes, die Sie auf einem Client verwalten, sind:

• read:basic — Lesen der Stundenpläne, Dashboards und Konsultationen (Module Startseite, Stundenpläne, Dashboard, Stundenplanverwaltung);
• read:user — Lesen der Benutzerliste;
• write:data — Schreiben auf ebendiesen Konsultationsmodulen;
• admin — Verwaltungszugang (Module Verwaltung, Abwesenheitsverwaltung, Stundenplanverwaltung).

Der Server kennt auch die OIDC-Scopes (openid, email, profile) und die schreibgeschützten OneRoster-Scopes (Präfix imsglobal.org). Letztere sind privilegiert: Ein Client kann sie sich nicht über die dynamische Registrierung selbst zuweisen; sie müssen von einem Administrator auf dem Datensatz des Clients bereitgestellt werden.

Der tatsächlich gewährte Scope ist die Schnittmenge dessen, was der Client anfordert, und dessen, was für ihn registriert ist: Ein Client erhält niemals mehr als das, was auf seinem Datensatz aufgeführt ist. Beim Benutzerfluss zeigt der Zustimmungsbildschirm (/oauth/consent) den Namen und das Logo des anfragenden Dienstes sowie die lesbare Liste der angeforderten Scopes an, mit den Schaltflächen Akzeptieren und Ablehnen. Das Genehmigen stellt den Autorisierungscode aus und schickt den Benutzer zum Dienst zurück; das Ablehnen schickt ihn mit einem Fehler access_denied zurück.

Die dynamische Registrierung von Clients

Der Zugangspunkt /oauth/register setzt die dynamische Registrierung (Dynamic Client Registration, RFC 7591) um: Ein konformer Dienst kann sich selbst als Client deklarieren, ohne vorheriges manuelles Eingreifen. Das ist es, was einem MCP-Agenten ermöglicht, sich allein aus der Server-URL zu konfigurieren.

Die dynamische Registrierung kann sich keinen privilegierten Scope (die OneRoster-Scopes) zuweisen: Diese werden stillschweigend verworfen, und wenn kein gültiger Scope verbleibt, wird read:basic standardmäßig gewährt. Die privilegierten Scopes bleiben einer Bereitstellung durch einen Administrator vorbehalten.

Der Bildschirm zur Verwaltung der OAuth2-Clients

Auf Premium-Konten verwalten Sie die Clients über Verwaltung → Import/Export, Abschnitt OAuth2, mit der Schaltfläche OAuth2. Der Zugang verlangt zunächst das Administratorpasswort — eine zusätzliche Bestätigung, bevor der Bildschirm geöffnet wird.

Der Bildschirm listet die registrierten Clients auf und zeigt für jeden seinen Zustand (aktiv / inaktiv), seinen Namen, seine Scopes, seine Kontakte und seine URIs an (Website, Logo, Weiterleitungs-URIs). Sie können:

• Einen Client registrieren — geben Sie den Namen, eine optionale software_id, die Scopes, die Kontakte, die Website, das Logo und die Weiterleitungs-URIs an. Bei der Erstellung zeigt Omniscol ein einziges Mal die client_id und das client_secret an.
• Einen Client bearbeiten — nur sichere Felder sind änderbar: Name, Scopes, Kontakte, Website und Logo. Die Weiterleitungs-URIs, die software_id und das Secret werden hier nicht geändert.
• Einen Client aktivieren oder deaktivieren — bei einem deaktivierten Client werden seine Token ab dem nächsten Aufruf abgelehnt.
• Einen Client löschen — das Löschen ist endgültig.

Das Secret des Clients

Das client_secret wird ein einziges Mal angezeigt, bei der Registrierung. Omniscol bewahrt daneben nur einen Fingerabdruck des Secrets auf, niemals das Secret im Klartext: Es kann danach nicht erneut angezeigt oder wiederhergestellt werden. Kopieren Sie es sofort in einen Secrets-Manager.

Die client_id hingegen ist deterministisch: Sie leitet sich vom Namen des Kontos, vom Namen des Clients und einem Fingerabdruck seiner technischen Metadaten ab. Zwei strikt identische Registrierungen ergeben so dieselbe Kennung.

Das Secret erneuern (Rotation)

Die Rotation des Secrets existiert: Sie stellt ein neues Secret aus, bewahrt davon nur den neuen Fingerabdruck auf und gibt dieses neue Secret nur einmal zurück. Sie erfolgt über den Zugangspunkt zur Verwaltung der dynamischen Registrierung (/oauth/register/<client_id>/rotation) und setzt voraus, dass der Registrierungstoken vorgelegt wird, der dem Client bei seiner dynamischen Registrierung ausgehändigt wurde. Sie wird daher nicht über den oben genannten Verwaltungsbildschirm ausgelöst, der diesen Token nicht handhabt.

OAuth2 oder API-Schlüssel: welchen wählen

Omniscol bietet zwei Mechanismen für den maschinellen Zugang mit unterschiedlichen Vertrauensmodellen:

• OAuth2 (diese Seite) — ein registrierter Dritter erhält nach der Zustimmung eines Benutzers einen kurzlebigen Token (1 h), begrenzt auf die gewährten Scopes, aktualisierbar und widerrufbar (durch Deaktivieren des Clients). Der Fluss client_credentials deckt darüber hinaus die Maschine-zu-Maschine-Verbindung ohne Benutzer ab. Es ist der für einen identifizierten Drittanbieterdienst, für MCP und für OneRoster geeignete Modus.
• API-Schlüssel (siehe Omniscol-API) — ein eigenständiger Token, vom Server signiert, der eine Liste autorisierter Zugangspunkte einbettet und den Sie selbst dem externen System aushändigen: kein registrierter Dritter, kein Zustimmungsbildschirm, keine Aktualisierung. Es ist eine Delegation der eigenen Rechte des Administrators an ein System, das er kontrolliert.

Kurz gesagt: Der API-Schlüssel passt, wenn Sie selbst einem System, das Sie kontrollieren, einen Zugang aushändigen; OAuth2 passt, wenn ein identifizierter Drittanbieterdienst einen delegierten, gescopten und widerrufbaren Zugang erhalten muss, oder wenn das Protokoll es vorschreibt (MCP, OneRoster).