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.
① 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.
Pobranie offline token
Pobranie tokena dostępowego wymaga wysłania żądania HTTP metodą POST z podaniem odpowiednich parametrów.
① 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”.