Download the PHP package knpuniversity/oauth2-client-bundle without Composer

OAuth / Social Integration for Symfony: KnpUOAuth2ClientBundle

Easily integrate with an OAuth2 server (e.g. Facebook, GitHub) for:

• "Social" authentication / login
• "Connect with Facebook" type of functionality
• Fetching access keys via OAuth2 to be used with an API
• Doing OAuth2 authentication with Symfony Custom Authenticator (or Guard Authenticator for legacy applications)

This bundle integrates with league/oauth2-client.

This Bundle or HWIOAuthBundle?

In addition to this bundle, another OAuth bundle exists for Symfony: hwi/oauth-bundle. You might be wondering "why are there two popular OAuth bundles?".

Great question! Generally speaking, hwi/oauth-bundle gives you more features out-of-the-box, including social authentication and registration (called "connect"). But, it's also a bit harder to install. The knpuniversity/oauth2-client-bundle, takes more work to setup, but gives you more low-level control.

Not sure which to use? If you need OAuth (social) authentication & registration, try hwi/oauth-bundle. If you don't like it, come back!

Installation

Install the bundle library via Composer by running the following command:

If you're using Symfony Flex, the bundle will be automatically enabled. For older apps, enable it in your AppKernel class.

Awesome! Now, you'll want to configure a client.

Configuring a Client

You'll need to configure one client for each OAuth2 server (GitHub, Facebook, etc) that you want to talk to.

Step 1) Download the Client Library

Choose the one you want from this list and install it via Composer:

Don't see a provider you need in this list? Please, check the full list of third-party provider clients from league/oauth2-client. Otherwise, consider creating a generic client yourself.

Step 2) Configure the Provider

Awesome! Now, you'll configure your provider. For Facebook, this will look something like this:

Notice the two '%env(var)%'calls? Add these in your .env file, or to the vault. These are the credentials for the OAuth provider. For Facebook, you'll get these by registering your app on developers.facebook.com:

See the full configuration for all the supported "types" in the Configuration section.

The type is facebook because we're connecting to Facebook. You can see all the supported type values below in the Configuration section.

Step 3) Use the Client Service

Each client you configured now has its own service that can be used to communicate with the OAuth2 server.

To start the OAuth process, you'll need to create a route and controller that redirects to Facebook. Because we used the key facebook_main above, you can simply:

Now, just go (or link to) /connect/facebook and watch the flow!

After completing the OAuth2 flow, the $client object can be used to fetch the user, the access token, or other things:

Authenticating with the new Symfony Authenticator

At this point, you now have a nice service that allows you to redirect your user to an OAuth server (e.g. Facebook) and fetch their access token and user information.

But often, you will want to actually authenticate that user: log them into your system. In that case, instead of putting all of the logic in connectCheckAction() as shown above, you'll leave that blank and create an authenticator which will hold similar logic.

Now you can use the new Symfony Authenticator system (available since Symfony 5.2, don't use it before this version) to login in your app. For legacy Symfony versions, use Guard Authenticator below.

Step 1) Using the new OAuth2Authenticator Class

Step 2) Configuring the Security

Next, enable the new authenticator manager and then register your authenticator in security.yaml under the custom_authenticators section:

CAUTION You can also inject the individual client (e.g. FacebookClient) into your authenticator instead of the ClientRegistry. However, this may cause circular reference issues and degrades performance (because authenticators are instantiated on every request, even though you rarely need the FacebookClient to be created). The ClientRegistry lazily creates the client objects.

Authenticating with Guard

Create a Guard Authenticator. A SocialAuthenticator base class exists to help with a few things:

Next, register your authenticator in security.yaml under the guard section:

For more details: see http://symfony.com/doc/current/cookbook/security/guard-authentication.html#step-2-configure-the-authenticator.

Authenticating any OAuth User

If you don't need to fetch/persist any information about the user, you can use the OAuthUserProvider service to quickly authenticate them in your application (if you're using Doctrine, use the normal entity user provider).

First, define the user provider in your security.yaml file:

Then in your Guard authenticator, use the user provider to easily fetch the user:

The logged-in user will be an instance of KnpU\OAuth2ClientBundle\Security\User\OAuthUser and will have the roles ROLE_USER and ROLE_OAUTH_USER.

Storing and Refreshing Tokens

You have a couple of options to store access tokens for use at a later time:

1. Store the AccessToken object (e.g. serializing into the session), this allows you to check expiry before refreshing:

2. Store the refresh token string (e.g. in the database user.refresh_token), this means you must always refresh. You can also store the access token and expiration and then avoid the refresh until the access token is actually expired:

Depending on your OAuth2 provider, you may need to pass some parameters when initially creating and/or refreshing the token:

Configuration

Below is the configuration for all of the supported OAuth2 providers. Don't see the one you need? Use the generic provider to configure any provider:

Configuring a Generic Provider

Is the OAuth server you want to connect with not here? No worries! You can configure a custom "provider" using the generic type.

1) Find / Create your Provider Library

First, see if your OAuth server already has a "provider library" that you can use: See Provider Client Libraries.

If you found one there, awesome! Install it. If not, you'll need to create your own Provider class. See the Provider Guide about this.

Either way, after this step, you should have a provider "class" (e.g. a class that extends AbstractProvider) that's ready to use!

2) Configuration

Now, just configure your provider like any other provider, but using the generic type:

That's it! Now you'll have a knpu.oauth2.client.foo_bar_oauth service you can use.

Extending / Decorating Client Classes

Maybe you need some extra services inside your client class? No problem! You can decorate existing client class with your own implementation. All you need is a new class that implements OAuth2ClientInterface:

And configure it:

Contributing

Of course, open source is fueled by everyone's ability to give just a little bit of their time for the greater good. If you'd like to see a feature, you can request it - but creating a pull request is an even better way to get things done.

Either way, please feel comfortable submitting issues or pull requests: all contributions and questions are warmly appreciated :).