Keycloak Laravel Package

Product Decisions This Supports

• Enterprise/B2B SSO as a roadmap item. This package is the smallest possible wedge for "log in with our company's identity provider" for Laravel-based products: it adapts Keycloak's OIDC endpoints to Laravel Socialite's driver contract, so a story that would otherwise be a multi-sprint auth project becomes a config entry plus a controller callback.
• Build vs. buy on identity. It lets you buy (Keycloak) the identity layer and buy (this package) the ~200-line adapter, rather than building OAuth2/OIDC plumbing, token exchange, and userinfo mapping in-house. The decision it unblocks is "do we own an IdP?" — and this package says the integration cost is not the reason to say no.
• On-prem / self-hosted / data-residency use cases. Keycloak is the default open-source answer when customers demand SSO inside their own network or in a specific region. This provider makes that deployment shape addressable without a bespoke auth stack, which is often a gating requirement in regulated or EU/public-sector deals.
• Multi-tenant and white-label auth. Because Keycloak realms are per-tenant, one integration pattern can serve many customers' directory backends; the PM decision it supports is whether to standardize on a single IdP protocol (OIDC via Keycloak) instead of accumulating one-off SAML integrations per enterprise account.
• Internal-tools and admin-console consolidation. Where the org already runs Keycloak for employees, reusing it across Laravel admin panels/apps is nearly free and reduces shadow local-password auth — a security and support-cost decision, not a feature decision.
• Scope boundary it clarifies: Socialite gives you identity, not authorization. Role/group mapping from Keycloak claims requires custom code (extending the provider or reading the ID token yourself). The PM should treat RBAC/entitlements as a separate line item, not assume it comes with the login button.

When to Consider This Package

Consider it when all of the following hold:

• You're on Laravel and already use (or are willing to use) Socialite as your OAuth entry point.
• Your identity provider is Keycloak — self-hosted, customer-hosted, or a managed Keycloak — and you need browser-based OIDC login.
• You need basic authentication only: login, callback, and a user profile (subject, email, username). Not fine-grained scopes, token refresh orchestration, back-channel logout, or Keycloak admin operations.
• You're comfortable with a community-maintained adapter in the SocialiteProviders family, whose support model is "the main providers repo is the source of truth."
• You accept the release cadence risk: last tagged release is April 2023. Validate it against your PHP/Laravel version and pin it; check the SocialiteProviders/Providers monorepo for newer unreleased fixes.

Look elsewhere when:

• You're not on Laravel/Socialite. The value here is the adapter, not the protocol; use a maintained OIDC client for your stack.
• You need SAML, not OIDC. Keycloak brokers SAML, but the contract with your app would still be OIDC — fine — yet if your customer mandates direct SAML to your app, this isn't the shape.
• You need enterprise-grade identity features — SCIM provisioning, group/role sync, logout propagation, MFA policy enforcement surfaced in your UI. Those are product work on top of this package or a reason to buy a full CIAM (Auth0, WorkOS, Entra, FusionAuth) instead.
• You want a vendor-backed SLA. 22 stars and a read-only subtree split is not a support contract; if identity is business-critical and you can't absorb the maintenance, budget for owning a fork.
• You only need consumer social login (Google, GitHub, Apple). Keycloak adds an IdP to operate with no payoff.
• You can't operate Keycloak. The real total cost is the server, realm configuration, upgrades, and backups — the package is the cheap part. If nobody owns Keycloak, this is a false economy.

How to Pitch It (Stakeholders)

For executives: This is a low-cost integration that removes a common blocker in enterprise sales — "can we use our own corporate login?" It's a thin connector between our Laravel app and Keycloak, an established open-source identity server. It doesn't add a vendor contract or a new platform; it lets us meet SSO requirements with configuration rather than custom engineering, and it keeps the door open to on-prem and data-residency deals. The costs to flag are operational, not licensing: someone must run Keycloak, and role/permission mapping is separate work.

For engineering: Adopt as a scoped adapter, not a platform. Add the Socialite provider event listener, configure client_id, client_secret, redirect, and the realm base_url in config/services.php, and handle the callback. Treat it as a starting point you may fork: expect to extend it for group/role claims, logout, and any refresh-token behavior. Pin the version, verify compatibility with your Laravel/PHP versions, and track the upstream SocialiteProviders/Providers monorepo since this split is read-only. Estimate one to three days for the happy path, plus explicit scope for authorization mapping and Keycloak operations.