OAuth2 / OIDC — connect a service to Omniscol

What Omniscol does as an OAuth2 server

An external service — an AI agent, a connector, a dashboard — becomes a client declared in your account; a school user approves its access through a consent screen; the service then receives a short-lived access token, whose reach is bounded by the granted scopes and the user's rights.

This mechanism is distinct from the user SSO described on OIDC / SSO, where Omniscol is, conversely, a client of your identity provider to sign your users in. Here, Omniscol is on the server side: services connect to it.

Two Omniscol integrations consume this server:

• MCP — the standard authentication of an AI agent goes through this OAuth2 server (see MCP — connect an external AI agent);
• OneRoster — the OneRoster producer authenticates callers with a machine-to-machine OAuth2 token issued by this same server (see OneRoster).

Any other OAuth2 / OIDC-compliant service can connect to it in the same way.

Discovery and protocol endpoints

Omniscol publishes its discovery metadata at the standard .well-known addresses, served at the root of your account's domain (for example https://your-school.omniscol.com). A compliant client finds all the endpoints there on its own, without manual configuration:

• /.well-known/oauth-authorization-server — authorization server metadata (RFC 8414);
• /.well-known/openid-configuration — OpenID Connect metadata (same content as the previous one);
• /.well-known/jwks.json — public verification keys (JWKS), which make it possible to verify the signature of id_tokens;
• /.well-known/oauth-protected-resource — protected resource metadata (RFC 9728).

This metadata advertises the protocol endpoints:

• /oauth/authorize — authorization request (login screen then consent screen);
• /oauth/token — exchange of the code for a token, and refresh;
• /oauth/register — dynamic client registration (RFC 7591);
• /oidc/userinfo — information about the signed-in user (OIDC);
• /oauth/revoke — token revocation (RFC 7009).

These protocol endpoints are public: they are not reserved for Premium accounts and do not need to be opened manually. Only the client management screen described below falls under Premium.

Authorization flows

Omniscol supports three OAuth2 flows:

• Authorization code with PKCE — the default flow for a service acting on behalf of a user. The service redirects the user to /oauth/authorize; after login and consent, Omniscol returns an authorization code (valid for 5 minutes) that the service exchanges on /oauth/token. The supported PKCE method is S256, and the only accepted response_type is code.
• Refresh (refresh_token) — to extend a delegated access without going through consent again.
• Client credentials — a machine-to-machine flow, with no user, used in particular by OneRoster consumers. The client authenticates directly and receives an access token.

At the exchange, the server issues an access token (Bearer, valid for 1 hour) and, for user flows, a refresh token (valid for 30 days). When the openid scope is requested, a signed OIDC id_token is also issued; its signature can be verified via /.well-known/jwks.json. The client_credentials flow issues only an access token, with no refresh token and no id_token.

The access token is then presented in the HTTP header Authorization: Bearer <token>. On every call, Omniscol verifies its signature, checks that the client is still active, that the user still exists and holds the required role, and that the token's scopes do cover the endpoint being called — otherwise the call is refused.

Scopes and consent

The scopes you manage on a client are:

• read:basic — read access to timetables, dashboards and consultation screens (Home, Timetable, Dashboard, Timetable management modules);
• read:user — read access to the user list;
• write:data — write access on those same consultation modules;
• admin — administration access (Administration, Absence management, Timetable management modules).

The server also knows the OIDC scopes (openid, email, profile) and the read-only OneRoster scopes (imsglobal.org prefix). The latter are privileged: a client cannot self-assign them through dynamic registration; they must be provisioned by an administrator on the client's record.

The scope actually granted is the intersection of what the client requests and what is registered for it: a client never obtains more than what its record lists. During the user flow, the consent screen (/oauth/consent) shows the name and logo of the requesting service along with a readable list of the requested scopes, with the Accept and Deny buttons. Approving issues the authorization code and sends the user back to the service; denying sends them back with an access_denied error.

Dynamic client registration

The /oauth/register endpoint implements dynamic registration (Dynamic Client Registration, RFC 7591): a compliant service can declare itself as a client, with no prior manual intervention. This is what lets an MCP agent configure itself from the server URL alone.

Dynamic registration cannot grant itself a privileged scope (the OneRoster scopes): those are silently discarded, and if no valid scope remains, read:basic is granted by default. Privileged scopes remain reserved for provisioning by an administrator.

The OAuth2 client management screen

On Premium accounts, you administer clients from Administration → Import/Export, OAuth2 section, with the OAuth2 button. Access first requires the administrator password — an extra confirmation before the screen opens.

The screen lists the registered clients and, for each one, shows its state (active / inactive), its name, its scopes, its contacts and its URIs (website, logo, redirect URIs). You can:

• Register a client — fill in the name, an optional software_id, the scopes, the contacts, the website, the logo and the redirect URIs. At creation, Omniscol shows the client_id and the client_secret only once.
• Edit a client — only safe fields can be changed: name, scopes, contacts, website and logo. The redirect URIs, the software_id and the secret cannot be changed here.
• Activate or deactivate a client — a deactivated client has its tokens refused from the very next call.
• Delete a client — deletion is permanent.

The client secret

The client_secret is shown only once, at registration. Omniscol keeps only a fingerprint of the secret alongside, never the secret in clear text: it cannot be shown again or recovered later. Copy it immediately into a secrets manager.

The client_id, on the other hand, is deterministic: it derives from the account name, the client name and a fingerprint of its technical metadata. Two strictly identical registrations therefore land on the same identifier.

Renewing the secret (rotation)

Secret rotation exists: it issues a new secret, keeps only the new fingerprint, and returns this new secret only once. It is performed through the dynamic registration management endpoint (/oauth/register/<client_id>/rotation) and requires presenting the registration token handed to the client during its dynamic registration. It is therefore not triggered from the management screen above, which does not handle that token.

OAuth2 or API key: which one to choose

Omniscol offers two machine access mechanisms, with different trust models:

• OAuth2 (this page) — a registered third party obtains, after a user's consent, a short-lived token (1 h), bounded by the granted scopes, refreshable and revocable (by deactivating the client). The client_credentials flow additionally covers machine-to-machine access with no user. It is the mode suited to an identified third-party service, to MCP and to OneRoster.
• API key (see Omniscol API) — a self-contained token signed by the server, which embeds a list of authorized endpoints and which you hand to the external system yourself: no registered third party, no consent screen, no refresh. It is a delegation, by the administrator, of their own rights to a system they control.

In short: the API key fits when you yourself hand access to a system you control; OAuth2 fits when an identified third-party service must obtain a delegated, scoped and revocable access, or when the protocol requires it (MCP, OneRoster).