Token API

Token API pozwala oprogramowaniu zewnętrznemu wywoływać punkty dostępu API Omniscol w imieniu szkoły — w trybie odczytu oraz, jeśli wybrano punkty dostępu API do zapisu, także w trybie zapisu.

Daje to duże możliwości — dlatego należy obchodzić się z nim ostrożnie.

Generowanie

Token generuje się w Udostępnianie (Import/Eksport > Udostępnianie). Proszę podać:

• klucz (generowany w Omniscol, z etykietą i ewentualną datą wygaśnięcia; tę datę wygaśnięcia można później zmienić),
• zakres: listę punktów dostępu API, które ten token będzie mógł wywoływać (proszę przyznać tylko to, co jest absolutnie niezbędne),
• opcjonalnie datę wygaśnięcia tokenu. Data ta jest wpisywana do wygenerowanego JWT i nie można jej później zmienić.

Usunięcie klucza lub upływ jego daty wygaśnięcia natychmiast unieważnia wygenerowane z niego tokeny. Aby zmienić datę wygaśnięcia pojedynczego tokenu, proszę wygenerować nowy JWT.

Użycie

Token przekazuje się w nagłówku HTTP Authorization: Bearer <token> albo (mniej zalecane w środowisku produkcyjnym) w adresie URL przez ?auth=<token>.

Dobre praktyki

• Jeden klucz na integrację — ułatwia niezależne unieważnianie.
• Minimalny zakres — proszę zaznaczać tylko potrzebne API, a nie wszystko domyślnie.
• Wygaśnięcie na właściwym poziomie — daty wygaśnięcia klucza proszę używać do prowadzenia integracji w dłuższym czasie, a daty wygaśnięcia tokenu — do dostępu tymczasowego, którego nie da się zmienić.
• Rotacja okresowa — proszę generować klucz ponownie co 6-12 miesięcy.
• Nie w Gicie — token nie może trafić do publicznego repozytorium pod kontrolą wersji. Proszę korzystać ze zmiennych środowiskowych serwera.

Różnica wobec OIDC / SSO

Do logowania rzeczywistych użytkowników ich tożsamością instytucjonalną służy OIDC / SSO. Token API jest przeznaczony do technicznych integracji serwer-serwer, a nie do codziennego logowania użytkowników.