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
W 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:
Kod jednorazowy, czyli One Time Token (OTT) można pozyskać na 3 sposoby:
a) Za pomocą aplikacji do obsługi żądań API – np. POSTMAN.
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:
– dla środowiska testowego PBN Alpha – https://pbn-micro-alpha.opi.org.pl/auth/pbn/api/registration/user/token/APPLICATION-ID
(APPLICATION-ID to identyfikator aplikacji = X-App-Id)
– dla środowiska produkcyjnego – https://pbn.nauka.gov.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.
b) Z poziomu aplikacji PBN
Najprostszym sposobem na pozyskanie kodu jednorazowego w ramach instytucji, jest wygenerowanie go z poziomu aplikacji PBN. Operacja jest możliwa do wykonania dla użytkownika z rolą Managera aplikacji lub Importera publikacji.
W celu wygenerowania OTT należy przejść do modułu Konto użytkownika, który dostępny jest z poziomu rozwijanego menu z poziomu górnej belki użytkownika, a następnie do zakładki Twoje aplikacje.
Z prawej strony, nad listą wpisów, zawierającą informacje o tokenach aplikacji, znajduje się przycisk „Pobierz OTT”.
Naciśniecie przycisku spowoduje otworzenie się okna modalnego z listą wyboru Tokenu aplikacji, dla której chcemy wygenerować OTT.
Po wybraniu właściwej aplikacji, w celu pobrania OTT konieczne jest zatwierdzenie przyciskiem „Pobierz”. Po zatwierdzeniu użytkownikowi prezentowany jest komunikat o pomyślnym wystawieniu OTT:
W przypadku braku dokonania wyboru i zatwierdzenia przyciskiem „Pobierz” system wyświetli komunikat informujący użytkownika o konieczności podania tokenu aplikacji: „Podanie tokenu aplikacji jest wymagane!”. Zamknięcia okna bez konieczności wyboru, można dokonać za pomocą przycisku „Anuluj” lub przyciskiem „X”.
c) Przy użyciu przeglądarki internetowej
W celu uzyskania kodu jednorazowego za pomocą przeglądarki internetowej, konieczne jest uprzednie zalogowanie się do aplikacji PBN. Następnie w pasku adresu dowolnej przeglądarki internetowej należy wpisać następujące żądanie:
https://pbn.nauka.gov.pl/auth/pbn/api/registration/user/token/APPLICATION-ID, przy czym zamiast APPLICATION-ID, należy umieścić Identyfikator aplikacji X-App-Id
Po wysłaniu żądania (enter bądź kliknięcie w przycisk lupki) użytkownik zostanie przekierowany na adres zwrotny aplikacji zarejestrowanej w PBN. Na końcu adresu w pasku adresu strony będzie doklejony kod jednorazowy OTT:
2) Pozyskanie tokenu użytkownika na podstawie uzyskanego jednorazowego kodu (OTT)
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:
- dla środowiska testowego PBN Alpha – https://pbn-micro-alpha.opi.org.pl/auth/pbn/api/user/token
- dla środowiska produkcyjnego – https://pbn.nauka.gov.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. |