Szybki start

Załóż aplikację, podłącz SDK przeglądarkowe i zaloguj się po raz pierwszy — w całości w sandboksie.

Na końcu tej strony przeglądarka zaloguje się do Twojej własnej aplikacji i przekaże Twojemu kodowi token dostępu. Wszystko dzieje się w sandboksie, gdzie użytkowników możesz kasować bez żalu.

1. Załóż aplikację

Zaloguj się do konsoli. Konto bez żadnej aplikacji wita kreator w trzech krokach, którego drugi krok to formularz tworzenia; jeśli masz już jakąś aplikację, kolejną zakładasz przyciskiem Utwórz aplikację na liście Aplikacje.

Z nazwy powstaje slug, a ze sluga dwa stałe adresy:

Środowisko	Adres
Produkcja	`https://acme.kleora.eu`
Sandbox	`https://acme.sandbox.kleora.eu`

To są adresy wydawcy (issuer) tej aplikacji. Sluga nie da się później zmienić: to on stoi w polu iss każdego wydanego tokenu i to jego zapamiętała każda usługa, która kiedykolwiek sprawdziła Twój token. Wybierz go tak uważnie jak domenę.

Po zakończeniu kreatora trafiasz na przegląd środowiska sandbox — a tam są trzy wartości potrzebne na dalszej części tej strony: issuer, identyfikator domyślnego klienta i adres dokumentu discovery.

2. Zarejestruj adresy powrotne

Wejdź w Integracja → Klienci i otwórz klienta o nazwie Default. Jest to klient typu spa, tworzony razem z aplikacją, i nie ma ani jednego adresu powrotnego. Dopóki go nie dodasz, endpoint autoryzacyjny nie ma dokąd odesłać przeglądarki.

Dodaj dwa, których użyje Twój serwer deweloperski:

Pole	Wartość
Redirect URI	`http://localhost:5173/callback`
Post-logout redirect URI	`http://localhost:5173/`

Oba są porównywane dokładnie. Ukośnik na końcu, inny port albo dodatkowy parametr w query to z punktu widzenia endpointu autoryzacyjnego zupełnie inny adres.

3. Zainstaluj SDK przeglądarkowe

npm install @kleora-io/browser

Paczka nie ma zależności w czasie działania i jest publikowana wyłącznie jako moduły ES. Pozostałe cztery opisuje Instalacja SDK.

4. Zaloguj się

Do klienta trafiają trzy wartości: issuer i identyfikator klienta ze strony przeglądu oraz redirect URI zarejestrowany przed chwilą.

import { createKleora } from '@kleora-io/browser'

const kleora = createKleora({
  issuer: 'https://acme.sandbox.kleora.eu',
  clientId: '<client_id>',
  redirectUri: location.origin + '/callback',
})

if (location.pathname === '/callback') {
  await kleora.handleRedirectCallback()
} else if (!(await kleora.checkSession())) {
  await kleora.loginWithRedirect()
}

const user = kleora.getUser()
const token = await kleora.getAccessToken()

Uruchom. Przeglądarka wychodzi na hostowaną stronę logowania Twojej aplikacji, gdzie możesz od razu założyć pierwszego użytkownika — samodzielna rejestracja jest w nowym środowisku włączona — i wraca na /callback z kodem autoryzacyjnym. handleRedirectCallback() wymienia go na tokeny, sprawdza ID token, zapisuje wynik i usuwa kod z paska adresu.

Wylogowanie to jedno wywołanie, a returnTo musi być jednym z zarejestrowanych adresów po wylogowaniu:

await kleora.logout({ returnTo: location.origin + '/' })

5. Sprawdź token w swoim API

Token dostępu to podpisany JWT. Twoje API sprawdza go względem zestawu kluczy publikowanego przez Twój issuer — bez odpytywania nas i bez współdzielonego sekretu.

import { authenticate } from '@kleora-io/node'

const claims = await authenticate(request, {
  issuer: 'https://acme.sandbox.kleora.eu',
  audience: '<client_id>',
})

console.log(claims.sub, claims.tenant, claims.permissions)

from kleora import verify_access_token

claims = verify_access_token(
    token,
    issuer="https://acme.sandbox.kleora.eu",
    audience="<client_id>",
)

print(claims.sub, claims.tenant, claims.permissions)

authenticate przyjmuje cokolwiek, co ma własność headers.authorization, więc zadziała z dowolnym frameworkiem w Node; @kleora-io/node dostarcza też middleware dla Express i Fastify. claims.roles i claims.permissions są już w tokenie, więc autoryzacja żądania kosztuje tyle, co sprawdzenie elementu na liście.

Co SDK robi za Ciebie

Wywołanie	Czym się zajmuje
`loginWithRedirect()`	Generuje `state`, `nonce` i weryfikator PKCE, po czym przechodzi na endpoint autoryzacyjny.
`handleRedirectCallback()`	Sprawdza `state` i `iss`, wymienia kod, weryfikuje ID token, zapisuje tokeny, czyści adres.
`getAccessToken()`	Oddaje token z pamięci, dopóki do jego wygaśnięcia zostało więcej niż 30 sekund; potem odświeża. Tokeny odświeżania rotują przy każdym użyciu.
`checkSession()`	Odtwarza sesję przy wczytaniu strony, po cichu, bez pokazywania logowania od nowa.
`logout({ returnTo })`	Czyści stan lokalny i kończy sesję u wydawcy.
`onAuthChange(cb)`	Odpala się przy zalogowaniu, wylogowaniu i odświeżeniu tokenu. Zwraca funkcję odsubskrybowania.

Gdzie leżą tokeny

Domyślnie oba tokeny są trzymane w pamięci, w domknięciu. Nic nie przeżywa przeładowania strony — i właśnie dlatego przy wczytaniu wywołuje się checkSession(). Opcja storage: 'session' dodatkowo odkłada token odświeżania w sessionStorage, który należy do jednej karty i znika razem z nią.

localStorage nie jest opcją i nie będzie. Trwa w nieskończoność, dzielą go wszystkie karty tego samego origin i czyta go każdy skrypt, jaki się tam kiedykolwiek wykona — w tym ten, który jutro przyjedzie w zależności wdrożonej dziś.

Dalej

Instalacja SDK — Nuxt, Node, Python i Django.
TOTP, zaproszenia do przestrzeni roboczych czy oznaczenie strony logowania własną marką włączysz z konsoli; żadna z tych rzeczy nie zmienia kodu powyżej.