Token dan Klaim

Halaman ini menjelaskan token response fields, ekspektasi ID token validation, scopes, dan claims yang diekspos oleh OIDC endpoints Muhajir Studio.

Token Response

POST /api/auth/oauth2/token mengembalikan OidcTokenResponse saat berhasil:

Field	Type	Catatan
access_token	string	Bearer token untuk UserInfo dan external APIs.
token_type	Bearer	Token type selalu Bearer.
expires_in	number	Positive integer lifetime dalam detik.
id_token	string	Opsional di schema; hadir saat OIDC provider menerbitkannya untuk flow tersebut.
refresh_token	string	Opsional; hadir saat refresh-token behavior tersedia untuk grant/client.
scope	string	Optional space-separated granted scope string.

Gunakan Authorization: Bearer ACCESS_TOKEN untuk bearer-protected endpoints.

Access Tokens

Access tokens disimpan oleh OIDC provider dan di-resolve server-side untuk first-party external APIs. /api/external/me hanya menerima OIDC bearer access tokens; cookie-only sessions tidak diterima di sana.

Access token ditolak saat:

• header Authorization tidak ada
• scheme bukan Bearer
• token tidak dikenal
• token sudah expired
• token tidak memiliki associated user

Dalam kasus tersebut, bearer-protected APIs mengembalikan 401.

ID Tokens

ID token claims schema mengizinkan standard OIDC fields dan beberapa optional claims:

Claim	Catatan
iss	Issuer. Harus sama dengan configured OIDC_ISSUER.
sub	Stable subject identifier.
aud	Audience. Harus mencakup client_id Anda.
exp	Expiration time. Harus di masa depan.
iat	Issued-at time.
nonce	Hadir ketika nonce dikirim dan harus sama dengan stored nonce Anda.
email	Tersedia saat email-related claims diberikan.
email_verified	Tersedia saat email-related claims diberikan.
name	Tersedia saat profile-related claims diberikan.
picture	Tersedia saat profile-related claims diberikan.
given_name	Tersedia saat profile-related claims diberikan.
family_name	Tersedia saat profile-related claims diberikan.
permissions	Tersedia saat scope permissions diberikan dan claims disertakan.

Saat memakai ID token untuk local sign-in, validasi:

• signature dengan keys dari /api/auth/jwks
• iss
• aud
• exp
• iat sesuai client policy Anda
• nonce saat Anda mengirimnya di authorize request

Scopes

Supported scopes berasal dari OIDC_SCOPE_METADATA dan diekspos oleh GET /api/public/oidc/scopes.

Scope	Tujuan developer	Claims
openid	Required OIDC scope untuk stable subject identity.	sub
profile	Mengizinkan profile claims seperti name dan picture jika tersedia.	name, picture, given_name, family_name
email	Mengizinkan email dan email verification claims jika tersedia.	email, email_verified
offline_access	Mengizinkan refresh-token based sessions jika didukung.	none
permissions	Mengizinkan permissions claim dan permission-based fields di supported APIs.	permissions

Untuk dynamic applications, admin-selected scopes adalah source of truth. Saat authorization, server menulis ulang request scope menjadi configured scope set milik aplikasi.

Permissions Claim

OIDC provider menambahkan custom UserInfo claims melalui buildAdditionalUserInfoClaims. Saat ini, fungsi ini hanya menambahkan permissions dan hanya ketika granted scopes mencakup permissions.

Saat disertakan, permissions adalah effective permission key list pengguna dari roles/permissions system.

Contoh:

{
  "sub": "user-id",
  "permissions": ["manage-applications", "login-web-admin"]
}

Jangan pernah mengecek user roles secara langsung di clients. Permission keys adalah authorization signal yang didukung.

External Current User Claims

GET /api/external/me mengembalikan stable external API shape yang lebih kecil dan difilter berdasarkan granted scopes:

Scope	Response fields
openid	sub
profile	name, picture
email	email, emailVerified
permissions	permissions

Endpoint ini membutuhkan openid. Jika bearer token valid tetapi tidak memiliki openid, response adalah:

{
  "error": "FORBIDDEN",
  "missingScopes": ["openid"]
}

Refresh Tokens

Refresh tokens dapat hadir di standard token responses saat refresh behavior tersedia untuk grant/client. Scope offline_access ditujukan untuk refresh-token based sessions jika didukung.

First-party cookie-token helpers memindahkan refresh tokens dari JSON response ke HTTP-only cookie. Third-party integrations biasanya sebaiknya memakai standard /api/auth/oauth2/token endpoint dan menangani refresh tokens sesuai platform security model mereka.

OAuth Error Shape

OIDC dan token errors mengikuti OAuth error schema:

{
  "error": "invalid_request",
  "error_description": "...",
  "error_uri": "https://example.com/docs/error"
}

error_description dan error_uri bersifat opsional.