From 90755e74b19189c58679a2c90a2e5f339994b076 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bal=C3=A1zs=20Orb=C3=A1n?= Date: Fri, 1 Nov 2024 01:15:28 +0100 Subject: [PATCH] docs: Update credentials.mdx Fixes https://github.com/nextauthjs/next-auth/issues/12157 --- .../authentication/credentials.mdx | 67 ++++++++++--------- 1 file changed, 35 insertions(+), 32 deletions(-) diff --git a/docs/pages/getting-started/authentication/credentials.mdx b/docs/pages/getting-started/authentication/credentials.mdx index dec604d2ae..526cea9e37 100644 --- a/docs/pages/getting-started/authentication/credentials.mdx +++ b/docs/pages/getting-started/authentication/credentials.mdx @@ -7,7 +7,29 @@ import { Code } from "@/components/Code" # Credentials -To setup Auth.js with external authentication mechanisms or simply use username and password, we need to use the `Credentials` provider. This provider is designed to forward any credentials inserted into the login form (i.e. username/password) to your authentication service via the `authorize` callback on the provider configuration. +To setup Auth.js with any external authentication mechanisms or use a traditional username/email and password flow, we can use the `Credentials` provider. This provider is designed to forward any credentials inserted into the login form (i.e. username/password, but not limited to) to your authentication service. + + + The industry has come a long way since usernames and passwords + as the go-to mechanism for authenticating and authorizing users to + web applications. Therefore, if possible, we recommend a more modern and + secure authentication mechanism such as any of the [OAuth + providers](/getting-started/authentication/oauth), [Email Magic + Links](/getting-started/authentication/email), or [WebAuthn + (Passkeys)](/getting-started/authentication/webauthn) options instead. + + However, we also want to be flexible and support anything + you deem appropriate for your application and use case, + so there are no plans to remove this provider. + + + + + By default, the Credentials provider does not persist data in the database. + However, you can still create and save any data in your database, + you just have to provide the necessary logic, eg. to encrypt passwords, + add rate-limiting, add password reset functionality, etc. + @@ -44,8 +66,8 @@ export const { handlers, signIn, signOut, auth } = NextAuth({ if (!user) { // No user found, so this is their first attempt to login - // meaning this is also the place you could do registration - throw new Error("User not found.") + // Optionally, this is also the place you could do a user registration + throw new Error("Invalid credentials.") } // return user object with their profile data @@ -110,7 +132,9 @@ export const { signIn, signOut, handle } = SvelteKitAuth({ user = await getUserFromDb(credentials.email, pwHash) if (!user) { - throw new Error("User not found.") + // No user found, so this is their first attempt to login + // Optionally, this is also the place you could do a user registration + throw new Error("Invalid credentials.") } // return JSON object with the user data @@ -161,8 +185,8 @@ app.use( if (!user) { // No user found, so this is their first attempt to login - // meaning this is also the place you could do registration - throw new Error("User not found.") + // Optionally, this is also the place you could do a user registration + throw new Error("Invalid credentials.") } // return user object with the their profile data @@ -305,15 +329,15 @@ export default component$(() => { -## Verifying Data with Zod +## Validating credentials -To improve the security of your `Credentials` provider use, we can leverage a run-time schema validation library like [Zod](https://zod.dev) to validate that the inputs match what we expect. +Always validate the credentials server-side, i.e. by leveraging a schema validation library like [Zod](https://zod.dev). ```bash npm2yarn npm install zod ``` -Next, we'll setup the schema and parsing in our `auth.ts` configuration file, using the `authorize` callback on the `Credentials` provider. +Next, we'll set up the schema and parsing in our `auth.ts` configuration file, using the `authorize` callback on the `Credentials` provider. @@ -363,7 +387,7 @@ export const { handlers, auth } = NextAuth({ user = await getUserFromDb(email, pwHash) if (!user) { - throw new Error("User not found.") + throw new Error("Invalid credentials.") } // return JSON object with the user data @@ -470,7 +494,7 @@ export const { handle } = SvelteKitAuth({ user = await getUserFromDb(email, pwHash) if (!user) { - throw new Error("User not found.") + throw new Error("Invalid credentials.") } // return JSON object with the user data @@ -489,24 +513,3 @@ export const { handle } = SvelteKitAuth({ - - - The industry has come a long way since usernames and passwords were first - introduced as the go-to mechanism for authenticating and authorizing users to - web applications. Therefore, if possible, we recommend a more modern and - secure authentication mechanism such as any of the [OAuth - providers](/getting-started/authentication/oauth), [Email Magic - Links](/getting-started/authentication/email), or [WebAuthn - (Passkeys)](/getting-started/authentication/webauthn) options instead of - username / password. - -However, we also want to be flexible and support anything -you deem appropriate for your application and use-case. - - - - - The Credentials provider only supports the JWT session strategy. You can still - create and save a database session and reference it from the JWT via an id, - but you'll need to provide that logic yourself. -