Single Sign-On untuk Instalasi On-Premise

Halaman ini untuk operator instalasi MonoChat on-premise. Halaman ini menjelaskan cara mengizinkan staf Anda masuk dengan penyedia identitas (IdP) perusahaan melalui OpenID Connect (OIDC), misalnya Microsoft Entra ID, Okta, Keycloak, AD FS, atau Google Workspace.

Single sign-on diatur untuk seluruh instalasi di pengaturan server, bukan per organisasi. Satu akun MonoChat dapat menjadi milik beberapa organisasi, dan orang masuk sebelum memilih salah satunya. Masuk memberi akun, bukan akses: seseorang baru melihat sebuah organisasi setelah organisasi itu mengundangnya dan memberinya peran.

Cara kerja masuk

Saat seseorang mengklik tombol SSO di halaman masuk, MonoChat membuka halaman masuk IdP Anda di pop-up. Setelah orang itu masuk di sana, IdP mengirim browser kembali ke MonoChat dengan kode sekali pakai. Server MonoChat menukar kode itu dengan token ID dan memeriksanya sebelum memasukkan orang tersebut:

• Endpoint dan kunci tanda tangan IdP dibaca dari dokumen discovery-nya, <issuer>/.well-known/openid-configuration, pada setiap proses masuk.
• Proses masuk memakai alur authorization code dengan PKCE (S256), sebuah state, dan sebuah nonce. Permintaan masuk berlaku 10 menit dan hanya dapat dipakai sekali.
• Token ID harus ditandatangani dengan salah satu kunci IdP dan memuat issuer Anda (iss), client ID Anda (aud), nonce permintaan, serta waktu kedaluwarsa (exp) yang belum lewat.
• Token ID harus berisi alamat email orang tersebut (email). Proses masuk ditolak jika IdP menyatakan alamat itu belum diverifikasi (email_verified: false).

1. Daftarkan MonoChat di penyedia identitas Anda

Buat aplikasi (klien) untuk MonoChat di IdP Anda dengan nilai berikut:

Pengaturan di IdP	Nilai
Jenis aplikasi	Aplikasi web dengan client secret (klien rahasia)
URI pengalihan masuk	https://<your MonoChat domain>/api/oauth/oidc/redirect
Jenis grant	Authorization code
Scope	openid email profile
Autentikasi klien di endpoint token	Client secret yang dikirim dengan autentikasi HTTP Basic (client_secret_basic)

Pastikan token ID berisi claim email. Catat client ID, client secret, dan issuer. Issuer adalah nilai issuer di dokumen discovery IdP. Bentuk umum:

Penyedia identitas	Issuer
Microsoft Entra ID	https://login.microsoftonline.com/<tenant id>/v2.0
Okta	https://<your Okta domain>/oauth2/default, atau https://<your Okta domain>
Keycloak	https://<your Keycloak host>/realms/<realm>
AD FS (2016 atau lebih baru)	https://<your AD FS host>/adfs
Google Workspace	https://accounts.google.com

Buka <issuer>/.well-known/openid-configuration di browser dan salin nilai issuer-nya persis, termasuk / di akhir jika ada. MonoChat menolak memasukkan siapa pun jika keduanya berbeda.

2. Tambahkan pengaturan

Tambahkan blok oidc ke pengaturan server dan mulai ulang MonoChat. Blok publik berada di bawah public.oauth, blok rahasia di bawah oauth:

{
  "oauth": {
    "oidc": {
      "clientSecret": "<client secret>",
      "autoCreateAccounts": true,
      "allowedEmailDomains": ["company.com"]
    }
  },
  "public": {
    "oauth": {
      "oidc": {
        "issuer": "https://login.microsoftonline.com/<tenant id>/v2.0",
        "clientId": "<client id>",
        "redirectPath": "/api/oauth/oidc/redirect",
        "scope": "openid email profile",
        "buttonLabel": "Sign in with Company SSO"
      }
    }
  }
}

Pengaturan	Fungsinya
public.oauth.oidc.issuer	Issuer dari langkah 1
public.oauth.oidc.clientId	Client ID dari langkah 1
public.oauth.oidc.redirectPath	Path URI pengalihan dari langkah 1
public.oauth.oidc.scope	Scope yang diminta MonoChat
public.oauth.oidc.buttonLabel	Teks tombol masuk. Jika kosong, menampilkan "Masuk dengan SSO" dalam bahasa orang tersebut
oauth.oidc.clientSecret	Client secret. Tetap berada di server
oauth.oidc.autoCreateAccounts	true membuat akun MonoChat saat seseorang pertama kali masuk dengan SSO, bahkan jika pendaftaran hanya lewat undangan (public.disableSignup)
oauth.oidc.allowedEmailDomains	Hanya orang dengan alamat email di salah satu domain ini yang dapat masuk dengan SSO. Hilangkan untuk mengizinkan semua domain

Tombol SSO kemudian muncul di halaman masuk.

Siapa yang dapat masuk

• Orang baru. Dengan autoCreateAccounts: true, proses masuk SSO pertama seseorang membuat akunnya. Tanpanya, akun hanya dibuat jika public.disableSignup nonaktif atau orang itu masuk dari undangan.
• Orang yang sudah memiliki akun dengan alamat email yang sama. Dengan oauth.autoMerge: true, proses masuk SSO pertama menautkan SSO ke akun yang ada, tetapi hanya jika token ID menyatakan alamat itu sudah diverifikasi (email_verified: true). Selain itu, dan selalu tanpa autoMerge, MonoChat meminta orang itu masuk sekali dengan kata sandinya, lalu menautkan SSO ke akun saat itu; menerima undangan ke sebuah organisasi juga menautkannya. Microsoft Entra ID dan AD FS tidak mengirim email_verified, jadi untuk keduanya, tetap izinkan masuk dengan kata sandi sampai semua orang sudah menautkan SSO, atau undang ulang orang-orang tersebut.
• Domain yang diizinkan. Dengan allowedEmailDomains, alamat dari domain lain ditolak. Untuk Google Workspace (issuer https://accounts.google.com), MonoChat memeriksa claim hd, yaitu domain Workspace akun, alih-alih alamat email, karena akun Google pribadi dapat memakai alamat dari domain apa pun.

Jadikan SSO satu-satunya metode masuk

1. Atur public.auth.methods ke ["oidc"]. Halaman masuk lalu hanya menampilkan tombol SSO, dan server menolak masuk dengan kata sandi dan akun media sosial.
2. Pengguna root super (pengguna dengan peran root super di organisasi root) tetap dapat masuk dengan kata sandinya di /auth/signin?fallback=1, sehingga instalasi tidak pernah terkunci jika IdP mati.
3. Untuk mencegah akun SSO baru membuka organisasinya sendiri, atur public.disableTenantCreation ke true. Setelah itu hanya orang dengan peran yang sesuai di sebuah organisasi yang dapat membuat organisasi di bawahnya.

Jaringan

• Pastikan /api/oauth/oidc/authorize dan redirectPath Anda dapat diakses oleh orang yang masuk. Keduanya dibuka di browser mereka.
• Server MonoChat harus dapat menjangkau dokumen discovery, endpoint token, dan set kunci (jwks_uri) IdP Anda melalui HTTPS.

Batasan

• Aplikasi seluler MonoChat belum mendukung SSO. Jika Anda menjadikan SSO satu-satunya metode masuk, agen tidak dapat masuk ke aplikasi seluler.
• Keluar dari MonoChat tidak mengeluarkan orang itu dari IdP, dan keluar dari IdP belum mengeluarkannya dari MonoChat.

Periksa pengaturan Anda

1. Buka halaman masuk dan klik tombol SSO. Masuk di IdP Anda; pop-up tertutup dan Anda sudah masuk ke MonoChat.
2. Masuk dengan orang yang belum memiliki akun MonoChat, dan pastikan akunnya dibuat (atau ditolak, jika Anda tidak mengaktifkan autoCreateAccounts).
3. Jika Anda mengatur allowedEmailDomains, coba dengan orang dari domain lain dan pastikan proses masuk ditolak.
4. Jika Anda mengatur public.auth.methods, pastikan masuk dengan kata sandi ditolak, dan pengguna root super masih dapat masuk di /auth/signin?fallback=1.