Integrasi Mobile PKCE

Recipe ini menjelaskan cara native mobile app memakai Muhajir Studio dengan Authorization Code Flow with PKCE.

Model Redirect yang Didukung

Application registration di Muhajir Studio berbasis HTTP(S) web origins plus redirect paths. Untuk production mobile apps, gunakan verified HTTPS redirect URI yang ditangani oleh Universal Links atau Android App Links.

Service	URL Produksi	Digunakan untuk
API	https://api.muhajirstudio.com/	Authorization, token exchange, refresh, dan external APIs.
Main web	https://login.muhajirstudio.com/	Hosted login, signup, verification, dan consent.
Admin web	https://admin.muhajirstudio.com/	Application registration.

Custom URL schemes seperti myapp://callback bukan allowedWebOrigins yang valid dalam model registrasi saat ini. Gunakan HTTPS app link seperti https://app.example.com/mobile/callback.

Setup Admin

Daftarkan mobile application dengan:

Field	Contoh	Catatan
Allowed web origin	https://app.example.com	HTTPS origin yang dikontrol app/team Anda.
Redirect path	/mobile/callback	Path yang dibuka oleh Universal Link atau App Link handler Anda.
Redirect URI	https://app.example.com/mobile/callback	Diturunkan dari origin + path.
Scopes	openid profile email offline_access	Sertakan offline_access hanya ketika long-lived sessions diperlukan dan didukung.

1. Buka System Browser

Gunakan system browser atau secure browser tab milik platform, bukan embedded web view. Generate code_verifier, code_challenge, state, dan nonce di device sebelum membuka authorization.

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

Simpan code_verifier, state, dan nonce di short-lived app storage hingga callback diterima.

2. Terima App Link Callback

Ketika pengguna menyelesaikan login, verification, dan consent, sistem membuka app link callback Anda dengan:

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

atau OAuth error parameters seperti:

https://app.example.com/mobile/callback?error=access_denied&state=STATE

Aplikasi Anda harus:

1. Memverifikasi state yang kembali.
2. Membaca code jika tersedia.
3. Memuat code_verifier yang sesuai.
4. Menukar code di token endpoint.

3. Tukar Code

Kirim form-encoded request dari aplikasi ke API 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%2Fmobile%2Fcallback

Mobile applications yang dibuat admin adalah Public PKCE clients. Jangan kirim client_secret.

4. Simpan Tokens secara Aman

Simpan tokens di secure storage milik platform, seperti Keychain di iOS atau encrypted credential storage di Android. Hindari logging tokens atau memasukkannya ke crash reports.

Jika refresh token diterbitkan, simpan dengan perlindungan yang sama seperti access token. Ketika refresh gagal dengan invalid_grant, hapus local tokens dan mulai login lagi.

5. Panggil External APIs

Gunakan bearer authentication untuk external APIs:

GET /api/external/me
Authorization: Bearer ACCESS_TOKEN

401 berarti access token tidak dapat digunakan. 403 berarti token valid tetapi tidak memiliki required scope, seperti openid untuk /api/external/me.

Checklist Produksi

• Gunakan HTTPS Universal Links atau Android App Links untuk redirect handling.
• Daftarkan HTTPS origin dan redirect path yang tepat.
• Gunakan system browser atau secure browser tab.
• Generate PKCE values per login attempt.
• Validasi state sebelum token exchange.
• Simpan tokens hanya di secure platform storage.
• Hapus tokens dan mulai login ulang pada invalid_grant atau response 401 berulang.