Dokumentacja OAuth2

Informacje podstawowe

Przed przystąpieniem do procesu autoryzacji przy użyciu OAuth2 konieczna jest rejestracja aplikacji, prowadząca do wygenerowania danych dostępowych niezbędnych do uwierzytelnienia aplikacji w serwisie Furgonetka.pl. Niezbędne do komunikacji w ramach protokołu OAuth2 jest uzyskanie Client ID, Client Secret oraz w przypadku standardowej autoryzacji użytkownika kodem, ustalenie adresu powrotu na stronę aplikacji. W tym celu należy skorzystać z naszego narzędzia do zarządzania aplikacjami OAuth2.

Tokeny dostępowe są zgodne ze standardem JWT.

Dla każdej aplikacji OAuth użytkownik może mieć otwartych maksymalnie 20 sesji naraz. Utworzenie nowego tokena dostępowego ponad ten limit spowoduje automatyczne unieważnienie najstarszego tokena.

Autoryzacja użytkownika

Do autoryzacji użytkownika wykorzystana została najpopularniejsza dla standardu OAuth2 autoryzacja dostępu - authorization code. Jest to ścieżka aktywnie angażująca użytkownika i jest wykorzystywana, gdy aplikacja potrzebuje wykonywać operacje w imieniu użytkownika.

Niezbędne jest otrzymanie zgody użytkownika na takie działanie. W tym celu użytkownik zostanie przekierowany na stronę logowania, a następnie na stronę, na której może wyrazić zgodę na to, aby aplikacja miała możliwość wykonywania operacji w jego imieniu.

Przebieg procesu autoryzacji

W aplikacji dostępny jest odnośnik, np. "Zaloguj się przez Furgonetka.pl", wywołujący odpowiednio sparametryzowane żądanie HTTP do zasobu obsługującego uwierzytelnienie użytkownika.

https://api.furgonetka.pl/oauth/authorize?response_type=code&client_id=344...0b9&redirect_uri=https://example.redirect.uri&state=b066559b9b516ccb8c1d12fbfaa4145a

Korzystając z niego użytkownik zostaje przekierowany na formularz logowania na stronie Furgonetka.pl.

Po poprawnym zalogowaniu, użytkownik zostanie przekierowany do strony, na której powinien wyrazić zgodę na dostęp do konta, aby dana aplikacja miała możliwość wykonywania operacji w jego imieniu.

Po wyrażeniu zgody na dostęp, użytkownik zostaje przekierowany do aplikacji na adres przekazany wcześniej w parametrze redirect_uri wraz z parametrami code i opcjonalnie state. Wartość parametru code to kod autoryzacyjny, niezbędny do uzyskania tokena dostępowego. Kod jest jednorazowego użytku i jest ważny przez 30 sekund.

https://example.redirect.uri?code=3ad...5c1&state=b066559b9b516ccb8c1d12fbfaa4145a

Pozyskiwanie tokena

Mając ważny kod, aplikacja zgłasza się po token wykonując żądanie HTTP metodą POST na adres: https://api.furgonetka.pl/oauth/token, dołączając nagłówek Authorization z odpowiednią zawartością.

Przykład użycia

curl -X "POST" "https://api.furgonetka.pl/oauth/token" \
     -H "Authorization: Basic eyJ...V6w" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     --data-urlencode "grant_type=authorization_code" \
     --data-urlencode "code=3ad...5c1"
     --data-urlencode "redirect_uri=https://example.redirect.uri" \

Po poprawnym wykonaniu żądania, zwrócona zostanie odpowiedź w formacie JSON zawierająca m.in. token dostępowy:

{
  "token_type": "Bearer",
  "expires_in": 2678400,
  "access_token": "eyJ...aeg",
  "refresh_token": "def...540",
}

Przedłużenie ważności tokena

Token dostępowy (access_token) ważny jest 30 dni. Aby nie zmuszać użytkownika do ponownej autoryzacji aplikacji zbyt często, udostępniamy również możliwość odświeżania tokenów. Służy do tego refresh_token, który pozwala na uzyskanie nowego tokena dostępowego dla danego użytkownika bez konieczności ingerencji z jego strony. Taki token jest jednorazowego użytku, a po jego użyciu wygenerowany zostaje nowy token dostępowy (ważny kolejne 30 dni) oraz nowy refresh_token.

Przykład użycia

Przykładowe żądanie o przedłużenie ważności tokena:

curl -X "POST" "https://api.furgonetka.pl/oauth/token" \
     -H "Authorization: Basic eyJ...V6w" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     --data-urlencode "grant_type=refresh_token" \
     --data-urlencode "refresh_token=def...540"

Po poprawnym wykonaniu żądania, zwrócona zostanie odpowiedź w formacie JSON, zawierająca nowy access_token oraz nowy refresh_token:

{
  "token_type": "Bearer",
  "expires_in": 2678400,
  "access_token": "eyJ...84c",
  "refresh_token": "def...861",
}

Pozostałe metody pozyskiwania tokena

Autoryzacja typu "password"

Ta metoda pozyskiwania tokena, zakłada, że aplikacja (klient) poprosi o dane uwierzytelniające użytkownika i prześle je bezpośrednio w żądaniu o token dostępowy. Autoryzacja tego typu jest wykorzystywana, gdy aplikacja potrzebuje wykonywać operacje w imieniu użytkownika.

Jeśli użytkownik ma włączone uwierzytelnianie dwuskładnikowe (2FA), żądanie do /oauth/token zwróci błąd autoryzacji zamiast standardowej odpowiedzi z tokenem dostępowym. W takim przypadku w odpowiedzi znajdzie się pole hint zawierające uuid, które należy wykorzystać do kontynuowania procesu uwierzytelniania. Aby zakończyć autoryzację, aplikacja powinna wykonać dodatkowe żądanie do /oauth/2fa, przekazując w nim uzyskany w poprzednim żądaniu uuid, ponownie przesłać identifier oraz kod 2FA wygenerowany przez użytkownika (np. z aplikacji TOTP) twoFactorCode. Użytkownik ma 5 minut na dokończenie procesu uwierzytelniania. Po przekroczeniu tego czasu należy rozpocząć cały proces od nowa.

Przykład użycia

Aby pozyskać token dostępowy należy wysłać żądanie HTTP metodą POST na adres: https://api.furgonetka.pl/oauth/token, dołączając nagłówek Authorization z odpowiednią zawartością.

curl -X "POST" "https://api.furgonetka.pl/oauth/token" \
     -H "Authorization: Basic eyJ...V6w" \
     --data-urlencode "grant_type=password" \
     --data-urlencode "scope=api" \
     --data-urlencode "username=user@example.uri" \
     --data-urlencode "password=p...d"

Po poprawnym przetworzeniu i weryfikacji żądania, zwrócona zostanie odpowiedź w formacie JSON zawierająca access_token oraz refresh_token.

{
  "token_type": "Bearer",
  "expires_in": 2588400,
  "access_token": "eyJ...ygA",
  "refresh_token": "def...ca2",
}

Przykład z włączonym 2FA

Jeśli użytkownik ma włączone 2FA, żądanie /oauth/token zwróci błąd typu 2fa_required, informujący o konieczności wysłania dodatkowego żądania /oauth/2fa.

{
  "error": "2fa_required",
  "error_description": "Konto ma włączone logowanie dwuetapowe.",
  "hint": "0d29d8ab-54da-49b6-b05f-d92b2a15ed0e",
  "message": "Konto ma włączone logowanie dwuetapowe."
}

Aby pozyskać token dostępowy należy wysłać żądanie HTTP metodą POST na adres: https://api.furgonetka.pl/oauth/2fa, dołączając nagłówek Authorization z odpowiednią zawartością.

curl -X "POST" "https://api.furgonetka.pl/oauth/2fa" \
     -H "Authorization: Basic eyJ...V6w" \
     --data-urlencode "uuid=1234-...789" \
     --data-urlencode "identifier=user@example.uri" \
     --data-urlencode "twoFactorCode=123456"

Autoryzacja typu "client credentials"

Tryb client credentials może być pomocny w przypadku, gdy integrowane są z sobą dwa systemy, np. aplikacja wykonująca żądanie API niewymagające uprawnień użytkownika. Należy pamiętać, iż nie ma możliwości przedłużania ważności tokenów pozyskanych w ten sposób.

Przykład użycia

Aby pozyskać token dostępowy należy wysłać żądanie HTTP metodą POST na adres: https://api.furgonetka.pl/oauth/token, dołączając nagłówek Authorization z odpowiednią zawartością.

curl -X "POST" "https://api.furgonetka.pl/oauth/token" \
     -H "Authorization: Basic eyJ...V6w" \
     --data-urlencode "grant_type=client_credentials" \
     --data-urlencode "scope=api"

Po poprawnej weryfikacji i przetworzeniu żądania, zwrócona zostanie odpowiedź w formacie JSON, zawierająca access_token ważny 60 minut.

{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "eyJ...v6A",
}