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 the security route loader, which also defines 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:
    resource: security.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' => [
        'resource' => 'security.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
8

# config/packages/security.yaml
security:
    firewalls:
        main:
            oidc_login:
                # ...
                authorization_params:
                    response_mode: 'form_post'

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' => [
                    // ...
                    'authorization_params' => [
                        'response_mode' => 'form_post',
                    ],
                ],
            ],
        ],
    ],
]);

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).

tls_client_auth and self_signed_tls_client_auth

Authenticate with the TLS certificate of the client (see How to Log in Users with OpenID Connect). They don't take any parameter, so client_authentication: tls_client_auth is the short form.

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, tls_client_auth and self_signed_tls_client_auth is the short form (e.g. client_authentication: App\Security\KmsJwtAuthentication).

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

# config/packages/security.yaml
security:
    firewalls:
        main:
            oidc_login:
                provider_uri: 'https://accounts.example.com'
                client_id: '%env(OIDC_CLIENT_ID)%'
                client_authentication:
                    private_key_jwt:
                        key: '%env(OIDC_CLIENT_SIGNING_KEY)%'
                        audience: 'token_endpoint'

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' => [
                    'provider_uri' => 'https://accounts.example.com',
                    'client_id' => '%env(OIDC_CLIENT_ID)%',
                    'client_authentication' => [
                        'private_key_jwt' => [
                            'key' => '%env(OIDC_CLIENT_SIGNING_KEY)%',
                            'audience' => 'token_endpoint',
                        ],
                    ],
                ],
            ],
        ],
    ],
]);

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

# config/packages/security.yaml
security:
    firewalls:
        main:
            oidc_login:
                # ...
                client_certificate:
                    # the paths of the PEM files of the certificate
                    # and its private key
                    certificate: '%env(OIDC_CLIENT_CERT_PATH)%'
                    key: '%env(OIDC_CLIENT_KEY_PATH)%'
                    # only needed if the private key is encrypted
                    passphrase: '%env(OIDC_CLIENT_KEY_PASSPHRASE)%'
                client_authentication: tls_client_auth

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

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

return App::config([
    'security' => [
        'firewalls' => [
            'main' => [
                'oidc_login' => [
                    // ...
                    'client_certificate' => [
                        // the paths of the PEM files of the certificate
                        // and its private key
                        'certificate' => '%env(OIDC_CLIENT_CERT_PATH)%',
                        'key' => '%env(OIDC_CLIENT_KEY_PATH)%',
                        // only needed if the private key is encrypted
                        'passphrase' => '%env(OIDC_CLIENT_KEY_PASSPHRASE)%',
                    ],
                    'client_authentication' => 'tls_client_auth',
                ],
            ],
        ],
    ],
]);

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/KmsJwtAuthentication.php
namespace App\Security;

use App\Kms\AssertionSigner;
use Symfony\Component\Security\Http\OAuth2\ClientAuthentication\ClientAuthenticationInterface;

final class KmsJwtAuthentication implements ClientAuthenticationInterface
{
    public function __construct(
        private AssertionSigner $assertionSigner,
    ) {
    }

    public function authenticate(
        string $clientId,
        string $tokenEndpoint,
        array $options,
    ): array {
        // the private key never leaves the KMS, which signs the assertion
        $options['body']['client_assertion_type'] =
            'urn:ietf:params:oauth:client-assertion-type:jwt-bearer';
        $options['body']['client_assertion'] =
            $this->assertionSigner->sign($clientId, $tokenEndpoint);

        return $options;
    }

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

1
2
3
4
5
6
7

# config/packages/security.yaml
security:
    firewalls:
        main:
            oidc_login:
                # ...
                client_authentication: App\Security\KmsJwtAuthentication

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;

use App\Security\KmsJwtAuthentication;

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

Binding Tokens to a Key (DPoP)

By default, the tokens issued by the provider are bearer tokens: anyone who steals one can use it. With DPoP (Demonstrating Proof of Possession, defined in RFC 9449), the application signs a proof with its private key in each request to the provider, and the provider binds the tokens it issues to that key. A stolen token is useless without the key. FAPI 2.0 accepts DPoP as an alternative to mutual TLS to bind the tokens.

Set the dpop option to enable it:

1
2
3
4
5
6
7
8
9

# config/packages/security.yaml
security:
    firewalls:
        main:
            oidc_login:
                # ...
                dpop:
                    key: '%env(OIDC_DPOP_KEY)%'
                    algorithm: 'ES256'

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' => [
                    // ...
                    'dpop' => [
                        'key' => '%env(OIDC_DPOP_KEY)%',
                        'algorithm' => 'ES256',
                    ],
                ],
            ],
        ],
    ],
]);

key is the JSON-encoded JWK of a private EC or RSA key (you can also pass this value directly as a string to dpop). The key must match the algorithm, which defaults to ES256: public keys and keys of another type or curve are rejected. Keep this key as secret as a client secret. You don't have to register it at the provider, because each proof includes the public key. The algorithm must be one of those listed by your provider in the dpop_signing_alg_values_supported entry of its discovery document.

When DPoP is enabled, the requests to the token endpoint (including token refreshes) and to the UserInfo endpoint include a proof, and the access token is sent with the DPoP authorization scheme instead of Bearer. The authorization request also includes the dpop_jkt parameter with the thumbprint of the key, so an attacker who steals the authorization code can't exchange it for tokens. The authenticator manages this parameter, so you can't set it in authorization_params.

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

For the same reason, define the TLS client certificate in the client_certificate option (see How to Log in Users with OpenID Connect) instead of the local_cert and local_pk options of this HTTP client. The requests that present the client_certificate ignore the local_cert, local_pk and passphrase options of the HTTP client.

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,
                    ],
                ],
            ],
        ],
    ],
]);

Injecting the Client of a Firewall

Each firewall that uses oidc_login has its own OidcClientInterface service, which sends the requests of your application to the provider (e.g. to exchange the authorization code or to renew the tokens). Inject it when you need to call other endpoints of the provider, such as revoking a token.

To autowire it, type-hint the interface and name the argument after the firewall in camelCase followed by OidcClient (e.g. $mainOidcClient for the main firewall or $adminAreaOidcClient for the admin_area firewall):

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

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

use Symfony\Component\Security\Http\Authenticator\Oidc\OidcClientInterface;

class TokenRevoker
{
    public function __construct(
        private OidcClientInterface $mainOidcClient,
    ) {
    }

    public function revoke(string $refreshToken): void
    {
        // the first argument is the name of the endpoint in the discovery
        // document of the provider; the second one is the form body; the
        // optional third one is an array of HttpClient options (e.g. to
        // add an 'Accept' header); the client authenticates the request
        // and adds the 'client_id' parameter to the body
        $response = $this->mainOidcClient->request('revocation_endpoint', [
            'token' => $refreshToken,
            'token_type_hint' => 'refresh_token',
        ]);

        // the response is lazy, so check its status code yourself
        if (200 !== $response->getStatusCode()) {
            throw new \RuntimeException('The token was not revoked.');
        }
    }
}

Alternatively, use the Target attribute with the name of the firewall. In that case, the name of the argument doesn't matter:

1
2
3
4
5
6
7
8

use Symfony\Component\DependencyInjection\Attribute\Target;
use Symfony\Component\Security\Http\Authenticator\Oidc\OidcClientInterface;

public function __construct(
    #[Target('main')]
    private OidcClientInterface $oidcClient,
) {
}

The interface can't be autowired without the name of the firewall, because an application can define several oidc_login firewalls. You can also inject the client using its service id, which is security.authenticator.oidc_login.client.<firewallname>.

Calling Other Endpoints of the Provider

Besides logging users in, your application may need to call other endpoints of the provider: to revoke a token (RFC 7009), to introspect it (RFC 7662), to push an authorization request (RFC 9126) or to run a grant that Symfony doesn't provide, such as the client credentials grant. Use the request() method of the firewall client to make a client-authenticated POST request to any endpoint announced by the provider. This request uses the same client authentication, TLS client certificate and mTLS endpoint aliases (RFC 8705) as the other requests sent to the provider.

The method returns the raw HttpClient response, because each endpoint answers differently: a JSON object, a signed JWT or an empty body. It throws an AuthenticationException if the provider doesn't announce the endpoint or if the endpoint URL doesn't use HTTPS.

Keep these rules in mind:

• Symfony overrides the body and max_redirects HttpClient options that you pass.
• A client assertion (see How to Log in Users with OpenID Connect) names the same audience as in the requests to the token endpoint (the issuer or the token endpoint, depending on the audience option), regardless of the endpoint that you call.
• When using DPoP (RFC 9449), Symfony only sends a proof to the token and pushed authorization request endpoints. A grant run through this method returns a DPoP-bound token whose token_type Symfony doesn't check, and your application must send its own proofs when using that token.
• Public clients (client_authentication: none) can use this method too (e.g. to revoke a token or to redeem a device code). The only request that Symfony refuses is redeeming an authorization code without a PKCE verifier.

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>

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

# config/packages/security.yaml
security:
    firewalls:
        main:
            oidc_login:
                provider_uri: 'https://accounts.example.com'
                client_id: '%env(OIDC_CLIENT_ID)%'
                client_authentication:
                    client_secret_basic: '%env(OIDC_CLIENT_SECRET)%'
                # these are the default values; set this option to
                # 'true' to enable the feature using them
                backchannel_logout:
                    path: /oidc/backchannel-logout
                    cache: cache.security
                    lifetime: 86400

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

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

return App::config([
    'security' => [
        'firewalls' => [
            'main' => [
                'oidc_login' => [
                    'provider_uri' => 'https://accounts.example.com',
                    'client_id' => '%env(OIDC_CLIENT_ID)%',
                    'client_authentication' => [
                        'client_secret_basic' => '%env(OIDC_CLIENT_SECRET)%',
                    ],
                    // these are the default values; set this option to
                    // 'true' to enable the feature using them
                    'backchannel_logout' => [
                        'path' => '/oidc/backchannel-logout',
                        'cache' => 'cache.security',
                        'lifetime' => 86400,
                    ],
                ],
            ],
        ],
    ],
]);

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

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

use Symfony\Component\EventDispatcher\Attribute\AsEventListener;
use Symfony\Component\Security\Http\Event\TokenDeauthenticatedEvent;
use Symfony\Component\Security\Http\Exception\OidcSessionEndedException;

final class OidcSessionEndedListener
{
    #[AsEventListener]
    public function onTokenDeauthenticated(TokenDeauthenticatedEvent $event): void
    {
        if ($event->getException() instanceof OidcSessionEndedException) {
            $event->getRequest()->getSession()->invalidate();
        }
    }
}

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), tls_client_auth or self_signed_tls_client_auth (with the client_certificate option), none (for public clients) or id (with the id of a service that implements ClientAuthenticationInterface). Any string value other than none, tls_client_auth and self_signed_tls_client_auth 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.client_secret_jwt.audience (default: issuer)

What the assertion names as its audience: issuer (the issuer of the provider) or token_endpoint (for a provider that refuses the issuer).

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.

client_authentication.private_key_jwt.audience (default: issuer)

What the assertion names as its audience: issuer (the issuer of the provider) or token_endpoint (for a provider that refuses the issuer).

client_certificate

The TLS client certificate presented in the token and UserInfo requests. Required by the tls_client_auth and self_signed_tls_client_auth methods. Passing a string sets client_certificate.certificate.

client_certificate.certificate (required)

The path of the PEM file of the certificate.

client_certificate.key (default: null)

The path of the PEM file of the private key, if the certificate file doesn't contain it.

client_certificate.passphrase (default: null)

The passphrase of the private key, if it's encrypted.

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).

dpop.key (required when dpop is set)

The JSON-encoded JWK of the private key used to sign the DPoP proofs and to which the provider binds the tokens (see How to Log in Users with OpenID Connect). Passing a string to dpop sets this value.

dpop.algorithm (default: ES256)

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

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.

backchannel_logout.path (default: /oidc/backchannel-logout)

The path of the route that receives the logout tokens sent by the provider (Back-Channel Logout). Setting backchannel_logout to true enables this feature with the default values.

backchannel_logout.cache (default: cache.security)

The id of the cache pool that stores the ended sessions.

backchannel_logout.lifetime (default: 86400)

For how many seconds an ended session is remembered.

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).