PHPackages                             deroy2112/laravel-synology-sso - 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. deroy2112/laravel-synology-sso

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

deroy2112/laravel-synology-sso
==============================

Laravel Socialite driver for Synology SSO (OIDC) with PKCE S256, ID token verification, and group-to-role mapping

v1.1.0(6mo ago)033MITPHPPHP ^8.2|^8.3|^8.4CI passing

Since Nov 2Pushed 6mo agoCompare

[ Source](https://github.com/Deroy2112/laravel-synology-sso)[ Packagist](https://packagist.org/packages/deroy2112/laravel-synology-sso)[ RSS](/packages/deroy2112-laravel-synology-sso/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (4)Dependencies (8)Versions (6)Used By (0)

Laravel Synology SSO
====================

[](#laravel-synology-sso)

[![Latest Version on Packagist](https://camo.githubusercontent.com/dd448a125d56931cc6bbab9624c36dcd79ddfb7ecbfac9629993801d48f968b9/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6465726f79323131322f6c61726176656c2d73796e6f6c6f67792d73736f2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/deroy2112/laravel-synology-sso)[![Total Downloads](https://camo.githubusercontent.com/9cba0a15af2a66939aaa9d73ab8e13ad79c02f646ed90e5af73dd9e6f01b1742/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6465726f79323131322f6c61726176656c2d73796e6f6c6f67792d73736f2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/deroy2112/laravel-synology-sso)[![License](https://camo.githubusercontent.com/f6b8a54e0c8c5a3386fa0007a10b4956670cdec3c5f30d25d19d9bbc6a05133f/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f6465726f79323131322f6c61726176656c2d73796e6f6c6f67792d73736f2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/deroy2112/laravel-synology-sso)

A Laravel Socialite driver for **Synology SSO Server** with full OIDC support, PKCE S256, ID token verification, and group-to-role mapping.

Features
--------

[](#features)

- ✅ **PKCE S256** - Secure authorization with Proof Key for Code Exchange (RFC 7636)
- ✅ **ID Token Verification** - RS256 signature validation using JWKS
- ✅ **OIDC Auto-Discovery** - Automatic endpoint configuration
- ✅ **Group-to-Role Mapping** - Map Synology groups to Laravel roles
- ✅ **JIT User Provisioning** - Auto-create users on first login
- ✅ **Laravel 11 & 12 Support** - Compatible with latest Laravel versions
- ✅ **Security Best Practices** - State parameter, SSL verification, secure token storage

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

[](#requirements)

- PHP 8.2, 8.3, or 8.4
- Laravel 11.x or 12.x
- Synology DSM with SSO Server package installed
- Valid SSL certificate (or self-signed for development)

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

[](#installation)

### Step 1: Install Package

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

```
composer require deroy2112/laravel-synology-sso
```

### Step 2: Run Install Command

[](#step-2-run-install-command)

```
php artisan synology-sso:install
```

This will:

- Publish configuration file to `config/synology-sso.php`
- Optionally publish documentation to `docs/synology-sso/`
- Display environment variable template

### Step 3: Configure Environment

[](#step-3-configure-environment)

#### Finding Your Synology SSO Host URL

[](#finding-your-synology-sso-host-url)

To get the correct `SYNOLOGY_SSO_HOST` value:

1. Open **DSM** > **SSO Server** > **Services** > **OIDC**
2. Locate the **Well-Known URL** field
3. Copy the URL shown (e.g., `https://sso.example.com/webman/sso/.well-known/openid-configuration`)
4. **Remove** `/.well-known/openid-configuration` from the end
5. Use the remaining URL as your `SYNOLOGY_SSO_HOST`

**Example:**

- Well-Known URL: `https://sso.example.com/webman/sso/.well-known/openid-configuration`
- SYNOLOGY\_SSO\_HOST: `https://sso.example.com/webman/sso`

#### Environment Variables

[](#environment-variables)

Add to your `.env` file:

```
SYNOLOGY_SSO_HOST=https://sso.example.com/webman/sso
SYNOLOGY_SSO_CLIENT_ID=your-client-id
SYNOLOGY_SSO_CLIENT_SECRET=your-client-secret
SYNOLOGY_SSO_REDIRECT_URI="${APP_URL}/auth/synology/callback"
```

Quick Start
-----------

[](#quick-start)

### 1. Configure Synology SSO Server

[](#1-configure-synology-sso-server)

1. Open **DSM** > **SSO Server**
2. Go to **Application Portal** > **Create**
3. Configure OAuth 2.0 Client:
    - **Name:** Your Laravel App
    - **Redirect URIs:** `https://your-app.com/auth/synology/callback`
    - **Scopes:** `openid`, `email`, `groups`
4. Copy **Client ID** and **Client Secret**

### 2. Add Routes

[](#2-add-routes)

Add to `routes/web.php`:

```
use Laravel\Socialite\Facades\Socialite;

Route::get('/auth/synology', function () {
    return Socialite::driver('synology')->redirect();
});

Route::get('/auth/synology/callback', function () {
    $user = Socialite::driver('synology')->user();

    // $user->id          - Synology user ID (sub claim)
    // $user->name        - User's display name
    // $user->email       - User's email
    // $user->groups      - Array of groups:
    //                      Without Domain/LDAP: ["administrators", "users"]
    //                      With Domain/LDAP:    ["administrators@example.com", "users@example.com"]

    // Find or create user
    $localUser = User::updateOrCreate(
        ['email' => $user->email],
        ['name' => $user->name]
    );

    Auth::login($localUser);

    return redirect('/dashboard');
});
```

### 3. Add Login Button

[](#3-add-login-button)

```

    Login with Synology SSO

```

Group-to-Role Mapping
---------------------

[](#group-to-role-mapping)

### Configuration

[](#configuration)

Edit `config/synology-sso.php`:

```
'group_role_mappings' => [
    // Without Domain/LDAP (Standard Synology)
    'administrators' => 'admin',
    'users' => 'user',

    // With Domain/LDAP (if configured)
    'administrators@example.com' => 'admin',
    'users@example.com' => 'user',

    // Multiple roles example
    'developers' => ['developer', 'user'],
],

'default_role' => 'user', // Or null to deny unmapped users
```

**Note:** Group format depends on LDAP configuration:

- **Without Domain/LDAP**: `administrators`, `users`
- **With Domain/LDAP**: `administrators@domain.com`, `users@domain.com`

### Usage in Controller

[](#usage-in-controller)

```
use Deroy2112\LaravelSynologySso\GroupRoleMapper;

Route::get('/auth/synology/callback', function (GroupRoleMapper $mapper) {
    $ssoUser = Socialite::driver('synology')->user();

    // Check access
    if (!$mapper->hasAccess($ssoUser->groups)) {
        abort(403, 'Access denied');
    }

    // Get roles
    $roles = $mapper->mapGroupsToRoles($ssoUser->groups);
    // Returns: ['admin', 'user']

    // Get primary role
    $primaryRole = $mapper->getPrimaryRole($ssoUser->groups);
    // Returns: 'admin' (based on role_priority config)

    // Create/update user
    $user = User::updateOrCreate(
        ['email' => $ssoUser->email],
        ['name' => $ssoUser->name]
    );

    // Assign roles (e.g., with spatie/laravel-permission)
    $user->syncRoles($roles);

    Auth::login($user);

    return redirect('/dashboard');
});
```

Extending Token Lifetime
------------------------

[](#extending-token-lifetime)

**Problem:** Synology SSO tokens expire after 180 seconds (3 minutes) by default.

**Solution:** Use DSM Task Scheduler to extend token lifetime.

### Automated Script (Recommended)

[](#automated-script-recommended)

1. Open **DSM** > **Control Panel** > **Task Scheduler**
2. Create > **Scheduled Task** > **User-defined script**
3. Configure:
    - **User:** root
    - **Schedule:** Run on the following date (one-time)
4. **Script:**

```
#!/bin/bash

# Check if SSO Server is installed
if ! synopkg list | grep -q "SSOServer"; then
    echo "Error: SSO Server not installed"
    exit 1
fi

# Backup original config
cp /var/packages/SSOServer/etc/oidc-config.json \
   /var/packages/SSOServer/etc/oidc-config.json.bak

# Extend token lifetime to 30 minutes (1800 seconds)
sed -i 's/"ExpAccessToken":180/"ExpAccessToken":1800/g' \
    /var/packages/SSOServer/etc/oidc-config.json
sed -i 's/"ExpIdToken":180/"ExpIdToken":1800/g' \
    /var/packages/SSOServer/etc/oidc-config.json
sed -i 's/"ExpAuthCode":180/"ExpAuthCode":1800/g' \
    /var/packages/SSOServer/etc/oidc-config.json

# Restart SSO Server to apply changes
synopkg restart SSOServer

echo "Token lifetime extended to 1800 seconds (30 minutes)"
```

5. Click **OK** and **Run** the task

### Verification

[](#verification)

Check the config file:

```
cat /var/packages/SSOServer/etc/oidc-config.json
```

Expected output:

```
{
  "BaseURL": "https://sso.example.com",
  "Enabled": true,
  "ExpAccessToken": 1800,
  "ExpAuthCode": 1800,
  "ExpIdToken": 1800
}
```

**Note:** Changes persist across reboots but may be reset by DSM updates. Re-run the script after updates.

Configuration Options
---------------------

[](#configuration-options)

### Environment Variables

[](#environment-variables-1)

VariableRequiredDefaultDescription`SYNOLOGY_SSO_HOST`Yes-Synology SSO Server URL`SYNOLOGY_SSO_CLIENT_ID`Yes-OAuth Client ID`SYNOLOGY_SSO_CLIENT_SECRET`Yes-OAuth Client Secret`SYNOLOGY_SSO_REDIRECT_URI`Yes`${APP_URL}/auth/synology/callback`OAuth redirect URI`SYNOLOGY_SSO_AUTO_CREATE_USERS`No`true`JIT user provisioning`SYNOLOGY_SSO_DEFAULT_ROLE`No`user`Default role (or `null`)`SYNOLOGY_SSO_VERIFY_SSL`No`true`SSL verification`SYNOLOGY_SSO_CACHE_DURATION`No`3600`OIDC/JWKS cache (seconds)### Group Configuration

[](#group-configuration)

```
// config/synology-sso.php

'allowed_groups' => [
    // Without Domain/LDAP
    'administrators',
    'users',

    // With Domain/LDAP (optional)
    'administrators@example.com',
    'users@example.com',
], // Empty = allow all

'role_priority' => [
    'admin',      // Highest priority
    'moderator',
    'user',       // Lowest priority
],
```

Advanced Usage
--------------

[](#advanced-usage)

### Custom User Creation

[](#custom-user-creation)

```
Route::get('/auth/synology/callback', function () {
    $ssoUser = Socialite::driver('synology')->user();

    $user = User::firstOrNew(['email' => $ssoUser->email]);

    if (!$user->exists) {
        // Custom logic for new users
        $user->fill([
            'name' => $ssoUser->name,
            'synology_id' => $ssoUser->id,
            'email_verified_at' => now(), // Trust SSO email
        ])->save();
    }

    Auth::login($user);

    return redirect('/dashboard');
});
```

### With Rate Limiting

[](#with-rate-limiting)

```
Route::middleware(['throttle:10,1'])->group(function () {
    Route::get('/auth/synology', [SsoController::class, 'redirect']);
    Route::get('/auth/synology/callback', [SsoController::class, 'callback']);
});
```

### Logout

[](#logout)

```
Route::post('/logout', function () {
    Auth::logout();
    request()->session()->invalidate();
    request()->session()->regenerateToken();

    return redirect('/');
});
```

Documentation
-------------

[](#documentation)

- **[Configuration Guide](docs/CONFIGURATION.md)** - Complete setup instructions
- **[Synology Quirks](docs/SYNOLOGY_QUIRKS.md)** - Known issues and workarounds
- **[Developer Reference](docs/DEVELOPER_REFERENCE.md)** - Technical deep-dive (OIDC endpoints, PKCE, ID token verification)
- **[API Response Examples](docs/API_RESPONSES.md)** - Real-world response examples from Synology SSO
- **[Security Checklist](docs/SECURITY_CHECKLIST.md)** - Best practices

Testing
-------

[](#testing)

```
composer install
vendor/bin/phpunit
```

Security
--------

[](#security)

### Best Practices

[](#best-practices)

- ✅ Always use HTTPS in production
- ✅ Enable SSL verification (`SYNOLOGY_SSO_VERIFY_SSL=true`)
- ✅ Rotate client secrets regularly
- ✅ Use group-based authorization
- ✅ Enable rate limiting on auth routes
- ✅ Store tokens server-side only (sessions)

### Reporting Vulnerabilities

[](#reporting-vulnerabilities)

**DO NOT** open public issues for security vulnerabilities.

Email: \[Your security contact - replace this\]

Synology SSO Limitations
------------------------

[](#synology-sso-limitations)

FeatureStatusWorkaroundRefresh Tokens❌ Not supportedExtend access token lifetimeToken Lifetime⚠️ 180s defaultEdit config file (see above)Silent Auth⚠️ UnreliableUse extended tokensPKCE✅ SupportedAlways enabledGroups✅ SupportedFormat: `name@domain.com`See [SYNOLOGY\_QUIRKS.md](docs/SYNOLOGY_QUIRKS.md) for details.

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

[](#troubleshooting)

### "redirect\_uri\_mismatch"

[](#redirect_uri_mismatch)

**Solution:** Ensure exact match in Synology SSO Server configuration (including protocol, domain, port, and trailing slash).

### "Invalid state"

[](#invalid-state)

**Solution:** Enable cookies, check session configuration.

### "Token expired"

[](#token-expired)

**Solution:** [Extend token lifetime](#extending-token-lifetime) to 1800 seconds.

### "SSL certificate problem"

[](#ssl-certificate-problem)

**Solution (dev only):**

```
SYNOLOGY_SSO_VERIFY_SSL=false
```

### Debug Mode

[](#debug-mode)

```
APP_DEBUG=true
```

Check logs:

```
tail -f storage/logs/laravel.log
```

Changelog
---------

[](#changelog)

Please see [CHANGELOG.md](CHANGELOG.md) for recent changes.

Contributing
------------

[](#contributing)

Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.

Credits
-------

[](#credits)

- [Deroy2112](https://github.com/Deroy2112)
- [All Contributors](../../contributors)

License
-------

[](#license)

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

Links
-----

[](#links)

- **Packagist:**
- **GitHub:**
- **Issues:**
- **Laravel Socialite:**
- **Synology SSO Server:** Available in DSM Package Center

###  Health Score

37

—

LowBetter than 83% of packages

Maintenance69

Regular maintenance activity

Popularity7

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity56

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

Every ~3 days

Total

5

Last Release

180d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/359567fc78660c7f10efe0abd8523677312d463ee8c71c12226a19d4edc2fbf7?d=identicon)[Deroy2112](/maintainers/Deroy2112)

---

Top Contributors

[![Deroy2112](https://avatars.githubusercontent.com/u/81692934?v=4)](https://github.com/Deroy2112 "Deroy2112 (9 commits)")

---

Tags

laravelAuthenticationSSOsocialiteoidcpkcesynology

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Type Coverage Yes

### Embed Badge

![Health badge](/badges/deroy2112-laravel-synology-sso/health.svg)

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

###  Alternatives

[ellaisys/aws-cognito

AWS Cognito package that allows Auth and other related features using the AWS SDK for PHP

120220.7k1](/packages/ellaisys-aws-cognito)[kovah/laravel-socialite-oidc

OpenID Connect OAuth2 Provider for Laravel Socialite

2073.7k](/packages/kovah-laravel-socialite-oidc)[zefy/laravel-sso

Simple PHP SSO integration for Laravel

1013.0k](/packages/zefy-laravel-sso)[maicol07/laravel-oidc-client

OpenID Connect Client for Laravel

251.1k](/packages/maicol07-laravel-oidc-client)[truckersmp/steam-socialite

Laravel Socialite provider for Steam OpenID.

1516.7k](/packages/truckersmp-steam-socialite)

PHPackages © 2026

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