JWT dan Otorisasi
Route yang Aman

Login bukan akhir proses auth, login hanya menghasilkan bukti sementara agar request berikutnya bisa dikenali.

Di React, setelah user login biasanya frontend menyimpan access token lalu mengirim header Authorization: Bearer ... pada request berikutnya. Di Laravel, konsepnya mirip middleware auth dan can, tetapi Go membuat alurnya lebih eksplisit: middleware membaca token, memverifikasi signature, lalu memasukkan identitas user ke context.Context request.

Dalam backend online shop skincare, customer boleh melihat order miliknya, menambah cart, dan checkout. Admin boleh membuka /v1/admin/*, mengelola produk, melihat semua order, dan memproses refund. JWT membantu API mengenali user, tetapi otorisasi role menentukan apakah user itu boleh masuk ke route tertentu.

JWT adalah token bertanda tangan, bukan database session dan bukan tempat menyimpan semua data user.

JWT biasanya berisi tiga bagian: header, payload, dan signature. Header menyebut algoritma, payload menyimpan claims, signature membuktikan bahwa token dibuat oleh server yang punya secret. Library yang kita pakai adalah github.com/golang-jwt/jwt/v5 (versi terbaru seri v5.3.x per Juni 2026), versi v5 memakai import path /v5 dan menyediakan RegisteredClaims untuk claims standar.

Selain empat claim di atas, RegisteredClaims juga menyimpan dua claim standar yang berguna saat sistem tumbuh: iss (issuer, siapa yang menerbitkan token) dan aud (audience, untuk siapa token ini ditujukan). Di proyek skincare, iss bisa diisi skincare-api dan aud diisi nama environment, sehingga token yang diterbitkan di staging tidak diam-diam diterima di production. Pada fase awal kita belum wajib memakainya, tetapi penting tahu bahwa validasinya tinggal mengaktifkan opsi parser jwt.WithIssuer dan jwt.WithAudience (dibahas di Section 04).

Contoh payload access tokenSalin
{
  "iss": "skincare-api",
  "sub": "user_9f3a",
  "role": "customer",
  "exp": 1780735840,
  "iat": 1780734940
}

HS256 memakai satu secret yang sama untuk membuat dan memverifikasi token.

HMAC-SHA256 cocok untuk modular monolith karena hanya satu API process yang menerbitkan dan memverifikasi token. Secret harus panjang, random, dan diambil dari environment atau secret manager, bukan hardcoded di repository. Untuk HS256, gunakan secret minimal 32 byte (256-bit) supaya kekuatannya setara dengan output HMAC-SHA256, secret yang lebih pendek memperkecil ruang kunci dan melemahkan tanda tangan.

TerminalSalin
# Cara cepat dengan openssl: 32 byte acak, di-encode base64
openssl rand -base64 32

Bila ingin men-generate dari Go (misalnya untuk tooling internal), crypto/rand adalah sumber acak yang aman secara kriptografis, bukan math/rand.

cmd/gensecret/main.goSalin
package main

import (
	"crypto/rand"
	"encoding/base64"
	"fmt"
)

func main() {
	buf := make([]byte, 32)
	if _, err := rand.Read(buf); err != nil {
		panic(err)
	}
	fmt.Println(base64.StdEncoding.EncodeToString(buf))
}

Saat nanti arsitektur berkembang ke banyak service yang perlu memverifikasi token tanpa boleh menerbitkannya, kita bisa pindah ke asymmetric signing seperti RS256: penerbit memegang private key untuk sign, semua verifier cukup memegang public key. Selama masih satu process yang sign dan verify, HS256 lebih sederhana dan cukup.

internal/auth/token.goSalin
package auth

import (
	"time"

	"github.com/golang-jwt/jwt/v5"
)

type Role string

const (
	RoleCustomer Role = "customer"
	RoleAdmin    Role = "admin"
)

type AccessClaims struct {
	Role string `json:"role"`
	jwt.RegisteredClaims
}

// Issuer membedakan token antar-environment. Validasinya opsional di Section 04.
const Issuer = "skincare-api"

func NewAccessToken(userID string, role Role, secret []byte, now time.Time) (string, error) {
	claims := AccessClaims{
		Role: string(role),
		RegisteredClaims: jwt.RegisteredClaims{
			Issuer:    Issuer,
			Subject:   userID,
			IssuedAt:  jwt.NewNumericDate(now),
			ExpiresAt: jwt.NewNumericDate(now.Add(15 * time.Minute)),
		},
	}

	token := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)
	return token.SignedString(secret)
}

Access token pendek menimbulkan pertanyaan praktis: apa yang terjadi setiap 15 menit? Inilah siklus penuhnya, menyambung dengan refresh token flow dari R7.C1. Modul ini bertanggung jawab pada bagian “active” dan “expired -> 401”, sementara langkah refresh sudah dibahas sebelumnya.

stateDiagram-v2
  [*] --> Issued: login berhasil (NewAccessToken)
  Issued --> Active: dipakai di header Authorization
  Active --> Active: request berhasil (token belum exp)
  Active --> Expired: lewat 15 menit
  Expired --> Refreshing: client kirim refresh token (R7.C1)
  Refreshing --> Issued: access token baru diterbitkan
  Refreshing --> [*]: refresh token invalid, user login ulang

Gambar 1. Siklus access token: token aktif sebentar, expired memicu 401, lalu client menukar refresh token jadi access token baru.

Middleware auth adalah gerbang pertama sebelum handler membaca data user.

Alur middleware: baca header Authorization, ambil token setelah kata Bearer, parse claims, validasi algoritma HS256, cek signature, cek exp, cek iat, pastikan sub dan role valid, lalu sisipkan user ringkas ke context. Kita memakai jwt.WithValidMethods untuk membatasi algoritma agar token dengan algoritma lain tidak diterima.

Sebelum ke kode, perhatikan satu hal desain: Role, AccessClaims, dan NewAccessToken sudah didefinisikan di package auth (Section 03). Agar tetap satu sumber kebenaran, middleware tidak mendefinisikan ulang tipe-tipe itu, melainkan meng-import dari auth. Yang menjadi milik middleware hanyalah AuthUser ringkas, key context, dan fungsi guard.

sequenceDiagram
  participant FE as Frontend React
  participant MW as JWT Middleware
  participant H as Handler
  participant S as Service
  participant DB as PostgreSQL
  FE->>MW: GET /v1/orders Authorization Bearer token
  MW->>MW: Parse claims, verify HS256, check exp
  MW->>H: Request dengan AuthUser di context
  H->>S: ListOrders(ctx)
  S->>DB: SELECT orders WHERE user_id = sub
  DB-->>S: rows
  S-->>H: orders
  H-->>FE: 200 OK

Gambar 2. Token diverifikasi sekali di middleware, lalu identitas user dibawa lewat context sampai service.

Perhatikan bahwa ada dua lapis penjagaan yang berbeda peran. Lapis pertama adalah authentication (membuktikan token sah), lapis kedua adalah authorization (memutuskan role boleh masuk). Memisahkan keduanya membuat alasan setiap penolakan jelas: 401 untuk token, 403 untuk izin.

flowchart LR
  REQ[Request masuk] --> MW["JWT middleware<br/>verify signature, exp, alg"]
  MW -->|token invalid| E401[401 Unauthorized]
  MW -->|token valid| RR["RequireRole<br/>cek role di allowed map"]
  RR -->|role tidak cocok| E403[403 Forbidden]
  RR -->|role cocok| H[Handler]

Gambar 3. Dua lapis terpisah: authentication dulu (JWT), baru authorization (RequireRole). Setiap lapis punya kode status sendiri.

middleware/jwt.goSalin
package middleware

import (
	"context"
	"errors"
	"net/http"
	"strings"
	"time"

	"github.com/golang-jwt/jwt/v5"

	"github.com/kamu/skincare-backend/internal/auth"
)

type AuthUser struct {
	ID   string
	Role auth.Role
}

type contextKey struct{}

var authUserKey = contextKey{}

func JWT(secret []byte) func(http.Handler) http.Handler {
	return func(next http.Handler) http.Handler {
		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
			tokenString, err := bearerToken(r.Header.Get("Authorization"))
			if err != nil {
				writeAuthError(w, http.StatusUnauthorized, "missing_or_invalid_authorization_header")
				return
			}

			claims := new(auth.AccessClaims)
			token, err := jwt.ParseWithClaims(
				tokenString,
				claims,
				func(token *jwt.Token) (any, error) {
					return secret, nil
				},
				jwt.WithValidMethods([]string{jwt.SigningMethodHS256.Alg()}),
				jwt.WithIssuer(auth.Issuer),
				jwt.WithExpirationRequired(),
				jwt.WithIssuedAt(),
				jwt.WithLeeway(30*time.Second),
			)
			if err != nil || !token.Valid {
				writeAuthError(w, http.StatusUnauthorized, "invalid_or_expired_token")
				return
			}

			if claims.Subject == "" {
				writeAuthError(w, http.StatusUnauthorized, "missing_subject")
				return
			}

			role := auth.Role(claims.Role)
			if !isKnownRole(role) {
				writeAuthError(w, http.StatusForbidden, "unknown_role")
				return
			}

			user := AuthUser{ID: claims.Subject, Role: role}
			ctx := context.WithValue(r.Context(), authUserKey, user)
			next.ServeHTTP(w, r.WithContext(ctx))
		})
	}
}

func CustomerOnly() func(http.Handler) http.Handler {
	return RequireRole(auth.RoleCustomer)
}

func AdminOnly() func(http.Handler) http.Handler {
	return RequireRole(auth.RoleAdmin)
}

func RequireRole(roles ...auth.Role) func(http.Handler) http.Handler {
	allowed := make(map[auth.Role]struct{}, len(roles))
	for _, role := range roles {
		allowed[role] = struct{}{}
	}

	return func(next http.Handler) http.Handler {
		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
			user, ok := UserFromContext(r.Context())
			if !ok {
				writeAuthError(w, http.StatusUnauthorized, "unauthenticated")
				return
			}

			if _, ok := allowed[user.Role]; !ok {
				writeAuthError(w, http.StatusForbidden, "forbidden")
				return
			}

			next.ServeHTTP(w, r)
		})
	}
}

func UserFromContext(ctx context.Context) (AuthUser, bool) {
	user, ok := ctx.Value(authUserKey).(AuthUser)
	return user, ok
}

func bearerToken(header string) (string, error) {
	if header == "" {
		return "", errors.New("authorization_header_required")
	}

	const prefix = "Bearer "
	if !strings.HasPrefix(header, prefix) {
		return "", errors.New("bearer_prefix_required")
	}

	token := strings.TrimSpace(strings.TrimPrefix(header, prefix))
	if token == "" {
		return "", errors.New("token_required")
	}

	return token, nil
}

func isKnownRole(role auth.Role) bool {
	switch role {
	case auth.RoleCustomer, auth.RoleAdmin:
		return true
	default:
		return false
	}
}

func writeAuthError(w http.ResponseWriter, code int, message string) {
	w.Header().Set("Content-Type", "application/json")
	w.WriteHeader(code)
	_, _ = w.Write([]byte(`{"error":"` + message + `"}`))
}

Lima opsi parser di ParseWithClaims bukan hiasan, masing-masing menutup satu celah nyata. Memahaminya membuat kamu tahu persis apa yang dijaga dan apa yang tidak.

Setelah token diverifikasi, peran middleware selesai sebagai authentication. Jalur gagal punya kode status sendiri: token hilang atau invalid menghasilkan 401, sedangkan role yang tidak dikenal langsung 403. Diagram berikut menunjukkan skenario negatif yang paling sering disalahpahami, customer yang tokennya valid tetapi mencoba route admin.

sequenceDiagram
  participant FE as Frontend (customer)
  participant MW as JWT Middleware
  participant RR as AdminOnly
  participant H as Admin Handler
  FE->>MW: GET /v1/admin/orders Bearer token-customer
  MW->>MW: Verify HS256, exp, iat (token VALID)
  MW->>RR: Request dengan AuthUser role=customer
  RR->>RR: role customer tidak ada di allowed map
  RR-->>FE: 403 Forbidden
  Note over RR,H: Admin Handler tidak pernah dipanggil

Gambar 4. Token valid tidak otomatis berarti boleh masuk. Authentication lolos (bukan 401), tetapi authorization menolak (403).

Context membawa data yang scoped ke satu request, bukan tempat menyimpan dependency global.

Package context mendefinisikan Context untuk membawa deadline, cancellation signal, dan request-scoped values melewati API boundary. Untuk auth, menyimpan AuthUser di context masuk akal karena identitas user memang melekat pada request HTTP saat ini.

Kenapa memakai type contextKey struct{} dan variabel private? Karena key context bertipe string raw seperti "user" bisa bertabrakan dengan package lain. Tipe private membuat key unik di package middleware, sehingga hanya fungsi resmi seperti UserFromContext yang dipakai untuk membaca user.

internal/order/service.goSalin
package order

import (
	"context"
	"errors"

	"github.com/kamu/skincare-backend/middleware"
)

var ErrUnauthenticated = errors.New("unauthenticated")

type Repository interface {
	ListByUserID(ctx context.Context, userID string) ([]Order, error)
}

type Service struct {
	repo Repository
}

func (s *Service) ListMine(ctx context.Context) ([]Order, error) {
	user, ok := middleware.UserFromContext(ctx)
	if !ok {
		return nil, ErrUnauthenticated
	}

	return s.repo.ListByUserID(ctx, user.ID)
}

Authentication menjawab siapa user-nya, authorization menjawab apa yang boleh ia lakukan.

Role-based access sederhana cukup untuk fase awal online shop skincare: customer untuk pembeli dan admin untuk backoffice. Middleware CustomerOnly dan AdminOnly membaca AuthUser dari context, lalu mengembalikan 403 Forbidden bila role tidak cocok. Perhatikan bedanya dengan 401 Unauthorized: 401 berarti belum login atau token invalid, sedangkan 403 berarti sudah dikenali tetapi tidak punya izin.

Kenapa RequireRole(roles ...auth.Role) dibuat variadic, bukan satu role saja? Karena begitu role bertambah (misalnya nanti ada role staff yang boleh melihat order tetapi tidak boleh refund), kita ingin menggabungkan beberapa role yang diizinkan dalam satu route tanpa menulis middleware baru. Cukup tulis RequireRole(auth.RoleAdmin, roleStaff) untuk route yang boleh dimasuki keduanya, sementara CustomerOnly/AdminOnly tetap menjadi pemanggilan tipis untuk kasus satu role.

flowchart TD
  A[Request masuk] --> B{JWT valid?}
  B -->|Tidak| C[401 Unauthorized]
  B -->|Ya| D[AuthUser masuk context]
  D --> E{Route admin?}
  E -->|Tidak| F[Handler customer]
  E -->|Ya| G{role admin?}
  G -->|Tidak| H[403 Forbidden]
  G -->|Ya| I[Handler admin]

Gambar 5. Role check dilakukan setelah token valid dan sebelum handler admin dijalankan.

Dengan chi, proteksi route bisa ditempel per group sehingga batas admin dan customer terlihat di file routes.

Struktur route yang baik membuat keamanan mudah diaudit. Route publik seperti login dan register tidak memakai middleware JWT. Route customer memakai JWT plus CustomerOnly. Route admin memakai JWT plus AdminOnly. Dengan pola ini, developer baru bisa membaca file route dan langsung tahu area mana yang publik, customer, atau admin.

cmd/api/routes.goSalin
package api

import (
	"net/http"

	"github.com/go-chi/chi/v5"
	"github.com/kamu/skincare-backend/middleware"
)

type Handlers struct {
	Auth  AuthHandler
	Me    MeHandler
	Order OrderHandler
	Admin AdminHandler
}

type AuthHandler interface {
	Login(w http.ResponseWriter, r *http.Request)
	Register(w http.ResponseWriter, r *http.Request)
}

type MeHandler interface {
	Show(w http.ResponseWriter, r *http.Request)
}

type OrderHandler interface {
	ListMine(w http.ResponseWriter, r *http.Request)
	Checkout(w http.ResponseWriter, r *http.Request)
}

type AdminHandler interface {
	ListOrders(w http.ResponseWriter, r *http.Request)
	UpdateProduct(w http.ResponseWriter, r *http.Request)
}

func NewRouter(h Handlers, jwtSecret []byte) http.Handler {
	r := chi.NewRouter()

	r.Route("/v1", func(r chi.Router) {
		r.Post("/auth/register", h.Auth.Register)
		r.Post("/auth/login", h.Auth.Login)

		r.Group(func(r chi.Router) {
			r.Use(middleware.JWT(jwtSecret))
			r.Get("/me", h.Me.Show)
		})

		r.Group(func(r chi.Router) {
			r.Use(middleware.JWT(jwtSecret))
			r.Use(middleware.CustomerOnly())
			r.Get("/orders", h.Order.ListMine)
			r.Post("/orders/checkout", h.Order.Checkout)
		})

		r.Route("/admin", func(r chi.Router) {
			r.Use(middleware.JWT(jwtSecret))
			r.Use(middleware.AdminOnly())
			r.Get("/orders", h.Admin.ListOrders)
			r.Patch("/products/{id}", h.Admin.UpdateProduct)
		})
	})

	return r
}

Handler boleh membaca user untuk response ringan, tetapi business rule tetap sebaiknya ditegakkan di service.

Untuk endpoint /v1/me, handler cukup membaca user dari context dan mengembalikan data dasar. Untuk order, service tetap harus memakai user.ID dari context saat query. Jangan menerima user_id dari request body untuk operasi customer, karena customer bisa memalsukan ID user lain.

internal/me/handler.goSalin
package me

import (
	"encoding/json"
	"net/http"

	"github.com/kamu/skincare-backend/middleware"
)

type Handler struct{}

type response struct {
	UserID string `json:"user_id"`
	Role   string `json:"role"`
}

func (h Handler) Show(w http.ResponseWriter, r *http.Request) {
	user, ok := middleware.UserFromContext(r.Context())
	if !ok {
		http.Error(w, "unauthenticated", http.StatusUnauthorized)
		return
	}

	w.Header().Set("Content-Type", "application/json")
	_ = json.NewEncoder(w).Encode(response{
		UserID: user.ID,
		Role:   string(user.Role),
	})
}

internal/order/handler.goSalin
package order

import (
	"context"
	"net/http"
)

type Service interface {
	ListMine(ctx context.Context) ([]Order, error)
}

type Handler struct {
	service Service
}

func (h Handler) ListMine(w http.ResponseWriter, r *http.Request) {
	orders, err := h.service.ListMine(r.Context())
	if err != nil {
		writeError(w, err)
		return
	}

	writeJSON(w, http.StatusOK, orders)
}

Bahaya konkretnya bernama IDOR (Insecure Direct Object Reference). Bayangkan endpoint GET /v1/orders/:id. Customer A login sah, lalu menebak order_id milik customer B dan mengaksesnya. Kalau query hanya WHERE id = $1, customer A berhasil membaca order orang lain. Pertahanannya sederhana dan wajib: query selalu menyertakan user_id dari context, sehingga order yang bukan miliknya tidak akan pernah ditemukan.

internal/order/repository.goSalin
package order

import (
	"context"

	"github.com/jackc/pgx/v5/pgxpool"
)

type PgRepository struct {
	pool *pgxpool.Pool
}

// GetByID selalu mengikat id DAN user_id, jadi customer lain tidak bisa
// membaca order milik orang lain meski menebak id yang benar.
func (r *PgRepository) GetByID(ctx context.Context, id, userID string) (Order, error) {
	const q = `
		SELECT id, user_id, total_rupiah, status
		FROM orders
		WHERE id = $1 AND user_id = $2`

	var o Order
	err := r.pool.QueryRow(ctx, q, id, userID).
		Scan(&o.ID, &o.UserID, &o.TotalRupiah, &o.Status)
	if err != nil {
		return Order{}, err
	}
	return o, nil
}

Latihan ini mengunci alur dari login, token, sampai route admin yang menolak customer.

TerminalSalin
go get github.com/golang-jwt/jwt/v5

TerminalSalin
TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

curl -i http://localhost:8080/v1/orders \
  -H "Authorization: Bearer $TOKEN"

curl -i http://localhost:8080/v1/admin/orders \
  -H "Authorization: Bearer $TOKEN"

Expected behaviorSalin
GET /v1/orders
200 OK untuk role customer dengan token valid

GET /v1/admin/orders
403 Forbidden untuk role customer
401 Unauthorized untuk token kosong, salah, atau expired
200 OK untuk role admin dengan token valid

Banyak bug auth bukan karena JWT sulit, tetapi karena boundary authentication dan authorization tidak jelas.

JWT memberi identitas request, role middleware menegakkan izin route, dan service tetap menjaga business rule.

Untuk proyek online shop skincare, modul ini mengunci fondasi route protection: customer bisa checkout dan melihat order miliknya, sedangkan admin punya jalur backoffice yang terpisah. Di modul berikutnya, pola ini dipakai bersama input validation, CSRF/CORS boundary, secret management, dan audit log agar API siap masuk production.