Praktik Keamanan Terbaik

Gunakan praktik berikut saat mengintegrasikan aplikasi pihak ketiga dengan Muhajir Studio di production.

Batas Layanan Produksi

Service	URL Produksi	Peran keamanan
API	https://api.muhajirstudio.com/	OIDC endpoints, token exchange, JWKS, public metadata, dan external APIs.
Main web	https://login.muhajirstudio.com/	Hosted user login, signup, email verification, dan consent.
Admin web	https://admin.muhajirstudio.com/	Application registration, scope selection, dan RBAC-protected administration.

Jaga agar layanan ini tetap terpisah dalam konfigurasi client. External integrations hanya sebaiknya memanggil endpoint OIDC, public metadata, dan /api/external/* yang terdokumentasi.

Gunakan Authorization Code Flow with PKCE

Applications yang dibuat admin adalah Public PKCE clients:

• client_id bersifat public.
• client_secret tidak diterbitkan.
• code_challenge_method harus S256.
• Plain PKCE challenges dinonaktifkan.
• Setiap login attempt harus menghasilkan state, nonce, dan code_verifier baru.

Validasi state sebelum menukar authorization code. Perlakukan state yang invalid sebagai login attempt yang gagal dan mulai ulang flow.

Daftarkan Redirects dan Origins secara Tepat

Muhajir Studio menurunkan redirect URIs dari dua nilai terdaftar:

Nilai terdaftar	Contoh	Aturan
Allowed web origin	https://app.example.com	Origin saja; tanpa path, query, fragment, atau wildcard.
Redirect path	/auth/callback	Path saja; tanpa host, query, atau fragment.

Redirect URI hasilnya harus sama persis, misalnya https://app.example.com/auth/callback.

Rekomendasi keamanan:

• Gunakan HTTPS origins di production.
• Daftarkan hanya origins yang Anda kontrol.
• Pakai callback paths khusus untuk OAuth/OIDC handling.
• Jangan menerima callback URLs dari request parameters yang tidak tepercaya.
• Untuk mobile apps, gunakan HTTPS Universal Links atau Android App Links, bukan custom URL schemes.

Request Least-Privilege Scopes

Application scopes yang dipilih admin adalah source of truth. Selama authorization, Muhajir Studio membatasi effective requested scope set ke scopes yang terdaftar pada aplikasi.

Gunakan hanya scopes yang benar-benar dibutuhkan integrasi Anda:

Scope	Memberi akses ke
openid	Stable subject identifier; wajib untuk /api/external/me.
profile	Basic profile fields seperti name dan picture.
email	Email address dan verification status.
permissions	Assigned permission keys jika didukung.
offline_access	Refresh-token based sessions jika didukung.

Setelah scope berubah, pengguna harus memulai authorization flow baru untuk menerima tokens dengan grants terbaru.

Validasi Tokens dengan Benar

Gunakan token sesuai tujuannya:

Token	Penggunaan yang tepat
Access token	Kirim ke /api/external/* dengan Authorization: Bearer ACCESS_TOKEN.
ID token	Validasi authentication claims pengguna di client atau backend Anda. Jangan kirim ke external APIs.
Refresh token	Simpan dengan aman dan gunakan hanya untuk memperbarui session.

Saat memvalidasi ID tokens, periksa setidaknya:

• issuer sama dengan production issuer
• audience sama dengan client_id Anda
• expiration belum lewat
• nonce sama dengan nilai yang dibuat untuk login attempt saat Anda memintanya

Ambil signing keys dari JWKS endpoint yang diumumkan oleh OIDC discovery, bukan hardcoding keys.

Simpan Tokens Berdasarkan Tipe Aplikasi

Tipe aplikasi	Storage yang direkomendasikan
Backend web app	Simpan tokens di sisi server; berikan browser hanya application session cookie Anda.
Browser SPA	Utamakan in-memory access-token storage; persistent browser storage adalah trade-off XSS eksplisit.
Mobile app	Simpan tokens di platform secure storage seperti Keychain atau encrypted credential storage.

Jangan pernah logging tokens, authorization codes, refresh tokens, atau ID tokens. Redact dari analytics, crash reports, support tickets, dan browser console output.

Gunakan External APIs dengan Bearer Tokens

Third-party integrations sebaiknya memakai /api/external/* sebagai stable external API namespace.

GET /api/external/me
Authorization: Bearer ACCESS_TOKEN

Cookie-only sessions tidak diterima oleh /api/external/*. Bearer access token yang hilang, expired, atau invalid mengembalikan 401 UNAUTHORIZED. Token valid tanpa required scopes mengembalikan 403 FORBIDDEN dengan missingScopes jika tersedia.

Pahami Browser CORS Rules

Browser-based third-party calls hanya diizinkan dari registered application origins.

Dynamic third-party CORS berlaku untuk:

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

CORS ini sengaja non-credentialed:

Setting	Nilai
Credentials	false
Methods	GET, POST, OPTIONS
Allowed headers	Authorization, Content-Type
Registered-origin cache	60 detik

Jangan memakai credentials: 'include' dari third-party browser clients saat memanggil token atau external API endpoints. Kirim bearer tokens secara eksplisit.

Lindungi Admin Access dengan Permissions

Admin surfaces dilindungi permissions. Admin API membutuhkan login-web-admin untuk admin-only namespaces dan feature-specific permissions seperti:

• manage-users
• manage-roles
• manage-services
• manage-authentication
• manage-branding
• manage-applications

Jangan mengandalkan UI hiding sebagai security boundary. Backend permission checks adalah source of truth.

Saat mengedit role yang ditetapkan ke akun Anda sendiri, Admin API menolak perubahan permission yang akan menghapus akses login-web-admin atau manage-roles milik Anda sendiri. Gunakan akun administrator lain untuk transfer admin access yang disengaja atau emergency recovery.

Pisahkan First-Party dan Third-Party Flows

First-party web applications dapat memakai cookie-backed helper endpoints jika terdokumentasi secara eksplisit, seperti cookie token wrapper yang digunakan oleh web-admin. Third-party integrations sebaiknya memakai standard OIDC token endpoint dan bearer-token external APIs kecuali diinstruksikan sebaliknya.

Pemisahan ini mencegah browser integrations bergantung pada internal cookie-session assumptions.

Checklist Keamanan

• Gunakan HTTPS untuk semua production redirect origins.
• Gunakan Authorization Code Flow with PKCE dan S256.
• Generate state, nonce, dan PKCE values baru untuk setiap login.
• Validasi state dan, saat memakai ID tokens, validasi nonce.
• Daftarkan hanya exact origins dan redirect paths.
• Request least-privilege scopes.
• Simpan tokens sesuai tipe aplikasi.
• Kirim access tokens hanya di header Authorization: Bearer.
• Jangan logging credentials, tokens, authorization codes, atau refresh tokens.
• Gunakan backend permissions, bukan frontend visibility, untuk admin enforcement.