Wszystkie żądania REST API wymagają przekazania w nagłówku (Authorization) tokena dostępowego (access token). Token dostępowy mogą pobrać użytkownicy Systemu POL-on posiadający konto w Module Centralnego Logowania (MCL). Token dostępowy należy pobrać wykonując żądanie HTTP metodą POST do serwera produkcyjnego Modułu Centralnego Logowania.
Moduł Centralnego Logowania nie posiada środowiska demonstracyjnego. Token dostępowy należy pobrać ze środowiska produkcyjnego MCL, niezależnie od serwera, do którego wysłane jest żądanie dotyczące studentów.
Uwierzytelnianie z tokenem autoryzacyjnym (access token)
Pobranie tokena
Pobranie tokena dostępowego wymaga wysłania żądania HTTP metodą POST z podaniem odpowiednich parametrów.
W przypadku wprowadzenia logowania 2FA pobranie tokena będzie wymagało podania kodu (drugiego składnika) w zapytaniu pobierającym access-token (w polu: totp).
① https://mcl.opi.org.pl/auth/realms/OPI/protocol/openid-connect/token: adres usługi uwierzytelniającej
② header: nagłówek żądania.
③ client_id: identyfikator systemu, w którym zostanie uwierzytelniony użytkownik (dla Systemu POL-on 2.0 należy podać „polon2”).
④ grant_type: rodzaj dostępu potrzebny do uzyskania tokena (dla MCL należy podać „password” – dostęp na podstawie hasła).
⑤ username: nazwa użytkownika.
⑥ password: hasło użytkownika.
Struktura odpowiedzi z tokenem autoryzacyjnym (access token)
Poprawna odpowiedź
W przypadku wysłania poprawnych danych uwierzytelniających, Moduł Centralnego Logowania zwróci token dostępowy (access_token) wraz z informacją o okresie jego ważności.
① access_token: token dostępowy, który umożliwia wykonywanie operacji na zasobach API w imieniu zalogowanego użytkownika.
② expires_in: czas ważności tokena dostępowego (wartość podana w sekundach)
③ refresh_expires_in: czas ważności tokena przedłużającego uwierzytelnienie (wartość podana w sekundach)
④ refresh_token: token umożliwiający wygenerowanie nowego tokena dostępowego bez konieczności ponownego przesyłania loginu i hasła. Ponowne pobranie tokena dostępowego z użyciem refresh tokena zostało opisane w punkcie „Odświeżanie tokena autoryzacyjnego”.
⑤ token_type: typ tokena, w Systemie POL-on używany jest token typu „bearer”.
⑥ not-before-policy: data graniczna, od kiedy można stosować uwierzytelnianie poprzez MCL (czas UNIX).
⑦ session_state: stan sesji (nie ma zastosowania w przypadku korzystania z MCL przez aplikacje zewnętrzne lub zewnętrznych klientów REST API).
⑧ scope: zakresy określające poziom uprawnień.
Błąd uwierzytelniania
W przypadku wystąpienia błędu uwierzytelniania Moduł Centralnego Logowania zwraca komunikat wraz z dodatkowym opisem.
① error: nazwa błędu
② error_description: opis błędu
Odświeżanie tokena autoryzacyjnego
① https://mcl.opi.org.pl/auth/realms/OPI/protocol/openid-connect/token: adres usługi uwierzytelniającej
② header: nagłówek żądania.
③ client_id: identyfikator systemu, w którym zostanie uwierzytelniony użytkownik (dla Systemu POL-on 2.0 należy podać „polon2”).
④ grant_type: rodzaj dostępu potrzebny do uzyskania tokena dostępowego. W przypadku odświeżania tokena dostępowego należy podać wartość refresh_token.
⑤ refresh_token: wartość refresh tokena wykorzystywanego do odświeżenia tokena dostępowego. Należy podać wartość, która została zwrócona w polu refresh_token w odpowiedzi na żądanie opisane w punkcie „Pobranie tokena” lub punkcie „Pobranie offline token”.
Uwierzytelnianie z tokenem autoryzacyjnym typu offline (offline token)
Użytkownik podczas logowania do Modułu Centralnego Logowania może pobierać token typu offline, który nie ma określonej ważności. Offline token służy do pobierania access_tokena, który wymagany jest przy korzystaniu z usług REST API.
Offline token może być zapisany przez użytkownika na dysku, serwerze lub w bazie danych i wykorzystywany wielokrotnie w okresie jego ważności do korzystania z REST API w celu pobierania tokenów dostępowych (access_token) bez konieczności podawania loginu i hasła użytkownika.
Offline token traci ważności po 30 dniach od momentu ostatniego jego użycia w celu pobrania tokena dostępowego (access_token). Po upłynięciu 30 dni od ostatniego użycia offline tokena konieczne jest ponowne jego pobranie i zapisanie z użyciem loginu i hasła użytkownika.
Pobranie offline token
Pobranie tokena dostępowego wymaga wysłania żądania HTTP metodą POST z podaniem odpowiednich parametrów.
W przypadku wprowadzenia logowania 2FA pobranie tokena będzie wymagało podania kodu (drugiego składnika) w zapytaniu pobierającym access-token (w polu: totp).
① https://mcl.opi.org.pl/auth/realms/OPI/protocol/openid-connect/token: adres usługi uwierzytelniającej
② header: nagłówek żądania.
③ client_id: identyfikator systemu, w którym zostanie uwierzytelniony użytkownik (dla Systemu POL-on 2.0 należy podać „polon2”).
④ grant_type: rodzaj dostępu potrzebny do uzyskania tokena (dla MCL należy podać „password” – dostęp na podstawie hasła).
⑤ username: nazwa użytkownika.
⑥ password: hasło użytkownika.
⑦ scope: parametr wywołania usługi, który umożliwia pobranie tokena typu offline. W celu pobrania tokena offline należy dla tego parametru podać wartość „offline_access”.
Struktura odpowiedzi z tokenem autoryzacyjnym
Poprawna odpowiedź
① access_token: token dostępowy, który umożliwia wykonywanie operacji na zasobach API w imieniu zalogowanego użytkownika.
② expires_in: czas ważności tokena dostępowego (wartość podana w sekundach)
③ refresh_expires_in: czas ważności tokena przedłużającego uwierzytelnienie (wartość podana w sekundach). W przypadku tokena typu offline wartość równa się 0, co oznacza, że refresh token nie wygasa pod warunkiem korzystania z niego częściej niż co 30 dni.
④ refresh_token: token typu offline zwracany w przypadku wywołania usługi uwierzytelniania z dodatkowym parametrem 'scope=offline_access’. Token umożliwiający wygenerowanie nowego tokena dostępowego bez konieczności podawania hasła i loginu użytkownika. Pobieranie nowego tokenu dostępowego z użyciem refresh tokena opisane jest w punkcie „Odświeżanie tokena autoryzacyjnego”.
⑤ token_type: typ tokena, w Systemie POL-on używany jest token typu „bearer”.
⑥ not-before-policy: data graniczna, od kiedy można stosować uwierzytelnianie poprzez MCL (czas UNIX).
⑦ session_state: stan sesji (nie ma zastosowania w przypadku korzystania z MCL przez aplikacje zewnętrzne lub zewnętrznych klientów REST API).
⑧ scope: zakresy określające poziom uprawnień. Dla tokena typu offline w polu scope zwracana jest wartość offline_access.
Błąd uwierzytelniania
① error: nazwa błędu
② error_description: opis błędu
Odświeżanie tokena autoryzacyjnego na podstawie offline tokena
W celu pobrania nowego tokena dostępowego z użyciem offline tokena należy wykonać działania opisane w punkcie „Odświeżanie tokena autoryzacyjnego”.