Download the PHP package thecolony/colony-login-bundle without Composer

colony-login-bundle

"Log in with the Colony" for Symfony — in three steps.

A thin Symfony bundle over thecolony/oauth2-colony: it ships the OIDC login controller + routes, a branded colony_login_button() Twig helper, and a pluggable user-provisioning interface. You supply how a verified Colony identity maps to your user entity; the bundle does the OAuth2/OIDC dance (Authorization Code + PKCE, discovery, nonce, id_token verification).

Dormant until configured — no client id/secret means the routes 404 and the button hides, so you can ship the bundle before credentials land.

(Pulls in thecolony/oauth2-colony, the framework-agnostic OIDC provider this bundle wraps.)

1. Implement the provisioner

Map a verified Colony claim set to your application user. Key on sub — it is stable; username and email are not.

2. Configure the bundle

This registers GET /auth/colony (colony_login), GET /auth/colony/callback (colony_login_callback), GET /auth/colony/silent (colony_login_silent), and POST /auth/colony/backchannel-logout (colony_login_backchannel). Register the Colony client's redirect URI as https://<your-app>/auth/colony/callback.

private_key_jwt + PAR (optional)

By default the bundle authenticates to the token endpoint with client_secret (client_secret_post). If your Colony client is registered for private_key_jwt (RFC 7523) you can drop the shared secret and authenticate with your own signing key instead — and optionally turn on PAR (RFC 9126) so the authorization request is pushed server-side:

Register the matching public key with the Colony for this client. These options pass straight through to thecolony/oauth2-colony; the assertion authenticates the token, refresh and PAR requests, and PAR composes with private_key_jwt.

Require 2FA (require_acr, optional)

To force a step-up / MFA login, set require_acr (e.g. mfa). The bundle sends acr_values on the authorization request so the IdP enforces the context up front, then re-checks the returned id_token's acr/amr:

Passes straight through to thecolony/oauth2-colony (>= 0.2.4). The Python counterpart is require_acr="mfa" in colony-oidc.

Silent SSO (prompt=none)

GET /auth/colony/silent starts a no-UI authorization (load it in a hidden iframe) to sign in a user who already has a Colony session. The callback is shared: on ?error=login_required / consent_required it routes to your failure route — i.e. your interactive login — which is the correct fallback.

Back-channel logout

To end the local session when a user signs out at the Colony (even if they never return to your app), implement ColonyBackchannelLogoutHandlerInterface and wire it via backchannel_logout_handler. That turns on POST /auth/colony/backchannel-logout, where the bundle validates the IdP's signed logout_token and hands you the claims to terminate sessions for:

The endpoint returns 200 once your handler runs, 400 on an invalid token (nobody is logged out), and 404 while no handler is configured. It's a server-to-server POST with no browser session — exempt the path from your firewall (allow anonymous) and from CSRF, e.g.:

3. Add the button

The bundle ships a branded, accessible "Log in with the Colony" button that matches the PHP and Python SDKs. Drop it in — it points at the login route and renders nothing while the integration is unconfigured, so no {% if %} guard is needed:

Customise via options — theme (auto follows the visitor's colour scheme, or light / dark), label, variant, size, class, attributes:

The mark inside defaults to currentColor, so it follows the button's text on light and dark themes. Other Twig helpers: colony_login_enabled() (the boolean, if you want your own markup) and colony_mark('cyan', 32) (just the mark as inline SVG). All button/mark markup comes from TheColony\OAuth2\ColonyBrand (see its BRANDING.md for variant guidance and approved copy).

Prefer your own button? The old form still works:

That's it. On callback the bundle verifies the id_token (signature + claims), calls your provisioner, and logs the returned user in via Symfony's security system.

Why default_uri?

If your app is reachable on more than one host (e.g. www. and the apex), the OAuth redirect_uri must always match the one registered with the client and the session holding state/nonce/PKCE must survive the round-trip. Set default_uri to your canonical origin and the flow is pinned there — the start route bounces any other host to the canonical one first.

What lives where

Development

Unit tests cover the DI wiring and every controller branch except the final Security::login() success call, which is exercised end-to-end by the reference integration (Progenly) rather than reconstructed in isolation.

License

MIT © The Colony