PHPackages                             kodepik/ums-laravel - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Authentication & Authorization](/categories/authentication)
4. /
5. kodepik/ums-laravel

ActiveLibrary[Authentication & Authorization](/categories/authentication)

kodepik/ums-laravel
===================

Laravel SDK for UMS (User Management System) — SSO authentication & authorization

1.0.0(yesterday)00MITPHPPHP ^8.1

Since Jul 1Pushed yesterdayCompare

[ Source](https://github.com/taufiqtab/ums-laravel-sdk)[ Packagist](https://packagist.org/packages/kodepik/ums-laravel)[ RSS](/packages/kodepik-ums-laravel/feed)WikiDiscussions main Synced today

READMEChangelogDependencies (5)Versions (2)Used By (0)

UMS Laravel SDK
===============

[](#ums-laravel-sdk)

Laravel package for SSO authentication & authorization via **UMS (User Management System)**.

Package ini menyediakan:

- SSO Login/Logout (OAuth2 redirect flow via UMS → Keycloak)
- JWT token validation via JWKS public key (RS256)
- Middleware untuk protect routes berdasarkan permission, role, dan module
- Helper functions untuk cek akses di mana saja (controller, service, blade)
- API authentication dengan Bearer token

---

Daftar Isi
----------

[](#daftar-isi)

1. [Requirements](#requirements)
2. [Installation](#installation)
3. [Configuration](#configuration)
4. [Prasyarat di UMS Admin](#prasyarat-di-ums-admin)
5. [Quick Start — SSO Login](#quick-start--sso-login)
6. [Quick Start — API Bearer Token](#quick-start--api-bearer-token)
7. [Middleware Reference](#middleware-reference)
8. [Helper Functions](#helper-functions)
9. [UmsClaims Object](#umsclaims-object)
10. [Facade](#facade)
11. [Implementasi Lengkap (Step by Step)](#implementasi-lengkap-step-by-step)
12. [Blade Template](#blade-template)
13. [Advanced: Custom Routes](#advanced-custom-routes)
14. [Advanced: Token Refresh](#advanced-token-refresh)
15. [Troubleshooting](#troubleshooting)
16. [Security Notes](#security-notes)

---

Requirements
------------

[](#requirements)

- PHP 8.1+
- Laravel 10.x atau 11.x
- UMS server yang sudah running

---

Installation
------------

[](#installation)

### 1. Install package

[](#1-install-package)

```
composer require kodepik/ums-laravel
```

> Package menggunakan Laravel auto-discovery — ServiceProvider dan Facade otomatis terdaftar.

### 2. Publish config

[](#2-publish-config)

```
php artisan vendor:publish --tag=ums-config
```

File `config/ums.php` akan dibuat.

---

Configuration
-------------

[](#configuration)

Tambahkan ke file `.env`:

```
# URL server UMS
UMS_BASE_URL=https://ums.yourserver.com

# App ID yang didaftarkan di UMS Admin
UMS_APP_ID=your-app-id

# Callback URL (harus didaftarkan juga di UMS Admin)
UMS_CALLBACK_URL=https://yourapp.com/ums/callback

# SSL verification (set false jika development dengan self-signed cert)
UMS_VERIFY_SSL=true

# Optional: disable auto-registered routes
UMS_ROUTES_ENABLED=true

# Optional: ganti prefix routes (default: 'ums')
UMS_ROUTES_PREFIX=ums

# Optional: JWKS cache duration (default: 3600 seconds / 1 jam)
UMS_JWKS_CACHE_TTL=3600
```

---

Prasyarat di UMS Admin
----------------------

[](#prasyarat-di-ums-admin)

Sebelum integrasi, pastikan di UMS Admin:

1. **Application sudah dibuat** — catat `app_id` (contoh: `APP-xxxxx`)
2. **Callback URL didaftarkan** — `https://yourapp.com/ums/callback`
3. **Logout redirect URL didaftarkan** — `https://yourapp.com/login`
4. **User di-assign ke application** — user yang bisa login
5. **Module, Role, Permission** — sudah di-assign ke user sesuai kebutuhan

---

Quick Start — SSO Login
-----------------------

[](#quick-start--sso-login)

Setelah install dan config, SSO **langsung bisa dipakai** tanpa coding tambahan.

### Auto-registered routes:

[](#auto-registered-routes)

RouteMethodNameFungsi`/ums/login`GET`ums.login`Redirect ke UMS → Keycloak`/ums/callback`GET`ums.callback`Handle callback setelah login`/ums/logout`GET`ums.logout`Logout + redirect ke UMS logout`/ums/refresh`POST`ums.refresh`Refresh token yang expired### Di halaman login kamu:

[](#di-halaman-login-kamu)

```
Login with SSO
```

### Setelah login berhasil:

[](#setelah-login-berhasil)

User di-redirect ke `/dashboard` (configurable di `UmsAuthController`). Data tersimpan di session:

```
session('ums_token');         // JWT access token
session('ums_refresh_token'); // Refresh token
session('ums_user');          // Decoded claims (array)
```

### Logout:

[](#logout)

```
Logout
```

---

Quick Start — API Bearer Token
------------------------------

[](#quick-start--api-bearer-token)

Untuk API endpoint yang di-consume frontend/mobile, gunakan Bearer token:

```
// routes/api.php
Route::middleware(['ums.auth'])->group(function () {
    Route::get('/profile', function () {
        return response()->json(ums_user()->toArray());
    });
});
```

Client mengirim request dengan header:

```
Authorization: Bearer

```

---

Middleware Reference
--------------------

[](#middleware-reference)

### `ums.auth` — Validasi Token

[](#umsauth--validasi-token)

Memastikan request memiliki Bearer token yang valid.

```
Route::middleware(['ums.auth'])->group(function () {
    // Semua route di sini butuh token valid
});
```

Response jika gagal:

```
{"success": false, "message": "Missing authorization token"}     // 401
{"success": false, "message": "Invalid or expired token"}        // 401
```

---

### `ums.permission:module,permission` — Cek Permission

[](#umspermissionmodulepermission--cek-permission)

Memastikan user punya permission tertentu di module tertentu.

```
// User harus punya permission 'read' di module 'inventory'
Route::middleware(['ums.auth', 'ums.permission:inventory,read'])->group(function () {
    Route::get('/items', [ItemController::class, 'index']);
});

// User harus punya permission 'write' di module 'inventory'
Route::middleware(['ums.auth', 'ums.permission:inventory,write'])->group(function () {
    Route::post('/items', [ItemController::class, 'store']);
});
```

Response jika gagal:

```
{"success": false, "message": "Permission denied: inventory.write"}  // 403
```

---

### `ums.role:module,role` — Cek Role

[](#umsrolemodulerole--cek-role)

Memastikan user punya role tertentu di module tertentu.

```
// User harus punya role 'admin' di module 'dashboard'
Route::middleware(['ums.auth', 'ums.role:dashboard,admin'])->group(function () {
    Route::get('/admin', [AdminController::class, 'index']);
});
```

Response jika gagal:

```
{"success": false, "message": "Role denied: dashboard.admin"}  // 403
```

---

### `ums.module:module` — Cek Akses Module

[](#umsmodulemodule--cek-akses-module)

Memastikan user punya akses ke module tertentu (tanpa cek permission/role spesifik).

```
// User harus punya akses ke module 'reports'
Route::middleware(['ums.auth', 'ums.module:reports'])->group(function () {
    Route::get('/reports', [ReportController::class, 'index']);
});
```

Response jika gagal:

```
{"success": false, "message": "Module access denied: reports"}  // 403
```

---

### Kombinasi Middleware

[](#kombinasi-middleware)

Middleware bisa di-chain:

```
// Harus login + punya module inventory + permission delete
Route::middleware(['ums.auth', 'ums.module:inventory', 'ums.permission:inventory,delete'])
    ->delete('/items/{id}', [ItemController::class, 'destroy']);
```

---

Helper Functions
----------------

[](#helper-functions)

Tersedia global helper yang bisa dipanggil dari mana saja:

```
// Get current user (dari request attribute atau session)
$user = ums_user();              // UmsClaims|null

// Cek permission
ums_can('inventory', 'read');    // bool
ums_can('inventory', 'delete');  // bool

// Cek role
ums_has_role('dashboard', 'admin');    // bool
ums_has_role('dashboard', 'viewer');   // bool

// Cek module access
ums_has_module('inventory');      // bool
ums_has_module('reports');        // bool

// Get raw JWT token dari session
ums_token();                     // string|null
```

---

UmsClaims Object
----------------

[](#umsclaims-object)

Object yang dikembalikan oleh `ums_user()`:

```
$user = ums_user();

// Properties
$user->userId;       // "d4c8546e-3166-4afe-a79f-70c073a7c1f7"
$user->email;        // "user@example.com"
$user->appId;        // "APP-10cd66bc"
$user->modules;      // array of module claims
$user->exp;          // 1782881536 (token expiry unix timestamp)
$user->iat;          // 1782877936 (token issued at)
$user->jti;          // "e2a4b879-ffd9-4a1a-9536-f0edcb1a9ebb"

// Methods
$user->hasPermission('inventory', 'read');     // bool
$user->hasRole('inventory', 'admin');          // bool
$user->hasModule('inventory');                 // bool
$user->getModuleRoles('inventory');            // ['admin', 'editor']
$user->getModulePermissions('inventory');      // ['read', 'write', 'delete']
$user->getModuleNames();                      // ['dashboard', 'inventory']
$user->isExpired();                           // bool
$user->toArray();                             // array
```

### Struktur `modules`:

[](#struktur-modules)

```
$user->modules = [
    [
        'module' => 'dashboard',
        'parent_module' => null,
        'roles' => ['admin'],
        'permissions' => ['create', 'delete', 'update', 'view'],
    ],
    [
        'module' => 'reports',
        'parent_module' => 'dashboard',
        'roles' => ['viewer'],
        'permissions' => ['read'],
    ],
];
```

---

Facade
------

[](#facade)

```
use Kodepik\UMS\Facades\UMS;

// Validate token secara manual
$claims = UMS::validateToken($jwtToken);

// Validate via UMS server (server-side, lebih aman)
$claims = UMS::validateTokenRemote($jwtToken);

// Refresh token
$result = UMS::refreshToken($refreshToken);
// $result = ['token' => '...', 'refresh_token' => '...']

// Get URLs
$loginUrl = UMS::getLoginUrl();
$logoutUrl = UMS::getLogoutUrl('https://myapp.com/login');

// Clear JWKS cache (setelah key rotation di UMS)
UMS::invalidateJwksCache();
```

---

Implementasi Lengkap (Step by Step)
-----------------------------------

[](#implementasi-lengkap-step-by-step)

### Step 1: Install & Config

[](#step-1-install--config)

```
composer require kodepik/ums-laravel
php artisan vendor:publish --tag=ums-config
```

Tambahkan ke `.env`:

```
UMS_BASE_URL=https://ums.yourserver.com
UMS_APP_ID=APP-xxxxx
UMS_CALLBACK_URL=http://localhost:8000/ums/callback
UMS_VERIFY_SSL=false
```

### Step 2: Buat Login Page

[](#step-2-buat-login-page)

```
{{-- resources/views/login.blade.php --}}
Login with UMS SSO
```

### Step 3: Buat Dashboard (Protected Page)

[](#step-3-buat-dashboard-protected-page)

```
// routes/web.php
Route::get('/dashboard', [DashboardController::class, 'index'])->name('dashboard');
```

```
// app/Http/Controllers/DashboardController.php