Quickstart Login Public PKCE

Quickstart ini menunjukkan jalur tercepat bagi aplikasi pihak ketiga untuk melakukan sign in pengguna dengan Muhajir Studio dan mengambil scope-filtered profile pengguna saat ini.

Prasyarat

Sebelum menulis kode, minta nilai berikut dari admin Muhajir Studio:

Nilai	Deskripsi
API base URL	https://api.muhajirstudio.com/ — menyediakan /api/auth/*, /api/public/*, dan /api/external/*.
Login web base URL	https://login.muhajirstudio.com/ — menyediakan login, signup, verification, dan consent pages.
Admin web base URL	https://admin.muhajirstudio.com/ — tempat admin mendaftarkan dan mengelola aplikasi.
client_id	Public client identifier yang dibuat di web-admin.
Registered redirect URI	URI persis yang diturunkan dari konfigurasi allowedWebOrigins dan redirectPaths aplikasi.
Allowed scopes	Scope yang dipilih untuk aplikasi ini di web-admin.

Gunakan URL produksi ini untuk integrasi live. Jika Anda berintegrasi dengan sandbox atau staging, gunakan URL layanan yang sesuai dari kontak Muhajir Studio Anda saat mendaftarkan web origins, redirect paths, dan callback URLs.

Aplikasi yang dibuat admin adalah Public PKCE clients. Jangan memakai client_secret; tidak ada client secret yang diterbitkan untuk client ini.

1. Buat Nilai PKCE dan State

Untuk setiap percobaan login, buat dan simpan nilai berikut di browser session pengguna atau backend session Anda:

Nilai	Tujuan
code_verifier	Nilai random rahasia yang digunakan nanti di token endpoint.
code_challenge	Base64url-encoded SHA-256 hash dari code_verifier.
state	Nilai proteksi CSRF yang harus kembali ke callback Anda.
nonce	Nilai proteksi replay untuk divalidasi saat memakai id_token.

Muhajir Studio mewajibkan code_challenge_method=S256; plain PKCE challenge dinonaktifkan.

2. Redirect ke Authorization

Arahkan browser pengguna ke Muhajir Studio authorization endpoint di https://api.muhajirstudio.com/api/auth/oauth2/authorize:

GET /api/auth/oauth2/authorize?client_id=CLIENT_ID&redirect_uri=https%3A%2F%2Fapp.example.com%2Fauth%2Fcallback&response_type=code&scope=openid%20profile%20email&state=STATE&nonce=NONCE&code_challenge=CODE_CHALLENGE&code_challenge_method=S256

Parameter wajib:

Parameter	Nilai
client_id	Public client ID dari web-admin.
redirect_uri	Registered redirect URI yang persis. Muhajir Studio tidak menyimpulkan nilai ini dari browser Origin.
response_type	Harus code.
scope	Scope dipisahkan spasi. Samakan dengan app scopes yang dikonfigurasi oleh admin.
state	Nilai proteksi CSRF Anda.
nonce	Direkomendasikan saat memvalidasi id_token.
code_challenge	PKCE S256 challenge.
code_challenge_method	Harus S256.

Muhajir Studio memvalidasi bahwa redirect_uri terdaftar untuk client. Untuk dynamic applications, Muhajir Studio juga membatasi effective authorization scopes ke scope yang dikonfigurasi pada aplikasi.

3. Pengguna Sign In, Verifikasi Email, dan Consent

Muhajir Studio menangani alur yang terlihat oleh pengguna di web-main:

1. Jika pengguna belum authenticated, pengguna dikirim ke halaman login atau signup.
2. Jika email pengguna yang sudah sign in belum terverifikasi, Muhajir Studio mengirim pengguna ke /verify-email sebelum authorization selesai.
3. Setelah verifikasi, Muhajir Studio melanjutkan authorization request asli dengan parameter OIDC yang dipertahankan.
4. Muhajir Studio menampilkan consent screen menggunakan registered application metadata dari GET /api/public/applications/{clientId} dan shared scope descriptions.
5. Pengguna approve atau deny access.

Demi keamanan, consent screen menonaktifkan approval jika registered application details tidak dapat dimuat.

4. Tangani Callback

Setelah approval, Muhajir Studio redirect browser kembali ke redirect_uri terdaftar Anda dengan query parameters:

https://app.example.com/auth/callback?code=AUTHORIZATION_CODE&state=STATE

Callback handler Anda harus:

1. Memastikan state yang kembali sama dengan nilai yang disimpan.
2. Membaca authorization code.
3. Memuat code_verifier yang disimpan untuk percobaan login ini.
4. Melanjutkan ke token exchange.

Jika pengguna menolak akses atau request gagal, Muhajir Studio dapat redirect kembali dengan OAuth error parameters sebagai pengganti code.

5. Tukar Code dengan Tokens

Kirim form-encoded POST request ke token endpoint:

POST /api/auth/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=AUTHORIZATION_CODE&code_verifier=CODE_VERIFIER&client_id=CLIENT_ID&redirect_uri=https%3A%2F%2Fapp.example.com%2Fauth%2Fcallback

Untuk Public PKCE clients, jangan kirim client_secret.

Response berhasil dapat berisi:

{
  "access_token": "...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "id_token": "...",
  "refresh_token": "...",
  "scope": "openid profile email"
}

refresh_token hanya hadir saat refresh-token behavior tersedia untuk granted scopes/client. Scope offline_access adalah scope yang ditujukan untuk long-lived refresh-token based sessions jika didukung.

6. Ambil Pengguna Saat Ini

Gunakan OIDC access token ke stable external API:

GET /api/external/me
Authorization: Bearer ACCESS_TOKEN

Token harus memiliki openid; jika tidak, Muhajir Studio mengembalikan 403 dengan missingScopes: ["openid"].

Contoh response dengan openid profile email:

{
  "sub": "user-id",
  "name": "Jane Doe",
  "picture": null,
  "email": "jane@example.com",
  "emailVerified": true
}

Jika token juga memiliki permissions, response dapat menyertakan permissions dengan effective Muhajir Studio permission keys milik pengguna.

Bentuk Integrasi Umum

Server-Rendered atau Backend Web App

Gunakan backend Anda untuk membuat authorization URL, menyimpan state, nonce, dan code_verifier, menangani callback, menukar code, memvalidasi id_token, dan menyimpan token di server. Bentuk ini disarankan saat aplikasi Anda sudah memiliki backend session.

React SPA

Browser SPA dapat memakai PKCE secara langsung, tetapi browser origin harus terdaftar sebagai allowedWebOrigin untuk aplikasi. Dukungan third-party CORS Muhajir Studio dibatasi per route untuk /api/auth/oauth2/token dan /api/external/*, serta tidak memakai credentialed CORS.

Mobile App

Mobile apps sebaiknya memakai Authorization Code with PKCE dan registered redirect URI yang sesuai untuk platform, seperti app link atau universal link. Simpan token di platform secure storage.

Kesalahan Quickstart yang Umum

• Mengirim client_secret untuk Public PKCE client yang dibuat admin.
• Memakai code_challenge_method=plain, bukan S256.
• Mengirim redirect_uri yang tidak sama persis dengan salah satu derived registered redirect URIs.
• Memanggil /api/external/me tanpa Authorization: Bearer access token.
• Mengharapkan /api/external/me mengembalikan field untuk scope yang tidak diberikan.