From 4f37754523c8fdf80b4a5ced365883efc72cddb2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bal=C3=A1zs=20Orb=C3=A1n?= Date: Sun, 7 Nov 2021 14:39:15 +0100 Subject: [PATCH 1/6] Update options.md --- docs/configuration/options.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/docs/configuration/options.md b/docs/configuration/options.md index 704c5943..547ae1c1 100644 --- a/docs/configuration/options.md +++ b/docs/configuration/options.md @@ -66,11 +66,17 @@ See the [providers documentation](/configuration/providers/oauth-provider) for a #### Description -A random string used to hash tokens, sign cookies and generate cryptographic keys. +A random string used to hash tokens, sign/encrypt cookies and generate cryptographic keys. -If not specified, it uses a hash for all configuration options, including Client ID / Secrets for entropy. +If not specified, it uses a hash for all configuration options, including OAuth Client ID / Secrets for entropy. Although if the user does not use such a provider, the configuration might be guessed. -The default behaviour is volatile, and it is strongly recommended you explicitly specify a value to avoid invalidating end user sessions when configuration changes are deployed. +:::warn +The default behaviour is volatile, and it is strongly recommended you explicitly specify a value. If `secret` is omitted in production, we will throw an error. +::: + +:::tip +If you rely on the default secret generation in development, you might notice JWT decryption errors, since the secret changes whenever you change your configuration. Defining a secret will make this problem go away. +::: --- From c01254ce373ba9a893735691d02059619f9a9520 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bal=C3=A1zs=20Orb=C3=A1n?= Date: Sun, 7 Nov 2021 14:46:00 +0100 Subject: [PATCH 2/6] Update errors.md --- docs/errors.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/errors.md b/docs/errors.md index a82a6769..3a5e687e 100644 --- a/docs/errors.md +++ b/docs/errors.md @@ -166,6 +166,10 @@ This error happens when `[...nextauth].js` file is not found inside `pages/api/a Make sure the file is there and the filename is written correctly. +#### NO_SECRET + +In production, we expect you to define a `secret` property in your configuration. In development, this is shown as a warning for convenienve. [Read more](https://next-auth.js.org/configuration/options#secret) + #### oauth_callback_error expected 200 OK with body but no body was returned This error might happen with some of the providers. It happens due to `openid-client`(which is peer dependency) node version mismatch. For instance, `openid-client` requires `>=14.2.0` for `lts/fermium` and has similar limits for the other versions. For the full list of the compatible node versions please see [package.json](https://github.com/panva/node-openid-client/blob/2a84e46992e1ebeaf685c3f87b65663d126e81aa/package.json#L78) From a679239c8451d299183b07909bc714fd55bd4a33 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bal=C3=A1zs=20Orb=C3=A1n?= Date: Sun, 7 Nov 2021 14:48:58 +0100 Subject: [PATCH 3/6] Update warnings.md --- docs/warnings.md | 32 ++++++-------------------------- 1 file changed, 6 insertions(+), 26 deletions(-) diff --git a/docs/warnings.md b/docs/warnings.md index e7e21ee2..669c993a 100644 --- a/docs/warnings.md +++ b/docs/warnings.md @@ -15,39 +15,19 @@ All warnings indicate things which you should take a look at, but do not inhibit Environment variable `NEXTAUTH_URL` missing. Please set it in your `.env` file. +:::note +On [Vercel](https://vercel.com) deployments, we will read the `VERCEL_URL` environment variable, so you won't need to define `NEXTAUTH_URL`. +::: + --- ## Server These warnings are displayed on the terminal. -#### JWT_AUTO_GENERATED_SIGNING_KEY - -To remedy this warning, you can either: - -**Option 1**: Pass a pre-regenerated Private Key (and, optionally a Public Key) in the jwt options. - -```js title="/pages/api/auth/[...nextauth].js" -jwt: { - signingKey: process.env.JWT_SIGNING_PRIVATE_KEY, - - // You can also specify a public key for verification if using public/private key (but private only is fine) - // verificationKey: process.env.JWT_SIGNING_PUBLIC_KEY, - - // If you want to use some key format other than HS512 you can specify custom options to use - // when verifying (note: verificationOptions should include a value for maxTokenAge as well). - // verificationOptions = { - // maxTokenAge: `${maxAge}s`, // e.g. `${30 * 24 * 60 * 60}s` = 30 days - // algorithms: ['HS512'] - // }, -} -``` - -You can use [node-jose-tools](https://www.npmjs.com/package/node-jose-tools) to generate keys on the command line and set them as environment variables, i.e. `jose newkey -s 256 -t oct -a HS512`. - -**Option 2**: Specify custom encode/decode functions on the jwt object. This gives you complete control over signing / verification / etc. +#### NO_SECRET -#### JWT_AUTO_GENERATED_ENCRYPTION_KEY +In development, we generate a `secret` based on your configuration for convenience. This is volatile and will throw an error in production. [Read more](https://next-auth.js.org/configuration/options#secret) ## Adapter From ab36a7bd2bd194976d506e4e399ae1ee60e8f95c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bal=C3=A1zs=20Orb=C3=A1n?= Date: Sun, 7 Nov 2021 14:57:10 +0100 Subject: [PATCH 4/6] Update options.md --- docs/configuration/options.md | 31 +++++-------------------------- 1 file changed, 5 insertions(+), 26 deletions(-) diff --git a/docs/configuration/options.md b/docs/configuration/options.md index 547ae1c1..c4eb408b 100644 --- a/docs/configuration/options.md +++ b/docs/configuration/options.md @@ -119,38 +119,17 @@ session: { JSON Web Tokens can be used for session tokens if enabled with `session: { jwt: true }` option. JSON Web Tokens are enabled by default if you have not specified a database. -By default JSON Web Tokens are signed (JWS) but not encrypted (JWE), as JWT encryption adds additional overhead and comes with some caveats. You can enable encryption by setting `encryption: true`. +By default JSON Web Tokens are encrypted (JWE). We recommend you keep this behavoiur, but you can override it by defining your own `encode` and `decode` methods. #### JSON Web Token Options ```js jwt: { - // A secret to use for key generation - you should set this explicitly - // Defaults to NextAuth.js secret if not explicitly specified. - // This is used to generate the actual signingKey and produces a warning - // message if not defined explicitly. + // A secret to use for key generation. Defaults to the top-level `session`. secret: 'INp8IvdIyeMcoGAgFGoA61DdBglwwSqnXJZkgz8PSnw', - // You can generate a signing key using `jose newkey -s 512 -t oct -a HS512` - // This gives you direct knowledge of the key used to sign the token so you can use it - // to authenticate indirectly (eg. to a database driver) - signingKey: { - kty: "oct", - kid: "Dl893BEV-iVE-x9EC52TDmlJUgGm9oZ99_ZL025Hc5Q", - alg: "HS512", - k: "K7QqRmJOKRK2qcCKV_pi9PSBv3XP0fpTu30TP8xn4w01xR3ZMZM38yL2DnTVPVw6e4yhdh0jtoah-i4c_pZagA" - }, - // If you chose something other than the default algorithm for the signingKey (HS512) - // you also need to configure the algorithm - verificationOptions: { - algorithms: ['HS256'] - }, - // Set to true to use encryption. Defaults to false (signing only). - encryption: true, - encryptionKey: "", - // decryptionKey: encryptionKey, - decryptionOptions: { - algorithms: ['A256GCM'] - }, + // The maximum age of the NextAuth.js issued JWT in seconds. + // Defaults to `session.maxAge`. + maxAge: 60 * 60 * 24 * 30, // You can define your own encode/decode functions for signing and encryption // if you want to override the default behaviour. async encode({ secret, token, maxAge }) {}, From dd46912a2d7f991b9c3cb7e3d83ced45e65a8c0a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bal=C3=A1zs=20Orb=C3=A1n?= Date: Sun, 7 Nov 2021 16:05:30 +0100 Subject: [PATCH 5/6] Update options.md --- docs/configuration/options.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/configuration/options.md b/docs/configuration/options.md index c4eb408b..9dd1a4df 100644 --- a/docs/configuration/options.md +++ b/docs/configuration/options.md @@ -17,8 +17,8 @@ If your Next.js application uses a custom base path, specify the route to the AP _e.g. `NEXTAUTH_URL=https://example.com/custom-route/api/auth`_ -:::tip -To set environment variables on Vercel, you can use the [dashboard](https://vercel.com/dashboard) or the `vercel env` command. +:::note +On [Vercel](https://vercel.com) deployments, we will read the `VERCEL_URL` environment variable, so you won't need to define `NEXTAUTH_URL`. ::: ### NEXTAUTH_URL_INTERNAL From f36237b3f2585f04c3d395c3bd30862a4fb09ee1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bal=C3=A1zs=20Orb=C3=A1n?= Date: Mon, 8 Nov 2021 13:56:31 +0100 Subject: [PATCH 6/6] Update options.md --- docs/configuration/options.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/configuration/options.md b/docs/configuration/options.md index 9dd1a4df..136d6120 100644 --- a/docs/configuration/options.md +++ b/docs/configuration/options.md @@ -70,7 +70,7 @@ A random string used to hash tokens, sign/encrypt cookies and generate cryptogra If not specified, it uses a hash for all configuration options, including OAuth Client ID / Secrets for entropy. Although if the user does not use such a provider, the configuration might be guessed. -:::warn +:::warning The default behaviour is volatile, and it is strongly recommended you explicitly specify a value. If `secret` is omitted in production, we will throw an error. :::