Autentikasi & Otorisasi

Dokumentasi lengkap sistem autentikasi dan otorisasi di LMS Codeverta.

Ikhtisar Sistem Autentikasi

LMS Codeverta menggunakan JWT (JSON Web Token) berbasis autentikasi dengan dukungan Access Token dan Refresh Token. Sistem ini juga mendukung session-based authentication sebagai fallback, serta WebAuthn (Passkey) untuk autentikasi tanpa password.

Alur Autentikasi Dasar

┌──────────┐        ┌──────────┐        ┌──────────┐
│  Client  │        │   API    │        │ Database │
└────┬─────┘        └────┬─────┘        └────┬─────┘
     │                   │                   │
     │   POST /login     │                   │
     │   {email, pass}   │                   │
     │──────────────────▶│                   │
     │                   │  Verify Creds     │
     │                   │──────────────────▶│
     │                   │◀──────────────────│
     │                   │                   │
     │   {access_token   │                   │
     │    refresh_token} │                   │
     │◀──────────────────│                   │
     │                   │                   │
     │   GET /courses    │                   │
     │   (Bearer token)  │                   │
     │──────────────────▶│                   │
     │                   │  Validate JWT     │
     │                   │  (middleware)     │
     │                   │                   │
     │   {courses data}  │                   │
     │◀──────────────────│                   │

Metode Autentikasi

Metode autentikasi standar menggunakan email dan password.

Endpoint: POST /api/auth/login

Request:

{
  "email": "user@example.com",
  "password": "password123"
}

Response (Sukses):

{
  "success": true,
  "message": "Login successful",
  "data": {
    "user": {
      "id": "uuid-user",
      "email": "user@example.com",
      "display_name": "User Display Name",
      "role": 1,
      "status": 1
    },
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIs..."
  }
}

2. Refresh Token

Access Token memiliki masa berlaku yang pendek (5 menit). Gunakan Refresh Token untuk mendapatkan Access Token baru tanpa login ulang.

Endpoint: POST /api/auth/refresh

Request:

{
  "refresh_token": "eyJhbGciOiJIUzI1NiIs..."
}

Response:

{
  "success": true,
  "message": "Token refreshed successfully",
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIs... (new)",
    "refresh_token": "eyJhbGciOiJIUzI1NiIs... (new)"
  }
}

3. WebAuthn (Passkey)

LMS Codeverta mendukung WebAuthn untuk autentikasi tanpa password menggunakan passkey (biometric, PIN, atau security key).

Cara Kerja:

User melakukan registrasi perangkat (public key disimpan di server)
Saat login, user cukup menggunakan sidik jari, face ID, atau PIN
Tidak perlu memasukkan password

Endpoint WebAuthn:

POST /api/auth/webauthn/register/begin — Memulai registrasi passkey
POST /api/auth/webauthn/register/finish — Menyelesaikan registrasi
POST /api/auth/webauthn/login/begin — Memulai login passkey
POST /api/auth/webauthn/login/finish — Menyelesaikan login

4. Session-Based Authentication (Fallback)

Selain JWT, sistem juga mendukung session-based auth menggunakan gin-contrib/sessions:

Session disimpan di Redis (jika Redis enabled) atau Cookie store (fallback)

Token Lifetime & Security

Access Token

Properti	Nilai
Durasi	5 menit
Penyimpanan	Memory / localStorage (client)
Penggunaan	Setiap request ke API (Authorization header)
Risiko	Informasi bisa dibaca payload (base64 encoded, bukan encrypted)

Refresh Token

Properti	Nilai
Durasi	7 hari
Penyimpanan	httpOnly cookie / secure storage
Penggunaan	Hanya untuk mendapatkan access token baru
Keamanan	Harus disimpan dengan aman (jangan di localStorage)

Best Practice Keamanan Token

Rekomendasi

Simpan access token di memory — Jangan di localStorage (rawan XSS)
Simpan refresh token di httpOnly cookie — Tidak bisa diakses JavaScript
Gunakan HTTPS — Enkripsi semua komunikasi
Rotasi refresh token — Setiap kali refresh, token lama tidak valid
Set expiry yang wajar — Access token pendek, refresh token lebih panjang
Jangan sertakan data sensitif di payload JWT — Payload hanya base64 encoded

Otorisasi: Role-Based Access Control (RBAC)

Level Role

LMS Codeverta menggunakan sistem RBAC dengan level numerik:

Role	Level	Kode	Deskripsi
Super Admin	100	`role_admin_root`	Akses penuh ke semua fitur sistem
Admin	99	`role_admin`	Akses manajemen platform sehari-hari
Mentor	30	`role_mentor`	Mengelola siswa, menilai tugas
Orang Tua	10	`role_parent`	Memantau progres belajar anak
Siswa	1	`role_common_user` / `role_student`	Mengakses kursus dan belajar

Pengecekan Role di Backend

Backend memeriksa role user di setiap endpoint yang memerlukan otorisasi:

// Contoh pengecekan role di controller
userID, role, ok := currentLMSUser(c)
if role < 99 {
    sendError(c, http.StatusForbidden, "Insufficient permission", nil)
    return
}

Route Protection

Setiap route group dilindungi oleh middleware yang sesuai:

Route Group	Minimum Role	Middleware
`/api/auth/*`	Public	-
`/api/me/*`	1 (Siswa)	Auth middleware
`/api/students/*`	1 (Siswa)	Auth middleware
`/api/admin/*`	99 (Admin)	Auth + Admin middleware
`/api/lms/admin/*`	99 (Admin)	Auth + Admin middleware
`/api/lms/mentor/*`	30 (Mentor)	Auth + Mentor middleware
`/api/lms/students/*`	1 (Siswa)	Auth middleware
`/api/parent/*`	10 (Orang Tua)	Auth + Parent middleware

Hierarki Akses

Super Admin (100) ─── Bisa melakukan apa saja
     │
Admin (99) ─── Bisa mengelola semua kecuali Super Admin
     │
Mentor (30) ─── Bisa mengelola siswa dan tugas
     │
Orang Tua (10) ─── Bisa memantau anak sendiri
     │
Siswa (1) ─── Bisa mengakses kursus dan belajar

Aturan Hierarki:

User hanya bisa memodifikasi user dengan role lebih rendah
Super Admin (100) tidak bisa dimodifikasi oleh siapapun
User tidak bisa menaikkan role user lain ke level yang sama atau lebih tinggi

Middleware Autentikasi

Auth Middleware

Auth middleware memverifikasi token JWT atau session sebelum mengizinkan akses ke endpoint:

// Pseudocode middleware auth
func AuthMiddleware() gin.HandlerFunc {
    return func(c *gin.Context) {
        token := extractBearerToken(c)
        if token == "" {
            // Cek session sebagai fallback
            session := sessions.Default(c)
            userID := session.Get("id")
            if userID == nil {
                sendError(c, 401, "Unauthorized", nil)
                c.Abort()
                return
            }
        } else {
            // Validasi JWT
            claims, err := validateToken(token)
            if err != nil {
                sendError(c, 401, "Invalid token", nil)
                c.Abort()
                return
            }
            c.Set("id", claims.UserId)
            c.Set("role", claims.Role)
        }
        c.Next()
    }
}

Admin Middleware

Memeriksa apakah user memiliki role admin (≥ 99) setelah autentikasi.

Tenant Middleware

TenantMiddleware digunakan untuk mendukung multi-tenant. Middleware ini:

Mengekstrak identitas tenant dari subdomain atau header
Menyimpan tenant context di request
Data query akan di-scope berdasarkan tenant

Flow Diagram

User membuka LMS Codeverta
        │
        ▼
Halaman Login (Email/PW atau WebAuthn)
        │
        ▼
User memasukkan kredensial
        │
        ▼
┌───────────────────────────────┐
│  Backend memverifikasi:       │
│  1. Email terdaftar?          │
│  2. Password cocok?           │
│  3. Akun aktif?               │
│  4. Password login enabled?   │
└───────────────┬───────────────┘
                │
      ┌─────────┴──────────┐
      ▼                    ▼
   Success              Failed
      │                    │
      ▼                    ▼
Generate Access      Response error
Token + Refresh      dengan pesan
Token & simpan       yang sesuai
session
      │
      ▼
Response ke client:
- User info (safe)
- Access token
- Refresh token
      │
      ▼
Client redirect ke
Dashboard sesuai role

Kondisi	HTTP Status	Pesan
Email tidak terdaftar	400	"Invalid parameters" / "User not found"
Password salah	400	"Invalid parameters"
Akun dinonaktifkan	403	"Your account has been deactivated..."
Password login disabled	400	"Password login has been disabled..."

Logout

Endpoint: POST /api/auth/logout

Proses logout:

Client menghapus access token dari memory
Refresh token dihapus dari cookie/storage
(Opsional) Backend bisa mem-blacklist token yang masih valid

Registrasi Pengguna Baru

Endpoint: POST /api/auth/register

Ketentuan Registrasi

Registrasi harus diaktifkan oleh admin (RegisterEnabled)
Registrasi password harus diaktifkan (PasswordRegisterEnabled)
Jika email verification aktif, user harus memverifikasi email terlebih dahulu

Request

{
  "username": "newuser",
  "email": "newuser@example.com",
  "password": "password123",
  "display_name": "New User",
  "verification_code": "123456"  // (jika email verification enabled)
}

Response

{
  "success": true,
  "message": "Participant successful",
  "data": {
    "username": "newuser",
    "display_name": "New User",
    "email": "newuser@example.com"
  }
}

Manajemen Token

Struktur JWT Payload

{
  "id": "uuid-user",
  "username": "username",
  "role": 1,
  "iss": "gin-template",
  "exp": 1700000000,
  "iat": 1699999700
}

Verifikasi Token (di Backend)

Backend memverifikasi token dengan:

Memeriksa signature (HMAC-SHA256 dengan secret key)
Memeriksa expiry (token kadaluarsa ditolak)
Memeriksa issuer ("gin-template")
Mengekstrak user ID dan role dari claims

FAQ Autentikasi

Ya, Anda bisa login di beberapa perangkat. Setiap perangkat akan mendapatkan token yang berbeda.

Kenapa saya tiba-tiba logout?

Access token memiliki masa berlaku 5 menit. Jika refresh token juga kedaluwarsa (7 hari), Anda harus login ulang.

Apakah password saya aman?

Password disimpan dalam bentuk hash (bukan plain text) menggunakan algoritma hashing yang aman. Backend tidak pernah menyimpan password asli.

Bagaimana WebAuthn bekerja?

WebAuthn menggunakan public key cryptography. Perangkat Anda membuat pasangan kunci (public & private). Kunci public disimpan di server, kunci private tetap aman di perangkat Anda. Saat login, server memverifikasi bahwa Anda memiliki kunci private tanpa perlu mengirimkannya.

Apakah session saya tetap ada setelah refresh token kedaluwarsa?

Tidak. Setelah refresh token kedaluwarsa (7 hari), Anda perlu login ulang untuk mendapatkan token baru.

Terakhir diperbarui: Juni 2026

Ikhtisar Sistem Autentikasi​

Alur Autentikasi Dasar​

Metode Autentikasi​

1. Login dengan Email & Password​

2. Refresh Token​

3. WebAuthn (Passkey)​

4. Session-Based Authentication (Fallback)​

Token Lifetime & Security​

Access Token​

Refresh Token​

Best Practice Keamanan Token​

Otorisasi: Role-Based Access Control (RBAC)​

Level Role​

Pengecekan Role di Backend​

Route Protection​

Hierarki Akses​

Middleware Autentikasi​

Auth Middleware​

Admin Middleware​

Tenant Middleware​

Alur Login Lengkap​

Flow Diagram​

Kondisi Gagal Login​

Logout​

Registrasi Pengguna Baru​

Ketentuan Registrasi​

Request​

Response​

Manajemen Token​

Struktur JWT Payload​

Verifikasi Token (di Backend)​

FAQ Autentikasi​

Apakah saya bisa login di beberapa perangkat sekaligus?​

Kenapa saya tiba-tiba logout?​

Apakah password saya aman?​

Bagaimana WebAuthn bekerja?​

Apakah session saya tetap ada setelah refresh token kedaluwarsa?​