From 89de21e3e54c9af35e358d56fff9a178be3786e3 Mon Sep 17 00:00:00 2001 From: Sai Sridhar Date: Thu, 6 Aug 2026 22:30:13 +0530 Subject: [PATCH] docs: correct misleading "encrypted" claims for signed-only auth cookies CookieAuthentication.set_cookie, CookiesTokensStore, and the OIDC result-handler docstrings described id_token/access_token/refresh_token cookies as "encrypted". They're actually only signed via itsdangerous.URLSafeSerializer (get_serializer), which provides tamper-protection but no confidentiality - the cookie payload is just base64, readable to anyone with access to the cookie. Clarify the docstrings so users don't mistakenly assume these cookies hide sensitive claims/token contents from the client. --- blacksheep/server/authentication/cookie.py | 6 ++++-- blacksheep/server/authentication/oidc.py | 17 ++++++++++++----- 2 files changed, 16 insertions(+), 7 deletions(-) diff --git a/blacksheep/server/authentication/cookie.py b/blacksheep/server/authentication/cookie.py index 3a9ac4b4..615c8cb9 100644 --- a/blacksheep/server/authentication/cookie.py +++ b/blacksheep/server/authentication/cookie.py @@ -69,8 +69,10 @@ def set_cookie(self, data: Any, response: Response, secure: bool = False) -> Non """ Sets the cookie used for authentication. If a cookie is set, it is assumed that the user is recognized (authenticated). The passed value is serialized, meaning - signed and encrypted using the `itsdangerous.Serializer` associated with this - CookieAuthentication handler. A common scenario is that data is a dictionary + signed (not encrypted) using the `itsdangerous.Serializer` associated with this + CookieAuthentication handler - the cookie value protects against tampering, but + its contents remain readable to anyone with access to the cookie, so it should + not be used to store secrets. A common scenario is that data is a dictionary with claims describing the identity of the user (e.g. id_token claims). Parameters diff --git a/blacksheep/server/authentication/oidc.py b/blacksheep/server/authentication/oidc.py index 98a452ab..6872c9b7 100644 --- a/blacksheep/server/authentication/oidc.py +++ b/blacksheep/server/authentication/oidc.py @@ -483,8 +483,10 @@ async def get_success_response( ) -> Response: """ Returns a redirect response that includes Set-Cookie headers - to configure an encrypted id_token and, optionally, also encrypted - access_token and refresh_token. + to configure a signed (not encrypted) id_token and, optionally, also + signed access_token and refresh_token. The cookie values are protected + against tampering, but remain readable to anyone with access to the + cookie. """ response = redirect(original_path) await self._set_tokens_in_response(request, response, id_token, token_response) @@ -588,8 +590,10 @@ async def get_success_response( ) -> Response: """ Returns a redirect response that includes Set-Cookie headers - to configure an encrypted id_token and, optionally, also encrypted - access_token and refresh_token. + to configure a signed (not encrypted) id_token and, optionally, also + signed access_token and refresh_token. The cookie values are protected + against tampering, but remain readable to anyone with access to the + cookie. """ response = html( self._get_html( @@ -699,7 +703,10 @@ class TokenType(Enum): class CookiesTokensStore(TokensStore): """ - A class that can store access and refresh tokens in encrypted form in cookies. + A class that can store access and refresh tokens in cookies, signed (not + encrypted) using `itsdangerous`. The cookie values are protected against + tampering, but remain readable to anyone with access to the cookie - do not + rely on this for confidentiality of the token contents. Beware that cookies size can be problematic when storing all information in cookies. If this is the case, consider implementing a type of `BaseTokensStore` that uses