Mendaftarkan Aplikasi Pihak Ketiga

Admin memakai halaman Applications di web-admin pada https://admin.muhajirstudio.com/ untuk mendaftarkan OIDC client applications yang mengautentikasi pengguna melalui Muhajir Studio. Setiap aplikasi yang dibuat admin adalah Public PKCE client: aplikasi menerima public client_id, tidak menerima client_secret, dan harus memakai Authorization Code Flow with PKCE.

Persyaratan Akses

Application management dilindungi di UI dan API:

• Admin shell membutuhkan permission login-web-admin.
• Halaman Applications membutuhkan permission manage-applications.
• Admin API routes di bawah /api/applications juga membutuhkan manage-applications.

Alur Registrasi

1. Buka web-admin di https://admin.muhajirstudio.com/.
2. Masuk ke Applications.
3. Pilih New application.
4. Isi application details, redirect configuration, dan scopes.
5. Buat aplikasi.
6. Salin client_id yang dibuat untuk developer aplikasi.

Application card yang dibuat menampilkan public credentials, allowed web origins, redirect paths, derived redirect URIs, selected scopes, dan logo controls.

Field Aplikasi

Client Name

clientName wajib diisi dan ditampilkan kepada admin serta pengguna. Nilai ini juga disinkronkan ke underlying OAuth application name.

Validasi:

• Wajib.
• Di-trim.
• Panjang maksimum: 120 karakter.

Description

clientDescription bersifat opsional. Jika diisi, nilai ini tersedia pada public application metadata dan dapat ditampilkan di authorization atau consent UI yang terlihat oleh pengguna.

Validasi:

• Opsional.
• Nilai kosong disimpan sebagai null.
• Di-trim.
• Panjang maksimum: 2000 karakter.

Allowed Web Origins

allowedWebOrigins mendefinisikan browser origins milik aplikasi. Origins ini juga digunakan oleh browser-safe third-party CORS untuk /api/auth/oauth2/token dan /api/external/*.

Setiap origin harus berupa exact HTTP(S) origin, tanpa path, query, fragment, credentials, atau wildcard.

Contoh valid:

https://app.example.com
https://staging.example.com
http://localhost:3000

Contoh tidak valid:

https://app.example.com/auth/callback
https://*.example.com
https://user:pass@app.example.com
https://app.example.com?debug=true

Validasi:

• Wajib.
• Minimum entries: 1.
• Maksimum entries: 20.
• Setiap entry dinormalisasi ke origin-nya.
• Setiap entry memiliki panjang maksimum 255 sebelum normalisasi.

Redirect Paths

redirectPaths mendefinisikan callback paths untuk aplikasi. Muhajir Studio menggabungkan setiap allowed web origin dengan setiap redirect path untuk menurunkan OAuth redirectUris yang tepat dan disimpan untuk client.

Contoh valid:

/auth/callback
/oauth/callback
/login/provider/callback

Contoh tidak valid:

auth/callback
//app.example.com/callback
/auth/callback?code=example
/auth/callback#fragment
https://app.example.com/auth/callback

Validasi:

• Wajib.
• Minimum entries: 1.
• Maksimum entries: 20.
• Harus dimulai dengan /.
• Tidak boleh dimulai dengan //.
• Tidak boleh menyertakan host, query, fragment, atau backslash.
• Setiap entry memiliki panjang maksimum 1024.

Derived Redirect URIs

Admin tidak memasukkan full OAuth redirect URIs secara langsung. Muhajir Studio menurunkannya dari allowedWebOrigins dan redirectPaths.

Contoh:

Allowed web origin	Redirect path	Derived redirect URI
https://app.example.com	/auth/callback	https://app.example.com/auth/callback
https://staging.example.com	/auth/callback	https://staging.example.com/auth/callback

OAuth authorize request tetap harus mengirim satu full redirect_uri terdaftar yang persis. Server memvalidasi redirect_uri terhadap derived list dan mengembalikan INVALID_REDIRECT_URI jika tidak terdaftar untuk client tersebut.

Post-Verification Redirect Path

postVerificationRedirectPath bersifat opsional. Nilai ini mengontrol ke mana pengguna melanjutkan setelah email verification ketika OIDC flow tertahan untuk verifikasi.

Nilai ini hanya path. Jika memungkinkan, Muhajir Studio menggabungkannya dengan origin dari OAuth redirect_uri yang sudah divalidasi. Jika tidak ada konteks caller redirect_uri dan aplikasi hanya memiliki satu allowed web origin, Muhajir Studio dapat menurunkan post-verification URI dari origin tunggal tersebut.

Validasi:

• Opsional.
• Nilai kosong disimpan sebagai null.
• Menggunakan aturan validasi path yang sama dengan redirectPaths.

Scopes

Setiap aplikasi harus memiliki setidaknya satu selected scope. Scope yang tersedia berasal dari tabel app_scope dan ditampilkan dengan metadata dari OIDC_SCOPE_METADATA.

Scope yang didukung saat ini:

Scope	Tujuan
openid	Required OIDC identity scope. Mengaktifkan stable subject identity.
profile	Mengizinkan profile claims seperti name dan picture jika tersedia.
email	Mengizinkan email dan email verification status.
offline_access	Mengizinkan refresh-token based sessions jika didukung.
permissions	Mengizinkan permission claims dan permission-based API fields.

Validasi:

• Minimum selected scopes: 1.
• Maksimum selected scopes: 50.
• Scope ID yang tidak dikenal ditolak dengan UNKNOWN_SCOPE_IDS.

Saat authorization, dynamic applications memakai scopes yang dikonfigurasi pada aplikasi. Authorize middleware menulis ulang request scope menjadi configured scope set milik aplikasi terdaftar sebelum OIDC provider menangani request.

Generated Credentials

Setelah pembuatan, application card menampilkan:

Field	Nilai
client_id	Generated public client identifier.
client_type	Public PKCE.

Tidak ada client_secret yang dibuat atau ditampilkan. Developer harus memakai Authorization Code Flow with PKCE dan code_challenge_method=S256.

Logo Upload

Admin dapat mengunggah application logo dari application card. Logo disimpan sebagai public object dan URL yang dihasilkan disinkronkan ke OAuth application icon.

Jika upload gagal, admin UI tetap menampilkan application card dan menampilkan error toast dengan alasan kegagalan.

Batasan upload:

• Form field name: file.
• Ukuran maksimum: 2 MiB.
• MIME types yang diizinkan: image/png, image/jpeg, image/jpg, image/svg+xml, image/webp.
• File yang tidak ada mengembalikan FILE_REQUIRED.
• File terlalu besar mengembalikan FILE_TOO_LARGE.
• File type yang tidak didukung mengembalikan INVALID_FILE_TYPE.

Ringkasan Admin API

UI memakai admin endpoints berikut:

Method	Endpoint	Tujuan
GET	/api/applications/scopes	List available app scopes.
GET	/api/applications	List registered applications.
GET	/api/applications/{id}	Get one application.
POST	/api/applications	Create an application.
PATCH	/api/applications/{id}	Update an application.
DELETE	/api/applications/{id}	Delete an application when allowed.
POST	/api/applications/{id}/logo	Upload or replace the application logo.

Endpoint ini memvalidasi request dan response payloads dengan schemas dari @drova/schemas.