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.
Uwierzytelnianie z tokenem autoryzacyjnym (access token)
Pobranie tokena
Pobranie tokena dostępowego wymaga wysłania żądania HTTP metodą POST z podaniem odpowiednich parametrów.
1. https://mcl.opi.org.pl/auth/realms/OPI/protocol/openid-connect/token: adres usługi uwierzytelniającej
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 można przeczytać na stronach pomocy: Moduł Centralnego Logowania – logowanie do konta za pomocą dwuetapowego uwierzytelniania
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.
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.
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. https://mcl.opi.org.pl/auth/realms/OPI/protocol/openid-connect/token: adres usługi uwierzytelniającej
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. https://mcl.opi.org.pl/auth/realms/OPI/account/sessions/identyfikatorSesji: adres usługi, której wywołanie skutkuje unieważnieniem określonej sesji. 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.
Pobranie offline token
Pobranie tokena dostępowego wymaga wysłania żądania HTTP metodą POST z podaniem odpowiednich parametrów.
Numery wierszy w kodzie odpowiadają poniższym numerom.
1. https://mcl.opi.org.pl/auth/realms/OPI/protocol/openid-connect/token: adres usługi uwierzytelniającej
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 można przeczytać na stronach pomocy: Moduł Centralnego Logowania – logowanie do konta za pomocą dwuetapowego uwierzytelniania
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.
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.
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. https://mcl.opi.org.pl/auth/realms/OPI/protocol/openid-connect/token: adres usługi uwierzytelniającej
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. https://mcl.opi.org.pl/auth/realms/OPI/protocol/openid-connect/token: adres usługi uwierzytelniającej.
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.
- 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.
- 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”.