rustbasic-passport
OAuth2 server dan Personal Access Token untuk aplikasi Rust — port dari
laravel/passport ke ekosistem Rust,
bagian dari keluarga crate RustBasic (lihat rustbasic-permission).
Fitur
| Fitur Passport (Laravel) | Implementasi di rustbasic-passport |
|---|---|
| Authorization Code Grant (+ PKCE) | authorization_code grant, PKCE S256 & plain (RFC 7636) |
| Password Grant | password grant dengan UserProvider |
| Client Credentials Grant | client_credentials grant |
| Refresh Token dengan rotasi | refresh_token grant sekali pakai (rotate) |
| Device Authorization Grant (RFC 8628) | issue_device_code + approve_device_code + urn:ietf:params:oauth:grant-type:device_code |
| Personal Access Token | create_personal_access_token() + personal_access grant |
| Grant Types per client (Passport 13.x) | kolom grant_types (has_grant_type) menggantikan personal_access_client/password_client |
| Token JWT ditandatangani RSA (RS256) | crate jsonwebtoken + rsa, dukungan kid untuk key rotation |
Guard auth:api (TokenGuard) |
middleware require_auth (axum) |
Middleware scope:... |
middleware check_scopes (ScopePolicy::any / all) |
Passport::routes() |
axum::router::<S>() → /oauth/token, /oauth/authorize, /oauth/revoke, /oauth/device, /oauth/device/verify |
| Integrasi loco.rs | feature loco: loco::routes() + Initializer (Extension) |
Perintah Artisan passport:keys |
binary CLI generate-keys |
Migrations oauth_* |
perintah CLI install (SQL: sqlite / postgres / mysql) |
Passport::tokensExpireIn() dll. |
Config (TTL access / refresh / auth code / PAT) |
Cara Kerja
- Anda mengimplementasi 6 trait penyimpanan (
ClientStore,AccessTokenStore,AuthCodeStore,RefreshTokenStore,DeviceCodeStore,UserProvider) di atas database/backend Anda (SQLx, Diesel, in-memory, dll). - Susun dengan
StoreBundle, buatPassportServerdenganSigningKeyRSA danConfig. - Panggil
server.issue_token(&TokenRequest)(grants) atau gunakan middleware axum untuk melindungi route.
Penggunaan
1. Implementasi store
use Client;
use Error;
use ClientStore;
// + AccessTokenStore, AuthCodeStore, RefreshTokenStore, DeviceCodeStore, UserProvider
2. Bangun server
use SigningKey;
use ;
use StoreBundle;
let stores = new;
let server = new;
3. Terbitkan token (password grant)
let resp = server.issue_token.await?;
println!; // JWT RS256
Grant lain cukup ganti grant_type:
authorization_code (+ code, redirect_uri, code_verifier),
client_credentials, refresh_token, personal_access,
atau urn:ietf:params:oauth:grant-type:device_code (+ device_code).
4. Device Authorization Grant (RFC 8628)
use DeviceAuthorizationRequest;
// Client TV meminta device code (body: client_id, client_secret, scope)
let device = server.issue_device_code.await?;
// device.user_code -> tampilkan di layar TV, mis. "BCDF-GHKJ"
// User membuka halaman verifikasi dan memasukkan user_code:
server.approve_device_code.await?;
// (user_code dinormalisasi otomatis: uppercase, spasi/tanda pisah dibuang)
// TV polling /oauth/token dengan grant_type device_code:
// - belum disetujui -> authorization_pending (polling ulang setelah `interval` detik)
// - polling terlalu cepat -> slow_down
// - disetujui -> access + refresh token
5. Personal Access Token
let pat = server
.create_personal_access_token
.await?;
// pat.access_token -> JWT, pat.token -> AccessToken tersimpan
6. Integrasi axum (feature axum)
[]
= { = "0.0", = ["axum"] }
Handler mengambil PassportServer lewat request extension, bukan router
state — sehingga router /oauth/* bisa di-merge bebas, termasuk ke framework
di atas axum yang mengunci tipe state (seperti loco.rs).
use Extension;
use middleware;
use axum as passport_axum;
use ;
type MyStores = /* StoreBundle<...> */;
// 1. Rute OAuth (mirip Passport::routes()) — server disuplai satu kali
let server = /* PassportServer::new(...) */;
let app = new
.merge // /oauth/* tanpa state
.layer; // tersedia di semua route
// 2. API terproteksi
let api = new
.route
.route_layer
.route_layer;
let app = app.merge;
Handler mengambil user via Extension<AuthContext> (diisi require_auth):
use Extension;
async
Catatan: dalam axum,
.route_layer()terakhir = layer terluar, jadirequire_authharus didaftarkan setelahcheck_scopes.
Respons error mengikuti RFC 6749/6750: invalid_client, invalid_grant,
invalid_token, insufficient_scope, dll.
7. Integrasi loco.rs (feature loco)
[]
= { = "0.0", = ["loco"] }
loco.rs membangun semua rute di atas axum::Router ber-state AppContext;
passport kompatibel karena handler-nya mengambil server via Extension.
// src/app.rs
use *;
use PassportServer;
type MyStores = /* StoreBundle<...> yang diimplementasikan di atas model sea-orm */;
;
Route API terproteksi cukup pakai require_auth / check_scopes seperti
axum biasa (works di loco karena bersifat self-contained):
.route_layer
Alternatif bentuk axum::Router<AppContext>: rustbasic_passport::loco::router::<MyStores>()
(bisa di-merge di Hooks::before_routes). Test integrasi nyata dalam router
loco ada di tests/loco_integration.rs (cargo test --features loco-testing).
CLI
# Generate RSA key pair (oauth-private.key / oauth-public.key)
# Cetak skema SQL tabel oauth_* (sqlite | postgres | mysql)
Contoh Lengkap
examples/in_memory.rs— seluruh alur (password, refresh, auth code + PKCE, device grant, PAT) dengan store in-memory, tanpa framework.examples/axum_server.rs— server axum lengkap dengan middleware.
Struktur Proyek
src/
├── entity.rs # Client (grant_types), AccessToken, AuthCode, RefreshToken, DeviceCode, PAT result
├── store.rs # trait penyimpanan + StoreBundle
├── jwt.rs # SigningKey (RSA RS256), claims, sign/verify
├── server.rs # PassportServer: grants, authorize, validate, revoke
├── axum.rs # (feature) routes, require_auth, check_scopes — berbasis Extension
├── loco.rs # (feature) Routes / Initializer untuk loco.rs
├── error.rs # Error + mapping ke OAuth error response
└── bin/ # CLI: generate-keys, install
Change Log
v0.0.1 — 2026-08-10 · Audit keamanan & perbaikan
Perbaikan keamanan dari hasil audit:
- Breking change: trait
AuthCodeStoredanRefreshTokenStorekini mewajibkan methodrevoke_if_unrevoked(&self, id) -> Result<bool, Error>(revoke atomik). Grantauthorization_codedanrefresh_tokenmemakai method ini untuk menegakkan single-use terhadap race condition (TOCTOU): dua permintaan tukar yang datang bersamaan tidak bisa lagi sama-sama menghasilkan token. Implementasi wajib atomik, misal:UPDATE oauth_auth_codes SET revoked = 1 WHERE id = ? AND revoked = 0. - Breking change:
RefreshTokenkini membawaclient_id, dan grantrefresh_tokenmemverifikasi bahwa token dipakai oleh client penerbitnya. Refresh token curian tidak lagi bisa ditebus oleh client lain. Skema SQLoauth_refresh_tokensbertambah kolomclient_id VARCHAR(64) NOT NULL(+ index) di semua dialect (sqlite / postgres / mysql). - Security fix: perbandingan client secret dan PKCE
plainkini constant-time (subtle+ SHA-256), tidak lagi rentan timing attack (server.rs::constant_time_eq). Dependency baru:subtle = "2".
Test baru: single-use auth code di bawah konkurensi (8 request simultan, hanya 1 berhasil) dan penolakan refresh token lintas client.
Lisensi
MIT