Protokol

OpenID Connect

Warstwa tozsamosci nad OAuth 2.0: discovery, id_token, claimy i to, co robimy inaczej niz typowy dostawca — pairwise sub i zakresy o rozdzielczosci jednego pola.

Spis treści

Discovery

Jesli Twoja biblioteka umie discovery, wystarczy jej issuer. Reszte — adresy, klucze, obslugiwane metody — pobierze sama. 

issuer:    https://elogowanie.pl
discovery: https://elogowanie.pl/.well-known/openid-configuration
jwks:      https://elogowanie.pl/oauth2/jwks

Klucze podpisujace rotujemy bez zapowiedzi. Nie kopiuj ich do konfiguracji — pobieraj z JWKS i buforuj z uwzglednieniem kid z naglowka tokenu.

id_token

Podpisany RS256. Zanim mu zaufasz, sprawdz w tej kolejnosci:

  • Podpis kluczem z JWKS o pasujacym kid.

  • iss rowny dokladnie https://elogowanie.pl.

  • aud zawiera Twoj client_id.

  • exp w przyszlosci, iat nie z odleglej przeszlosci.

  • nonce rowny temu, ktory wyslales.

id_token potwierdza fakt logowania. Do pobrania aktualnych danych sluzy /oauth2/userinfo — dane w tokenie sa zamrozone na moment wydania.

Identyfikator sub

Wydajemy identyfikator pairwise w rozumieniu OpenID Connect Core: ta sama osoba ma inny sub w kazdej aplikacji. 

osoba A  ->  aplikacja sklepu   ->  sub = 7f3c1a...   (staly)
osoba A  ->  aplikacja banku    ->  sub = c0d942...   (inny, tez staly)

Co to daje: dwie niezalezne firmy nie moga zestawic swoich baz po identyfikatorze. Czego to nie daje: anonimowosci wobec pojedynczej aplikacji — ta rozpoznaje uzytkownika przy kazdym logowaniu i wlasnie o to chodzi.

Konsekwencja praktyczna: jesli masz dwie aplikacje OAuth i chcesz rozpoznac w nich te sama osobe, sub Ci tego nie zalatwi. Uzyj jednej aplikacji dla obu produktow albo polacz konta u siebie.

Claimy i zakresy

Kazdy zakres wnosi wylacznie swoje claimy. Nie ma zakresu zbiorczego, ktory po cichu dokladalby wiecej, niz sugeruje nazwa.

Zakresy OIDC i wnoszone claimy
ZakresClaimy
openid sub
profile name, given_name, family_name, gender, locale, updated_at
given_name given_name
family_name family_name
email email
email_verified email_verified
phone ⚠ phone_number
phone_verified phone_number_verified
age_over_18 age_over_18
age ⚠ age
birthdate ⚠ birthdate
address ⚠ address
document ⚠ document_verified, document_type, document_country, document_expires_at
pesel ⚠ pesel
verified_claims elg_verification

⚠ oznacza zakres wrazliwy — na ekranie zgody jest wyrozniony, a uzytkownik czesciej go odrzuca. Pros o niego tylko wtedy, gdy naprawde go potrzebujesz.

Minimalizacja w praktyce

Najczestszy blad integracji to prosba o date urodzenia, zeby sprawdzic pelnoletnosc. Mamy do tego osobny zakres, ktory zwraca jedno pole logiczne: 

scope=openid age_over_18
{
  "sub": "7f3c1a...",
  "age_over_18": true
}

scope=openid birthdate            <- prosisz o date urodzenia
{
  "sub": "7f3c1a...",
  "birthdate": "1994-03-12"       <- i o nia sie tlumaczysz przed uzytkownikiem
}

Ekran zgody pokazuje uzytkownikowi dokladnie to, co dostaniesz. Zakres age_over_18 przechodzi bez zastanowienia; birthdate czesto nie.

Poziom potwierdzenia danych

Dane w profilu maja rozne pochodzenie i nie udajemy, ze sa rowne. Zakres verified_claims dokłada claim elg_verification z poziomem dla kazdego wydanego pola: 

{
  "given_name": "Anna",
  "elg_verification": {
    "given_name": { "level": "DOCUMENT", "verified_at": "2026-08-14T10:22:31Z" },
    "email":      { "level": "OTP",      "verified_at": "2026-07-02T08:10:00Z" }
  }
}
Poziomy potwierdzenia
PoziomCo znaczy
SELFUzytkownik wpisal sam. Niczym niepotwierdzone.
OTPPotwierdzone kodem wyslanym na adres lub numer.
DOCUMENTZgodne z zweryfikowanym dokumentem tozsamosci.
AUTHORITYPotwierdzone przez rejestr. Zarezerwowane — jeszcze nie wydajemy.

Jesli Twoj proces wymaga potwierdzonych danych, sprawdzaj poziom, a nie samo istnienie pola. Bez tego przyjmiesz imie wpisane recznie tak samo jak odczytane z dowodu.

Wylogowanie

GET https://elogowanie.pl/oauth2/wyloguj
      ?id_token_hint=<id_token>
      &post_logout_redirect_uri=<adres z panelu>

Adres powrotu musi byc wczesniej zapisany w aplikacji, tak samo jak redirect_uri. Wylogowanie u nas nie konczy sesji w Twojej aplikacji — to Twoja strona musi wyczyscic wlasna sesje.

Pelna dokumentacja Warstwa OAuth 2.0