Copy page

Autentikasi

RBAC dan matriks izin

RBAC dan matriks izin

OmniStream menggunakan sistem RBAC (Role-Based Access Control) berbasis permission granular. Setiap role memiliki kumpulan permission yang dapat dikonfigurasi, bukan aturan akses hardcode per peran.

Sistem ini terdiri dari:

• Tabel roles — role bawaan (admin, supervisor, agent) dan role kustom yang dibuat admin
• Tabel permissions — 26 permission statis yang tersedia di sistem
• Tabel role_permissions — relasi many-to-many antara role dan permission
• JWT claims — permission dimuat ke token saat login sehingga setiap request membawa daftar permission aktif

Lihat Model Data — Roles & Permissions untuk skema tabel lengkap dan daftar seluruh kode permission.

Halaman ini mendokumentasikan peran bawaan, cara enforcement bekerja, dan matriks izin per endpoint berdasarkan konfigurasi default.

Peran

Peran	Use case	Visibilitas percakapan	Aksi administratif
admin	Pemilik, IT, manajer sistem	Semua percakapan	Semua: manage users, divisi, SLA, integrasi, webhook keluar, template
supervisor	Team lead, kepala shift	Semua percakapan	Dashboard analitik, monitor SLA, assign ulang, manage quick reply; tidak boleh manage user/integrasi
agent	Frontline customer support	Hanya percakapan yang di-assign kepadanya	Membalas pesan, membuat note, transfer ke kolega

Enum sumber kebenaran ada di crates/omni-common/src/models/agent.rs:

Code
pub enum AgentRole {
    #[serde(rename = "admin")]      Admin,
    #[serde(rename = "supervisor")] Supervisor,
    #[serde(rename = "agent")]      Agent,
}

Cara enforcement bekerja

1. Middleware JWT (crates/api-gateway/src/middleware/auth.rs) memvalidasi token, mendekode AgentClaims, dan memasukkannya ke Request::extensions().
2. Permission dimuat saat login — daftar permission aktif dari role_permissions dimasukkan ke dalam JWT claims sebagai array string (claims.permissions).
3. Setiap handler mengambil claims via Extension<AgentClaims> lalu memeriksa apakah permission yang diperlukan ada di claims.permissions, misalnya:

   Code
   if !claims.permissions.contains("agents.manage") {
       return Err(ApiError::Forbidden("Permission denied".to_string()));
   }

4. Scope data — beberapa handler mempersempit cakupan data berdasarkan role (mis. agent hanya melihat percakapan yang di-assign kepadanya) ketimbang menolak total. Pola ini umum pada GET /api/conversations, GET /api/contacts, GET /api/agents.

Admin dapat menyesuaikan permission per role melalui UI User Management → Roles tanpa mengubah kode. Role bawaan (admin, supervisor, agent) tidak dapat dihapus namanya, tetapi permission-nya dapat dimodifikasi.

Matriks izin per fitur

Tabel di bawah mencerminkan pemeriksaan claims.role aktual di handler. Kolom bernilai:

• ✔ = izin penuh
• ◑ = izin terbatas (biasanya scoped ke data milik sendiri/assigned)
• ✘ = ditolak dengan 403 Forbidden

Autentikasi & profil diri

Endpoint	Admin	Supervisor	Agent
POST /api/auth/login	✔	✔	✔
GET /api/auth/me	✔	✔	✔
GET /api/auth/token	✔	✔	✔
POST /api/auth/logout	✔	✔	✔

Manajemen agent

Endpoint	Admin	Supervisor	Agent
GET /api/agents (list)	✔	✔	✘
GET /api/agents/:id	✔	✔	◑ (hanya diri sendiri)
POST /api/agents (create)	✔	✘	✘
PATCH /api/agents/:id	✔	✘	◑ (hanya profil diri terbatas)
DELETE /api/agents/:id	✔	✘	✘

Percakapan & pesan

Endpoint	Admin	Supervisor	Agent
GET /api/conversations	✔ (semua)	✔ (semua)	◑ (hanya yang di-assign)
GET /api/conversations/:id	✔	✔	◑ (jika assigned)
POST /api/messages	✔	✔	◑ (jika assigned ke percakapan)
POST /api/conversations/:id/transfer	✔	✔	◑ (keluar dari dirinya)
POST /api/conversations/:id/notes	✔	✔	◑ (jika assigned)

Kontak

Endpoint	Admin	Supervisor	Agent
GET /api/contacts	✔	✔	◑ (scoped ke kontak pada percakapan ia pegang)
GET /api/contacts/:id	✔	✔	◑
POST /api/contacts	✔	✔	✘
PATCH /api/contacts/:id	✔	✔	✘

Supervisor-only

Endpoint	Admin	Supervisor	Agent
GET /api/analytics/*	✔	✔	✘
GET /api/activity-logs	✔	✔	✘
GET /api/sla/*	✔	✔	✘

Admin-only (paling sensitif)

Endpoint	Admin	Supervisor	Agent
GET /api/integrations, PUT /api/integrations/:channel	✔	✘	✘
POST /api/divisions, DELETE /api/divisions/:id	✔	✘	✘
POST /api/sla/policies, DELETE /api/sla/policies/:id	✔	✘	✘
POST /api/outgoing-webhooks, DELETE /api/outgoing-webhooks/:id	✔	✘	✘
POST /api/campaigns	✔	◑ (tergantung policy)	✘
GET /api/wa-templates, POST /api/wa-templates	✔	◑	✘

WebSocket: routing berbasis peran

ws-server ikut memakai peran saat merutekan event Redis:

• admin dan supervisor menerima event conversation_updates untuk semua percakapan (broadcast).
• agent hanya menerima event untuk percakapan yang di-assign kepadanya (berdasarkan assigned_agent_id).
• agent_presence disiarkan ke semua peran.
• sla_breaches disiarkan ke semua peran (supervisor-facing tetapi tidak ada filter ekstra).

Lihat WebSocket → Events untuk rincian payload.

Menambah peran baru

Role kustom dapat dibuat langsung dari UI tanpa modifikasi kode:

1. Buka User Management → tab Roles.
2. Klik New Role, isi nama dan deskripsi.
3. Centang permission yang diinginkan dari 26 permission yang tersedia.
4. Klik Create Role.

Role baru langsung tersedia sebagai pilihan saat membuat atau mengedit agent.

Lihat Manajemen Role & Permission untuk panduan lengkap.

Troubleshooting

• 403 Forbidden pada endpoint yang seharusnya diizinkan — verifikasi nilai role pada token dengan mendecode JWT di jwt.io (pakai environment dev). Jika peran salah di DB, update kolom agents.role dan login ulang supaya klaim baru diterbitkan.
• Supervisor tidak melihat integrasi — ini by design; hanya admin yang boleh. Buat dua akun (satu admin untuk konfigurasi, satu supervisor untuk operasional).
• Agent tidak menerima event WebSocket — pastikan percakapan benar-benar assigned_agent_id ke id agent yang sedang login. Tanpa assignment, filter ws-server tidak meneruskan event.

File terkait

• Enum peran: crates/omni-common/src/models/agent.rs
• Middleware auth: crates/api-gateway/src/middleware/auth.rs
• Contoh pola enforcement: crates/api-gateway/src/routes/agents.rs (create/update admin-only), crates/api-gateway/src/routes/conversations/core.rs (agent-scope filter), crates/api-gateway/src/routes/outgoing_webhooks.rs (admin-only)