Protokol

OAuth 2.0 w elogowanie.pl

Jeden przeplyw, authorization code z PKCE. Ta strona opisuje parametry, bledy i decyzje, ktore odbiegaja od domyslnych - reszte zrobi za Ciebie biblioteka zgodna ze standardem.

Spis treści

Przeplyw

Obslugujemy wylacznie authorization code. Implicit i password grant nie sa wspierane i nie beda — oba przekazuja token albo haslo przez kanaly, ktorych nie kontrolujemy. 

1. przegladarka  ->  https://elogowanie.pl/oauth2/auth?...      (uzytkownik sie loguje i zgadza)
2. przegladarka  ->  https://twoja-aplikacja/callback?code=...&state=...
3. Twoj serwer   ->  https://elogowanie.pl/oauth2/token          (kod -> tokeny)
4. Twoj serwer   ->  https://elogowanie.pl/oauth2/userinfo       (token -> claimy)

Krok 3 i 4 wykonuje serwer, nie przegladarka. Klient publiczny (SPA, aplikacja mobilna) pomija sekret i obowiazkowo uzywa PKCE.

PKCE

Wymagane dla klientow publicznych, zalecane dla wszystkich. Obslugujemy metode S256; plain odrzucamy. 

code_verifier   = losowe 43-128 znakow [A-Za-z0-9-._~]
code_challenge  = base64url( sha256( code_verifier ) )   bez znakow '='

/oauth2/auth  ...&code_challenge=<challenge>&code_challenge_method=S256
/oauth2/token ...&code_verifier=<verifier>

Verifier trzymaj po stronie, ktora rozpoczela przeplyw. Jesli zgubisz go miedzy przekierowaniami (np. przez nowy proces workera), wymiana kodu zwroci invalid_grant — to nie jest blad po naszej stronie.

Parametry zadania autoryzacji

Parametry /oauth2/auth
ParametrWymaganyZnaczenie
client_idtakIdentyfikator aplikacji z panelu firmy.
redirect_uritakMusi byc dokladnie jednym z zapisanych adresow. Porownujemy znak po znaku, bez dopasowania wzorcow.
response_typetakZawsze code.
scopetakLista rozdzielona spacjami. Musi zawierac openid.
statetak w praktyceTwoja ochrona przed CSRF. Nie sprawdzamy jej za Ciebie — sprawdz po powrocie.
noncezalecanyWraca w id_token. Chroni przed powtorzeniem tokenu.
code_challengeklient publicznyPatrz PKCE wyzej.
promptnieconsent wymusza ekran zgody, login wymusza ponowne logowanie, none zabrania jakiejkolwiek interakcji.

Wymiana kodu na tokeny

POST https://elogowanie.pl/oauth2/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic base64(client_id:client_secret)

grant_type=authorization_code
&code=<kod z przekierowania>
&redirect_uri=<ten sam co w kroku 1>
&code_verifier=<jesli uzyto PKCE>

Kod jest jednorazowy i wazny minute. Uzycie go drugi raz to nie tylko blad — traktujemy to jak probe powtorzenia i kasujemy caly grant.

Refresh token i rotacja

Najczestszy problem integracji: sam zakres offline_access nie wystarczy. Specyfikacja OIDC kaze go zignorowac bez prompt=consent — dostaniesz wtedy sam access token na godzine i bedziesz szukal bledu u siebie. 

/oauth2/auth?...&scope=openid%20profile%20offline_access&prompt=consent

Refresh tokeny wydajemy tylko klientom poufnym (serwerowym). Kazde uzycie zwraca nowy refresh token, a stary natychmiast przestaje dzialac — to rotacja z wykrywaniem powtorzen:

  • Zapisz nowy refresh_token z kazdej odpowiedzi. Nadpisanie starego jest obowiazkowe.

  • Uzycie zuzytego tokenu oznacza, ze albo zgubiles zapis, albo ktos go ukradl. Nie zgadujemy ktore — kasujemy caly grant i uzytkownik loguje sie ponownie.

  • Nie odswiezaj rownolegle z wielu procesow. Dwa jednoczesne odswiezenia wygladaja identycznie jak kradziez.

Access token: 1 godzina. Refresh token: 30 dni od ostatniego uzycia.

Uniewaznianie

POST https://elogowanie.pl/oauth2/revoke
Authorization: Basic base64(client_id:client_secret)

token=<access lub refresh>&token_type_hint=refresh_token

Uzytkownik moze cofnac dostep w swoim panelu w kazdej chwili. Wtedy Twoje tokeny przestaja dzialac natychmiast: /oauth2/userinfo zwroci 401, a /oauth2/token — invalid_grant. Obsluz oba przypadki jako "trzeba zalogowac ponownie", nie jako awarie.

Bledy, ktore zobaczysz

Kody bledow OAuth
KodZwykle znaczy
invalid_clientZly client_id/sekret albo aplikacja nie ma statusu aktywnej.
invalid_grantKod zuzyty lub przeterminowany, zly code_verifier, albo uzytkownik cofnal zgode.
invalid_redirect_uriAdres powrotu nie jest identyczny z zapisanym (czesto rozni sie ukosnikiem na koncu).
invalid_scopeProsisz o zakres, ktorego aplikacja nie ma przyznanego w panelu.
consent_requiredUzyto prompt=none, a zgoda jest potrzebna.
access_deniedUzytkownik odmowil. To nie jest blad — obsluz go jak decyzje.

Trzy pulapki specyficzne dla nas

  • Adres e-mail nie jest prawdziwym adresem

    Zakres email zwraca alias <cos>@elogowanie.pl, ktory przekazuje poczte do uzytkownika. Traktuj go jak zwykly adres, ale nie probuj po nim laczyc kont z innych zrodel — kazda aplikacja dostaje inny.

  • sub jest inny dla kazdej aplikacji

    To identyfikator pairwise. Stale rozpoznasz po nim tego samego uzytkownika u siebie, ale nie zestawisz go z baza innej firmy. Nie da sie tez przeniesc miedzy Twoimi aplikacjami — kazda ma wlasny.

  • Uzytkownik moze odznaczyc zakres

    Na ekranie zgody kazdy zakres poza openid mozna odrzucic. Odpowiedz zawiera wtedy mniej pol, niz prosiles. Sprawdz, co faktycznie dostales, zamiast zakladac komplet.

Pelna dokumentacja Warstwa OpenID Connect