InsERT API - Wprowadzenie

[Marcin Kasprzycki 111]

 Wstęp

 

W ramach portalu dewelopera InsERT API udostępniamy możliwość tworzenia integracji z aplikacjami webowymi firmy InsERT. Z jego poziomu dostępna jest specyfikacja interfejsów API poszczególnych produktów, możliwość subskrybowania wybranego API oraz rejestrowania tworzonego rozwiązania.
 

 

Rejestracja aplikacji OAuth 2.0

Autoryzacja użytkowników w tworzonych rozwiązaniach odbywa się przy użyciu standardowego protokołu autoryzacji OAuth 2.0. Przed przystąpieniem do procesu autoryzacji wymagane jest zarejestrowanie aplikacji w portalu dewelopera, które prowadzi do uzyskania danych niezbędnych do uwierzytelnienia aplikacji w InsERT API.
 

W procesie rejestrowania aplikacji należy wprowadzić jej nazwę, opis oraz określić zakres wykorzystywanych API (scopes).
 

 

Dodatkowo konieczne jest określenie adresu strony www autora integracji, adresu polityki prywatności oraz adresu powrotu, na który nastąpi przekierowanie po poprawnym przeprowadzeniu procesu uwierzytelnienia i autoryzacji użytkownika.
 

 

Po zarejestrowaniu aplikacji uzyskiwany jest unikalny Client ID oraz Client Secret, które są niezbędne w procesie komunikacji w ramach protokołu OAuth 2.0.

 

 

Autoryzacja użytkownika
 

Proces autoryzacji użytkownika przy użyciu protokołu OAuth 2.0 realizowany jest z wykorzystaniem Authorization Code (with PKCE).

 

W aplikacji, z której użytkownik inicjuje integrację z produktem webowym Insertu, zostaje umieszczony przez autora integracji odnośnik np. Połącz z Subiektem 123, będący odpowiednio przygotowanym adresem URL prowadzącym do serwisu, w którym nastąpi uwierzytelnienie oraz autoryzacja użytkownika.
 

Przykład:

https://kontoapi.insert.com.pl/connect/authorize
	?response_type=code
	&client_id=932...3804c
	&state=fd9...16e97
	&scope=openid%20profile%20email%20subiekt123%20offline_access
	&redirect_uri=https%3A%2F%2Fprzykladowa-integracja.pl%2Fv1%2Fcallback
	&code_challenge=odd...dWm3
	&code_challenge_method=S256

Parametry żądania:

Rodzaje scopów:

 

Po skorzystaniu z opcji Połączenia z Subiektem 123 użytkownik zostaje przekierowany na stronę logowania do Konta InsERT, na której potwierdza swoją tożsamość za pomocą konta wykorzystywanego podczas dostępu do aplikacji.

 

 

W kolejnym kroku użytkownik wyraża zgodę na dostęp do danych swojego Konta InsERT (dane profilowe, e-mail) oraz danych, które gromadzi w aplikacji Subiekt 123.
 

 

Po wyrażeniu zgody następuje przekierowanie na adres powrotu zdefiniowany podczas rejestrowania aplikacji przez jej autora. W odpowiedzi przekazany zostaje m.in. parametr code, który pozwala w okresie jego ważności (60 sekund) uzyskać token dostępowy (access_token).
 

Przykład odpowiedzi:

https://przykladowa-integracja.pl/v1/callback
	?code=fa1...25d3d9
	&state=fd9...16e97

 

 

Pozyskiwania oraz odświeżanie tokenów dostępowych
 

W oparciu o otrzymany po poprawnej autoryzacji użytkownika parametr code, aplikacja uzyskuje token wykonując żądanie HTTP z dołączonym nagłówkiem:

POST https://kontoapi.insert.com.pl/connect/token

 

Nagłówek:

Parametry żądania:

Przykład odpowiedzi po poprawnym wykonaniu żądania:

{
	"id_token": "eyJ...TaNgITUw",
	"access_token": "ey...16M9YA",
	"expires_in": 3600,
	"token_type": "Bearer",
	"refresh_token": "78C...5F3A5",
	"scope": "openid profile email subiekt123 offline_access"
}

Uzyskany token dostępowy (access_token) posiada ważność przez 60 minut. W celu uzyskania nowego tokena dostępowego należy posłużyć się tokenem odświeżającym (refresh_token), którego ważność została ustalona na 90 dni. Każde uzyskanie nowego tokena dostępowego, wydłuża ważność tokena odświeżającego. Maksymalny czas życia dla tokena odświeżającego został ustalony na 365 dni.
 

Przykład żądania pozwalającego uzyskać nowy token dostępowy w oparciu o posiadany token odświeżający:

POST https://kontoapi.insert.com.pl/connect/token

Nagłówek:

Parametry żądania:

Przykład odpowiedzi po poprawnym wykonaniu żądania:

{
	"id_token": "eyJ...TaNgITUw",
	"access_token": "ey...16M9YA",
	"expires_in": 3600,
	"token_type": "Bearer",
	"refresh_token": "78C...5F3A5",
	"scope": "openid profile email subiekt123 offline_access"
}

 

 

Subskrypcja API
 

Korzystanie z API wymaga posiadania aktywnej subskrypcji dla wybranego produktu. W tym celu należy aktywować subskrypcję w portalu dewelopera InsERT API.
 

Dla każdej subskrypcji generowane są dwa klucze, co pozwala zapewnić nieprzerwane działanie tworzonego rozwiązania na wypadek potrzeby unieważnienia/przegenerowania jednego z nich.

 

Klucz subskrypcji należy przekazywać wraz z każdym żądaniem wysyłanym do API naszych produktów.

 

 

Przykłady integracji
 

Zapraszamy do zapoznania się z przykładami integracji, które zostały opublikowane w serwisie GitHub.