uitm/warga-auth-laravel

Laravel JWT SSO Library untuk sistem UiTM

1.0.2 2025-09-28 04:51 UTC

Requires

• php: ^7.4|^8.0|^8.1|^8.2|^8.3|^8.4
• firebase/php-jwt: ^5.5|^6.0
• illuminate/http: ^6.0|^7.0|^8.0|^9.0|^10.0|^11.0
• illuminate/support: ^6.0|^7.0|^8.0|^9.0|^10.0|^11.0

Requires (Dev)

• orchestra/testbench: ^4.0|^5.0|^6.0|^7.0|^8.0|^9.0
• phpunit/phpunit: ^8.0|^9.0|^10.0

MIT

• WargaAuth Team

README

Library Laravel yang simple untuk JWT SSO authentication. Validate JWT token dan redirect mengikut nilai dalam payload.

Features

✅ JWT Token Validation - Validate RS256 JWT tokens dengan signature verification
✅ Smart Redirect - Redirect mengikut field redirect dalam JWT payload, default ke home
✅ Error Handling - Redirect ke login page dengan error message jika gagal
✅ Minimal Setup - Hanya perlu config public key untuk mula guna
✅ Wide Compatibility - Support PHP 7.4+ dan Laravel 6+

How It Works

1. GET /sso/login?token=... - Validate JWT token menggunakan RS256
2. If valid - Redirect mengikut field redirect dalam payload (atau / jika tidak ada)
3. If invalid - Redirect ke login page (/login) dengan error message

JWT Payload Structure

{
  "type_user": "staf",               // Required: staf, student, other
  "iduitm": "123456",                // Required: UiTM ID
  "email": "[e-mail]",       // Required: Valid email
  "redirect": "/dashboard",          // Optional: Custom redirect path
  "iat": 1516239022,                 // Required: Issued at timestamp
  "exp": 1516239082                  // Required: Expiry timestamp
}

Field Descriptions

Field	Required	Type	Description
type_user	✅	string	User type: staf, student, atau other
iduitm	✅	string	UiTM ID (tidak boleh kosong)
email	✅	string	Email address dengan format yang valid
redirect	❌	string	Custom redirect path selepas login. Default: / jika tidak ada
iat	✅	number	Issued at time (Unix timestamp)
exp	✅	number	Expiry time (Unix timestamp)

Redirect Behavior

Dengan field redirect:

{
  "redirect": "/dashboard"
}

➜ User akan redirect ke /dashboard selepas validation berjaya

Tanpa field redirect:

{
  // no redirect field
}

➜ User akan redirect ke / (home page) selepas validation berjaya

Quick Start

1. Install Package

composer require uitm/warga-auth-laravel

2. Publish Files

# Option 1: Publish all files at once
php artisan vendor:publish --provider="Uitm\WargaAuthLaravel\JwtSsoServiceProvider"

3. Update SsoController

Update app/Http/Controllers/SsoController.php to add your authentication logic:

public function login(Request $request)
{
    try {
        // Get token from request
        $token = $request->query('token');

        if (!$token) {
            throw new InvalidTokenException('Token parameter is required');
        }

        // Validate and decode JWT token
        $payload = $this->jwtService->validateToken($token);

        // 🔴 UPDATE THIS PART: Add your authentication logic here
        // Example: Find or create user based on payload
        $user = \App\Models\User::where('email', $payload['email'])->first();
        if (!$user) {
            // Create user if not exists
            $user = \App\Models\User::create([
                'name' => $payload['iduitm'], // or any other field
                'email' => $payload['email'],
                'type_user' => $payload['type_user'],
                // add other fields as needed
            ]);
        }
        
        // Login the user
        \Auth::login($user);

        // Check if redirect is specified in payload
        if (isset($payload['redirect']) && !empty($payload['redirect'])) {
            $redirectPath = $payload['redirect'];
        } else {
            $redirectPath = '/dashboard'; // or your default redirect
        }

        // Redirect to specified path or home
        return redirect($redirectPath);

    } catch (InvalidTokenException | InvalidUserTypeException | MissingPayloadException $e) {
        \Log::warning('SSO login failed', [
            'error' => $e->getMessage(),
            'token' => substr($token ?? 'null', 0, 50) . '...'
        ]);

        return redirect('/login')->withErrors(['sso' => 'Login gagal: ' . $e->getMessage()]);

    } catch (\Exception $e) {
        return redirect('/login')->withErrors(['sso' => 'Terdapat masalah teknikal. Sila cuba lagi.']);
    }
}

4. Register Service Provider

Add to config/app.php:

'providers' => [
    // ... other providers
    Uitm\WargaAuthLaravel\JwtSsoServiceProvider::class,
],

5. Set Environment

# Option 1: File-based keys (recommended for production)
JWT_SSO_PUBLIC_KEY_PATH=/path/to/your/public.key

# Option 2: Direct key content in environment (for development/testing)
JWT_SSO_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"

# Algorithm settings
JWT_SSO_ALGORITHM=RS256
JWT_SSO_ALLOWED_ALGOS=RS256

6. Use SSO

https://yourapp.com/sso/login?token=YOUR_JWT_TOKEN

Note: This method gives you full control but requires manual file management.

Example Usage

Manual JWT Creation (External)

Token creation should be done by your SSO provider using the private key. This library only validates tokens.

Example of expected JWT payload structure:

{
  "type_user": "staf",
  "iduitm": "123456", 
  "email": "[e-mail]",
  "redirect": "/dashboard",
  "iat": 1516239022,
  "exp": 1516239082
}

Testing SSO Login

# Test dengan valid token
curl "https://yourapp.com/sso/login?token=VALID_JWT_TOKEN"
# Expected: Redirect mengikut payload atau ke home

# Test dengan invalid token  
curl "https://yourapp.com/sso/login?token=INVALID_TOKEN"
# Expected: Redirect ke /login dengan error message

Configuration

File config: config/jwt-sso.php

return [
    // Path ke public key untuk JWT verification (fallback)
    'public_key_path' => env('JWT_SSO_PUBLIC_KEY_PATH', storage_path('keys/public.key')),
    
    // Public key content directly from environment (takes precedence)
    'public_key' => env('JWT_SSO_PUBLIC_KEY'),
    
    // User types yang dibenarkan
    'allowed_user_types' => [
        'staf',
        'student', 
        'other'
    ],
    
    // Token settings
    'token' => [
        'algorithm' => env('JWT_SSO_ALGORITHM', 'RS256'),
        'allowed_algos' => explode(',', env('JWT_SSO_ALLOWED_ALGOS', 'RS256')),
        'leeway' => 60, // seconds tolerance for clock skew
    ]
];

Routes

Method	URL	Description
GET	/sso/login	Validate JWT token dan redirect

Error Handling

Error Type	Redirect To	Error Message
Missing token	/login	Token parameter is required
Expired token	/login	Login gagal: Token has expired
Invalid signature	/login	Login gagal: Token signature is invalid
Invalid user type	/login	Login gagal: Invalid user type
Invalid email	/login	Login gagal: Invalid email format
System error	/login	Terdapat masalah teknikal. Sila cuba lagi.

Compatibility

Component	Version Support
PHP	7.4, 8.0, 8.1, 8.2, 8.3
Laravel	6.x, 7.x, 8.x, 9.x, 10.x, 11.x
firebase/php-jwt	5.5+ dan 6.x (auto-detected)
JWT Algorithms	Configurable via JWT_SSO_ALGORITHM env (default: RS256)

Security Features

• Configurable Algorithm - JWT algorithm boleh configure via environment variable
• RS256 Signature Verification - Menggunakan public key untuk verify token dari SSO provider
• Token Expiry Check - Memastikan token belum expired
• Payload Validation - Validate semua required fields ada
• Email Format Validation - Check format email yang valid
• User Type Validation - Pastikan user type dalam allowed list
• Safe Redirect - Hanya redirect ke path yang diberikan dalam JWT payload
• No Token Creation - Library ini hanya untuk validation, bukan untuk create token

Test Cases

Test dengan Redirect Field

# Token dengan redirect ke '/dashboard'
curl "https://yourapp.com/sso/login?token=TOKEN_WITH_REDIRECT_DASHBOARD"
# Expected: Redirect ke '/dashboard'

# Token dengan redirect ke '/admin' 
curl "https://yourapp.com/sso/login?token=TOKEN_WITH_REDIRECT_ADMIN"
# Expected: Redirect ke '/admin'

Test tanpa Redirect Field

# Token tanpa redirect field
curl "https://yourapp.com/sso/login?token=TOKEN_WITHOUT_REDIRECT"
# Expected: Redirect ke '/' (home)

Test Error Cases

# Token expired
curl "https://yourapp.com/sso/login?token=EXPIRED_TOKEN"
# Expected: Redirect ke '/login' dengan error message

# Invalid signature
curl "https://yourapp.com/sso/login?token=INVALID_SIGNATURE_TOKEN"
# Expected: Redirect ke '/login' dengan error message

# Missing token parameter
curl "https://yourapp.com/sso/login"
# Expected: Redirect ke '/login' dengan error message

Installation Requirements

• PHP 7.4+ - Minimum PHP version (compatible dengan PHP 8.x)
• Laravel 6.0+ - Minimum Laravel version (compatible hingga Laravel 11)
• Composer - For package management
• OpenSSL extension - Required untuk RSA operations
• firebase/php-jwt - JWT library (auto-installed via composer)

Best Practices

1. HTTPS Only - Always guna HTTPS dalam production
2. Token Expiry - Set expiry time yang sesuai pada SSO provider (1 hour recommended)
3. Safe Redirects - Validate redirect paths untuk avoid open redirects
4. Key Security - Keep public keys secure dan validate dari trusted SSO provider
5. Algorithm Configuration - Configure JWT algorithm via environment variables
6. Rate Limiting - Implement rate limiting pada SSO endpoint
7. SSO Provider Integration - Pastikan SSO provider menggunakan private key yang sepadan dengan public key anda

License

MIT License

Support

Untuk issues atau questions, sila buka GitHub issue.