PHPackages                             liqwiz/laravel-sso-client - 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. liqwiz/laravel-sso-client

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

liqwiz/laravel-sso-client
=========================

Laravel SSO client package - turn any Laravel app into an SSO client using a Hub (OAuth2 IdP)

v1.0.0(3mo ago)15MITPHPPHP ^8.2

Since Feb 11Pushed 3mo agoCompare

[ Source](https://github.com/MuhammadAftabB/laravel-sso-client)[ Packagist](https://packagist.org/packages/liqwiz/laravel-sso-client)[ Docs](https://github.com/MuhammadAftabB/laravel-sso-client)[ RSS](/packages/liqwiz-laravel-sso-client/feed)WikiDiscussions main Synced 1mo ago

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

Laravel SSO Client
==================

[](#laravel-sso-client)

Laravel package that turns your app into an SSO client. Authenticate users against a central **SSO Hub** (OAuth2 IdP) and keep authorization (roles/permissions) local.

**Repository:** [github.com/MuhammadAftabB/laravel-sso-client](https://github.com/MuhammadAftabB/laravel-sso-client)

---

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

[](#requirements)

- PHP 8.2+
- Laravel 10, 11, or 12
- An SSO Hub that implements the [Hub API](#hub-api) (install token + register-client + userinfo)

---

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

[](#installation)

### 1. Install the package

[](#1-install-the-package)

**From Packagist (after the package is published):**

```
composer require liqwiz/laravel-sso-client
```

**From GitHub (development):**

```
composer require liqwiz/laravel-sso-client dev-main
```

Or add to `composer.json` and run `composer update`:

```
{
    "repositories": [
        {
            "type": "vcs",
            "url": "https://github.com/MuhammadAftabB/laravel-sso-client"
        }
    ],
    "require": {
        "liqwiz/laravel-sso-client": "dev-main"
    }
}
```

### 2. One-command setup

[](#2-one-command-setup)

Get a one-time **install token** from your Hub (e.g. Hub UI → SSO Install Tokens → Generate). Then run:

```
php artisan sso:install --token=YOUR_INSTALL_TOKEN --hub=https://hub.example.com
```

This will:

- Register this app with the Hub
- Write `SSO_HUB_URL`, `SSO_CLIENT_ID`, `SSO_CLIENT_SECRET`, `SSO_REDIRECT_URI` to `.env`
- Publish `config/sso-client.php` if not present

### 3. Optional: user columns for Hub linking

[](#3-optional-user-columns-for-hub-linking)

To link local users to Hub identities (recommended):

```
php artisan vendor:publish --tag=sso-client-migrations
php artisan migrate
```

Add to your User model `$fillable`: `hub_user_id`, `hub_email`, `hub_last_synced_at` (if you use the migration).

### 4. Add “Login with Hub” to your app

[](#4-add-login-with-hub-to-your-app)

In your login view:

```
Login with Hub
```

Protected routes: use `auth` middleware as usual. To **deny users with no local role** after SSO login, add the Access Gate middleware (see [Access Gate](#access-gate)).

---

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

[](#configuration)

### `config/sso-client.php`

[](#configsso-clientphp)

KeyEnvDescription`hub_url``SSO_HUB_URL`Hub base URL`client_id``SSO_CLIENT_ID`OAuth client ID from Hub`client_secret``SSO_CLIENT_SECRET`OAuth client secret`redirect_uri``SSO_REDIRECT_URI`Callback URL (e.g. `APP_URL/sso/callback`)`routes.prefix`-Route prefix (default: `sso`)`user.model`-Your User model class`gate.enabled`-Enable Access Gate (default: true)`gate.deny_if_no_role`-Deny if user has no role (default: true)`gate.required_roles`-Require at least one of these roles (Spatie)`gate.required_permissions`-Require at least one of these permissions (Spatie)`gate.custom_callback`-Custom callable for access check`gate.deny_message`-Message shown when access is denied`gate.deny_redirect`-Redirect path when access is denied (default: `/login`)### Access Gate

[](#access-gate)

After SSO login, the **Access Gate** can block users who have no local role/permission:

- **Default:** `deny_if_no_role` is `true` → user must have at least one role (Spatie) or a truthy `has_role` (fallback).
- With **Spatie Laravel Permission:** uses `hasAnyRole()` / `hasAnyPermission()` when `required_roles` or `required_permissions` are set.
- Without Spatie: uses a simple `has_role` attribute or config callback.

Apply the middleware to routes that should be protected by the gate:

```
Route::middleware(['auth', 'sso.access_gate'])->group(function () {
    Route::get('/dashboard', ...);
});
```

If the user fails the gate: they are logged out, session is invalidated, and they are redirected to login with an error message (configurable via `gate.deny_message`, `gate.deny_redirect`).

---

Hub API
-------

[](#hub-api)

The Hub must provide:

1. **POST /api/sso/install-tokens** (auth required) – returns a one-time install token.
2. **POST /api/sso/register-client** – body: `install_token`, `name`, `app_url`, `redirect_uri`; returns `client_id`, `client_secret`.
3. **GET /api/sso/userinfo** (OAuth2 Bearer) – returns `sub`, `email`, `name` (and optionally `avatar_url`, `updated_at`).

OAuth2: Authorization Code grant; authorize at `{hub}/oauth/authorize`, token at `{hub}/oauth/token`.

---

Troubleshooting
---------------

[](#troubleshooting)

### “SSO is not configured”

[](#sso-is-not-configured)

- Run `php artisan sso:install --token=... --hub=...` and ensure `.env` has `SSO_HUB_URL`, `SSO_CLIENT_ID`, `SSO_CLIENT_SECRET`, `SSO_REDIRECT_URI`.
- Run `php artisan config:clear`.

### Redirect URI mismatch

[](#redirect-uri-mismatch)

- `SSO_REDIRECT_URI` must be exactly the callback URL the Hub uses (e.g. `https://yourapp.com/sso/callback`).
- In production the Hub typically requires `redirect_uri` to use **https** and to match the app’s origin.

### Invalid state / Session lost

[](#invalid-state--session-lost)

- If the Hub and client run on the **same domain** (e.g. different ports on localhost), use a **unique session cookie name** in the client’s `.env` (e.g. `SESSION_COOKIE=my_client_session`) so the Hub does not overwrite the client’s session.

### invalid\_client / Token exchange failed

[](#invalid_client--token-exchange-failed)

- Confirm `SSO_CLIENT_ID` and `SSO_CLIENT_SECRET` match the Hub’s registered client.
- Ensure the client is **active** on the Hub (Registered Clients page).

### User not found / Could not resolve local user

[](#user-not-found--could-not-resolve-local-user)

- The Hub userinfo must include `sub` or `email`. The package resolves by `hub_user_id` then `email`, then creates a user if not found.
- If you use the migration, ensure `hub_user_id` / `hub_email` are in the User model’s `$fillable`.

### Access denied after login (no role)

[](#access-denied-after-login-no-role)

- By default, users with **no local role** are denied. Assign a role (e.g. with Spatie) or set `gate.deny_if_no_role` to `false`, or use `gate.required_roles` / `gate.custom_callback`.

---

License
-------

[](#license)

MIT. See the [repository](https://github.com/MuhammadAftabB/laravel-sso-client) for details.

###  Health Score

37

—

LowBetter than 83% of packages

Maintenance82

Actively maintained with recent releases

Popularity6

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity46

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

96d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/58737b3d533b504a382d4cc5dea2d23839fd122ec4c109588a0c107b2d9a2946?d=identicon)[MuhammadAftabB](/maintainers/MuhammadAftabB)

---

Top Contributors

[![MuhammadAftabB](https://avatars.githubusercontent.com/u/89566665?v=4)](https://github.com/MuhammadAftabB "MuhammadAftabB (7 commits)")

---

Tags

laravelSSOoauthsingle sign onpassport

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/liqwiz-laravel-sso-client/health.svg)

```
[![Health](https://phpackages.com/badges/liqwiz-laravel-sso-client/health.svg)](https://phpackages.com/packages/liqwiz-laravel-sso-client)
```

###  Alternatives

[roots/acorn

Framework for Roots WordPress projects built with Laravel components.

9682.1M97](/packages/roots-acorn)[laragear/two-factor

On-premises 2FA Authentication for out-of-the-box.

339785.3k8](/packages/laragear-two-factor)[aedart/athenaeum

Athenaeum is a mono repository; a collection of various PHP packages

245.2k](/packages/aedart-athenaeum)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)