# KnpUOAuth2ClientBundle: low-level OAuth2 clients for Symfony > A Symfony bundle that wraps league/oauth2-client and asks you to configure one client per OAuth2 server. Low-level control in exchange for building your own login and registration flow. **knpuniversity/oauth2-client-bundle** — Easily talk to an OAuth2 server for social functionality in Symfony - Repository: https://github.com/knpuniversity/oauth2-client-bundle - Website: https://symfonycasts.com - Stars: 840 · Forks: 153 - Language: PHP - License: MIT - Published: 2026-10-20 · Updated: 2026-10-20 · Language: en - Canonical page: https://hysenlabs.com/projects/knpuniversity-oauth2-client-bundle ## One client per OAuth2 server, and no provider code in the box The bundle's central rule is that you configure one client for each OAuth2 server you intend to talk to, and the provider code does not ship inside it. GitHub, Facebook, Discord, Keycloak and the dozens of other entries in the README's provider table each live in their own Composer package. A project that supports social login and also pulls API data from a second provider ends up with two client configurations and two provider dependencies. There is no generic social layer that discovers providers for you, and no single install that hands you Facebook and GitHub at once. What the bundle contributes is Symfony-shaped wiring around that low level client library, and the setup cost that wiring implies. ## The bundle wraps league/oauth2-client instead of reimplementing the protocol Underneath, the bundle integrates with league/oauth2-client, and the division of labour is clean. The league library handles the protocol mechanics, while the bundle turns those mechanics into services a Symfony application can use in controllers, forms and authenticators. The README lists social login, connect-with-provider buttons, fetching access keys for an API, and doing OAuth2 authentication with a Symfony Custom Authenticator as the intended use cases, with Guard Authenticator mentioned for legacy applications. Based on the repository layout, the PHP source sits in src/ with tests/ beside it, and the root carries phpstan, phpunit and php-cs-fixer configuration, which shows the project treats static analysis and style checks as routine work rather than optional extras. ## Installing the bundle and a GitHub provider in two Composer steps Installation is a single Composer command. Symfony Flex enables the bundle automatically after the install; on older applications you enable it yourself in the AppKernel class, though the README does not print that snippet. ```bash composer require knpuniversity/oauth2-client-bundle ``` Next comes the provider, again through Composer. Choosing GitHub from the provider table gives you this package: ```bash composer require league/oauth2-github ``` After that the remaining work is configuration rather than code: you define a client for that server, and the bundle expects one client per server. The README's provider table lists exact packages for a long set of providers, including Auth0, Bitbucket, Box, Dropbox, Google, Instagram, Keycloak, LinkedIn and many more. Because that list is data rather than code, adding a second API later means repeating the same two-step pattern with a different package and a second client entry. Provider selection is a per-server decision you make at build time, not something the bundle resolves at runtime. ## The README is silent on token storage, refresh and failure handling The honest limitation is scope. The README does not describe social registration, no automatic user creation on first login, and no built-in connect account screen. It also does not document how access tokens are stored, how they are refreshed after expiry, or what happens when an authorization is denied, and it does not cover the rollback of a partially completed login. That silence matters more here than for many bundles, because this one sits deliberately close to the protocol. Users expecting a ready-made sign-in screen find only plumbing. Developers who need to own token storage and account linking find exactly the level they asked for. The bundle is a foundation rather than a finished social login product. ## Why the README sends you to hwi/oauth-bundle for registration The README names the alternative directly. hwi/oauth-bundle also exists for Symfony, and the comparison the project itself draws is about where the default sits. hwi/oauth-bundle gives you more features out of the box, including social authentication and registration, but it is also a bit harder to install. This bundle takes more work to set up and gives more low-level control. So the choice is not quality, it is default behaviour: if you need social authentication and registration out of the box, the README suggests trying hwi/oauth-bundle first and coming back here if it does not suit you. If you only need OAuth for API access, or you want to own the redirect and token flow end to end, the lower level route here is the one that matches the job. ## MIT licence and a Symfony 8 release that narrowed version support On maintenance and upgrade cost, the facts are plain. The licence is MIT, which keeps the obligation light for commercial Symfony applications embedding it, with the licence text itself governing any such use. The repository is not archived, and the last push was on 2026-04-29. Release history shows steady but unspectacular patching: v2.20.2 shipped on 2026-02-12 with a cleanup, v2.20.1 on 2025-12-04 fixed support for POST params, and v2.20.0 on 2025-11-29 added Symfony 8 support while dropping support for versions that are no longer maintained. That last change is the upgrade cost to plan for, since an application on an older Symfony line may need a framework upgrade before it can take the newest release. ## Conclusion Pick it when you need API tokens or a custom OAuth flow and want to own the login screens yourself; skip it if social registration out of the box matters more than control. Before adopting, check that your Symfony version still sits inside the support range narrowed by v2.20.0, and that league/oauth2-client plus one provider package fit your dependency policy. ## FAQ ### How do I install KnpUOAuth2ClientBundle in a Symfony application? Run composer require knpuniversity/oauth2-client-bundle. Symfony Flex enables the bundle automatically, while older applications enable it in the AppKernel class. ### Do I need a separate package for each OAuth2 provider with KnpUOAuth2ClientBundle? Yes. Provider libraries are separate Composer packages, for example league/oauth2-github for GitHub, and you configure one client for each OAuth2 server you want to talk to. ### Does KnpUOAuth2ClientBundle include social registration or connect-with-Facebook features? No. The bundle focuses on OAuth2 access and client configuration. The README points to hwi/oauth-bundle for social authentication and registration that works out of the box. ### Which Symfony versions does the current KnpUOAuth2ClientBundle release support? Release v2.20.0, dated 2025-11-29, added Symfony 8 support and dropped support for versions that are no longer maintained, so older Symfony lines are outside the newest release's range. ## Sources - [knpuniversity/oauth2-client-bundle on GitHub](https://github.com/knpuniversity/oauth2-client-bundle) - [License: MIT](https://github.com/knpuniversity/oauth2-client-bundle/blob/main/LICENSE) - [Project website](https://symfonycasts.com) - [README](https://github.com/knpuniversity/oauth2-client-bundle/blob/main/README.md) - [Releases](https://github.com/knpuniversity/oauth2-client-bundle/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/knpuniversity-oauth2-client-bundle