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 włączenia uwierzytelniania dwuskładnikowego (2FA) pobranie tokena będzie wymagało podania kodu (drugiego składnika) w zapytaniu pobierającym access-token (w polu: totp).

Numery wierszy w kodzie odpowiadają poniższym numerom.
  1. adres usługi uwierzytelniającej: https://mcl.opi.org.pl/auth/realms/OPI/protocol/openid-connect/token
  2. header: nagłówek żądania.
  3. client_id: identyfikator systemu, w którym zostanie uwierzytelniony użytkownik (dla Systemu POL-on 2.0 należy podać „polon2”).
  4. grant_type: rodzaj dostępu potrzebny do uzyskania tokena (dla MCL należy podać „password” – dostęp na podstawie hasła).
  5. username: nazwa użytkownika.
  6. password: hasło użytkownika.
  7. totp: jednorazowy kod dostępu, który powinien zostać podany w przypadku włączonego uwierzytelniania dwuskładnikowego (2FA). W przypadku braku uwierzytelniania dwuskładnikowego pole można pominąć lub pozostawić puste. Kod powinien zostać wygenerowany przed wykonaniem żądania. Więcej o uwierzytelnianiu dwuskładnikowym przeczytasz tutaj.

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.

Numery wierszy w kodzie odpowiadają poniższym numerom.

  1. {
  2. access_token: token dostępowy, który umożliwia wykonywanie operacji na zasobach API w imieniu zalogowanego użytkownika. Token w formacie JWT.
  3. expires_in: czas ważności tokena dostępowego (wartość podana w sekundach)
  4. refresh_expires_in: czas ważności tokena przedłużającego uwierzytelnienie (wartość podana w sekundach)
  5. 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 w formacie JWT.
  6. token_type: typ tokena, w Systemie POL-on używany jest token typu „bearer”.
  7. not-before-policy: data graniczna, od kiedy można stosować uwierzytelnianie poprzez MCL (czas UNIX).
  8. session_state: identyfikator sesji.
  9. 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.

Numery wierszy w kodzie odpowiadają poniższym numerom.

  1. {
  2. error: nazwa błędu
  3. error_description: opis błędu

Odświeżanie tokena dostępowego

Odświeżenie tokena dostępowego polega na wysłaniu nowego żądania do usługi uwierzytelniającej. Ponowne odpytanie usługi z użyciem refresh tokena pozwala pobrać nowy token dostępowy bez konieczności przesyłania loginu i hasła użytkownika. W wyniku odświeżenia zwracany jest nowy zestaw tokenów – access token i refresh_token.

Opis procesu pobierania i odświeżania tokena dostępowego

  • Użytkownik za pomocą loginu, hasła i mechanizmu 2FA, o ile został skonfigurowany, pobiera token dostępowy oraz powiązany z nim refresh token. Opis sposobu pobierania tokena dostępowego znajduje się punkcie „Pobieranie tokena”.
  • Użytkownik zapisuje swój refresh token wraz z jego okresem ważności, który znajduje się w polu
    refresh_expires_in.
  • Użytkownik, posługując się refresh tokenem, wykonuje żądanie, którego celem jest pobranie nowego tokena dostępowego.

Odświeżenie tokena dostępowego wymaga wysłania żądania HTTP metodą POST z podaniem odpowiednich parametrów. Poniżej został przedstawiony przykład wywołania usługi uwierzytelniającej z użyciem refresh tokena.

Numery wierszy w kodzie odpowiadają poniższym numerom.

  1. adres usługi uwierzytelniającej: https://mcl.opi.org.pl/auth/realms/OPI/protocol/openid-connect/token
  2. header: nagłówek żądania.
  3. client_id: identyfikator systemu, w którym zostanie uwierzytelniony użytkownik (dla Systemu POL-on 2.0 należy podać „polon2”).
  4. 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.
  5. 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”.
  • Odświeżenie tokena dostępowego można wykonać w okresie, w którym refresh token zachowuje swoją ważność liczoną od momentu jego pobrania. Ważność refresh tokena określona jest w odpowiedzi usługi uwierzytelniającej w polu refresh_expires_in. Data ważności zapisana jest również w tokenie i można ją odczytać poprzez analizę jego zawartości. Token zwracany jest w formacie JWT, w którym data wygaśnięcia zapisana formacie UNIX znajduje się w polu exp.
  • W wyniku odpytania usługi uwierzytelniającej z użyciem refresh tokena użytkownik otrzymuje taką samą odpowiedź jak w przypadku pobierania tokena z użyciem hasła i loginu. Opis odpowiedzi został umieszczony w punkcie „Struktura odpowiedzi z tokenem dostępowym (akces token)”. W wyniku odświeżenia zwracany jest nowy zestaw tokenów – access token i refresh token.
  • Użytkownik zapisuje nowy refresh token wraz z jego okresem ważności refresh_expires_in. Zapisanie nowego refresh tokena pozwoli przejść proces odświeżania tokena dostępowego ponownie.
  • Użytkownik komunikuje się z REST API Systemu POL-on korzystając z odświeżonego tokena dostępowego (access token). Token może być używany do czasu jego odświeżenia lub wygaśnięcia.
  • Możliwe jest wielokrotne odświeżanie tokena dostępowego bez podawania hasła i loginu. Operację odświeżania można wykonać wielokrotnie, jeżeli za każdym razem użytkownik będzie posługiwał się nowym refresh tokenem, który został pobrany przy odświeżeniu i pod warunkiem że nie stracił on swojej ważności.

Unieważnienie sesji powiązanej z tokenem dostępowym

Moduł Centralnego Logowania pozwala na unieważnienie sesji, w której używany jest określony access token. Operację unieważnienia sesji można wykonać, jeżeli zaistniała konieczność wyłączenia z użycia określonego access tokena lub refresh tokena. W celu unieważnienia sesji konieczna jest znajomość wartości pola session_state, które zwracane jest podczas pobierania lub odświeżania tokena. Wartość pola session_state jest identyfikatorem sesji. Operacja unieważnienie sesji ma zastosowanie również w przypadku offline tokenów, o których mowa w punkcie „Pobieranie offline tokena”.

Unieważnienie sesji powiązanej z tokenem dostępowym wymaga wysłania żądania HTTP metodą DELETE z podaniem odpowiednich parametrów.

Numery wierszy w kodzie odpowiadają poniższym numerom.

  1. adres usługi, której wywołanie skutkuje unieważnieniem określonej sesji: https://mcl.opi.org.pl/auth/realms/OPI/account/sessions/identyfikatorSesji.
    Fragment adresu identyfikatorSesji należy zastąpić wartością zwracaną w polu session_state. Informacja o stanie sesji zwracana jest przy każdorazowym pobieraniu lub odświeżaniu tokena dostępowego.
  2. header: nagłówek żądania, w którym należy zastąpić tekst tokenDostępowyDoUnieważnienia wartością tokena.
  3. header: nagłówek żądania, nie wymaga zmian przed wykonanie polecenia.

Uwierzytelnianie z tokenem autoryzacyjnym typu offline (offline token)

Użytkownik podczas logowania do Modułu Centralnego Logowania może pobierać token typu offline. Offline token służy do pobierania tokena dostępowego (access_tokena), bez konieczności wprowadzania hasła i loginu.

Offline token może być zapisany przez użytkownika na dysku, serwerze lub w bazie danych i wykorzystywany w okresie jego ważności do korzystania z REST API systemu POL-on.

Offline token jest typem refresh tokena. Token ten jest zwracany przez usługę uwierzytelniająca po jej odpytaniu z użyciem określonych parametrów.

Pobieranie i odświeżanie offline tokena różni się od pobierania i odświeżania standardowego tokena dostępowego. Główna różnica polega na ustawieniu wartości parametru scope na offline_access, który w przypadku standardowego tokena dostępowego pozostaje pusty.

Offline token traci ważności po 30 dniach. Po upłynięciu 30 dni od jego pobrania konieczne jest ponowne wykonanie żądania, o którym mowa w punkcie „Pobieranie offline tokena”.
W okresie ważności refresh tokena możliwe jest pobranie nowego tokena offline za pomocą
procedury opisanej w punkcie „Odświeżanie tokena dostępowego na podstawie offline tokena” bez konieczności podawania loginu i hasła.

Pobranie offline token

Pobranie tokena dostępowego wymaga wysłania żądania HTTP metodą POST z podaniem odpowiednich parametrów.

W przypadku włączenia uwierzytelniania dwuskładnikowego (2FA) pobranie tokena będzie wymagało podania kodu (drugiego składnika) w zapytaniu pobierającym access-token (w polu: totp).

Numery wierszy w kodzie odpowiadają poniższym numerom.

  1. adres usługi uwierzytelniającej: https://mcl.opi.org.pl/auth/realms/OPI/protocol/openid-connect/token: 
  2. header: nagłówek żądania.
  3. client_id: identyfikator systemu, w którym zostanie uwierzytelniony użytkownik (dla Systemu POL-on 2.0 należy podać „polon2”).
  4. grant_type: rodzaj dostępu potrzebny do uzyskania tokena (dla MCL należy podać „password” – dostęp na podstawie hasła).
  5. username: nazwa użytkownika.
  6. password: hasło użytkownika.
  7. 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”.
  8. totp: jednorazowy kod dostępu, który powinien zostać podany w przypadku włączonego uwierzytelniania dwuskładnikowego (2FA). W przypadku braku uwierzytelniania dwuskładnikowego pole można pominąć lub pozostawić puste. Kod powinien zostać wygenerowany przed wykonaniem żądania. Więcej o uwierzytelnianiu dwuskładnikowym przeczytasz tutaj.

Struktura odpowiedzi usługi uwierzytelniającej, która została uruchomiona z użyciem offline tokena

Poprawna odpowiedź

Numery wierszy w kodzie odpowiadają poniższym numerom.

  1. {
  2. access_token: token dostępowy, który umożliwia wykonywanie operacji na zasobach API w imieniu zalogowanego użytkownika. Token w formacie JWT.
  3. expires_in: czas ważności tokena dostępowego (wartość podana w sekundach)
  4. refresh_expires_in: czas ważności tokena przedłużającego uwierzytelnienie (wartość podana w sekundach).
  5. 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 dostępowego na podstawie offline tokena”. Token w formacie JWT.
  6. token_type: typ tokena, w Systemie POL-on używany jest token typu „bearer”.
  7. not-before-policy: data graniczna, od kiedy można stosować uwierzytelnianie poprzez MCL (czas UNIX).
  8. session_state: identyfikator sesji.
  9. scope: informacje o zakresie danych, które są przechowywane w tokenie. Dla tokena typu offline w polu scope zwracana jest wartość offline_access.

Błąd uwierzytelniania

Numery wierszy w kodzie odpowiadają poniższym numerom.

  1. {
  2. error: nazwa błędu
  3. error_description: opis błędu

Odświeżanie tokena autoryzacyjnego na podstawie offline tokena

Odświeżenie tokena dostępowego polega na wysłaniu nowego żądania do usługi uwierzytelniającej. Ponowne odpytanie usługi z użyciem offline tokena (refresh tokena) pozwala pobrać nowy token dostępowy bez konieczności przesyłania loginu i hasła użytkownika. W wyniku odświeżenia zwracany jest nowy zestaw tokenów – access token i refresh_token. Odświeżanie offline tokena różni się od procesu odświeżania standardowego tokena dostępowego. Główna różnica polega na ustawieniu wartości parametru scope na offline_access, który w przypadku standardowego tokena dostępowego pozostaje pusty.

Opis procesu pobierania i odświeżania tokena dostępowego z użyciem offline tokena

  • Użytkownik za pomocą loginu, hasła i mechanizmu 2FA, o ile został skonfigurowany, pobiera token dostępowy oraz powiązany z nim refresh token. Opis sposobu pobierania tokena dostępowego znajduje się punkcie „Pobieranie offline tokena”.
  • Użytkownik zapisuje swój refresh token wraz z jego okresem ważności, który znajduje się w polu
    refresh_expires_in.
  • Użytkownik, posługując się refresh tokenem, wykonuje żądanie, którego celem jest pobranie nowego tokena dostępowego.

Poniżej został przedstawiony przykład wywołania usługi uwierzytelniającej z użyciem offline tokena (refresh tokena).

Numery wierszy w kodzie odpowiadają poniższym numerom.

  1. adres usługi uwierzytelniającej: https://mcl.opi.org.pl/auth/realms/OPI/protocol/openid-connect/token
  2. header: nagłówek żądania.
  3. client_id: identyfikator systemu, w którym zostanie uwierzytelniony użytkownik (dla Systemu POL-on 2.0 należy podać „polon2”).
  4. grant_type: rodzaj dostępu potrzebny do uzyskania tokena dostępowego. W przypadku odświeżania tokena dostępowego z użyciem offline tokena należy ustawić wartość parametru na refresh_token.
  5. refresh_token: wartość refresh tokena wykorzystywanego do odświeżenia tokena dostępowego. W tym przypadku należy podać wartość offline tokena, która została wcześniej pobrana i zapisana przez użytkownika. Należy podać wartość, która została zwrócona w polu refresh_token w odpowiedzi na żądanie opisane w punkcie „Pobranie offline token” lub w wyniku odświeżenia offline tokena.
  6. scope: informacja o zakresie danych, które są przechowywanych w tokenie. Dla tokena typu offline w polu scope należy podać wartość offline_access.
  • Odświeżenie tokena dostępowego można wykonać w okresie, w którym refresh token zachowuje swoją ważność liczoną od momentu jego pobrania. Ważność refresh tokena określona jest w odpowiedzi usługi uwierzytelniającej w polu refresh_expires_in. Data ważności zapisana jest również w tokenie i można ją odczytać poprzez analizę jego zawartości. Token zwracany jest w formacie JWT, w którym data wygaśnięcia zapisana formacie UNIX znajduje się w polu exp.
  • W wyniku odpytania usługi uwierzytelniającej z użyciem refresh tokena użytkownik otrzymuje taką samą odpowiedź jak w przypadku pobierania tokena z użyciem hasła i loginu. Opis odpowiedzi dostępny jest w punkcie „Struktury odpowiedzi usługi uwierzytelniającej, która została uruchomiona z użyciem offline tokena”
  • Użytkownik zapisuje nowy refresh token wraz z jego okresem ważności refresh_expires_in. Zapisanie nowego refresh tokena pozwoli przejść proces odświeżania tokena dostępowego ponownie.
  • Możliwe jest wielokrotne odświeżanie tokena dostępowego bez podawania hasła i loginu, jeżeli za każdym razem użytkownik będzie posługiwał się nowym refresh tokenem, który został pobrany przy odświeżeniu i pod warunkiem że nie stracił on swojej ważności.

Użycie tokena offline w integracji systemu zewnętrznego z systemem POL-on

Główną różnicą pomiędzy standardowym tokenem, o którym mowa w punkcie „Pobieranie tokena” a tokenem offline opisanym w punkcie „Pobieranie offline token” jest okres ważności. Wydłużony okres ważności offline tokena umożliwia jego zapisanie i wielokrotne używanie w komunikacji poprzez REST API bez konieczności częstego odpytywania usługi uwierzytelniającej. Offline token może zostać pobrany raz na jakiś czas z użyciem hasła i loginu, a następnie zapisany w systemie uczelnianym. Pobrany i zapisany token może być wielokrotnie odświeżany bez udziału użytkownika.

Zalecany scenariusz integracji z Systemem POL-on z użyciem offline tokena

  • Użytkownik za pomocą loginu, hasła i mechanizmu 2FA, o ile został skonfigurowany, pobiera token dostępowy oraz powiązany z nim refresh token typu offline (offline token). Opis sposobu pobierania tokena dostępowego typu offline znajduje się w punkcie „Pobieranie offline token”. Token typu offline znajduje się w odpowiedzi w polu refresh_token.
  • Użytkownik zapisuje refresh token typu offline wraz z jego datą ważności. Data ważności zapisana jest w tokenie i można ją odczytać poprzez analizę jego zawartości. Token zwracany jest w formacie JWT, w którym data wygaśnięcia zapisana formacie UNIX znajduje się w polu exp.
  • System uczelniany na początku sesji wysyłania danych do Systemu POL-on powinien pobrać standardowy token dostępowy. Pobranie standardowego tokena dostępowego powinno zostać wykonane z użyciem zapisanego wcześniej oflline tokena.

Pobranie tokena dostępowego na podstawie offline tokena wymaga wysłania żądania HTTP metodą POST z podaniem odpowiednich parametrów. Poniżej przykład pobrania standardowego tokena dostępowego z użyciem offline tokena.

Numery wierszy w kodzie odpowiadają poniższym numerom.

  1. adres usługi uwierzytelniającej: https://mcl.opi.org.pl/auth/realms/OPI/protocol/openid-connect/token
  2. header: nagłówek żądania.
  3. client_id: identyfikator systemu, w którym zostanie uwierzytelniony użytkownik (dla Systemu POL-on 2.0 należy podać „polon2”).
  4. grant_type: rodzaj dostępu potrzebny do uzyskania tokena dostępowego. W przypadku pobierania tokena dostępowego na podstawie offline tokena należy podać wartość refresh_token.
  5. refresh_token: wartość zapisanego offline tokena. Należy podać wartość, która została zwrócona w polu refresh_token w odpowiedzi na żądanie opisane w punkcie „Pobranie offline token”.
  • System uczelniany powinien zapisać otrzymany standardowy refresh_token oraz access_token jako
    tymczasowe zmienne związane z sesją wysyłania danych.
  • W trakcie wysyłania danych do Systemu POL-on 2.0 do uwierzytelniania należy korzystać z pobranego tymczasowego access_tokena. Gdy jego ważność wygaśnie, należy użyć refresh_tokena do uzyskiwania nowych access tokenów, zgodnie z procedurą opisaną w punkcie „Odświeżanie tokena dostępowego”. Przy każdej kolejnej operacji generowania tymczasowego access_tokena należy aktualizować powiązany z nim refresh_token.

Zaleca się używanie offline tokena tylko do inicjowania sesji wysyłania danych do Systemu
POL-on. Operacje wykonywanie w trakcie sesji wysyłania danych powinny być
uwierzytelniane za pomocą standardowego tokena dostępowego, o którym mowa w
punkcie „Pobieranie tokena” oraz w punkcie „Odświeżanie tokena dostępowego”.

  • Na koniec sesji wysyłania danych do Systemu POL-on, należy odświeżyć offline token, zgodnie z procedurą opisaną w punkcie „Odświeżanie tokena dostępowego na podstawie offline tokena” oraz zaktualizować zapisany offline token wraz z jego datą ważności.

Offline token traci ważności po 30 dniach. W związku z powyższym zalecane jest odświeżanie offline tokena po każdej sesji przekazywania danych do systemu POL-on, co zapobiegnie jego wygaśnięciu. Odświeżanie tokena zostało omówione w punkcie „Odświeżanie tokena dostępowego na podstawie offline tokena”.

  • System uczelniany raz na miesiąc powinien sprawdzać, czy nie wygasa ważność offline tokena. Jeżeli jego ważność wygasa należy go odświeżyć tak jak zostało to opisane w punkcie „Odświeżanie tokena dostępowego na podstawie offline tokena”

Unieważnienie sesji powiązanej z offline tokenem

Unieważnienie sesji z offline tokenem należy wykonać zgodnie z opisem umieszczonym w punkcie „Unieważnienie sesji powiązanej z tokenem dostępowym”.