Przejdź do treści Przejdź do głównej nawigacji Przejdź do stopki

Integracja z API PBN – uzyskanie uprawnień oraz sposób autentykacji

Uzyskanie uprawnień do API w wersji produkcyjnej systemu będzie możliwe dopiero po uzyskaniu prawidłowej integracji z API PBN na środowisku testowym (PBN Alpha). Wersja testowa API PBN jest dostępna pod adresem: https://pbn-micro-alpha.opi.org.pl/api/

I. W celu pobierania metadanych należy zarejestrować aplikację dla instytucji w API w celu pozyskania tokenu aplikacji.

Pozyskanie tokenu aplikacji będzie możliwe tylko jeśli w podmiocie istniała rola Menadżera Aplikacji. Rolę Menadżera Aplikacji nadaje Administrator systemu PBN na prośbę Administratora POL-on (osobę z rolą INST_ADM lub INST_NAUK_ADM) na podstawie oficjalnego zgłoszenia przesłanego za pomocą systemu Helpdesk. Zgłoszenie powinno zawierać dane użytkownika, do którego należy przypisać rolę Menadżera Aplikacji (w celach weryfikacyjnych powinno zawierać imię i nazwisko oraz adres e-mail użytkownika) oraz nazwę instytucji, do której rola ma zostać nadana.

Menadżer Aplikacji to rola, która wiąże użytkownika z danym podmiotem. To jej istnienie pozwala na zarządzanie dostępem do API (pozyskanie tokenu dla aplikacji instytucji). Innymi słowy instytucja nie będzie mogła otrzymać tokenu jeżeli nie będzie istniał dla niej Menadżer Aplikacji. Rola Menadżera Aplikacji nadawana jest w kontekście całego podmiotu.

W podmiocie może być więcej niż jeden Menadżer Aplikacji, jednak należy pamiętać, że zarządzają oni jednym i tym samym tokenem aplikacji. Oznacza to, że gdy jeden Menadżer Aplikacji odświeży token aplikacji, pozostałe osoby z rolą Importera Publikacji, które dotychczas pozyskały dla siebie token użytkownika, nie będą mogły z niego skorzystać (nie będzie możliwości dodania lub edycji publikacji, analizie poddawany jest identyfikator aplikacji, token aplikacji oraz token użytkownika)  – wówczas niezbędne będzie pozyskanie nowego tokenu użytkownika na podstawie nowego tokenu aplikacji.

Z tego powodu zalecamy, aby w instytucji był jeden Menadżer Aplikacji zarządzający tokenem aplikacji w całym podmiocie.

Po otrzymaniu zgłoszenia Administrator PBN nadaje rolę Menadżera Aplikacji i rejestruje aplikację dla instytucji, dzięki czemu instytucja otrzyma token aplikacji.

Autoryzacja w ramach pobierania i odczytu metadanych:

Tuż po wysłaniu żądania, analizie poddawane są nagłówki żądania:

  • X-App-Id – identyfikator zarejestrowanej aplikacji reprezentującej instytucję
  • X-App-Token – token dla aplikacji wystawiony podczas rejestracji
przypadku pobierania i odczytu danych z Profilu Instytucji (institution-profile-controller) niezbędny jest także token użytkownika „X-User-Token” w ramach zarejestrowanej aplikacji dla instytucji (pozyskiwanie X-User-Token zostało opisane w dalszej części tego artykułu.

Sprawdzeniu podlega ważność obydwu tokenów (np. mogą one zostać unieważnione, odświeżone) oraz identyfikator aplikacji (tj. jego zgodność z podanym tokenem aplikacji).

 

II. W celu dodawania i edycji publikacji dodatkowo (oprócz rejestracji aplikacji dla instytucji) niezbędne jest pozyskanie tokenu dla użytkownika aplikacji PBN w ramach zarejestrowanej wcześniej aplikacji/instytucji
Pozyskanie tokenu użytkownika w ramach instytucji odbywa się w dwóch etapach:
1) Wysłanie żądania wystawienia jednorazowego kodu, niezbędnego w kolejnym kroku do pozyskania tokenu użytkownika w ramach instytucji:

Poniżej znajduje się film instruktażowy prezentujący pozyskanie jednorazowego kodu (OTT). Pod filmem znajduje się instrukcja opisowa:

Jednorazowy kod można pozyskać przy pomocy np. programu POSTMAN, w tym celu wybieramy żądanie GET, które kierujemy na adres:
https://pbn-micro-alpha.opi.org.pl/auth/pbn/api/registration/user/token/APPLICATION-ID
(APPLICATION-ID
to identyfikator aplikacji = X-App-Id)

Proces uzyskania jednorazowego kodu wymaga autoryzacji – użytkownik musi być zalogowany. Kliknij tutaj, aby zapoznać się ze sposobem autoryzacji użytkownika na przykładzie programu Postman.

Uzyskanie jednorazowego kodu jest możliwe także w przeglądarce internetowej:

  1. Najpierw należy zalogować się do systemu PBN (w wersji testowej należy zalogować się tu: https://pbn-micro-alpha.opi.org.pl/core/#/home).
  2. Następnie należy wprowadzić następujące żądanie w pasek wyszukiwania:
    https://pbn-micro-alpha.opi.org.pl/auth/pbn/api/registration/user/token/APPLICATION-ID,
    przy czym APPLICATION-ID to identyfikator aplikacji dla instytucji, który znaleźć można w zakładce Menadżer Aplikacji:

Użytkownik, który nie jest zalogowany w aplikacji PBN, zostanie przekierowany na stronę logowania aplikacji PBN. Po zalogowaniu musi raz jeszcze wprowadzić ww. żądanie.

W pomyślnym wypadku użytkownik zostanie przekierowany na adres zwrotny aplikacji instytucji, w ramach której wystawienia tokenu żądano. Do adresu w pasku wyszukiwania w przeglądarce doklejony zostanie jednorazowy kod. Kod ten służy do pozyskania właściwego tokenu uwierzytelniającego (tokenu użytkownika). W przeciwnym wypadku o porażce informuje komunikat błędu.

Przykładowe żądanie:
https://pbn-micro-alpha.opi.org.pl/auth/pbn/api/registration/user/token/ZDSW

Przykładowa odpowiedź:
https://www.test.pl/callback?ott=c69df69c-f1da-4404-b3ea-4031b7399c45,
 
przy czym wspomniany „https://www.test.pl/callback” jest adresem zwrotnym podanym podczas rejestracji aplikacji dla instytucji. 

 

2) Pozyskanie tokenu użytkownika na podstawie jednorazowego kodu

Poniżej znajduje się film instruktażowy prezentujący pozyskanie tokenu użytkwonika na podstawie jednorazowego kodu (OTT). Pod filmem znajduje się instrukcja opisowa:

Żądanie POST należy kierować pod adres url:

https://pbn-micro-alpha.opi.org.pl/auth/pbn/api/user/token

Wymagane jest przesłanie nagłówków X-App-Id oraz X-App-Token, w ciele żądania należy podać otrzymany wcześniej jednorazowy kod (w polu „oneTimeToken” należy umieścić wartość pozyskanego tymczasowego kodu ” c69df69c-f1da-4404-b3ea-4031b7399c45″). 

 

W pomyślnym wypadku w ciele odpowiedzi zostaną wyświetlone prawidłowe tokeny:

  • X-User-Token – token użytkownika w ramach instytucji
  • X-App-Token – token dla instytucji
  • X-App-Id – identyfikator aplikacji instytucji

W przeciwnym wypadku o porażce informuje komunikat błędu.

Instrukcja pozyskiwania tokenu użytkownika (X-User-Token) do pobrania w pliku PDF: Pozyskiwanie X-User-Token

 

Autoryzacja w ramach dodawania/edycji publikacji oraz pobierania danych z końcówek institution-profile-controller (dotyczących danych z Profilu Instytucji): 

Po wysłaniu żądania użytkownika, analizie poddawane są nagłówki żądania:

  • X-App-Id – identyfikator zarejestrowanej aplikacji reprezentującej instytucję
  • X-App-Token – token dla aplikacji wystawiony podczas rejestracji
  • X-User-Token – token pozyskany przez użytkownika w ramach ww. aplikacji

W pierwszym etapie sprawdzeniu podlega ważność obydwu tokenów (np. mogą one zostać unieważnione, odświeżone) oraz identyfikator aplikacji (tj. jego zgodność z podanym tokenem aplikacji).

Następnie, po pomyślnej weryfikacji, sprawdzane jest powiązanie użytkownika. Weryfikowane są jego uprawnienia w kontekście instytucji reprezentowanej poprzez token aplikacji, ponieważ aby dodać/edytować publikacje musi on posiadać rolę Importera Publikacji w ramach danej instytucji. Rola Importera Publikacji musi być nadana w kontekście całego podmiotu.

Odświeżanie i unieważnianie tokenu aplikacji

UWAGA!

Odświeżenie tokenu aplikacji powoduje wygenerowanie nowego tokenu dla aplikacji. W wyniku tego traci on powiązanie z tokenami użytkowników aplikacji, które zostały pozyskane wcześniej z wykorzystaniem nieaktualnego już tokenu aplikacji. Aby pozwolić użytkownikowi korzystać z API w ramach danej instytucji należy ponownie dla niego pozyskać token.