Token dan klaim

ID token

JWT bertanda tangan RS256. Kunci publik di <issuer>/keys; kunci dirotasi berkala, jadi ambil ulang JWKS bila kid belum dikenal. Wajib diperiksa:

• tanda tangan dengan JWKS issuer organisasi,
• iss sama persis dengan issuer,
• aud berisi client ID aplikasi,
• exp belum lewat (toleransi jam beberapa detik sampai 2 menit),
• nonce sama dengan yang dikirim saat login.

Klaim	Isi
sub	ID pengguna (diawali USR_). Tidak pernah berubah, walau email berganti: pakai sebagai kunci akun lokal
name	Nama lengkap (scope profile)
email, email_verified	Email utama dan status verifikasinya (scope email)
sid	Sesi X-Guard. Simpan di sesi aplikasi untuk back-channel logout
auth_time	Waktu pengguna terakhir benar-benar login (bukan waktu token diterbitkan)
amr	Cara login, mis. ["pwd"]
iss, aud, exp, iat, nonce, at_hash	Standar OpenID Connect

X-Guard tidak mengirim role atau jabatan. Hak akses di aplikasi tetap urusan aplikasi.

Menautkan akun

1. Cari pengguna lokal lewat sub yang tersimpan (mis. kolom xguard_sub).
2. Login pertama: cari lewat email hanya bila email_verified bernilai true, lalu simpan sub-nya.
3. Tetap tidak ketemu: buat akun dengan hak paling rendah, atau tolak, sesuai kebijakan aplikasi.

Access token

JWT RS256 berumur 5 menit. Kirim ke API Anda sebagai Authorization: Bearer <token>.

Klaim	Isi
sub	ID pengguna
client_id	Aplikasi yang meminta token
aud	Aplikasi peminta dan API tujuan yang diminta lewat audience
scp	Scope yang diberikan
org	Slug organisasi pengguna
iss, exp, iat, jti	Standar

API yang menerima access token memeriksa tanda tangan, iss, exp, dan client_id atau aud miliknya. API yang melayani banyak organisasi juga wajib memeriksa iss dan org.

Refresh token

Diterbitkan bila scope offline_access diminta. Berlaku 30 hari dan dirotasi setiap kali dipakai: simpan refresh token baru dari setiap jawaban. Memakai refresh token yang sudah diputar mencabut seluruh rangkaiannya (dianggap bocor).

Refresh ditolak bila akses pengguna ke aplikasi dicabut, akunnya dinonaktifkan atau dihapus, atau pengguna logout dari sesi X-Guard. Aplikasi lalu meminta pengguna login lagi.

Userinfo dan introspeksi

<issuer>/userinfo dengan access token mengembalikan klaim profil yang sama dengan ID token. <issuer>/oauth/introspect (dengan client secret) memeriksa apakah sebuah token masih aktif.