Pemecahan Masalah Autentikasi

Gunakan panduan ini untuk mendiagnosis kegagalan umum OIDC, PKCE, CORS, token, dan external API saat berintegrasi dengan Muhajir Studio.

Mulai dari Tahap yang Gagal

Tahap	Endpoint atau page	Masalah paling umum
Authorization start	https://api.muhajirstudio.com/api/auth/oauth2/authorize	Redirect URI mismatch, missing PKCE, client_id salah.
Login / verification / consent	https://login.muhajirstudio.com/	User belum sign in, email belum verified, consent metadata hilang.
Token exchange	https://api.muhajirstudio.com/api/auth/oauth2/token	code_verifier hilang/salah, code dipakai ulang, redirect URI salah.
Browser API call	https://api.muhajirstudio.com/api/external/me	Origin belum terdaftar atau bearer token hilang.
External API auth	/api/external/*	Token expired, missing openid, insufficient scopes.

Redirect URI Mismatch

Gejala:

{
  "error": "INVALID_REDIRECT_URI",
  "message": "redirect_uri is not registered for this client"
}

Penyebab:

Muhajir Studio memvalidasi authorize redirect_uri terhadap registered origin/path matrix milik aplikasi. Nilainya harus sama persis dengan derived URI.

Perbaikan:

1. Pastikan client_id milik aplikasi yang sedang Anda uji.
2. Di web-admin, pastikan allowed web origin, misalnya https://app.example.com.
3. Pastikan redirect path, misalnya /auth/callback.
4. Kirim full URI yang persis: https://app.example.com/auth/callback.
5. Jangan menambah query strings, fragments, wildcards, atau trailing slash kecuali path persis itu terdaftar.

PKCE Hilang atau Invalid

Gejala dapat berupa OAuth errors seperti:

{
  "error": "invalid_request",
  "error_description": "..."
}

atau token exchange gagal dengan invalid_grant.

Perbaikan:

• Authorization requests harus menyertakan code_challenge.
• code_challenge_method harus S256.
• Token request harus menyertakan code_verifier asli.
• Generate verifier/challenge baru untuk setiap login attempt.
• Jangan memakai authorization code lebih dari sekali.

Plain PKCE challenges dinonaktifkan.

Invalid Client atau Metadata Loading Errors

Public application metadata dimuat dari:

GET /api/public/applications/{clientId}

Response umum:

Status	Error	Arti	Perbaikan
400	INVALID_CLIENT_ID	Client ID path parameter invalid.	Periksa kesalahan copy/paste.
404	NOT_FOUND	Tidak ada dynamic atau static client untuk ID tersebut.	Pastikan aplikasi masih ada dan belum dihapus.
500	INTERNAL_ERROR	Lookup gagal secara tidak terduga.	Coba ulang dan hubungi support jika terus terjadi.

Consent page menonaktifkan approval ketika application metadata tidak dapat dimuat.

Browser CORS Mismatch

Gejala:

• Browser console menampilkan CORS failure.
• Request berhasil dari server tool tetapi gagal dari browser.
• Header Access-Control-Allow-Origin tidak muncul untuk SPA origin Anda.

Penyebab:

Third-party browser CORS dibatasi per route dan per origin. Berlaku untuk:

• POST /api/auth/oauth2/token
• OPTIONS /api/auth/oauth2/token
• /api/external/*

CORS ini hanya mengizinkan origins yang terdaftar di allowedWebOrigins, tidak mengizinkan credentials, dan mengizinkan header Authorization plus Content-Type.

Perbaikan:

1. Daftarkan browser origin yang persis, seperti https://spa.example.com.
2. Jangan menyertakan path di allowed web origin.
3. Tunggu sebentar setelah perubahan admin; registered CORS origins di-cache selama 60 detik.
4. Jangan mengirim credentials: 'include' dari third-party SPA.
5. Gunakan bearer tokens untuk /api/external/*.

Token Exchange Mengembalikan invalid_grant

Penyebab umum:

• Authorization code sudah pernah dipakai.
• Authorization code expired.
• code_verifier tidak cocok dengan code_challenge asli.
• redirect_uri di token request berbeda dari authorize request.
• Refresh token hilang, expired, revoked, atau tidak lagi valid.

Perbaikan:

• Mulai ulang login flow dengan PKCE pair baru.
• Pastikan callback Anda menyimpan dan memuat verifier untuk browser/session attempt yang sama.
• Kirim string redirect_uri yang sama di authorize dan token requests.
• Saat refresh gagal, hapus tokens yang tersimpan dan sign in ulang.

External API Mengembalikan 401 UNAUTHORIZED

Response:

{
  "error": "UNAUTHORIZED"
}

Arti:

External API tidak menerima OIDC bearer access token yang dapat digunakan. Cookie-only sessions tidak diterima oleh /api/external/*.

Perbaikan:

• Kirim Authorization: Bearer ACCESS_TOKEN.
• Pastikan token adalah OIDC access token, bukan ID token.
• Pastikan token belum expired.
• Hapus local tokens dan mulai login ulang jika token unknown atau expired.

External API Mengembalikan 403 FORBIDDEN

Response:

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

Arti:

Token valid tetapi tidak menyertakan required scope. GET /api/external/me membutuhkan openid; field seperti email, profile, dan permissions membutuhkan scope yang sesuai.

Perbaikan:

1. Periksa selected scopes aplikasi di web-admin.
2. Minta admin menambahkan required scopes jika diperlukan.
3. Mulai login baru setelah scope changes agar pengguna menerima token dengan scope set terbaru.

Pengguna Tertahan di Email Verification

Muhajir Studio mewajibkan signed-in users memverifikasi email sebelum OIDC authorization selesai. Login UI mempertahankan OIDC parameters melalui login, signup, /verify-email, dan email-verified screen.

Perbaikan:

• Pertahankan authorize query parameters asli saat deep-linking pengguna kembali ke login atau verification pages.
• Pastikan pengguna menyelesaikan email verification sebelum mengharapkan authorization callback.
• Jika flow dimulai ulang, generate PKCE verifier dan state baru.

Checklist Diagnostik Cepat

• Apakah client_id benar dan aktif?
• Apakah redirect_uri sama persis dengan registered derived URI?
• Apakah code_challenge_method=S256 tersedia?
• Apakah token request memakai form-encoded body?
• Apakah client_secret dihilangkan untuk Public PKCE clients?
• Apakah browser Origin terdaftar untuk SPA calls?
• Apakah Anda mengirim access token, bukan ID token, ke /api/external/*?
• Apakah token menyertakan openid untuk /api/external/me?