Download the PHP package winter/wn-sso-plugin without Composer

Winter.SSO - Single Sign-On Plugin

Adds OAuth-based Single Sign-On (SSO) authentication to the Winter CMS backend using Laravel Socialite. Allow your backend users to authenticate using their existing accounts from providers like Google, GitHub, Microsoft 365, and more.

Features

• 8 Built-in Providers: GitHub, Google, Facebook, GitLab, Bitbucket, LinkedIn, Twitter (OAuth 1.0 & 2.0)
• Extensible: Easy integration with 100+ community Socialite Providers
• Provider Plugins: Install additional providers as separate plugins (e.g., Winter.SSOProviderMicrosoft)
• Event System: Comprehensive hooks for customizing authentication flow
• Security: SSO ID verification, email normalization, IP logging
• User Registration: Optionally create new users via SSO
• Native Auth Control: Disable username/password login, enforce SSO-only
• Audit Logging: Track all SSO authentication attempts
• Flexible Configuration: Environment-based or file-based setup

Installation

Install via Composer:

If using a public folder, republish assets:

Quick Start

Let's set up GitHub authentication as an example:

1. Create OAuth App on GitHub

1. Go to GitHub Developer Settings
2. Click "New OAuth App"
3. Fill in the details:
   • Application name: Your Site Name
   • Homepage URL: https://example.com
   • Authorization callback URL: https://example.com/backend/winter/sso/handle/callback/github
4. Save and copy your Client ID and Client Secret

2. Configure Environment Variables

Add to your .env file:

3. Enable the Provider

Edit config/winter/sso/config.php (create if it doesn't exist):

4. Test

Visit /backend/auth/signin - you'll see a "Sign in with GitHub" button!

Configuration Reference

Configuration file: config/winter/sso/config.php

Core Settings

Redirect URL Format

All providers use this URL pattern:

Examples:

• GitHub: /backend/winter/sso/handle/callback/github
• Google: /backend/winter/sso/handle/callback/google
• Microsoft: /backend/winter/sso/handle/callback/microsoft

Built-in Providers

These providers are supported out of the box by Laravel Socialite:

Adding Additional Providers

Option 1: Provider Plugins (Recommended)

Provider plugins package everything needed for a specific provider:

Provider plugins automatically:

• Install the Socialite provider package
• Register with Laravel Socialite
• Add configuration options
• Include provider logos and assets

See Creating Provider Plugins for building your own.

Option 2: Direct Socialite Providers

Use any provider from SocialiteProviders.com:

1. Install the provider package:

2. Register the provider in your plugin's boot() method:

3. Add configuration:

4. Add provider logo (optional): Place an SVG at /plugins/winter/sso/assets/images/providers/microsoft.svg

Events System

The plugin fires events at every stage of the authentication flow, allowing you to customize behavior:

Available Events

Each event is provider-specific. Replace {provider} with your provider name (e.g., google, github).

1. winter.sso.{provider}.authenticating

Fires before OAuth authentication begins. Return false to abort.

2. winter.sso.{provider}.authenticated

Fires after successful OAuth, before user lookup.

3. winter.sso.{provider}.beforeRegister

Fires before creating a new user account. Throw exception to prevent registration.

4. winter.sso.{provider}.registered

Fires after new user is created. Populate additional fields here.

5. winter.sso.{provider}.beforeLogin

Fires before session is created.

6. winter.sso.{provider}.afterLogin

Fires after successful login and session creation.

Accessing SSO Data

User SSO data is stored in the user's metadata:

Metadata structure: Backend\Models\User::metadata['winter.sso'][$provider][$key]

Security Features

SSO ID Verification

Once a user connects via a provider, their SSO ID is stored. On subsequent logins, the ID must match. This prevents account takeover if someone else registers the same email with a different provider.

Email Normalization

Emails are normalized to prevent duplicate accounts:

• Gmail: Dots are removed from usernames ([email protected] → [email protected])
• All domains: Lowercased

IP Logging

All authentication attempts are logged with:

• Provider used
• Action taken
• User ID
• SSO provider ID
• Email provided
• IP address
• Metadata (remember me, etc.)

View logs: Settings → Logs → SSO Logs

Session Security

The plugin automatically adjusts session.same_site from strict to lax when secure sessions are enabled, ensuring OAuth callbacks work correctly.

Troubleshooting

"The provider X is not enabled"

Cause: Provider not in enabled_providers array.

Solution: Add provider to config:

"Invalid state"

Cause: Session lost between redirect and callback, or CSRF protection too strict.

Solutions:

• Ensure sessions are working correctly
• Check session.same_site setting (plugin auto-adjusts to lax)
• Clear browser cookies and try again

"Email not found"

Cause: User doesn't exist and allow_registration is false.

Solution: Either:

• Create the user account manually in the backend
• Enable registration: 'allow_registration' => true

"Invalid SSO ID"

Cause: User previously connected with a different account from the same provider.

Solution: This is a security feature. The user must use the original account, or an admin must clear the SSO data:

SSO buttons not appearing

Checklist:

1. Provider is in enabled_providers array
2. client_id is set in provider config
3. Environment variables are loaded correctly
4. Assets are published (php artisan winter:mirror)

Provider-specific issues

Check the provider's setup guide in docs/providers/ for common issues.

Advanced Topics

Preventing Native Authentication

Force SSO-only login:

This will:

• Hide the username/password form
• Disable the login AJAX handler
• Show only SSO buttons

If only one provider is enabled, users are redirected directly to that provider.

Customizing Button Appearance

Override button configuration per provider:

Provider Scopes

Request additional OAuth scopes:

HTTP Client Options (Guzzle)

Configure HTTP client for providers behind proxies or with special requirements:

Further Documentation

• Architecture Overview - How the plugin works internally
• Creating Provider Plugins - Build custom provider plugins
• Google Setup Guide - Detailed Google OAuth setup

Contributing

Contributions are welcome! Please submit pull requests to the Winter CMS repository.

License

This plugin is licensed under the MIT License.