From f9046f9abf1d47145d29d592f36fdad7f3db3a56 Mon Sep 17 00:00:00 2001
From: Vincent Chalamon <407859+vincentchalamon@users.noreply.github.com>
Date: Fri, 17 Jan 2025 10:30:22 +0100
Subject: [PATCH] docs: add OIDC Discovery documentation

---
 security/access_token.rst | 145 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 145 insertions(+)

diff --git a/security/access_token.rst b/security/access_token.rst
index c0ff4692676..0370949e584 100644
--- a/security/access_token.rst
+++ b/security/access_token.rst
@@ -411,6 +411,72 @@ and retrieve the user info:
             ;
         };
 
+To enable the `OpenID Connect Discovery`_, the ``OidcUserInfoTokenHandler``
+requires the ``symfony/cache`` package to store the OIDC configuration in
+cache. If you haven't installed it yet, run this command:
+
+.. code-block:: terminal
+
+    $ composer require symfony/cache
+
+Then, configure the ``base_uri`` and ``discovery`` keys:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/security.yaml
+        security:
+            firewalls:
+                main:
+                    access_token:
+                        token_handler:
+                            oidc_user_info:
+                                base_uri: https://www.example.com/realms/demo/
+                                discovery:
+                                    cache: cache.app
+
+    .. code-block:: xml
+
+        <!-- config/packages/security.xml -->
+        <?xml version="1.0" encoding="UTF-8"?>
+        <srv:container xmlns="http://symfony.com/schema/dic/security"
+            xmlns:srv="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                https://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/security
+                https://symfony.com/schema/dic/security/security-1.0.xsd">
+
+            <config>
+                <firewall name="main">
+                    <access-token>
+                        <token-handler>
+                            <oidc-user-info base-uri="https://www.example.com/realms/demo/">
+                                <discovery cache="cache.app"/>
+                            </oidc-user-info>
+                        </token-handler>
+                    </access-token>
+                </firewall>
+            </config>
+        </srv:container>
+
+    .. code-block:: php
+
+        // config/packages/security.php
+        use Symfony\Config\SecurityConfig;
+
+        return static function (SecurityConfig $security) {
+            $security->firewall('main')
+                ->accessToken()
+                    ->tokenHandler()
+                        ->oidcUserInfo()
+                            ->baseUri('https://www.example.com/realms/demo/')
+                            ->discovery()
+                                ->cache('cache.app')
+            ;
+        };
+
 Following the `OpenID Connect Specification`_, the ``sub`` claim is used as user
 identifier by default. To use another claim, specify it on the configuration:
 
@@ -625,6 +691,84 @@ it and retrieve the user info from it:
     The support of multiple algorithms to sign the JWS was introduced in Symfony 7.1.
     In previous versions, only the ``ES256`` algorithm was supported.
 
+To enable the `OpenID Connect Discovery`_, the ``OidcTokenHandler``
+requires the ``symfony/cache`` package to store the OIDC configuration in
+cache. If you haven't installed it yet, run this command:
+
+.. code-block:: terminal
+
+    $ composer require symfony/cache
+
+Then, you can remove the ``keyset`` configuration key (it will be imported from
+the OpenID Connect Discovery), and configure the ``discovery`` key:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/security.yaml
+        security:
+            firewalls:
+                main:
+                    access_token:
+                        token_handler:
+                            oidc:
+                                claim: email
+                                algorithms: ['ES256', 'RS256']
+                                audience: 'api-example'
+                                issuers: ['https://oidc.example.com']
+                                discovery:
+                                    base_uri: https://www.example.com/realms/demo/
+                                    cache: cache.app
+
+    .. code-block:: xml
+
+        <!-- config/packages/security.xml -->
+        <?xml version="1.0" encoding="UTF-8"?>
+        <srv:container xmlns="http://symfony.com/schema/dic/security"
+            xmlns:srv="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                https://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/security
+                https://symfony.com/schema/dic/security/security-1.0.xsd">
+
+            <config>
+                <firewall name="main">
+                    <access-token>
+                        <token-handler>
+                            <oidc claim="email" audience="api-example">
+                                <algorithm>ES256</algorithm>
+                                <algorithm>RS256</algorithm>
+                                <issuer>https://oidc.example.com</issuer>
+                                <discovery base-uri="https://www.example.com/realms/demo/" cache="cache.app">
+                            </oidc>
+                        </token-handler>
+                    </access-token>
+                </firewall>
+            </config>
+        </srv:container>
+
+    .. code-block:: php
+
+        // config/packages/security.php
+        use Symfony\Config\SecurityConfig;
+
+        return static function (SecurityConfig $security) {
+            $security->firewall('main')
+                ->accessToken()
+                    ->tokenHandler()
+                        ->oidc()
+                            ->claim('email')
+                            ->algorithms(['ES256', 'RS256'])
+                            ->audience('api-example')
+                            ->issuers(['https://oidc.example.com'])
+                            ->discovery()
+                                ->baseUri('https://www.example.com/realms/demo/')
+                                ->cache('cache.app')
+            ;
+        };
+
 Following the `OpenID Connect Specification`_, the ``sub`` claim is used by
 default as user identifier. To use another claim, specify it on the
 configuration:
@@ -925,5 +1069,6 @@ for :ref:`stateless firewalls <reference-security-stateless>`.
 .. _`JSON Web Tokens (JWT)`: https://datatracker.ietf.org/doc/html/rfc7519
 .. _`OpenID Connect (OIDC)`: https://en.wikipedia.org/wiki/OpenID#OpenID_Connect_(OIDC)
 .. _`OpenID Connect Specification`: https://openid.net/specs/openid-connect-core-1_0.html
+.. _`OpenID Connect Discovery`: https://openid.net/specs/openid-connect-discovery-1_0.html
 .. _`RFC6750`: https://datatracker.ietf.org/doc/html/rfc6750
 .. _`SAML2 (XML structures)`: https://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html