How to Log in Users with OpenID Connect

Installation

The authenticator talks to the provider with the HttpClient component, and validates the ID token with the web-token/jwt-library package. Install both first:

1

$ composer require symfony/http-client web-token/jwt-library

1) Configure the Authenticator

Enable oidc_login in the firewall. Every client needs three options: the issuer URL of your provider, the client identifier that the provider issued to your application, and how your application authenticates at the token endpoint of the provider:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# config/packages/security.yaml
security:
    providers:
        oidc_provider_name:
            oidc: ~

    firewalls:
        main:
            provider: oidc_provider_name
            oidc_login:
                provider_uri: '%env(OIDC_PROVIDER_URI)%'
                client_id: '%env(OIDC_CLIENT_ID)%'
                client_authentication:
                    client_secret_basic: '%env(OIDC_CLIENT_SECRET)%'
                scope: ['openid', 'profile', 'email']

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

// config/packages/security.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

return App::config([
    'security' => [
        'providers' => [
            'oidc_provider_name' => [
                'oidc' => null,
            ],
        ],

        'firewalls' => [
            'main' => [
                'provider' => 'oidc_provider_name',
                'oidc_login' => [
                    'provider_uri' => '%env(OIDC_PROVIDER_URI)%',
                    'client_id' => '%env(OIDC_CLIENT_ID)%',
                    'client_authentication' => [
                        'client_secret_basic' => '%env(OIDC_CLIENT_SECRET)%',
                    ],
                    'scope' => ['openid', 'profile', 'email'],
                ],
            ],
        ],
    ],
]);

provider_uri is the issuer URL (e.g. https://accounts.example.com). The authenticator fetches .well-known/openid-configuration from it to discover the authorization, token and UserInfo endpoints, so you don't have to configure them. The discovery document is cached for one hour by default (change it with the discovery_cache_ttl option).

client_id identifies your application to the provider. The authenticator sends it in the authorization request and checks the aud claim of the ID token against it.

client_authentication defines how your application authenticates at the token endpoint when it exchanges the authorization code for tokens. client_secret_basic sends the client secret issued by the provider; the other methods are explained in How to Log in Users with OpenID Connect.

The provider redirects users back to check_path, which is /oidc/callback by default. Register the full URL of this path as a redirect URI in the provider (e.g. https://example.com/oidc/callback).

2) Import the OIDC Routes

The callback path needs a route; otherwise, the router returns a 404 error before the firewall can handle the redirect of the provider. Symfony defines this route (and the route that starts the flow, explained in the next section) in a route loader that your application must import, as it does for the logout routes. If your project uses Symfony Flex, the SecurityBundle recipe already imports it. Otherwise, import it yourself:

1
2
3
4

# config/routes/security.yaml
_security_oidc_login:
    resource: security.authenticator.oidc_login.route_loader
    type: service

1
2
3
4
5
6
7
8
9

// config/routes/security.php
namespace Symfony\Component\Routing\Loader\Configurator;

return Routes::config([
    '_security_oidc_login' => [
        'resource' => 'security.authenticator.oidc_login.route_loader',
        'type' => 'service',
    ],
]);

The loader names the routes after the firewall: _oidc_login_callback_<firewallname> and _oidc_login_start_<firewallname> (e.g. _oidc_login_callback_main). Use these names to generate their URLs.

If check_path or start_path is a route name instead of a path, the loader doesn't define a route for it, so you must define it yourself. Two firewalls can share the same callback path, but not the same start path, because the start route is tied to the firewall whose flow it starts.

3) Start the Flow

When oidc_login is the only authenticator of the firewall that can start the authentication, it also becomes the entry point of the firewall: when an anonymous user requests a protected page, Symfony redirects them to the authorization endpoint of the provider. You don't need anything else to log in users.

If the firewall uses other authenticators that can start the authentication (e.g. form_login), set the entry_point option of the firewall to the one you want to use; otherwise, Symfony throws an exception when compiling the container.

To display a "Log in with ..." button (e.g. in a login page that lists several ways to log in), link to the _oidc_login_start_<firewallname> route imported in the previous section. This route redirects to the provider. Its path is /oidc/start by default, and you can change it with the start_path option:

1

<a href="{{ path('_oidc_login_start_main') }}">Log in with Example</a>

Don't link to check_path, because it only handles the redirect coming back from the provider and rejects any request that doesn't include an authorization code.

1
2
3
4
5
6
7

# config/packages/security.yaml
security:
    firewalls:
        main:
            oidc_login:
                # ...
                failure_path: app_login_failed

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

// config/packages/security.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

return App::config([
    'security' => [
        'firewalls' => [
            'main' => [
                'oidc_login' => [
                    // ...
                    'failure_path' => 'app_login_failed',
                ],
            ],
        ],
    ],
]);

4) Load the User

After validating the ID token, the authenticator fetches the user claims from the UserInfo endpoint of the provider. Then, the user provider of the firewall loads the user using the sub claim as the identifier, and receives all the claims as attributes. You can change both the source of the claims and the identifier claim, as explained later in this section.

The built-in oidc user provider shown above creates an OidcUser object from those claims. It's a convenient way to get started, but it has two limitations:

• Claims can't grant roles or define the identity of the user: all users get ROLE_USER, and the roles and user_identifier claims sent by the identity provider are ignored;
• It can't load users by their identifier alone, so it doesn't work with user impersonation.

To map claims to your own roles or to load users from your own storage, create a custom user provider. If it implements AttributesBasedUserProviderInterface, it receives the claims as the second argument of loadUserByIdentifier():

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

// src/Security/OidcUserProvider.php
namespace App\Security;

use App\Entity\User;
use Doctrine\ORM\EntityManagerInterface;
use Symfony\Component\Security\Core\User\AttributesBasedUserProviderInterface;
use Symfony\Component\Security\Core\User\UserInterface;

/**
 * @implements AttributesBasedUserProviderInterface<User>
 */
class OidcUserProvider implements AttributesBasedUserProviderInterface
{
    public function __construct(
        private EntityManagerInterface $entityManager,
    ) {
    }

    // $identifier is the "sub" claim by default; $attributes has all claims
    public function loadUserByIdentifier(
        string $identifier,
        array $attributes = [],
    ): UserInterface {
        $user = $this->entityManager->getRepository(User::class)
            ->findOneBy(['oidcSubject' => $identifier]) ?? new User($identifier);

        $isAdmin = \in_array('admins', $attributes['groups'] ?? [], true);
        $user->setEmail($attributes['email'] ?? null);
        $user->setRoles($isAdmin ? ['ROLE_ADMIN'] : []);

        $this->entityManager->persist($user);
        $this->entityManager->flush();

        return $user;
    }

    // ...
}

Use the scope option to request the claims you need. The authenticator always requests the openid scope, because OIDC requires it; add scopes like profile or email to get their related claims.

The authenticator stores the tokens returned by the provider as attributes of the security token, so you can use them to call the APIs of the provider:

1
2
3
4
5
6

$token = $security->getToken();

$accessToken = $token->getAttribute('oidc_access_token');
$idToken = $token->getAttribute('oidc_id_token');
$refreshToken = $token->getAttribute('oidc_refresh_token');
$expiresAt = $token->getAttribute('oidc_access_token_expires_at');

The last two attributes are null when the provider doesn't return them. Providers only issue a refresh token when you request it (on most providers, with the offline_access scope), and expires_in is optional in the token response. Read How to Log in Users with OpenID Connect to learn how to renew the access token using the refresh token.

1
2
3
4
5
6
7

# config/packages/security.yaml
security:
    firewalls:
        main:
            oidc_login:
                # ...
                user_data_source: id_token

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

// config/packages/security.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

return App::config([
    'security' => [
        'firewalls' => [
            'main' => [
                'oidc_login' => [
                    // ...
                    'user_data_source' => 'id_token',
                ],
            ],
        ],
    ],
]);

1
2
3
4
5
6
7

# config/packages/security.yaml
security:
    firewalls:
        main:
            oidc_login:
                # ...
                user_identifier_claim: email

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

// config/packages/security.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

return App::config([
    'security' => [
        'firewalls' => [
            'main' => [
                'oidc_login' => [
                    // ...
                    'user_identifier_claim' => 'email',
                ],
            ],
        ],
    ],
]);

Customizing the Authorization Request

The authenticator manages the parameters required by the flow: response_type, client_id, redirect_uri, scope, state, nonce, max_age and the PKCE parameters. Symfony throws an exception if you try to set any of them. Add any other parameter supported by your provider in the authorization_params option:

1
2
3
4
5
6
7
8
9

# config/packages/security.yaml
security:
    firewalls:
        main:
            oidc_login:
                # ...
                authorization_params:
                    prompt: 'consent'
                    ui_locales: 'fr-FR'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

// config/packages/security.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

return App::config([
    'security' => [
        'firewalls' => [
            'main' => [
                'oidc_login' => [
                    // ...
                    'authorization_params' => [
                        'prompt' => 'consent',
                        'ui_locales' => 'fr-FR',
                    ],
                ],
            ],
        ],
    ],
]);

OIDC Core 1.0, Section 3.1.2.1 defines the prompt, display, ui_locales, acr_values and login_hint parameters for this request. Providers can also support other custom parameters.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

// src/Security/OidcAuthorizationRequestListener.php
namespace App\Security;

use Symfony\Component\EventDispatcher\Attribute\AsEventListener;
use Symfony\Component\Security\Http\Event\OidcAuthorizationRequestEvent;

#[AsEventListener]
final class OidcAuthorizationRequestListener
{
    public function __invoke(OidcAuthorizationRequestEvent $event): void
    {
        $request = $event->getRequest();

        $event->setParam('ui_locales', $request->getLocale());

        if ($email = $request->getSession()->get('login_email')) {
            $event->setParam('login_hint', $email);
        } else {
            $event->removeParam('login_hint');
        }
    }
}

1
2
3
4
5
6
7

# config/packages/security.yaml
security:
    firewalls:
        main:
            oidc_login:
                # ...
                max_age: 300

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

// config/packages/security.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

return App::config([
    'security' => [
        'firewalls' => [
            'main' => [
                'oidc_login' => [
                    // ...
                    'max_age' => 300,
                ],
            ],
        ],
    ],
]);

1
2
3
4
5
6
7
8
9

# config/packages/security.yaml
security:
    firewalls:
        main:
            oidc_login:
                # ...
                pkce:
                    enabled: true
                    method: 'plain'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

// config/packages/security.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

return App::config([
    'security' => [
        'firewalls' => [
            'main' => [
                'oidc_login' => [
                    // ...
                    'pkce' => [
                        'enabled' => true,
                        'method' => 'plain',
                    ],
                ],
            ],
        ],
    ],
]);

Authenticating at the Token Endpoint

When exchanging the authorization code for tokens, your application authenticates at the token endpoint using the method configured in client_authentication. This option must define exactly one of the following keys:

client_secret_basic

Sends the client secret as HTTP Basic credentials. This is the method recommended by RFC 6749, Section 2.3.1, so use it when the provider supports it.

client_secret_post

Sends the client secret in the body of the token request. Use it only for providers that don't support any other method.

client_secret_jwt and private_key_jwt

Sign a JWT assertion instead of sending the secret (see How to Log in Users with OpenID Connect).

none

Declares a public client: an application that can't keep a secret (e.g. a single-page, mobile or native application). It relies on PKCE to protect the code exchange, and it can't disable PKCE or the ID token signature verification. client_authentication: none is the short form.

id

The id of a service that implements a custom authentication method (see How to Log in Users with OpenID Connect). Any string other than none is the short form (e.g. client_authentication: app.tls_client_auth).

Use the method registered for your application in the provider. Providers list the methods they support in the token_endpoint_auth_methods_supported entry of their discovery document. For example, to send the secret in the body of the request:

1
2
3
4
5
6
7
8

# config/packages/security.yaml
security:
    firewalls:
        main:
            oidc_login:
                # ...
                client_authentication:
                    client_secret_post: '%env(OIDC_CLIENT_SECRET)%'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

// config/packages/security.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

return App::config([
    'security' => [
        'firewalls' => [
            'main' => [
                'oidc_login' => [
                    // ...
                    'client_authentication' => [
                        'client_secret_post' => '%env(OIDC_CLIENT_SECRET)%',
                    ],
                ],
            ],
        ],
    ],
]);

To declare a public client, set client_authentication to none:

1
2
3
4
5
6
7
8

# config/packages/security.yaml
security:
    firewalls:
        main:
            oidc_login:
                provider_uri: '%env(OIDC_PROVIDER_URI)%'
                client_id: '%env(OIDC_CLIENT_ID)%'
                client_authentication: none

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

// config/packages/security.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

return App::config([
    'security' => [
        'firewalls' => [
            'main' => [
                'oidc_login' => [
                    'provider_uri' => '%env(OIDC_PROVIDER_URI)%',
                    'client_id' => '%env(OIDC_CLIENT_ID)%',
                    'client_authentication' => 'none',
                ],
            ],
        ],
    ],
]);

1
2
3
4
5
6
7
8
9
10
11

# config/packages/security.yaml
security:
    firewalls:
        main:
            oidc_login:
                # ...
                client_authentication:
                    private_key_jwt:
                        key: '%env(OIDC_CLIENT_SIGNING_KEY)%'
                        algorithm: 'ES256'
                        lifetime: 60

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

// config/packages/security.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

return App::config([
    'security' => [
        'firewalls' => [
            'main' => [
                'oidc_login' => [
                    // ...
                    'client_authentication' => [
                        'private_key_jwt' => [
                            'key' => '%env(OIDC_CLIENT_SIGNING_KEY)%',
                            'algorithm' => 'ES256',
                            'lifetime' => 60,
                        ],
                    ],
                ],
            ],
        ],
    ],
]);

1
2
3
4
5
6
7
8

# config/packages/security.yaml
security:
    firewalls:
        main:
            oidc_login:
                # ...
                client_authentication:
                    client_secret_jwt: '%env(OIDC_CLIENT_SECRET)%'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

// config/packages/security.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

return App::config([
    'security' => [
        'firewalls' => [
            'main' => [
                'oidc_login' => [
                    // ...
                    'client_authentication' => [
                        'client_secret_jwt' => '%env(OIDC_CLIENT_SECRET)%',
                    ],
                ],
            ],
        ],
    ],
]);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

// src/Security/TlsClientAuthentication.php
namespace App\Security;

use Symfony\Component\Security\Http\OAuth2\ClientAuthentication\ClientAuthenticationInterface;

final class TlsClientAuthentication implements ClientAuthenticationInterface
{
    public function __construct(
        private string $certificatePath,
        private string $privateKeyPath,
    ) {
    }

    public function authenticate(
        string $clientId,
        string $tokenEndpoint,
        array $options,
    ): array {
        // the TLS client certificate authenticates the client, which must
        // also include its ID in the request body (RFC 8705, Section 2)
        $options['body']['client_id'] = $clientId;
        $options['local_cert'] = $this->certificatePath;
        $options['local_pk'] = $this->privateKeyPath;

        return $options;
    }

    public function getMethod(): string
    {
        return 'tls_client_auth';
    }
}

1
2
3
4
5
6
7

# config/packages/security.yaml
security:
    firewalls:
        main:
            oidc_login:
                # ...
                client_authentication: app.tls_client_auth

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

// config/packages/security.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

return App::config([
    'security' => [
        'firewalls' => [
            'main' => [
                'oidc_login' => [
                    // ...
                    'client_authentication' => 'app.tls_client_auth',
                ],
            ],
        ],
    ],
]);

Verifying the ID Token Signature

The authenticator verifies the signature of the ID token by default. It gets the signing keys from the jwks_uri announced by the provider in its discovery document (this URL must use HTTPS, like all the other endpoints). The keys are cached for the lifetime advertised by the provider in that response (up to 30 days), or for discovery_cache_ttl seconds if the provider doesn't advertise any lifetime. If an ID token is signed with a key that isn't in the cache, the authenticator fetches the keys again, so you don't have to do anything when the provider rotates its keys.

By default, only the RS256 algorithm is accepted, because it's the only one that OIDC providers are required to support. If your provider uses other algorithms, list them in the algorithms option:

1
2
3
4
5
6
7
8

# config/packages/security.yaml
security:
    firewalls:
        main:
            oidc_login:
                # ...
                id_token_signature:
                    algorithms: ['ES256']

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

// config/packages/security.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

return App::config([
    'security' => [
        'firewalls' => [
            'main' => [
                'oidc_login' => [
                    // ...
                    'id_token_signature' => [
                        'algorithms' => ['ES256'],
                    ],
                ],
            ],
        ],
    ],
]);

The accepted algorithms are RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384 and PS512. Your provider lists the algorithms it uses in the id_token_signing_alg_values_supported entry of its discovery document. HMAC algorithms are not accepted, to prevent using a public key of the provider as a shared secret.

By default, only the keys that the provider explicitly designates for signing are used. Set id_token_signature.enforce_key_usage_verification to false to also accept keys that don't define any usage. Keys that are restricted to encryption are always rejected. This option works the same as in the OIDC access token handler.

Configuring the HTTP Client

The authenticator makes all its requests to the provider (discovery document, JWKS, token endpoint and UserInfo endpoint) with the http_client service. Some providers require a User-Agent header that identifies your application (and use it for quotas and diagnostics), and you might also want to define your own timeout or retry strategy. Use the http_client option to set the id of the HTTP client used in all those requests:

1
2
3
4
5
6
7

# config/packages/security.yaml
security:
    firewalls:
        main:
            oidc_login:
                # ...
                http_client: oidc.client

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

// config/packages/security.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

return App::config([
    'security' => [
        'firewalls' => [
            'main' => [
                'oidc_login' => [
                    // ...
                    'http_client' => 'oidc.client',
                ],
            ],
        ],
    ],
]);

oidc.client can be any service that implements HttpClientInterface. Usually, it's a scoped client (see HTTP Client):

1
2
3
4
5
6
7
8
9

# config/packages/framework.yaml
framework:
    http_client:
        scoped_clients:
            oidc.client:
                scope: 'https://accounts\.example\.com'
                headers: { 'User-Agent': 'AcmeApp/1.0 (+https://example.com)' }
                timeout: 5
                retry_failed: { max_retries: 2 }

If the provider uses several hosts for its endpoints, create the client with withOptions() instead, so its options apply to all requests, whatever their host:

1
2
3
4
5
6
7
8

# config/services.yaml
services:
    oidc.client:
        class: Symfony\Contracts\HttpClient\HttpClientInterface
        factory: ['@http_client', 'withOptions']
        arguments:
            - headers: { 'User-Agent': 'AcmeApp/1.0 (+https://example.com)' }
              timeout: 5

Renewing the Access Token

Access tokens are short-lived (they usually expire after a few minutes). To keep calling the APIs of the provider on behalf of the logged-in user, Symfony can renew the access token with the refresh token grant defined in RFC 6749, Section 6. Providers only issue a refresh token when you request it, so add the scope required by your provider (offline_access on most providers) to the scope option.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

// src/Service/ProviderApiClient.php
namespace App\Service;

use Symfony\Bundle\SecurityBundle\Security;
use Symfony\Component\DependencyInjection\Attribute\Autowire;
use Symfony\Component\Security\Http\Authenticator\Oidc\OidcTokenRefresher;
use Symfony\Contracts\HttpClient\HttpClientInterface;

class ProviderApiClient
{
    public function __construct(
        #[Autowire(
            service: 'security.authenticator.oidc_login.token_refresher.main',
        )]
        private OidcTokenRefresher $refresher,
        private Security $security,
        private HttpClientInterface $client,
    ) {
    }

    public function fetchProfile(): array
    {
        $token = $this->security->getToken();
        if (null === $token) {
            throw new \LogicException('The API requires a logged-in user.');
        }

        $this->refresher->refreshIfNeeded($token);

        return $this->client->request('GET', 'https://api.example.com/me', [
            'auth_bearer' => $token->getAttribute('oidc_access_token'),
        ])->toArray();
    }
}

1
2
3
4
5
6
7
8
9
10

# config/packages/security.yaml
security:
    firewalls:
        main:
            oidc_login:
                # ...
                scope: ['openid', 'profile', 'offline_access']
                refresh_access_token:
                    enabled: true
                    leeway: 30

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

// config/packages/security.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

return App::config([
    'security' => [
        'firewalls' => [
            'main' => [
                'oidc_login' => [
                    // ...
                    'scope' => ['openid', 'profile', 'offline_access'],
                    'refresh_access_token' => [
                        'enabled' => true,
                        'leeway' => 30,
                    ],
                ],
            ],
        ],
    ],
]);

Logging Out

Logging out works as usual. By default, it only ends the session in your application: the user is still logged in to the identity provider, so the next time they open a protected page, they are logged in again without being asked for their credentials.

1
2
3
4
5
6
7
8

# config/packages/security.yaml
security:
    firewalls:
        main:
            oidc_login:
                # ...
                enable_end_session: true
                post_logout_redirect_path: /

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

// config/packages/security.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

return App::config([
    'security' => [
        'firewalls' => [
            'main' => [
                'oidc_login' => [
                    // ...
                    'enable_end_session' => true,
                    'post_logout_redirect_path' => '/',
                ],
            ],
        ],
    ],
]);

1

<a href="{{ path('_logout_main') }}" data-turbo="false">Log out</a>

Security Considerations

The authenticator implements all the checks required by the specifications. You can only disable PKCE and the ID token signature verification, and public clients can't disable either of them. These are the main checks:

• provider_uri and all the endpoints announced in the discovery document must use HTTPS. For local development, loopback hosts (localhost, 127.0.0.1, ::1) and *.localhost hosts are also accepted;
• The issuer of the discovery document must match provider_uri;
• All authorization requests include a state parameter, which is checked in the callback against the value stored in the session. This prevents login CSRF attacks;
• The iss authorization response parameter (RFC 9207) is checked against the issuer, and it's required when the provider announces authorization_response_iss_parameter_supported. This prevents mix-up attacks against clients registered with several providers;
• All authorization requests include a nonce parameter, which is checked against the nonce claim of the ID token. This ties the ID token to the authorization request;
• PKCE (RFC 7636) is applied with the S256 challenge method (unless the pkce option changes it), so an intercepted authorization code can't be exchanged by anyone else;
• The ID token signature is verified with the keys published by the provider (unless id_token_signature.required is disabled);
• The parameters managed by the authenticator can't be overridden with authorization_params or with OidcAuthorizationRequestEvent listeners. The prompt=login and id_token_hint parameters of a re-authentication are applied after both of them, so neither can disable the re-authentication;
• The iss, aud, exp, iat and sub claims of the ID token are required and validated. The azp and nbf claims are also validated when the provider includes them. allowed_time_drift is the only tolerance applied to time claims;
• When the claims are fetched from the UserInfo endpoint, their sub claim must be the same as the one of the ID token;
• The user identifier is the sub claim. If user_identifier_claim sets another claim, that claim must be present and not empty;
• No redirects are followed in the discovery, JWKS, token and UserInfo requests;
• The built-in oidc user provider doesn't allow claims to grant roles.

Configuration Reference

provider_uri (required)

The issuer URL of the OIDC provider, used for .well-known/openid-configuration discovery. Must use HTTPS.

client_id (required)

The client identifier issued by the provider.

client_authentication (required)

How the application authenticates at the token endpoint: client_secret_basic or client_secret_post (with the client secret), client_secret_jwt or private_key_jwt (with an assertion signed by the client), none (for public clients) or id (with the id of a service that implements ClientAuthenticationInterface). Any string value other than none is considered a service id.

client_authentication.client_secret_jwt.secret (required)

The client secret used as the key of the HMAC that signs the assertion. Passing a string to client_secret_jwt sets this value.

client_authentication.client_secret_jwt.algorithm (default: HS256)

The MAC algorithm used to sign the assertion: HS256, HS384 or HS512.

client_authentication.client_secret_jwt.lifetime (default: 60)

For how many seconds the assertion is valid.

client_authentication.private_key_jwt.key (required)

The JSON-encoded JWK of the private key used to sign the assertion. Passing a string to private_key_jwt sets this value.

client_authentication.private_key_jwt.algorithm (default: RS256)

The algorithm used to sign the assertion: RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384 or PS512.

client_authentication.private_key_jwt.lifetime (default: 60)

For how many seconds the assertion is valid.

http_client (default: http_client)

The id of the HTTP client used in all requests made to the provider (discovery document, JWKS, token endpoint and UserInfo endpoint).

scope (default: ['openid'])

The scopes of the authorization request, as a list or as a space-separated string.

user_data_source (default: userinfo)

Where to read the user claims from: userinfo fetches them from the UserInfo endpoint and id_token reads them from the validated ID token.

user_identifier_claim (default: sub)

The claim that contains the user identifier. sub is the only claim that OIDC guarantees to be stable and unique for each user.

check_path (default: /oidc/callback)

The path where the provider redirects users after authenticating them. You can also use a route name; in that case, no route is defined for it.

start_path (default: /oidc/start)

The path of the route that starts the flow by redirecting to the provider. You can also use a route name; in that case, no route is defined for it.

enable_end_session (default: false)

Whether logging out also redirects the user to the end_session_endpoint of the provider (RP-Initiated Logout).

post_logout_redirect_path (default: /)

The path or route name of your application where the provider redirects users after RP-Initiated Logout. It's sent as post_logout_redirect_uri; set it to null to not send it. It's ignored unless enable_end_session is true.

refresh_access_token.enabled (default: false)

Whether to renew the access token automatically, using the refresh token, before it expires.

refresh_access_token.leeway (default: 30)

How many seconds before its expiration the access token is renewed.

id_token_signature.required (default: true)

Whether to verify the signature of the ID token using the keys published by the provider.

id_token_signature.algorithms (default: ['RS256'])

The signature algorithms accepted for the ID token.

id_token_signature.enforce_key_usage_verification (default: true)

Whether to only use the keys that the provider designates for signing to verify the ID token.

pkce.enabled (default: true)

Whether to protect the authorization code with PKCE.

pkce.method (default: S256)

The PKCE code challenge method: S256 or plain.

max_age (no default value)

The maximum time, in seconds, since the user last authenticated in the provider. When set, it's sent as the max_age authorization parameter and checked against the auth_time claim of the ID token.

authorization_params (default: [])

Additional parameters of the authorization request, such as prompt or login_hint.

discovery_cache_ttl (default: 3600)

For how many seconds the discovery document is cached. It's also used for the keys of the provider when it doesn't advertise their lifetime.

allowed_time_drift (default: 0)

The clock skew, in seconds, allowed when validating the time claims of the ID token.

This authenticator also accepts the options shared by all firewall authenticators: success_handler and failure_handler (to replace the default handlers with your own services), and login_path, default_target_path, always_use_default_target_path, target_path_parameter, use_referer, failure_path and failure_path_parameter (to configure the default handlers), as explained in Security Configuration Reference (SecurityBundle).