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.

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

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