OAuth2 / OIDC — podłączenie usługi do Omniscol

Co robi Omniscol jako serwer OAuth2

Usługa zewnętrzna — agent AI, konektor, panel zarządczy — staje się klientem zadeklarowanym na koncie; użytkownik szkoły zatwierdza jej dostęp na ekranie zgody; usługa otrzymuje wtedy token dostępu o krótkim czasie życia, którego zasięg jest ograniczony do przyznanych zakresów oraz do uprawnień tego użytkownika.

Ten mechanizm jest odrębny od SSO użytkowników opisanego na OIDC / SSO, gdzie Omniscol jest natomiast klientem dostawcy tożsamości i służy do logowania użytkowników. Tutaj Omniscol jest po stronie serwera: to usługi łączą się z nim.

Z tego serwera korzystają dwie integracje Omniscol:

• MCP — standardowe uwierzytelnianie agenta AI przebiega przez ten serwer OAuth2 (zob. MCP — podłączenie zewnętrznego agenta AI);
• OneRoster — producent OneRoster uwierzytelnia się tokenem OAuth2 maszyna-maszyna wydanym przez ten sam serwer (zob. OneRoster).

Każda inna usługa zgodna z OAuth2 / OIDC może się z nim połączyć w taki sam sposób.

Wykrywanie i punkty dostępu protokołu

Omniscol publikuje swoje metadane wykrywania pod standardowymi adresami .well-known, udostępnianymi w katalogu głównym domeny konta (na przykład https://nazwa-szkoly.omniscol.com). Zgodny klient odnajduje tam samodzielnie wszystkie punkty dostępu, bez ręcznej konfiguracji:

• /.well-known/oauth-authorization-server — metadane serwera autoryzacji (RFC 8414);
• /.well-known/openid-configuration — metadane OpenID Connect (treść identyczna z poprzednią);
• /.well-known/jwks.json — publiczne klucze weryfikacyjne (JWKS), które pozwalają sprawdzić podpis id_token;
• /.well-known/oauth-protected-resource — metadane chronionego zasobu (RFC 9728).

Metadane te ogłaszają punkty dostępu protokołu:

• /oauth/authorize — żądanie autoryzacji (ekran logowania, a potem zgody);
• /oauth/token — wymiana kodu na token oraz odświeżanie;
• /oauth/register — dynamiczna rejestracja klientów (RFC 7591);
• /oidc/userinfo — informacje o zalogowanym użytkowniku (OIDC);
• /oauth/revoke — unieważnienie tokenu (RFC 7009).

Te punkty dostępu protokołu są publiczne: nie są zastrzeżone dla kont Premium i nie trzeba ich otwierać ręcznie. Premium dotyczy jedynie ekranu zarządzania klientami opisanego niżej.

Przepływy autoryzacji

Omniscol obsługuje trzy przepływy OAuth2:

• Kod autoryzacyjny z PKCE — domyślny przepływ dla usługi działającej w imieniu użytkownika. Usługa przekierowuje użytkownika na /oauth/authorize; po zalogowaniu i wyrażeniu zgody Omniscol zwraca kod autoryzacyjny (ważny 5 minut), który usługa wymienia pod adresem /oauth/token. Przyjęta metoda PKCE to S256, a jedyny akceptowany response_type to code.
• Odświeżanie (refresh_token) — aby przedłużyć dostęp delegowany bez ponownego przechodzenia przez zgodę.
• Client credentials — przepływ maszyna-maszyna, bez użytkownika, używany w szczególności przez konsumentów OneRoster. Klient uwierzytelnia się bezpośrednio i otrzymuje token dostępu.

Przy wymianie serwer wydaje token dostępu (Bearer, ważny 1 godzinę), a w przepływach użytkownika także token odświeżający (ważny 30 dni). Gdy zażądano zakresu openid, wydawany jest również podpisany id_token OIDC; jego podpis weryfikuje się przez /.well-known/jwks.json. Przepływ client_credentials wydaje wyłącznie token dostępu, bez odświeżania i bez id_token.

Token dostępu przesyła się następnie w nagłówku HTTP Authorization: Bearer <token>. Przy każdym wywołaniu Omniscol weryfikuje jego podpis, sprawdza, czy klient jest nadal aktywny, czy użytkownik nadal istnieje i ma wymaganą rolę, oraz czy zakresy tokenu obejmują wywoływany punkt dostępu — w przeciwnym razie wywołanie jest odrzucane.

Zakresy i zgoda

Zakresy, którymi zarządza się dla klienta, to:

• read:basic — odczyt planów lekcji, paneli zarządczych i widoków przeglądania (moduły Strona główna, Plany lekcji, Panel zarządczy, Zarządzanie planami lekcji);
• read:user — odczyt listy użytkowników;
• write:data — zapis w tych samych modułach przeglądania;
• admin — dostęp administracyjny (moduły Administracja, Zarządzanie nieobecnościami, Zarządzanie planami lekcji).

Serwer zna także zakresy OIDC (openid, email, profile) oraz zakresy OneRoster tylko do odczytu (prefiks imsglobal.org). Te ostatnie są uprzywilejowane: klient nie może przypisać ich sobie sam przez dynamiczną rejestrację; musi je udostępnić administrator na karcie klienta.

Faktycznie przyznany zakres to część wspólna tego, o co klient prosi, i tego, co ma zarejestrowane: klient nigdy nie otrzymuje więcej, niż widnieje na jego karcie. W przepływie użytkownika ekran zgody (/oauth/consent) pokazuje nazwę i logo usługi żądającej dostępu oraz czytelną listę żądanych zakresów, z przyciskami Zaakceptuj i Odrzuć. Zatwierdzenie wydaje kod autoryzacyjny i odsyła użytkownika do usługi; odmowa odsyła go z błędem access_denied.

Dynamiczna rejestracja klientów

Punkt dostępu /oauth/register realizuje dynamiczną rejestrację (Dynamic Client Registration, RFC 7591): zgodna usługa może zadeklarować się sama jako klient, bez wcześniejszej ręcznej interwencji. To właśnie pozwala agentowi MCP skonfigurować się na podstawie samego adresu URL serwera.

Dynamiczna rejestracja nie może przypisać sobie zakresu uprzywilejowanego (zakresów OneRoster): są one po cichu pomijane, a jeśli nie zostanie żaden poprawny zakres, domyślnie przyznawany jest read:basic. Zakresy uprzywilejowane pozostają zastrzeżone do udostępnienia przez administratora.

Ekran zarządzania klientami OAuth2

Na kontach Premium klientami administruje się w module Administracja → Import/Eksport, w sekcji OAuth2, przyciskiem OAuth2. Dostęp wymaga najpierw hasła administratora — to dodatkowe potwierdzenie przed otwarciem ekranu.

Ekran wymienia zarejestrowanych klientów i dla każdego pokazuje jego stan (aktywny / nieaktywny), nazwę, zakresy, kontakty oraz URI (witryna, logo, URI przekierowania). Można:

• Zarejestrować klienta — proszę podać nazwę, opcjonalny software_id, zakresy, kontakty, witrynę, logo i URI przekierowania. Przy tworzeniu Omniscol wyświetla tylko raz client_id oraz client_secret.
• Zmodyfikować klienta — modyfikowalne są wyłącznie bezpieczne pola: nazwa, zakresy, kontakty, witryna i logo. URI przekierowania, software_id ani sekret nie podlegają tu zmianie.
• Włączyć lub wyłączyć klienta — tokeny wyłączonego klienta są odrzucane już przy następnym wywołaniu.
• Usunąć klienta — usunięcie jest nieodwracalne.

Sekret klienta

client_secret jest wyświetlany tylko raz, przy rejestracji. Omniscol zachowuje przy kliencie jedynie skrót sekretu, nigdy samego sekretu w postaci jawnej: nie można go później ponownie wyświetlić ani odzyskać. Proszę natychmiast skopiować go do menedżera sekretów.

Natomiast client_id jest deterministyczny: pochodzi od nazwy konta, nazwy klienta i skrótu jego metadanych technicznych. Dwie ściśle identyczne rejestracje dają więc ten sam identyfikator.

Odnowienie sekretu (rotacja)

Rotacja sekretu istnieje: wydaje nowy sekret, zachowuje z niego tylko nowy skrót i zwraca ten nowy sekret tylko raz. Przeprowadza się ją przez punkt dostępu do zarządzania dynamiczną rejestracją (/oauth/register/<client_id>/rotation), co wymaga przedstawienia tokenu rejestracyjnego przekazanego klientowi przy jego dynamicznej rejestracji. Nie jest więc wywoływana z opisanego wyżej ekranu zarządzania, który nie operuje tym tokenem.

OAuth2 czy klucz API: co wybrać

Omniscol udostępnia dwa mechanizmy dostępu maszynowego, o różnych modelach zaufania:

• OAuth2 (ta strona) — zarejestrowana strona trzecia otrzymuje, po wyrażeniu zgody przez użytkownika, token o krótkim czasie życia (1 godz.), ograniczony do przyznanych zakresów, odświeżalny i unieważnialny (przez wyłączenie klienta). Przepływ client_credentials obejmuje dodatkowo komunikację maszyna-maszyna bez użytkownika. To tryb właściwy dla zidentyfikowanej usługi zewnętrznej, dla MCP i dla OneRoster.
• Klucz API (zob. API Omniscol) — samodzielny token podpisany przez serwer, który przenosi listę dozwolonych punktów dostępu i który samodzielnie przekazuje się systemowi zewnętrznemu: bez zarejestrowanej strony trzeciej, bez ekranu zgody, bez odświeżania. To delegowanie przez administratora własnych uprawnień systemowi, nad którym sam ma kontrolę.

Podsumowując: klucz API nadaje się wtedy, gdy dostęp przekazuje się samodzielnie systemowi pozostającemu pod własną kontrolą; OAuth2 nadaje się wtedy, gdy zidentyfikowana usługa zewnętrzna ma uzyskać dostęp delegowany, zawężony zakresem i unieważnialny, albo gdy wymaga tego protokół (MCP, OneRoster).