Sso Auth Bundle Laravel Package

Getting Started

Install the package with Composer and let Laravel's package discovery register the service provider — no manual registration is normally required. Publish the package config (php artisan vendor:publish) and populate your SSO tenant/client credentials plus the callback/redirect route in your .env. Then wire the SSO guard into config/auth.php so the SsoAuthenticationProvider is used for the endpoints you want behind SSO.

Look first at SsoAuthenticationProvider. As of v1.0.1 its attributes are protected rather than private, which makes the class the intended extension seam for day-to-day customization: claim mapping, user resolution, and post-authentication hooks. That single change is the most useful thing to know when you start — it tells you the package authors expect you to subclass the provider rather than only configure it.

First use case: stand up the SSO login → callback → local user resolution flow, then bind your own subclass of SsoAuthenticationProvider in a service provider so you can adjust how SSO claims map onto your users table without forking the package.

Implementation Patterns

Subclass the provider for claim mapping. With v1.0.1, extend SsoAuthenticationProvider and override only the methods you need; the protected attributes are now reachable from the child class, so you can read and adjust provider state (identifier, resolved user attributes, etc.) without reflection hacks.

class AppSsoAuthenticationProvider extends SsoAuthenticationProvider
{
    protected function mapAttributes(array $claims): array
    {
        return [
            'email' => $claims['mail'],
            'name'  => $claims['displayName'] ?? $claims['mail'],
        ];
    }
}

Bind it in a service provider (or via config if the package supports a provider class key):

$this->app->bind(SsoAuthenticationProvider::class, AppSsoAuthenticationProvider::class);

Keep the base provider as the fallback. Prefer configuration over subclassing for anything the config already covers (client ID, secret, scopes, redirect URI) and reserve subclassing for behaviour the config can't express. This keeps your upgrade path clean.

Resolve local users in one place. Centralize "SSO identity → Eloquent user" logic in the provider subclass (or a dedicated action) so registration-on-first-login, email matching, and role sync are testable in isolation.

Test the flow with a fake/stubbed provider. Bind a stub implementation of the provider in your test suite so feature tests can exercise the callback route and guard without hitting the real IdP. Because the attributes are now protected, you can also unit-test your subclass by manipulating that state directly rather than mocking internals.

Middleware and guards. Apply the SSO guard only to the route groups that need it; keep a separate guard for local/API auth so a broken SSO config doesn't lock out admin or machine access.

Gotchas and Tips

• v1.0.1 is a non-breaking change. Moving attributes from private to protected doesn't change public behaviour, but it does widen the extension surface. If you have existing subclasses, audit any property names that now shadow the parent's — a child redeclaring an inherited protected property is a silent source of confusing state bugs.
• Don't reach into protected state from outside the hierarchy. The change invites reflection-free access from subclasses, but external code should still go through public methods. Reading/writing provider attributes from controllers tightens coupling and will hurt on the next refactor.
• Reflection-based workarounds are now obsolete. If you previously used ReflectionProperty::setAccessible(true) to poke at private provider attributes, replace that with a proper subclass — it will survive future releases far better.
• Clear config cache after changing provider bindings. php artisan config:clear / config:cache confusion is the usual cause of "my subclass isn't being used" in production.
• Debug the callback first. Most SSO failures are redirect URI mismatches, clock skew on token validation, or claim keys that differ from what you assumed. Log the raw claims once on a staging environment before writing mapping code.
• Watch upstream for the next release. A private → protected bump often precedes adding official extension points (hooks, overridable methods). Pin the version you've tested and follow the changelog so a later refactor of the provider doesn't surprise your subclasses.