diff --git a/docs/docs/configuration/callbacks.md b/docs/docs/configuration/callbacks.md index bd2024003c..e9f111b49c 100644 --- a/docs/docs/configuration/callbacks.md +++ b/docs/docs/configuration/callbacks.md @@ -104,7 +104,7 @@ The redirect callback may be invoked more than once in the same flow. ## JWT callback This callback is called whenever a JSON Web Token is created (i.e. at sign -in) or updated (i.e whenever a session is accessed in the client). The returned value will be [signed and optionally encrypted](/configuration/options#jwt), and it is stored in a cookie. +in) or updated (i.e whenever a session is accessed in the client). The returned value will be [encrypted](/configuration/options#jwt), and it is stored in a cookie. Requests to `/api/auth/signin`, `/api/auth/session` and calls to `getSession()`, `useSession()` will invoke this function, but only if you are using a [JWT session](/configuration/options#session). This method is not invoked when you persist sessions in a database. diff --git a/docs/docs/configuration/options.md b/docs/docs/configuration/options.md index 056bfb33e6..68bc900879 100644 --- a/docs/docs/configuration/options.md +++ b/docs/docs/configuration/options.md @@ -97,7 +97,7 @@ Default values for this option are shown below: ```js session: { // Choose how you want to save the user session. - // The default is `"jwt"`, an encrypted JWT (JWE) in the session cookie. + // The default is `"jwt"`, an encrypted JWT (JWE) stored in the session cookie. // If you use an `adapter` however, we default it to `"database"` instead. // You can still force a JWT session by explicitly defining `"jwt"`. // When using `"database"`, the session cookie will only contain a `sessionToken` value, diff --git a/docs/docs/faq.md b/docs/docs/faq.md index 1ba017c885..f1e70f060a 100644 --- a/docs/docs/faq.md +++ b/docs/docs/faq.md @@ -270,7 +270,7 @@ Ultimately if your request is not accepted or is not actively in development, yo

-NextAuth.js by default uses JSON Web Tokens for saving the user's session. However, if you use a [database adapter](/adapters/overview), the database will be used to persist the user's session. You can force the usage of JWT when using a database [through the configuration options](/configuration/options#session). +NextAuth.js by default uses JSON Web Tokens for saving the user's session. However, if you use a [database adapter](/adapters/overview), the database will be used to persist the user's session. You can force the usage of JWT when using a database [through the configuration options](/configuration/options#session). Since v4 all our JWT tokens are now encrypted by default with A256GCM.

@@ -285,11 +285,9 @@ JSON Web Tokens can be used for session tokens, but are also used for lots of ot - Advantages of using a JWT as a session token include that they do not require a database to store sessions, this can be faster and cheaper to run and easier to scale. -- JSON Web Tokens in NextAuth.js are secured using cryptographic signing (JWS) by default and it is easy for services and API endpoints to verify tokens without having to contact a database to verify them. +- JSON Web Tokens in NextAuth.js are secured using cryptographic encryption (JWE) to store the included information directly in a JWT session token. You may then use the token to pass information between services and APIs on the same domain without having to contact a database to verify the included information. -- You can enable encryption (JWE) to store include information directly in a JWT session token that you wish to keep secret and use the token to pass information between services / APIs on the same domain. - -- You can use JWT to securely store information you do not mind the client knowing even without encryption, as the JWT is stored in a server-readable-only-token so data in the JWT is not accessible to third party JavaScript running on your site. +- You can use JWT to securely store information you do not mind the client knowing even without encryption, as the JWT is stored in a server-readable-only cookie so data in the JWT is not accessible to third party JavaScript running on your site.

@@ -308,7 +306,7 @@ JSON Web Tokens can be used for session tokens, but are also used for lots of ot - As with database session tokens, JSON Web Tokens are limited in the amount of data you can store in them. There is typically a limit of around 4096 bytes per cookie, though the exact limit varies between browsers, proxies and hosting services. If you want to support most browsers, then do not exceed 4096 bytes per cookie. If you want to save more data, you will need to persist your sessions in a database (Source: [browsercookielimits.iain.guru](http://browsercookielimits.iain.guru/)) - The more data you try to store in a token and the more other cookies you set, the closer you will come to this limit. If you wish to store more than ~4 KB of data you're probably at the point where you need to store a unique ID in the token and persist the data elsewhere (e.g. in a server-side key/value store). + The more data you try to store in a token and the more other cookies you set, the closer you will come to this limit. Since v4 we have implemented cookie chunking so that cookies over the 4kb limit get split and reassembled upon parsing. However since this data needs to be transmitted on every request, if you wish to store more than ~4 KB of data you're probably at the point where you want to store a unique ID in the token and persist the data elsewhere (e.g. in a server-side key/value store). - Data stored in an encrypted JSON Web Token (JWE) may be compromised at some point. @@ -316,9 +314,8 @@ JSON Web Tokens can be used for session tokens, but are also used for lots of ot Avoid storing any data in a token that might be problematic if it were to be decrypted in the future. -- If you do not explicitly specify a secret for for NextAuth.js, existing sessions will be invalidated any time your NextAuth.js configuration changes, as NextAuth.js will default to an auto-generated secret. +- If you do not explicitly specify a secret for for NextAuth.js, existing sessions will be invalidated any time your NextAuth.js configuration changes, as NextAuth.js will default to an auto-generated secret. Since v4 this only impacts development and generating a secret is required in production. - If using JSON Web Token you should at least specify a secret and ideally configure public/private keys.

diff --git a/docs/docs/getting-started/introduction.md b/docs/docs/getting-started/introduction.md index c01658d58d..c4a9efa8af 100644 --- a/docs/docs/getting-started/introduction.md +++ b/docs/docs/getting-started/introduction.md @@ -38,8 +38,7 @@ _Note: Email sign-in requires a database to be configured to store single-use ve - Designed to be secure by default and encourage best practices for safeguarding user data - Uses Cross-Site Request Forgery Tokens on POST routes (sign in, sign out) - Default cookie policy aims for the most restrictive policy appropriate for each cookie -- When JSON Web Tokens are enabled, they are signed by default (JWS) with HS512 -- Use JWT encryption (JWE) by setting the option `encryption: true` (defaults to A256GCM) +- When JSON Web Tokens are enabled, they are encrypted by default (JWE) with A256GCM - Auto-generates symmetric signing and encryption keys for developer convenience - Features tab/window syncing and keepalive messages to support short-lived sessions - Attempts to implement the latest guidance published by [Open Web Application Security Project](https://owasp.org/) diff --git a/packages/next-auth/README.md b/packages/next-auth/README.md index f3765bdfe0..ee1490fb90 100644 --- a/packages/next-auth/README.md +++ b/packages/next-auth/README.md @@ -77,8 +77,7 @@ NextAuth.js can be used with or without a database. - Designed to be secure by default and encourage best practices for safeguarding user data - Uses Cross-Site Request Forgery (CSRF) Tokens on POST routes (sign in, sign out) - Default cookie policy aims for the most restrictive policy appropriate for each cookie -- When JSON Web Tokens are enabled, they are signed by default (JWS) with HS512 -- Use JWT encryption (JWE) by setting the option `encryption: true` (defaults to A256GCM) +- When JSON Web Tokens are enabled, they are encrypted by default (JWE) with A256GCM - Auto-generates symmetric signing and encryption keys for developer convenience - Features tab/window syncing and session polling to support short lived sessions - Attempts to implement the latest guidance published by [Open Web Application Security Project](https://owasp.org)