diff --git a/docs/_partials/cookie-size-callout.mdx b/docs/_partials/token-size-callout.mdx similarity index 80% rename from docs/_partials/cookie-size-callout.mdx rename to docs/_partials/token-size-callout.mdx index ecac85a6c3..5511b0eeaf 100644 --- a/docs/_partials/cookie-size-callout.mdx +++ b/docs/_partials/token-size-callout.mdx @@ -1,4 +1,4 @@ > [!CAUTION] > The entire session token has a max size of 4kb. Exceeding this size can have adverse effects, including a possible infinite redirect loop for users who exceed this size in Next.js applications. > It's recommended to move particularly large claims out of the JWT and fetch these using a separate API call from your backend. -> [Learn more](/docs/backend-requests/resources/cookie-size-limits). +> [Learn more](/docs/backend-requests/resources/session-tokens#size-limitations). diff --git a/docs/backend-requests/making/custom-session-token.mdx b/docs/backend-requests/making/custom-session-token.mdx index d034964679..60612ddf0c 100644 --- a/docs/backend-requests/making/custom-session-token.mdx +++ b/docs/backend-requests/making/custom-session-token.mdx @@ -9,7 +9,7 @@ By default, session tokens contain claims that are required for Clerk to functio This guide will show you how to customize a session token to include additional claims that you may need in your application. - + {/* TODO: Update the H3 to an H2 when the Steps component can accept headings other than H3. */} diff --git a/docs/backend-requests/making/jwt-templates.mdx b/docs/backend-requests/making/jwt-templates.mdx index aeb60881f1..d3cf28e355 100644 --- a/docs/backend-requests/making/jwt-templates.mdx +++ b/docs/backend-requests/making/jwt-templates.mdx @@ -10,7 +10,7 @@ Clerk offers the ability to generate [JSON Web Tokens](https://en.wikipedia.org/ You can control the claims that will go into these tokens by creating custom **JWT Templates** that fit your needs. This enables you to integrate with any third-party services that support authentication with JWTs. An example use case is integrating with a third-party service that is able to consume JWTs, but requires them to be in a particular format. - + ## What is a JWT template? diff --git a/docs/backend-requests/resources/cookie-size-limits.mdx b/docs/backend-requests/resources/cookie-size-limits.mdx deleted file mode 100644 index e56fa6e06d..0000000000 --- a/docs/backend-requests/resources/cookie-size-limits.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: Cookie size limits -description: Learn about cookie size limits and how to stay within them with Clerk. ---- - -All modern browsers [limit the maximum size of a cookie to 4kb](https://datatracker.ietf.org/doc/html/rfc2109#section-6.3). - -The Clerk [session token](/docs/backend-requests/resources/session-tokens) is stored in a Cookie, and is required for Clerk to function. Exceeding the 4kb max size can have adverse effects, including a possible infinite redirect loop for users who exceed this size in Next.js applications. - -A session token with the [default session claims](/docs/backend-requests/resources/session-tokens#default-session-claims) will not run into this issue, as this configuration produces a Cookie significantly smaller than 4kb. Only when [customizing your session token](/docs/backend-requests/making/custom-session-token) or creating a [custom JWT template](/docs/backend-requests/making/jwt-templates) do you have to be mindful of this limitation. - -It's recommended to move particularly large claims out of the JWT and fetch these using a separate API call from your backend. Notably, the `user.organizations` claim will often cause the cookie to exceed 4kb. Other claims to be cautious about are `user.public_metadata`, `user.unsafe_metadata`, `org.public_metadata`, and `org_membership.public_metadata`. With any of these claims, if enough data is stored as metadata, it will cause the cookie size to exceed the limit. If you are including any of these claims in your JWT, use extra caution around how much is stored in the metadata fields to avoid a cookie size overflow issue. diff --git a/docs/backend-requests/resources/session-tokens.mdx b/docs/backend-requests/resources/session-tokens.mdx index 72faf320e2..468659a991 100644 --- a/docs/backend-requests/resources/session-tokens.mdx +++ b/docs/backend-requests/resources/session-tokens.mdx @@ -5,6 +5,8 @@ description: Learn about session tokens and how to validate them in your backend When a user is authenticated in your application, Clerk generates a short-lived session token that you can use to authenticate requests to your backend. This token is a JSON Web Token (JWT) that contains information about the user and their session. +Learn more about how Clerk combines session token authentication and JWT authentication in the [blog post](https://clerk.com/blog/combining-the-benefits-of-session-tokens-and-jwts). + ## Default session claims Every generated token has default claims that cannot be overridden by templates. Clerk's default claims include: @@ -32,6 +34,22 @@ If you would like to add custom claims to your session token, you can [customize You can also create custom tokens using a [JWT template](/docs/backend-requests/making/jwt-templates). +## Size limitations + +The Clerk session token is stored in a cookie. All modern browsers [limit the maximum size of a cookie to 4kb](https://datatracker.ietf.org/doc/html/rfc2109#section-6.3). Exceeding this limit can have adverse effects, including a possible infinite redirect loop for users who exceed this size in Next.js applications. + +A session token with the [default session claims](#default-session-claims) won't run into this issue, as this configuration produces a cookie significantly smaller than 4kb. However, this limitation becomes relevant when implementing a [custom session token](/docs/backend-requests/making/custom-session-token) or creating a [custom JWT template](/docs/backend-requests/making/jwt-templates). In these cases, it's recommended to move particularly large claims out of the token and fetch these using a separate API call from your backend. + +Claims to monitor for size limits: + +- `user.organizations` +- `user.public_metadata` +- `user.unsafe_metadata` +- `org.public_metadata` +- `org_membership.public_metadata` + +If you include any of these claims in your token, use caution to ensure the stored data doesn't exceed the size limit. + ## Validate session tokens If you're using the middleware provided by our Clerk SDKs, this is all handled automatically in every request. If you're not using the middleware, you can still use the respective helpers provided by the SDKs to validate the tokens. diff --git a/docs/manifest.json b/docs/manifest.json index 9d16391a8c..89b2f99a8c 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -822,10 +822,6 @@ "title": "Session tokens", "href": "/docs/backend-requests/resources/session-tokens" }, - { - "title": "Cookie size limits", - "href": "/docs/backend-requests/resources/cookie-size-limits" - }, { "title": "Rate limits", "href": "/docs/backend-requests/resources/rate-limits"