From 0eae59cf1d7b3c8a02d6610127ea89115dd628dd Mon Sep 17 00:00:00 2001
From: Wouter de Jong <wouter@wouterj.nl>
Date: Mon, 16 Nov 2020 00:12:03 +0100
Subject: [PATCH] Documented passport attributes

---
 security/experimental_authenticators.rst | 37 ++++++++++++++++++++++++
 1 file changed, 37 insertions(+)

diff --git a/security/experimental_authenticators.rst b/security/experimental_authenticators.rst
index d0813795b12..0a713e6b0ca 100644
--- a/security/experimental_authenticators.rst
+++ b/security/experimental_authenticators.rst
@@ -502,3 +502,40 @@ authenticator, you would initialize the passport like this::
             ]);
         }
     }
+
+.. tip::
+
+    Besides badges, passports can define attributes, which allows the
+    ``authenticate()`` method to store arbitrary information in the
+    passport to access it from other authenticator methods (e.g.
+    ``createAuthenticatedToken()``)::
+
+        // ...
+        use Symfony\Component\Security\Core\Authentication\Token\TokenInterface;
+
+        class LoginAuthenticator extends AbstractAuthenticator
+        {
+            // ...
+
+            public function authenticate(Request $request): PassportInterface
+            {
+                // ... process the request
+
+                $passport = new SelfValidatingPassport($username, []);
+
+                // set a custom attribute (e.g. scope)
+                $passport->setAttribute('scope', $oauthScope);
+
+                return $passport;
+            }
+
+            public function createAuthenticatedToken(PassportInterface $passport, string $firewallName): TokenInterface
+            {
+                // read the attribute value
+                return new CustomOauthToken($passport->getUser(), $passport->getAttribute('scope'));
+            }
+        }
+
+.. versionadded:: 5.2
+
+    Passport attributes were introduced in Symfony 5.2.