KnpUOAuth2ClientBundle

https://github.com/knpuniversity/oauth2-client-bundle
Admin
KnpUOAuth2ClientBundle is a Symfony bundle that provides seamless OAuth2 integration with social...
Tokens:77,654
Snippets:436
Trust Score:9.5
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Direct usage example with route name

Source: https://github.com/knpuniversity/oauth2-client-bundle/blob/main/_autodocs/api-reference/providerfactory.md

Example showing how to use the factory directly to create a Facebook provider with a redirect route name.

```php
use KnpU\OAuth2ClientBundle\DependencyInjection\ProviderFactory;

/** @var ProviderFactory $factory (service knpu.oauth2.provider_factory) */
$provider = $factory->createProvider(
    \League\OAuth2\Client\Provider\Facebook::class,
    ['clientId' => 'CLIENT_ID', 'clientSecret' => 'SECRET', 'graphApiVersion' => 'v2.12'],
    'connect_facebook_check',     // route name → absolute URL generated by the router
    []                            // route params
);
```

--------------------------------

### Install KnpUOAuth2ClientBundle via Composer

Source: https://github.com/knpuniversity/oauth2-client-bundle/blob/main/README.md

Run this command to install the bundle using Composer. If using Symfony Flex, the bundle is enabled automatically; otherwise, enable it manually in the AppKernel class.

```bash
composer require knpuniversity/oauth2-client-bundle
```

--------------------------------

### YAML configuration example for knpu_oauth2_client

Source: https://github.com/knpuniversity/oauth2-client-bundle/blob/main/_autodocs/configuration.md

Example configuration for the bundle under the knpu_oauth2_client key. Shows commented-out http_client and http_client_options, and a facebook_main client with type, credentials, redirect route, and graph_api_version. Use this as a template for defining OAuth2 provider connections.

```yaml
knpu_oauth2_client:
    # http_client: 'my.guzzle.client'   # custom HTTP client service
    # http_client_options:
    #     timeout: 30
    #     proxy: 'http://proxy.example:8080'
    #     verify: false

    clients:
        facebook_main:
            type: facebook
            client_id: '%env(OAUTH_FACEBOOK_ID)%'
            client_secret: '%env(OAUTH_FACEBOOK_SECRET)%'
            redirect_route: connect_facebook_check
            redirect_params: {}
            graph_api_version: v2.12
            use_state: true
```

--------------------------------

### Usage example: MyFacebookAuthenticator subclass

Source: https://github.com/knpuniversity/oauth2-client-bundle/blob/main/_autodocs/api-reference/oauth2authenticator.md

A basic usage example of fetchAccessToken() inside a subclass's authenticate() method. It shows how to retrieve the client, fetch the access token, and create a SelfValidatingPassport with a UserBadge.

```php
namespace App\Security;

use KnpU\OAuth2ClientBundle\Security\Authenticator\OAuth2Authenticator;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\Security\Http\Authenticator\Passport\Badge\UserBadge;
use Symfony\Component\Security\Http\Authenticator\Passport\Passport;
use Symfony\Component\Security\Http\Authenticator\Passport\SelfValidatingPassport;

class MyFacebookAuthenticator extends OAuth2Authenticator
{
    public function supports(Request $request): ?bool
    {
        return $request->attributes->get('_route') === 'connect_facebook';
    }

    public function authenticate(Request $request): Passport
    {
        $client = $this->clientRegistry->getClient('facebook_main');
        $accessToken = $this->fetchAccessToken($client); // exceptions already translated

        return new SelfValidatingPassport(
            new UserBadge($accessToken->getToken(), function () use ($accessToken, $client) {
                /** @var FacebookUser $user */
                $user = $client->fetchUserFromToken($accessToken);
                // ... load or create your User entity, return it
            })
        );
    }
}
```

--------------------------------

### Common pattern for provider client classes (GoogleClient example)

Source: https://github.com/knpuniversity/oauth2-client-bundle/blob/main/_autodocs/api-reference/provider-clients.md

Shows the typical structure of a provider-specific client class, extending `OAuth2Client` and overriding `fetchUserFromToken()` and `fetchUser()` with docblocks that narrow the return type to the provider's resource owner class. This example uses `GoogleClient` and `GoogleUser`.

```php
class GoogleClient extends OAuth2Client
{
    /**
     * @return GoogleUser|\League\OAuth2\Client\Provider\ResourceOwnerInterface
     */
    public function fetchUserFromToken(AccessToken $accessToken)
    {
        return parent::fetchUserFromToken($accessToken);
    }

    /**
     * @return GoogleUser|\League\OAuth2\Client\Provider\ResourceOwnerInterface
     */
    public function fetchUser()
    {
        return parent::fetchUser();
    }
}
```

--------------------------------

### Controller action to start OAuth flow and fetch user

Source: https://github.com/knpuniversity/oauth2-client-bundle/blob/main/README.md

PHP controller with two actions: one to redirect to Facebook and one to handle the callback. The first action uses ClientRegistry to get the 'facebook_main' client and redirect with scopes. The callback action fetches the user, access token, and provider, handling IdentityProviderException on failure.

```php
namespace App\Controller;

use KnpU\OAuth2ClientBundle\Client\ClientRegistry;
use League\OAuth2\Client\Provider\Exception\IdentityProviderException;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\Routing\Annotation\Route;

class FacebookController extends AbstractController
{
    /**
     * Link to this controller to start the "connect" process
     *
     * @Route("/connect/facebook", name="connect_facebook_start")
     */
    public function connectAction(ClientRegistry $clientRegistry)
    {
        // will redirect to Facebook!
        return $clientRegistry
            ->getClient('facebook_main') // key used in config/packages/knpu_oauth2_client.yaml
            ->redirect([
                'public_profile', 'email' // the scopes you want to access
            ]);
    }

    /**
     * After going to Facebook, you're redirected back here
     * because this is the "redirect_route" you configured
     * in config/packages/knpu_oauth2_client.yaml
     *
     * @Route("/connect/facebook/check", name="connect_facebook_check")
     */
    public function connectCheckAction(Request $request, ClientRegistry $clientRegistry)
    {
        // ** if you want to *authenticate* the user, then
        // leave this method blank and create a Guard authenticator
        // (read below)

        /** @var \KnpU\OAuth2ClientBundle\Client\Provider\FacebookClient $client */
        $client = $clientRegistry->getClient('facebook_main');

        try {
            // the exact class depends on which provider you're using
            /** @var \League\OAuth2\Client\Provider\FacebookUser $user */
            $user = $client->fetchUser();

            // do something with all this new power!
            // e.g. $name = $user->getFirstName();
            var_dump($user); die;
            // ...
        } catch (IdentityProviderException $e) {
            // something went wrong!
            // probably you should return the reason to the user
            var_dump($e->getMessage()); die;
        }
    }
}
```

--------------------------------

### Usage of getEnabledClientKeys() to render login links

Source: https://github.com/knpuniversity/oauth2-client-bundle/blob/main/_autodocs/api-reference/clientregistry.md

Example of iterating over enabled client keys to output login links for each provider.

```php
// render a link per configured OAuth provider
foreach ($clientRegistry->getEnabledClientKeys() as $key) {
    // $key e.g. 'facebook_main', 'google_main'
    echo sprintf('<a href="/connect/%s">Login with %s</a>', $key, $key);
}
```

--------------------------------

### Usage with absolute URL redirect

Source: https://github.com/knpuniversity/oauth2-client-bundle/blob/main/_autodocs/api-reference/providerfactory.md

Example showing how to use the factory with a hard-coded callback URL that is used untouched.

```php
$provider = $factory->createProvider(
    $class,
    $options,
    'https://app.example.com/oauth/callback', // already a URL — used untouched
    [],
    ['httpClient' => $customGuzzleClient]
);
```

--------------------------------

### Basic usage of getClient() in a controller

Source: https://github.com/knpuniversity/oauth2-client-bundle/blob/main/_autodocs/api-reference/clientregistry.md

Example of using getClient() to redirect to an OAuth provider. The client is lazily instantiated.

```php
use KnpU\OAuth2ClientBundle\Client\ClientRegistry;

class FacebookController extends AbstractController
{
    public function connectAction(ClientRegistry $clientRegistry)
    {
        return $clientRegistry->getClient('facebook_main')->redirect(['public_profile', 'email']);
    }
}
```

--------------------------------

### Basic usage of redirect() via registry

Source: https://github.com/knpuniversity/oauth2-client-bundle/blob/main/_autodocs/api-reference/oauth2pkceclient.md

Shows how to call redirect() on a PKCE client obtained from the registry. The keycloak_pkce type yields a KeycloakPkceClient that extends OAuth2PKCEClient, and the example passes the 'openid' scope.

```php
// via registry: keycloak_pkce type yields a KeycloakPkceClient which extends OAuth2PKCEClient
return $clientRegistry->getClient('keycloak_pkce_main')->redirect(['openid']);
```

--------------------------------

### Generic OAuth2 client configuration example

Source: https://github.com/knpuniversity/oauth2-client-bundle/blob/main/_autodocs/configuration.md

Example YAML configuration for a generic OAuth2 client using the KnpUOAuth2ClientBundle. Defines a client with type 'generic', custom provider and client classes, optional provider options, and environment-variable-based credentials. Use this as a template for custom providers extending AbstractProvider.

```yaml
knpu_oauth2_client:
    clients:
        foo_bar_oauth:
            type: generic
            provider_class: Some\Class\FooBarProvider
            client_class: App\Client\MyCustomOAuth2Client   # optional
            provider_options: {}                            # optional custom provider ctor options
            client_id: '%env(FOO_BAR_CLIENT_ID)%'
            client_secret: '%env(FOO_BAR_CLIENT_SECRET)%'
            redirect_route: connect_foo_bar_check
            redirect_params: {}
```

--------------------------------

### Implementing a custom provider configurator

Source: https://github.com/knpuniversity/oauth2-client-bundle/blob/main/_autodocs/api-reference/provider-configurators.md

Shows the required methods for a custom provider configurator: buildConfiguration, getProviderClass, getProviderOptions, getClientClass, getPackagistName, getLibraryHomepage, and getProviderDisplayName. The example uses a required 'base_url' node and maps it to the provider options. Registering a new type key requires extending the bundle; for application-level custom providers use 'type: generic' instead.

```php
use KnpU\OAuth2ClientBundle\DependencyInjection\Providers\ProviderConfiguratorInterface;
use Symfony\Component\Config\Definition\Builder\NodeBuilder;

class MyProviderConfigurator implements ProviderConfiguratorInterface
{
    public function buildConfiguration(NodeBuilder $node): void
    {
        $node->scalarNode('base_url')->isRequired()->end();
    }

    public function getProviderClass(array $config)
    {
        return \My\Provider::class;
    }

    public function getProviderOptions(array $config)
    {
        return [
            'clientId' => $config['client_id'],
            'clientSecret' => $config['client_secret'],
            'baseUrl' => $config['base_url'],
        ];
    }

    public function getClientClass(array $config) { return \KnpU\OAuth2ClientBundle\Client\OAuth2Client::class; }
    public function getPackagistName() { return 'me/my-oauth-provider'; }
    public function getLibraryHomepage() { return 'https://github.com/me/my-oauth-provider'; }
    public function getProviderDisplayName() { return 'My Provider'; }
}
```

--------------------------------

### Fetch user and access token after OAuth flow

Source: https://github.com/knpuniversity/oauth2-client-bundle/blob/main/README.md

PHP code showing how to use the client after the OAuth flow to fetch the user, get the access token, and access the underlying provider. Includes an example for Facebook to get a long-lived access token.

```php
// get the user directly
$user = $client->fetchUser();

// OR: get the access token and then user
$accessToken = $client->getAccessToken();
$user = $client->fetchUserFromToken($accessToken);

// access the underlying "provider" from league/oauth2-client
$provider = $client->getOAuth2Provider();
// if you're using Facebook, then this works:
$longLivedToken = $provider->getLongLivedAccessToken($accessToken);
```

--------------------------------

### Usage example: onAuthenticationFailure error handling

Source: https://github.com/knpuniversity/oauth2-client-bundle/blob/main/_autodocs/api-reference/oauth2authenticator.md

An example of handling translated exceptions in the onAuthenticationFailure() method. It shows how to check for specific exception types and return a forbidden response.

```php
use KnpU\OAuth2ClientBundle\Security\Exception\IdentityProviderAuthenticationException;
use KnpU\OAuth2ClientBundle\Security\Exception\InvalidStateAuthenticationException;
use KnpU\OAuth2ClientBundle\Security\Exception\NoAuthCodeAuthenticationException;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Security\Core\Exception\AuthenticationException;

public function onAuthenticationFailure(Request $request, AuthenticationException $exception): ?Response
{
    $message = strtr($exception->getMessageKey(), $exception->getMessageData());

    if ($exception instanceof NoAuthCodeAuthenticationException) {
        // user denied access ("Did you authorize our app?")
    } elseif ($exception instanceof InvalidStateAuthenticationException) {
        // CSRF-style state mismatch
    } elseif ($exception instanceof IdentityProviderAuthenticationException) {
        // provider error, original wrapped as $exception->getPrevious()
    }

    return new Response($message, Response::HTTP_FORBIDDEN);
}
```

--------------------------------

### Class KnpU\OAuth2ClientBundle\Security\User\OAuthUserProvider

Source: https://github.com/knpuniversity/oauth2-client-bundle/blob/main/_autodocs/api-reference/oauth-user-and-provider.md

Documentation for the OAuthUserProvider class, including its constructor, methods, and usage examples.

```APIDOC
## Class `KnpU\OAuth2ClientBundle\Security\User\OAuthUserProvider`

### Description
A `Symfony\Component\Security\Core\User\UserProviderInterface` implementation that creates `OAuthUser` instances on the fly. Registered in the container as `knpu.oauth2.user_provider`.

### Constructor

```php
public function __construct(array $roles = ['ROLE_USER', 'ROLE_OAUTH_USER'])
```

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `$roles` | `array` | no | `['ROLE_USER', 'ROLE_OAUTH_USER']` | Roles assigned to every loaded user |

### Methods

#### `loadUserByUsername()`

```php
public function loadUserByUsername($username): UserInterface
```

Delegates to `loadUserByIdentifier($username)`.

#### `loadUserByIdentifier()`

```php
public function loadUserByIdentifier(string $identifier): UserInterface
```

Returns `new OAuthUser($identifier, $this->roles)`.

#### `refreshUser()`

```php
public function refreshUser(UserInterface $user): UserInterface
```

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `$user` | `UserInterface` | yes | — | The user being refreshed |

**Return**: `UserInterface` — a freshly loaded `OAuthUser` with the identifier of the given user.

**Throws**: `Symfony\Component\Security\Core\Exception\UnsupportedUserException` — when `$user` is not an `OAuthUser` instance; message: `` Instances of "<class>" are not supported. ``

#### `supportsClass()`

```php
public function supportsClass($class): bool
```

Returns `true` only when `$class === OAuthUser::class`.

### Usage

Wire as the security user provider, then load users by the OAuth identifier:

```yaml
# config/packages/security.yaml
security:
    providers:
        oauth:
            id: knpu.oauth2.user_provider
```

```php
// inside a Guard/authenticator — load the user by the provider's resource-owner id
return $userProvider->loadUserByUsername($client->fetchUserFromToken($credentials)->getId());
// the logged-in user is an OAuthUser with roles ROLE_USER and ROLE_OAUTH_USER
```

### Usage (error handling — refreshUser on wrong user class)

```php
use Symfony\Component\Security\Core\Exception\UnsupportedUserException;

try {
    $refreshed = $oauthUserProvider->refreshUser($someOtherUser);
} catch (UnsupportedUserException $e) {
    // provider only supports OAuthUser instances
}
```
```

--------------------------------

### Get client from registry

Source: https://github.com/knpuniversity/oauth2-client-bundle/blob/main/_autodocs/api-reference/oauth2client.md

Obtains an OAuth2Client instance from the client registry. In normal application code, you never construct this directly.

```php
/** @var OAuth2Client $client */
$client = $clientRegistry->getClient('facebook_main');
```

--------------------------------

### Create MyFacebookAuthenticator class extending SocialAuthenticator

Source: https://github.com/knpuniversity/oauth2-client-bundle/blob/main/README.md

Use this PHP class to authenticate users with Facebook via OAuth2. It requires the KnpU OAuth2ClientBundle and Doctrine ORM. The supports() method checks the route, getCredentials() fetches the access token, and getUser() finds or creates the user by Facebook ID or email. onAuthenticationSuccess redirects to a route, and onAuthenticationFailure returns a 403 response. The start() method redirects to the login page. Note the commented code for Symfony < 3.4 and the 'facebook_main' client key from knpu_oauth2_client.yaml.

```php
namespace App\Security;

use App\Entity\User; // your user entity
use Doctrine\ORM\EntityManagerInterface;
use KnpU\OAuth2ClientBundle\Security\Authenticator\SocialAuthenticator;
use KnpU\OAuth2ClientBundle\Client\Provider\FacebookClient;
use KnpU\OAuth2ClientBundle\Client\ClientRegistry;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\RouterInterface;
use Symfony\Component\Security\Core\Authentication\Token\TokenInterface;
use Symfony\Component\Security\Core\Exception\AuthenticationException;
use Symfony\Component\Security\Core\User\UserProviderInterface;

class MyFacebookAuthenticator extends SocialAuthenticator
{
    private $clientRegistry;
    private $em;
    private $router;

    public function __construct(ClientRegistry $clientRegistry, EntityManagerInterface $em, RouterInterface $router)
    {
        $this->clientRegistry = $clientRegistry;
        $this->em = $em;
        $this->router = $router;
    }

    public function supports(Request $request)
    {
        // continue ONLY if the current ROUTE matches the check ROUTE
        return $request->attributes->get('_route') === 'connect_facebook_check';
    }

    public function getCredentials(Request $request)
    {
        // this method is only called if supports() returns true

        // For Symfony lower than 3.4 the supports method need to be called manually here:
        // if (!$this->supports($request)) {
        //     return null;
        // }

        return $this->fetchAccessToken($this->getFacebookClient());
    }

    public function getUser($credentials, UserProviderInterface $userProvider)
    {
        /** @var FacebookUser $facebookUser */
        $facebookUser = $this->getFacebookClient()
            ->fetchUserFromToken($credentials);

        $email = $facebookUser->getEmail();

        // 1) have they logged in with Facebook before? Easy!
        $existingUser = $this->em->getRepository(User::class)
            ->findOneBy(['facebookId' => $facebookUser->getId()]);
        if ($existingUser) {
            return $existingUser;
        }

        // 2) do we have a matching user by email?
        $user = $this->em->getRepository(User::class)
            ->findOneBy(['email' => $email]);

        // 3) Maybe you just want to "register" them by creating
        // a User object
        $user->setFacebookId($facebookUser->getId());
        $this->em->persist($user);
        $this->em->flush();

        return $user;
    }

    /**
     * @return FacebookClient
     */
    private function getFacebookClient()
    {
        return $this->clientRegistry
            // "facebook_main" is the key used in config/packages/knpu_oauth2_client.yaml
            ->getClient('facebook_main');
    }

    public function onAuthenticationSuccess(Request $request, TokenInterface $token, $providerKey)
    {
        // change "app_homepage" to some route in your app
        $targetUrl = $this->router->generate('app_homepage');

        return new RedirectResponse($targetUrl);
    
        // or, on success, let the request continue to be handled by the controller
        //return null;
    }

    public function onAuthenticationFailure(Request $request, AuthenticationException $exception)
    {
        $message = strtr($exception->getMessageKey(), $exception->getMessageData());

        return new Response($message, Response::HTTP_FORBIDDEN);
    }

    /**
     * Called when authentication is needed, but it's not sent.
     * This redirects to the 'login'.
     */
    public function start(Request $request, AuthenticationException $authException = null)
    {
        return new RedirectResponse(
            '/connect/', // might be the site, where users choose their oauth provider
            Response::HTTP_TEMPORARY_REDIRECT
        );
    }

    // ...
}
```

--------------------------------

### Error handling for unknown client key

Source: https://github.com/knpuniversity/oauth2-client-bundle/blob/main/_autodocs/api-reference/clientregistry.md

Example of catching InvalidOAuth2ClientException when the client key comes from user input, converting it to a 404 response.

```php
use KnpU\OAuth2ClientBundle\DependencyInjection\InvalidOAuth2ClientException;

try {
    $client = $clientRegistry->getClient($providerKeyFromUserInput);
} catch (InvalidOAuth2ClientException $e) {
    // e.g. invalid provider selection UI state
    throw $this->createNotFoundException('Unknown OAuth client.', $e);
}
```

--------------------------------

### PassageClient logout usage example

Source: https://github.com/knpuniversity/oauth2-client-bundle/blob/main/_autodocs/api-reference/provider-clients.md

Shows how to use the logout method with a PassageClient instance retrieved from the client registry. It catches a RuntimeException for provider mismatch, indicating a misconfigured client.

```php
use KnpU\OAuth2ClientBundle\Client\Provider\PassageClient;

/** @var PassageClient $client */
$client = $clientRegistry->getClient('passage_main');
try {
    return $client->logout();
} catch (\RuntimeException $e) {
    // provider mismatch — misconfigured client
}
```

--------------------------------

### fetchUser() basic usage

Source: https://github.com/knpuniversity/oauth2-client-bundle/blob/main/_autodocs/api-reference/oauth2client.md

Calls fetchUser() to get the user object. This is a shortcut for getAccessToken() followed by fetchUserFromToken().

```php
$user = $client->fetchUser(); // getAccessToken() + fetchUserFromToken()
```

--------------------------------

### Catching FinishRegistrationException

Source: https://github.com/knpuniversity/oauth2-client-bundle/blob/main/_autodocs/api-reference/security-exceptions.md

Example of catching the exception in an authentication failure handler and redirecting the user to a registration page.

```APIDOC
## Catching FinishRegistrationException

### Description
Example of catching the exception in an authentication failure handler and redirecting the user to a registration page.

### Usage Example
```php
if ($exception instanceof FinishRegistrationException) {
    $this->saveUserInfoToSession($request, $exception);
    return new RedirectResponse($this->router->generate('register_oauth'));
}
```
```

--------------------------------

### Passage OAuth2 Client Configuration

Source: https://github.com/knpuniversity/oauth2-client-bundle/blob/main/README.md

Configures the Passage OAuth2 client. Requires the malteschlueter/oauth2-passage package. Creates the 'knpu.oauth2.client.passage' service. Set OAUTH_PASSAGE_CLIENT_ID and OAUTH_PASSAGE_CLIENT_SECRET environment variables. The 'type' must be 'passage'. 'redirect_route' is a route name you create. 'sub_domain' is required, e.g., 'example' from 'https://example.withpassage.com'. 'use_state' defaults to true.

```yaml
# will create service: "knpu.oauth2.client.passage"
# an instance of: KnpU\OAuth2ClientBundle\Client\Provider\PassageClient
# composer require malteschlueter/oauth2-passage
passage:
    # must be "passage" - it activates that type!
    type: passage
    # add and set these environment variables in your .env files
    client_id: '%env(OAUTH_PASSAGE_CLIENT_ID)%'
    client_secret: '%env(OAUTH_PASSAGE_CLIENT_SECRET)%'
    # a route name you'll create
    redirect_route: connect_passage_check
    redirect_params: {}
    # Passage sub domain. For example, from passage url "https://example.withpassage.com" only "example" is required.
    sub_domain: 'example'
    # whether to check OAuth2 "state": defaults to true
    # use_state: true
```

--------------------------------

### Error handling for getAccessToken()

Source: https://github.com/knpuniversity/oauth2-client-bundle/blob/main/_autodocs/api-reference/oauth2pkceclient.md

Demonstrates catching the three main exception types: LogicException for missing verifier, InvalidStateException for state mismatch, and IdentityProviderException for provider rejection. The LogicException handler restarts the OAuth flow by redirecting to the connect start route.

```php
try {
    $token = $client->getAccessToken();
} catch (\LogicException $e) {
    // verifier missing/expired — restart the OAuth flow (redirect again)
    return $this->redirectToRoute('connect_start');
} catch (\KnpU\OAuth2ClientBundle\Exception\InvalidStateException $e) {
    // state mismatch
} catch (\League\OAuth2\Client\Provider\Exception\IdentityProviderException $e) {
    // provider rejected the exchange
}
```

--------------------------------

### Pass special parameters when creating or refreshing tokens

Source: https://github.com/knpuniversity/oauth2-client-bundle/blob/main/README.md

Some OAuth2 providers require additional parameters when creating or refreshing tokens. Use these examples to pass scopes or other parameters as needed.

```php
// Some providers may require special parameters when creating the token in order to allow refreshing
$accessToken = $client->getAccessToken(['scopes' => 'offline_access']);

// They may also require special parameters when refreshing the token
$accessToken = $client->refreshAccessToken($accessToken->getRefreshtoken(), ['scopes' => 'offline_access']);
```

--------------------------------

### Redirect with extra options and error boundary

Source: https://github.com/knpuniversity/oauth2-client-bundle/blob/main/_autodocs/api-reference/oauth2client.md

Redirects with extra query parameters and catches a LogicException when a session is required but not available. Configure use_state: false or start a session to avoid this error.

```php
try {
    $response = $client->redirect(
        ['public_profile'],
        ['optionA' => 'FOO'] // extra query parameter on the authorization URL
    );
    return $response;
} catch (\LogicException $e) {
    // state mode requires a session — configure use_state: false, or start a session
    throw $this->createNotFoundException('A session is required for the OAuth2 flow.', $e);
}
```

--------------------------------

### Redirect back after login using getPreviousUrl()

Source: https://github.com/knpuniversity/oauth2-client-bundle/blob/main/_autodocs/api-reference/security-helpers.md

Example usage of getPreviousUrl() in an authentication success handler. It redirects to the previously requested URL if available, otherwise to a default homepage route.

```php
public function onAuthenticationSuccess(Request $request, TokenInterface $token, string $firewallName): ?Response
{
    if ($previousUrl = $this->getPreviousUrl($request, $firewallName)) {
        return new RedirectResponse($previousUrl);
    }
    return new RedirectResponse($this->router->generate('app_homepage'));
}
```

--------------------------------

### Save authentication error and redirect on failure

Source: https://github.com/knpuniversity/oauth2-client-bundle/blob/main/_autodocs/api-reference/security-helpers.md

Example usage of saveAuthenticationErrorToSession() in an authentication failure handler. It saves the exception and redirects to a start route when a NoAuthCodeAuthenticationException occurs, otherwise returns null.

```php
public function onAuthenticationFailure(Request $request, AuthenticationException $exception): ?Response
{
    if ($exception instanceof NoAuthCodeAuthenticationException) {
        $this->saveAuthenticationErrorToSession($request, $exception);
        return new RedirectResponse($this->router->generate('connect_facebook_start'));
    }
    return null;
}
```

--------------------------------

### Configure Zendesk OAuth2 client

Source: https://github.com/knpuniversity/oauth2-client-bundle/blob/main/README.md

Configures the Zendesk OAuth2 client. Requires the stevenmaguire/oauth2-zendesk package. Creates service 'knpu.oauth2.client.zendesk' with redirect route 'connect_zendesk_check'. Includes a subdomain setting. State checking defaults to true.

```yaml
# will create service: "knpu.oauth2.client.zendesk"
# an instance of: KnpU\OAuth2ClientBundle\Client\Provider\ZendeskClient
# composer require stevenmaguire/oauth2-zendesk
zendesk:
    # must be "zendesk" - it activates that type!
    type: zendesk
    # add and set these environment variables in your .env files
    client_id: '%env(OAUTH_ZENDESK_CLIENT_ID)%'
    client_secret: '%env(OAUTH_ZENDESK_CLIENT_SECRET)%'
    # a route name you'll create
    redirect_route: connect_zendesk_check
    redirect_params: {}
    # Your Zendesk subdomain
    subdomain: null
    # whether to check OAuth2 "state": defaults to true
    # use_state: true
```

--------------------------------

### Stateless error handling for redirect()

Source: https://github.com/knpuniversity/oauth2-client-bundle/blob/main/_autodocs/api-reference/oauth2pkceclient.md

Demonstrates catching the LogicException thrown when redirect() is called without a session. PKCE requires a session even if use_state is false, so this error indicates a stateless environment.

```php
try {
    return $client->redirect(); // requires a session even if use_state: false
} catch (\LogicException $e) {
    // "You must have a session to utilize the PKCE OAuth2 Client flow..."
    // PKCE is inherently session-based; you cannot combine it with stateless mode
}
```

--------------------------------

### Configure Wave OAuth2 client

Source: https://github.com/knpuniversity/oauth2-client-bundle/blob/main/README.md

Configures the Wave OAuth2 client. Requires the qdequippe/oauth2-wave package. Creates service 'knpu.oauth2.client.wave' with redirect route 'connect_wave_check'. State checking defaults to true.

```yaml
# will create service: "knpu.oauth2.client.wave"
# an instance of: KnpU\OAuth2ClientBundle\Client\Provider\WaveClient
# composer require qdequippe/oauth2-wave
wave:
    # must be "wave" - it activates that type!
    type: wave
    # add and set these environment variables in your .env files
    client_id: '%env(OAUTH_WAVE_CLIENT_ID)%'
    client_secret: '%env(OAUTH_WAVE_CLIENT_SECRET)%'
    # a route name you'll create
    redirect_route: connect_wave_check
    redirect_params: {}
    # whether to check OAuth2 "state": defaults to true
    # use_state: true
```

--------------------------------

### Bitbucket OAuth2 Client Configuration

Source: https://github.com/knpuniversity/oauth2-client-bundle/blob/main/README.md

Configures the Bitbucket OAuth2 client, creating service 'knpu.oauth2.client.bitbucket' as an instance of KnpU\OAuth2ClientBundle\Client\Provider\BitbucketClient. Requires composer package stevenmaguire/oauth2-bitbucket. Includes environment variables for client ID and secret, redirect route, and optional state checking.

```yaml
# will create service: "knpu.oauth2.client.bitbucket"
        # an instance of: KnpU\OAuth2ClientBundle\Client\Provider\BitbucketClient
        # composer require stevenmaguire/oauth2-bitbucket
        bitbucket:
            # must be "bitbucket" - it activates that type!
            type: bitbucket
            # add and set these environment variables in your .env files
            client_id: '%env(OAUTH_BITBUCKET_CLIENT_ID)%'
            client_secret: '%env(OAUTH_BITBUCKET_CLIENT_SECRET)%'
            # a route name you'll create
            redirect_route: connect_bitbucket_check
            redirect_params: {}
            # whether to check OAuth2 "state": defaults to true
            # use_state: true
```

--------------------------------

### FusionAuth OAuth2 Client Configuration

Source: https://github.com/knpuniversity/oauth2-client-bundle/blob/main/README.md

Configures the FusionAuth OAuth2 client, creating the 'knpu.oauth2.client.fusion_auth' service. Requires the jerryhopper/oauth2-fusionauth package and environment variables OAUTH_FUSION_AUTH_CLIENT_ID and OAUTH_FUSION_AUTH_CLIENT_SECRET. The redirect route 'connect_fusion_auth_check' must be created, and the auth_server_url must be set to the FusionAuth server URL without a trailing slash.

```yaml
# will create service: "knpu.oauth2.client.fusion_auth"
# an instance of: KnpU\OAuth2ClientBundle\Client\Provider\FusionAuthClient
# composer require jerryhopper/oauth2-fusionauth
fusion_auth:
    # must be "fusion_auth" - it activates that type!
    type: fusion_auth
    # add and set these environment variables in your .env files
    client_id: '%env(OAUTH_FUSION_AUTH_CLIENT_ID)%'
    client_secret: '%env(OAUTH_FUSION_AUTH_CLIENT_SECRET)%'
    # a route name you'll create
    redirect_route: connect_fusion_auth_check
    redirect_params: {}
    # FusionAuth Server URL, no trailing slash
    auth_server_url: null
    # whether to check OAuth2 "state": defaults to true
    # use_state: true
```

--------------------------------

### Microsoft OAuth2 Client Configuration

Source: https://github.com/knpuniversity/oauth2-client-bundle/blob/main/README.md

Configures the Microsoft OAuth2 client. Requires the stevenmaguire/oauth2-microsoft package. Creates the 'knpu.oauth2.client.microsoft' service. Set OAUTH_MICROSOFT_CLIENT_ID and OAUTH_MICROSOFT_CLIENT_SECRET environment variables. The 'type' must be 'microsoft'. 'redirect_route' is a route name you create. Optional URL overrides are available. 'use_state' defaults to true.

```yaml
# will create service: "knpu.oauth2.client.microsoft"
# an instance of: KnpU\OAuth2ClientBundle\Client\Provider\MicrosoftClient
# composer require stevenmaguire/oauth2-microsoft
microsoft:
    # must be "microsoft" - it activates that type!
    type: microsoft
    # add and set these environment variables in your .env files
    client_id: '%env(OAUTH_MICROSOFT_CLIENT_ID)%'
    client_secret: '%env(OAUTH_MICROSOFT_CLIENT_SECRET)%'
    # a route name you'll create
    redirect_route: connect_microsoft_check
    redirect_params: {}
    # Optional value for URL Authorize
    # url_authorize: null
    # Optional value for URL Access Token
    # url_access_token: null
    # Optional value for URL Resource Owner Details
    # url_resource_owner_details: null
    # whether to check OAuth2 "state": defaults to true
    # use_state: true
```

--------------------------------

### Catching OAuth2ClientException

Source: https://github.com/knpuniversity/oauth2-client-bundle/blob/main/_autodocs/types.md

Example of catching the marker interface to handle InvalidStateException or MissingAuthorizationCodeException. Note that League IdentityProviderException is not covered.

```php
use KnpU\OAuth2ClientBundle\Exception\OAuth2ClientException;

try {
    $token = $client->getAccessToken();
} catch (OAuth2ClientException $e) {
    // InvalidStateException or MissingAuthorizationCodeException
    // (League IdentityProviderException is NOT covered)
}
```

--------------------------------

### Handling InvalidStateAuthenticationException with redirect

Source: https://github.com/knpuniversity/oauth2-client-bundle/blob/main/_autodocs/api-reference/security-exceptions.md

Example of checking for InvalidStateAuthenticationException and redirecting to restart the OAuth flow when a state mismatch occurs.

```php
if ($exception instanceof InvalidStateAuthenticationException) {
    // state mismatch — restart the OAuth flow
    return new RedirectResponse($this->router->generate('connect_start'));
}
```

--------------------------------

### refreshAccessToken() basic usage

Source: https://github.com/knpuniversity/oauth2-client-bundle/blob/main/_autodocs/api-reference/oauth2client.md

Basic usage refreshing a stored refresh token to get a new access token.

```php
$accessToken = $client->refreshAccessToken($storedRefreshToken);
```

--------------------------------

### Buddy OAuth2 Client Configuration

Source: https://github.com/knpuniversity/oauth2-client-bundle/blob/main/README.md

Configures the Buddy OAuth2 client, creating service 'knpu.oauth2.client.buddy' as an instance of KnpU\OAuth2ClientBundle\Client\Provider\BuddyClient. Requires composer package buddy-works/oauth2-client. Includes environment variables for client ID and secret, redirect route, and optional base API URL and state checking.

```yaml
# will create service: "knpu.oauth2.client.buddy"
        # an instance of: KnpU\OAuth2ClientBundle\Client\Provider\BuddyClient
        # composer require buddy-works/oauth2-client
        buddy:
            # must be "buddy" - it activates that type!
            type: buddy
            # add and set these environment variables in your .env files
            client_id: '%env(OAUTH_BUDDY_CLIENT_ID)%'
            client_secret: '%env(OAUTH_BUDDY_CLIENT_SECRET)%'
            # a route name you'll create
            redirect_route: connect_buddy_check
            redirect_params: {}
            # Base API URL, modify this for self-hosted instances
            # base_api_url: https://api.buddy.works
            # whether to check OAuth2 "state": defaults to true
            # use_state: true
```

--------------------------------

### getOAuth2Provider() basic usage

Source: https://github.com/knpuniversity/oauth2-client-bundle/blob/main/_autodocs/api-reference/oauth2client.md

Retrieves the underlying provider and calls a provider-specific method. The example shows Facebook's getLongLivedAccessToken().

```php
$provider = $client->getOAuth2Provider(); // League\OAuth2\Client\Provider\Facebook
$longLivedToken = $provider->getLongLivedAccessToken($accessToken);
```

--------------------------------

### Basic usage of getAccessToken()

Source: https://github.com/knpuniversity/oauth2-client-bundle/blob/main/_autodocs/api-reference/oauth2pkceclient.md

Shows the simplest way to obtain an access token after the user has been redirected back. Requires a valid session and code verifier; otherwise throws a LogicException.

```php
$accessToken = $client->getAccessToken();
```

--------------------------------

### Configure VKontakte OAuth2 client

Source: https://github.com/knpuniversity/oauth2-client-bundle/blob/main/README.md

Configures the VKontakte OAuth2 client. Requires the j4k/oauth2-vkontakte package. Creates service 'knpu.oauth2.client.vkontakte' with redirect route 'connect_vkontakte_check'. State checking defaults to true.

```yaml
# will create service: "knpu.oauth2.client.vkontakte"
# an instance of: KnpU\OAuth2ClientBundle\Client\Provider\VKontakteClient
# composer require j4k/oauth2-vkontakte
vkontakte:
    # must be "vkontakte" - it activates that type!
    type: vkontakte
    # add and set these environment variables in your .env files
    client_id: '%env(OAUTH_VKONTAKTE_CLIENT_ID)%'
    client_secret: '%env(OAUTH_VKONTAKTE_CLIENT_SECRET)%'
    # a route name you'll create
    redirect_route: connect_vkontakte_check
    redirect_params: {}
    # whether to check OAuth2 "state": defaults to true
    # use_state: true
```

--------------------------------

### Configure Spotify OAuth2 client

Source: https://github.com/knpuniversity/oauth2-client-bundle/blob/main/README.md

Configures the Spotify OAuth2 client. Requires the kerox/oauth2-spotify package. Set OAUTH_SPOTIFY_CLIENT_ID and OAUTH_SPOTIFY_CLIENT_SECRET environment variables. Optionally set use_state to false to disable state checking.

```yaml
# will create service: "knpu.oauth2.client.spotify"
# an instance of: KnpU\OAuth2ClientBundle\Client\Provider\SpotifyClient
# composer require kerox/oauth2-spotify
spotify:
    # must be "spotify" - it activates that type!
    type: spotify
    # add and set these environment variables in your .env files
    client_id: '%env(OAUTH_SPOTIFY_CLIENT_ID)%'
    client_secret: '%env(OAUTH_SPOTIFY_CLIENT_SECRET)%'
    # a route name you'll create
    redirect_route: connect_spotify_check
    redirect_params: {}
    # whether to check OAuth2 "state": defaults to true
    # use_state: true
```

--------------------------------

### OAuth2PKCEClient::redirect()

Source: https://github.com/knpuniversity/oauth2-client-bundle/blob/main/_autodocs/api-reference/oauth2pkceclient.md

Generates a PKCE code verifier, stores it in the session, computes the S256 challenge, and redirects the user to the authorization server with the code challenge parameters.

```APIDOC
## OAuth2PKCEClient::redirect()

### Description
Generates a PKCE code verifier, stores it in the session, computes the S256 challenge, and delegates to the parent redirect() method with the code_challenge and code_challenge_method parameters. Requires a session.

### Method
redirect

### Signature
public function redirect(array $scopes = [], array $options = [])

### Parameters
- **$scopes** (array) - Optional - Default: [] - Forwarded to parent::redirect().
- **$options** (array) - Optional - Default: [] - Forwarded to parent::redirect(); merged below the generated PKCE params, so the bundle's code_challenge/code_challenge_method win.

### Return
Symfony\Component\HttpFoundation\RedirectResponse

### Throws
- \LogicException - When the current request has no session. Message: 'You must have a session to utilize the PKCE OAuth2 Client flow. Ensure you are not utilizing PKCE in a stateless environment.'

### Behavior
1. Generates the verifier: $code_verifier = bin2hex(random_bytes(64)) (128 hex chars).
2. Stores it in the session under static::VERIFIER_KEY.
3. Computes the S256 challenge: base64url (+/ → -_, padded = stripped) of the SHA-256 hash of the verifier.
4. Delegates to parent::redirect($scopes, $options + $pkce) with code_challenge and code_challenge_method = 'S256' added.

### Usage Example
```php
// via registry: keycloak_pkce type yields a KeycloakPkceClient which extends OAuth2PKCEClient
return $clientRegistry->getClient('keycloak_pkce_main')->redirect(['openid']);
```

### Usage Example (stateless error handling)
```php
try {
    return $client->redirect(); // requires a session even if use_state: false
} catch (\LogicException $e) {
    // "You must have a session to utilize the PKCE OAuth2 Client flow..."
    // PKCE is inherently session-based; you cannot combine it with stateless mode
}
```
```

--------------------------------

### load method signature

Source: https://github.com/knpuniversity/oauth2-client-bundle/blob/main/_autodocs/api-reference/knpuoauth2clientbundle.md

Processes configuration and registers provider/client services. Throws InvalidConfigurationException for invalid config and LogicException for missing provider classes.

```php
public function load(array $configs, ContainerBuilder $container): void
```

--------------------------------

### Configure Vimeo OAuth2 Client

Source: https://github.com/knpuniversity/oauth2-client-bundle/blob/main/README.md

YAML configuration for the Vimeo OAuth2 client. Creates service 'knpu.oauth2.client.vimeo' with type 'vimeo'. Requires composer package saf33r/oauth2-vimeo and environment variables OAUTH_VIMEO_CLIENT_ID and OAUTH_VIMEO_CLIENT_SECRET. Redirect route is 'connect_vimeo_check'.

```yaml
# will create service: "knpu.oauth2.client.vimeo"
# an instance of: KnpU\OAuth2ClientBundle\Client\Provider\VimeoClient
# composer require saf33r/oauth2-vimeo
vimeo:
    # must be "vimeo" - it activates that type!
    type: vimeo
    # add and set these environment variables in your .env files
    client_id: '%env(OAUTH_VIMEO_CLIENT_ID)%'
    client_secret: '%env(OAUTH_VIMEO_CLIENT_SECRET)%'
    # a route name you'll create
    redirect_route: connect_vimeo_check
    redirect_params: {}
    # whether to check OAuth2 "state": defaults to true
    # use_state: true
```

--------------------------------

### KnpUOAuth2ClientExtension::load()

Source: https://github.com/knpuniversity/oauth2-client-bundle/blob/main/_autodocs/api-reference/knpuoauth2clientbundle.md

Processes knpu_oauth2_client configuration and registers provider/client services. Validates client configs, builds per-client config trees, and registers services in the container.

```APIDOC
## KnpUOAuth2ClientExtension::load()

### Description
Processes knpu_oauth2_client configuration and registers provider/client services. Validates client configs, builds per-client config trees, and registers services in the container.

### Method
`load()`

### Signature
```php
public function load(array $configs, ContainerBuilder $container): void
```

### Parameters
- **$configs** (array) - Required - Raw configuration arrays (as merged by the framework)
- **$container** (ContainerBuilder) - Required - The container to populate

### Return Value
`void`

### Throws
- `Symfony\Component\Config\Definition\Exception\InvalidConfigurationException` — when a client config entry is missing the `type` key, when `type` is not supported, or when the per-client config tree validation fails (missing required keys, etc.).
- `\LogicException` — when `checkExternalClassExistence` is `true` and the provider class does not exist. For known types: `` Run `composer require <package>` in order to use the "<type>" OAuth provider. ``; for the `generic` type: `` The provider class `<class>` must exist in order to use with the "generic" OAuth provider. ``

### Behavior
1. Processes the top-level config with `Configuration`.
2. Loads the base services from `src/Resources/config/services.php`.
3. For each entry under `clients`:
   - requires a `type` key,
   - validates the type against `$supportedProviderTypes`,
   - builds and processes a per-client config tree (`buildConfigurationForType()` adds `client_id` (required), `client_secret` (required unless the configurator implements `ProviderWithoutClientSecretConfiguratorInterface` and returns `false` from `needsClientSecret()`), `redirect_route` (required), `redirect_params` (scalar prototype), `use_state` (default `true`), then the configurator's own options),
   - resolves the configurator, calls `getProviderOptions($config)`,
   - if `http_client` is set, passes `['httpClient' => new Reference($httpClient)]` as collaborators, otherwise merges `http_client_options` into the provider options,
   - calls `configureProviderAndClient()` which registers `knpu.oauth2.provider.<key>` (private, factory `ProviderFactory::createProvider`) and `knpu.oauth2.client.<key>` (public, constructor args `[Reference(provider), Reference('request_stack')]`),
   - when `use_state` is `false`, adds a `setAsStateless` method call to the client definition,
   - registers a service alias from the client class to `knpu.oauth2.client.<key>` only if that provider type has not been used more than once (duplicate types are tracked in `$duplicateProviderTypes`).
4. Replaces argument 1 (the service map) of the `knpu.oauth2.registry` definition with the map `[configKey => clientServiceId]`.
```

--------------------------------

### Handle NoAuthCodeAuthenticationException with RedirectResponse

Source: https://github.com/knpuniversity/oauth2-client-bundle/blob/main/_autodocs/api-reference/security-exceptions.md

Use this snippet to catch a NoAuthCodeAuthenticationException, typically when the user has denied access to the OAuth application. Redirect the user to a friendly page or the connection start route.

```php
if ($exception instanceof NoAuthCodeAuthenticationException) {
    // user denied the app — show a friendly message or redirect
    return new RedirectResponse($this->router->generate('connect_start'));
}
```

--------------------------------

### Fitbit OAuth2 Client Configuration

Source: https://github.com/knpuniversity/oauth2-client-bundle/blob/main/README.md

Configures the Fitbit OAuth2 client, creating the 'knpu.oauth2.client.fitbit' service. Requires the djchen/oauth2-fitbit package and environment variables OAUTH_FITBIT_CLIENT_ID and OAUTH_FITBIT_CLIENT_SECRET. The redirect route 'connect_fitbit_check' must be created.

```yaml
# will create service: "knpu.oauth2.client.fitbit"
# an instance of: KnpU\OAuth2ClientBundle\Client\Provider\FitbitClient
# composer require djchen/oauth2-fitbit
fitbit:
    # must be "fitbit" - it activates that type!
    type: fitbit
    # add and set these environment variables in your .env files
    client_id: '%env(OAUTH_FITBIT_CLIENT_ID)%'
    client_secret: '%env(OAUTH_FITBIT_CLIENT_SECRET)%'
    # a route name you'll create
    redirect_route: connect_fitbit_check
    redirect_params: {}
    # whether to check OAuth2 "state": defaults to true
    # use_state: true
```
Tokens:
Raw