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.

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://konto.furgonetka.pl/oauth/authorize?response_type=code?client_id=344...0b9&redirect_uri=https://example.redirect.uri&state=b066559b9b516ccb8c1d12fbfaa4145a
Opis parametrów żądania
https://konto.furgonetka.pl/oauth/authorize wymagany End-point dla uwierzytelniania użytkownika w ramach OAuth2.
response_type wymagany Rodzaj odpowiedzi (w tym wypadku code).
client_id wymagany ID klienta otrzymane podczas rejestracji aplikacji.
redirect_uri wymagany Adres powrotu, na który wysłany zostanie kod. Musi być zgodny z tym podanym przy rejestracji aplikacji.
state opcjonalny Token CSRF. Jego użycie jest zalecane, służy do weryfikacji odpowiedzi. Może być zapisany np. w sesji użytkownika i powinien być zweryfikowany po odebraniu odpowiedzi.

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://konto.furgonetka.pl/oauth/token, dołączając nagłówek Authorization z odpowiednią zawartością.

Przykład użycia

curl -X "POST" "https://konto.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" \
Opis parametrów żądania
Authorization wymagany Nagłówek HTTP Authorization typu Basic, z zawartością w formie client_id:client_secret (dane otrzymane przy rejestracji aplikacji) w postaci Base64.
https://konto.furgonetka.pl/oauth/token wymagany End-point pozwalający na uzyskanie tokena OAuth2.
grant_type wymagany Rodzaj dostępu potrzebny do uzyskania tokena, w tym przypadku authorization_code.
code wymagany Kod autoryzacyjny uzyskany podczas procesu autoryzacji użytkownika. Przed przesłaniem należy go zdekodować np. przy pomocy funkcji urldecode($code).
redirect_uri wymagany Adres powrotu zgodny z tym podanym przy rejestracji aplikacji.

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",
}
Opis parametrów odpowiedzi
token_type Typ tokena, w tym przypadku Bearer.
expires_in Czas ważności tokena dostępowego w sekundach (30 dni).
access_token Token dostępowy.
refresh_token Token pozwalający na przedłużenie ważności autoryzacji użytkownika dla aplikacji do 3 miesięcy.

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://konto.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" \
     --data-urlencode "redirect_uri=https://example.redirect.uri"
Opis parametrów żądania
Authorization wymagany Nagłówek HTTP Authorization typu Basic, z zawartością w formie client_id:client_secret (dane otrzymane przy rejestracji aplikacji) w postaci Base64.
https://konto.furgonetka.pl/oauth/token wymagany End-point pozwalający na uzyskanie tokena OAuth2.
grant_type wymagany Rodzaj dostępu potrzebny do uzyskania tokena, w tym przypadku refresh_token.
refresh_token wymagany Wartość refresh tokena, uzyskanego przy generowaniu poprzedniego tokena dostępowego.
redirect_uri wymagany Adres powrotu zgodny z tym podanym przy rejestracji aplikacji.

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",
}
Opis parametrów odpowiedzi
token_type Typ tokena, w tym przypadku Bearer.
expires_in Czas ważności tokena dostępowego w sekundach (30 dni).
access_token Nowy token dostępowy.
refresh_token Nowy refresh_token, pozwalający na przedłużenie ważności autoryzacji użytkownika dla aplikacji do 3 miesięcy.

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.

Przykład użycia

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

curl -X "POST" "https://konto.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"
Opis parametrów żądania
Authorization wymagany Nagłówek HTTP Authorization typu Basic, z zawartością w formie client_id:client_secret (dane otrzymane przy rejestracji aplikacji) w postaci Base64.
https://konto.furgonetka.pl/oauth/token wymagany End-point pozwalający na uzyskanie tokena OAuth2.
grant_type wymagany Rodzaj dostępu potrzebny do uzyskania tokena, w tym przypadku password.
scope opcjonalny Zasięg funkcjonalności do których aplikacja ma mieć dostęp (domyślnie: api).
username wymagany Nazwa użytkownika.
password wymagany Hasło użytkownika.

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",
}
Opis parametrów odpowiedzi
token_type Typ tokena, w tym przypadku Bearer.
expires_in Czas ważności tokena dostępowego w sekundach (30 dni).
access_token Token dostępowy.
refresh_token Token pozwalający na przedłużenie ważności autoryzacji użytkownika dla aplikacji do 3 miesięcy.

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://konto.furgonetka.pl/oauth/token, dołączając nagłówek Authorization z odpowiednią zawartością.

curl -X "POST" "https://konto.furgonetka.pl/oauth/token" \
     -H "Authorization: Basic eyJ...V6w" \
     --data-urlencode "grant_type=client_credentials" \
     --data-urlencode "scope=api"
Opis parametrów żądania
Authorization wymagany Nagłówek HTTP Authorization typu Basic, z zawartością w formie client_id:client_secret (dane otrzymane przy rejestracji aplikacji) w postaci Base64.
https://konto.furgonetka.pl/oauth/token wymagany End-point pozwalający na uzyskanie tokena OAuth2.
grant_type wymagany Rodzaj dostępu potrzebny do uzyskania tokena, w tym przypadku client_credentials.
scope opcjonalny Zasięg funkcjonalności do których aplikacja ma mieć dostęp (domyślnie: 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",
}
Opis parametrów odpowiedzi
token_type Typ tokena, w tym przypadku Bearer.
expires_in Czas ważności tokena dostępowego w sekundach (60 minut).
access_token Token dostępowy.