Download the PHP package putheakhem/fsa-sso without Composer

⚠️ DISCLAIMER: This is an unofficial community package and is not affiliated with, endorsed by, or supported by the official FSA SSO Platform or the Non-Bank Financial Services Authority (FSA). This package is maintained independently. For official support, please contact the FSA SSO Platform directly.

A Laravel package for FSA SSO authentication with support for JWT verification via JWKS, user provisioning, and optional web login flow.

📋 What This Package Does

• Builds the FSA login URL: /auth/login?client_code=...
• Verifies FSA JWT using JWKS public keys (Ed25519 / EdDSA — no shared secret needed)
• Validates token claims: iss, aud, exp, client_code
• Upserts local users by stable FSA sub claim
• Proxies optional introspect and revoke calls to FSA API
• Registers a fsa-sso.auth middleware for per-request bearer token protection
• Registers an opt-in fsa-sso-api auth driver for API bearer authentication
• Registers package-managed web routes for browser login redirect and callback
• Keeps host-app auth:api / Laravel Passport separate from package-owned auth:fsa-sso-api

⚙️ Requirements

• PHP 8.2+
• Laravel 10, 11, 12, or 13
• ext-sodium enabled (for Ed25519 verification)

📦 Installation

The service provider is auto-discovered via Laravel's package discovery.

Publish Config and Migrations

If your app has many packages and tag-based publish does not detect resources, use provider-scoped commands:

The package also registers conventional config and migrations tags for compatibility.

🚀 Choose Your Integration Path

This package supports two main integration styles. Start with the one you actually need:

Option A — Web Login for Browser Users

Use this when users click a "Sign in with FSA SSO" button in your Laravel web app and should end up logged into your local web guard session.

You need:

• published config
• published migrations
• FSA_SSO_CLIENT_CODE
• FSA_SSO_ENABLE_WEB_ROUTES=true
• callback URL registered in FSA admin

Typical outcome:

• browser redirects to FSA SSO
• FSA redirects back to your app callback
• package verifies token, provisions the user, logs them in, and redirects

Jump to:

• Web Login Quick Start
• Integration Guide (Laravel + Inertia)

Option B — API Authentication for Incoming Bearer Tokens

Use this when another FSA-connected system calls your Laravel API with an existing FSA SSO bearer token and your routes should authenticate with auth:fsa-sso-api.

You need:

• published config
• published migrations
• FSA_SSO_API_AUTH_ENABLED=true
• JWKS / issuer / audience values configured
• protected routes using auth:fsa-sso-api

Typical outcome:

• client sends Authorization: Bearer <token>
• package verifies the token in jwt mode or introspects it in introspection mode
• your route receives an authenticated local user and request attributes

Jump to:

• API Auth Quick Start
• API Bearer Authentication

Optional Add-On — Shared Token Storage

Enable this only if your app needs to store the verified FSA token for later trusted downstream calls.

• set FSA_SSO_TOKEN_STORAGE_ENABLED=true
• publish the latest package migrations
• migrate your app so the token storage columns exist

If you do not need downstream token reuse, leave token storage disabled.

🌐 .env Configuration

Add these to your .env file:

✅ FSA_SSO_CLIENT_CODE must exactly match the client code registered in the FSA SSO admin portal.

✅ Use single backslashes for FSA_SSO_USER_MODEL in .env (example: App\Models\User).

🧭 Web Login Quick Start

Minimum setup for browser-based login:

1. Install the package.
2. Publish config and migrations.

3. Set these env values:

4. Register the exact callback URL in FSA admin:

• https://your-app.com/sso/callback-success

5. Add a login link or button to the package route:

That is enough for the package-managed web flow. The package will redirect to FSA, verify the callback token, provision the user, log them into the configured web guard, and redirect them to your intended route.

🔌 API Auth Quick Start

Minimum setup for protecting API routes that receive FSA SSO bearer tokens:

1. Install the package.
2. Publish config and migrations.

3. Set these env values:

4. Protect routes with the package guard:

5. Add optional client-code restriction when needed:

That is enough for the package to validate incoming bearer tokens and resolve a local user for your API routes.

🗄️ User Model — Fillable & Migration

The published migration adds these columns to your users table:

Add these columns to your User model's $fillable:

If you enable shared token storage, publish the latest package migration and migrate so the default storage columns are available:

The default migration adds:

If you want different column names, create your own migration and set the token_storage.*_column config values to match.

Migration Ownership Note

This package auto-loads package migrations until matching published copies exist in the host application's database/migrations directory.

• If you publish the package migrations, the published app copies become the migrations your app owns.
• Do not keep two different migrations that add the same FSA SSO columns with different filenames.
• If you customize the schema yourself, keep one clear owner for each column so rollback history stays consistent.

Design A: Shared FSA token for trusted downstream resource access

This package now supports an optional Design A integration pattern where a portal such as DPS stores the verified FSA SSO token and later reuses that same token when calling another trusted resource server such as Compendium.

• This is a trusted downstream resource-access pattern, not a token exchange flow.
• client_code still matters. Each downstream service can continue validating trusted callers through the verified FSA token claims it already receives.
• Authentication comes from FSA SSO, but authorization remains local to each portal or service.
• The package does not automatically forward tokens anywhere. It only offers opt-in storage and retrieval so the host application decides when a downstream call is appropriate.
• The feature is disabled by default and only activates when FSA_SSO_TOKEN_STORAGE_ENABLED=true.

How it works

1. User authenticates with FSA SSO and the package verifies the returned JWT via JWKS.
2. The package keeps user identity mapping based on sub, exactly as before.
3. If token_storage.enabled is true, the package stores the raw token plus metadata on the user record.
4. Later, the host app can retrieve the stored token and attach it to an outbound request to a trusted downstream portal or service.

Retrieving the stored token

You can retrieve the current authenticated user token:

Or retrieve it for a specific user model:

Token storage config

When encrypted is true, the package uses Laravel encryption before persisting the token. That keeps storage secure even if your User model does not define an encrypted cast for the token column.

API Bearer Authentication

FSA SSO authenticates the user's identity. The consuming Laravel application still owns authorization, roles, policies, and permissions.

The package only owns the fsa-sso-api guard and related middleware. It does not replace or modify a host application's api guard, Laravel Passport configuration, or internal auth:api routes.

Use the new opt-in guard when another FSA system calls your Laravel API with an existing FSA SSO JWT:

The package validates the bearer token through JWKS using EdDSA, resolves the local user from sub, and lets your application keep full control over authorization.

Environment

Auth Modes

jwt is the default mode. It preserves the current behavior:

• bearer token is decoded locally
• EdDSA / JWKS verification is enforced
• configured claims are validated before local user resolution

introspection is opt-in. Use it when the upstream token is opaque or when the upstream claim shape is not a locally verifiable JWT:

• bearer token is accepted as-is
• the package calls the configured introspection endpoint
• authentication succeeds only when active=true
• the introspection payload is mapped into FsaSsoUserData and resolved through the same local user flow

For older installs, FSA_SSO_USE_INTROSPECTION=true still maps to introspection mode when FSA_SSO_API_AUTH_MODE is not set.

Debug Logging

When the application is not running in production, auth rejections are logged with a structured reason and a SHA-256 token hash. Production logging stays off unless you opt in:

The package never logs the raw bearer token. Typical reasons include malformed token, unsupported algorithm, JWKS fetch failure, key parse failure, issuer mismatch, audience mismatch, missing required claim, inactive token, and user resolution failure.

Claim Mapping

Claim names are configurable per auth mode consumer. The defaults match the current package behavior exactly:

This is useful when introspection responses or partner-issued payloads use different field names while you still want the guard to populate:

• fsa_sso_user
• fsa_sso_client_code
• fsa_sso_jti
• fsa_sso_token_hash

Guard Registration

The package registers the fsa-sso-api driver. If you prefer to declare the guard explicitly in your application, use:

Route Examples

Sensitive endpoints can also confirm active=true through introspection:

The optional fsa-sso.introspect middleware remains compatible in both auth modes. In jwt mode it adds an active-token check after local verification. In introspection mode it reuses the same introspection endpoint and cache strategy as the guard.

Migration Example

🛣️ Package API Endpoints

The package auto-registers these routes under the configured prefix (auth/sso by default):

The package also auto-registers web routes (enabled by default):

🧪 Integration Guide (Laravel + Inertia)

This package now handles the common web flow internally.

Step 1 — Configure Callback URL in FSA Admin

Register the callback URL in FSA SSO admin:

• https://your-app.com/sso/callback-success

No custom app controller or app-level web route is required when FSA_SSO_ENABLE_WEB_ROUTES=true.

Using Different Callback URI Per Application

Each application can use its own callback path and route names while sharing the same package.

Example for another app:

Then register this exact URL in FSA admin for that application:

• https://other-app.com/auth/fsa/callback

Notes:

• Callback URL must match exactly between your app env config and FSA admin configuration.
• Keep a distinct FSA_SSO_CLIENT_CODE per application if required by your FSA SSO setup.

Step 2 — Confirm the Login Page Is Rendered by Inertia

Step 3 — Add the "Sign in with FSA SSO" Button (React / Inertia)

Use the generated Wayfinder route helper from @/routes. Call .url() when assigning it to a native <a href>.

🔄 Complete Authentication Flow

🛡️ Protecting Routes with the Middleware

Use the fsa-sso.auth middleware to protect API routes that require a valid FSA SSO bearer token:

The middleware:

• Reads the bearer token from the Authorization header
• Verifies the JWT via JWKS (EdDSA)
• Validates iss, aud, exp, and client_code
• Attaches claims to $request->attributes->get('fsa_sso_claims')
• Returns 401 for invalid or missing tokens

🧩 Using the Facade Directly

🔐 Security

• No shared secret required — JWT verification uses EdDSA asymmetric cryptography via JWKS
• JWKS is cached (default 10 minutes) to avoid hammering the FSA endpoint on every request
• Token verification is local — no sidecar or additional service needed
• Session is regenerated after login to prevent session fixation attacks
• Expected algorithm is EdDSA (Ed25519 curve) — RS256 and HS256 tokens are rejected

⚙️ Configuration Reference

All options are in config/fsa-sso.php after publishing:

Backward Compatibility

• Existing installs keep local EdDSA + JWKS verification by default.
• Existing auth:fsa-sso-api, fsa-sso.client-code, and fsa-sso.introspect middleware usage remains valid.
• Existing host-app Passport or auth:api behavior is not changed.
• FSA_SSO_USE_INTROSPECTION is still honored as a fallback for older configurations, but FSA_SSO_API_AUTH_MODE is the preferred setting going forward.

⚠️ Common Mistakes

🧪 Testing

The package includes standalone tests using Pest + Orchestra Testbench.

Run inside the package directory:

Support Me

If you find this package useful, consider supporting my work:

• Buy me a coffee

📄 License

The MIT License (MIT). Please see License File for more information.

Built with ❤️ by Puthea Khem