RFC: Token providers

[balazsorban44]

Goals:

• Backwards compatible: This is a superset of the Email provider, and so we could change its implementation to use the new type: "token" one under the hood. So this CAN be implemented in a backward-compatible way.

Background:

We are pushing against rolling your own email+password database solutions (although it can easily be implemented with the Credentials provider), as they are less secure since it is easier to introduce security holes without the proper knowledge.

There are many advantages with passwordless methods. In case of the existing Email provider, the security concerns* are moved from your app to your e-mail provider, who usually have a much more robust infrastructure in place for all kinds of threat mitigation already.

• Verification token encryption/hashing to prevent email security issues #1051 could make this flow even more secure, by only allowing to finish the login flow on the same device the login was initiated on. This could be implemented in a way that makes the developer aware of the drawbacks, and so we could introduce it opt-in.

Now there are ways of doing paswordless logins, than our current solution. For e-mail for starters, we require you to bring your own mail server, which might not be straight forward in some situations.

With the help of this RFC, we could create an abstraction that would make it easy to integrate against solutions like Magic, or SMS (anything else? Please add it in the comments)

• relevant issue: Open providers to more complex passwordless use cases #414

Implementation:

The implementation details are not fully clear yet, but we could probably build on the Email provider, also could look for inspiration in this now closed PR #409 that attempted to add webhook support.

Out of scope:

Open PR:

[narciero]

+1 for Magic support - it would be great to have a clean abstraction for handling integrations like that. I wrote a brief blog post here on how I am currently integrating Magic w/ NextAuth via a custom Credentials provider but would love to see first-class support for passwordless/token based providers.

[balazsorban44]

Very useful blog post! I just had a quick look and it verified what I suspected. For Magic to work, we will need some client-side code as well. I think we will need something like next-auth/magic or @next-auth/magic so not everyone will need to import the Magic SDK.

[narciero]

Cool, yea I think a @next-auth/magic package would be nice, are you thinking that would provide the helper methods for both generating the DID token (client-side) and validating/authorizing the token (server-side)?

[balazsorban44]

Feel free to add your blog post to our tutorials page in a PR for now! 😊

[narciero]

Done, thanks! #2340

[balazsorban44]

@narciero I am sorry to share with you that someone is copying your blog post 😞

Yours: https://dev.to/narciero/using-nextauth-js-with-magic-links-df4
Copied: https://sayed.cyou/blockchain-dev/using-nextauth-js-with-magic-links-blockchain-dev-feed/

I have seen other posts being copied from elsewhere by that person. I did not take further action, do as you please. But remember the person might not be aware what they are doing is unethical, so be kind first. 💚

[Izhaki]

What really confuses me is that for all I can tell EmailProvider can be made to support all of these.

But I guess we are trying to draw a distinction here between:

• the email link sent as a default with EmailProvider
• the type of flow where the user has to enter the token on the UI (no idea what to call this, there are a few names going around; Email/SMS/Magic code are common but not sure capture the full intention here).

However, this excludes the Magic proposal, because with it the authorisation is done via a 3rd party - this seems much more of a simple credentials case?

But as for scope:

1. The new provide will have a generateVerificationToken that by default be a 6 digit random code. Users can override in settings.
2. The sendVerificationRequest will be empty to allow SMS, nodemailer-free Email, whatever.
3. The signin page should add support for entering the token in the UI straight after providing and email/phone number. Similar to this demo.
4. Should we hash the token and store it in a cookie to ensure same device login? You anyhow need to send the email/phone with the token when you verify, so it is pretty much limited to same device anyhow (unless a hacker knows both your email/token). Hashing the token will make this tighter though.
5. Do we add Client API methods to verify the token? Related: Non-redirect Client API support for passwordless email/sms codes #3260
6. Do we support non-redirect flows? Related: Non-redirect Client API support for passwordless email/sms codes #3260

Anything missing, or incorrect?

[Izhaki]

Minor consideration: 6 digit codes can go stale on the DB.

Another thing to consider.

Currently (with EmailProvider) tokens are unique. However, if the magic code generated is, say, 6 digits, there is some (albeit remote) possibility that a user will get the same token twice (think over 10 years).

The issue with this is that an adapter's createVerificationToken stores that 6 digit token in the DB, and if not claimed then that token will stay there forever. This means that the next time the user get the same token, the adapter's useVerificationToken may return the old token, which has long expired.

The user can still generate a new token to overcome this, so at least they are not stuck forever.

Probably the best solution here is to instruct adapter authors to remove any expired tokens at the beginning of useVerificationToken.

[Izhaki]

How do we deal with multiple UIs?

Currently, the UI for EmailProvider is in src/core/pages/signin.tsx.

There are going to be some difference between SMS (country, phone number) and Email.

How do we handle this?

Options:

• Add a getSignInForm method to the provider.
• ?

[Izhaki]

Some thought on @armandabric proposal:

Add a generateVerificationContext(...). Called before the actual sendVerificationRequest, it allow to generate any data that could be used to validate an user: token/url for an email provider, code for an sms provider.

Where else this context will be used?

Currently there is generateVerificationToken and sendVerificationRequest.

I guess the generic sendVerificationRequest will have an empty body, so depending on the actual implementation developers can put whatever environment variables needed to send the request.

Add a notifyVerificationRequestWasSend(...). Called after sendVerificationRequest, this method could be use to implement the redirection to the email page in case of Email provider

You could just provide provider.signinUrl (used here), no?

Add a validateUser method to validate the user token/code. It will by called during the verify process

Add a verifyUser(providerName, args) function to the client. It would trigger the verify process on the passwordless provider

Agree. Although verifyUser is a possibly too generic? The name in the code is useVerificationCode, which is a good name other than the fact that use typically denotes a hook in react world.

verifyToken? verifyMagicCode?

[zingerj]

Any updates on this? I'm looking to use NextAuth with a custom backend (Node.js server) to handle SMS authentication. Currently, I'm exploring a workaround using either the email and credentials provider, but my requirements are being able to send a 6-digit code via SMS and I would prefer to not create a separate database connection from the Next app. Thanks!

[marcpicaud]

Hi,

Same request here.

We have a NextJS app where users need to authenticate on a REST API, through SMS OTP. The authentication flow consists on 2 steps (2 requests) :

• Create and send the OTP
• Confirm the OTP

On the UI, same flow :

• One <form> to fill in a phone number
• Then, one <form> to fill in the OTP

Right now, doing that with NextAuth and a CredentialProvider feels very hacky.

[fotoflo]

Hello, I'm not sure if this is the right place to comment but I'm trying to figure out how to send a magic link email so an authenticated user can invite a new team member.

It woudl be great to have some documentation about how to break into this flow from the backend, or some other way.

[grantvine-sc]

Any updates on the RFC?

[xegulon]

Would be great to have that :)

[philbaker4]

While this PR from @ThangHuuVu does allow the flexibility to send a verification link via SMS (or other method) in addition to email, I'm wondering if this provider should more accurately be named MagicLink. When I think of a Token flow, I am thinking of a case where a user enters a phone or email and then manually enters that verification token (either after a redirect or in the same UI) rather than accessing a link with a token query param. I realize this is possible today with a custom Credentials implementation like @marcpicaud is doing or even with the current Email (I.e. Token in the above PR), but it would be ideal to have this functionality built in to Auth.js without needing to manually override any UI, as others are requesting above. Additionally, it would be nice if the library's implementation could also provide some sensible defaults around OTP strength, lifespan, and rate limiting.

Perhaps all of this functionality could/should be built into a single provider, but it feels like there is a logical separation in intended flow for end users. I'd love to hear other's thoughts on this before spending any time on implementing. cc @balazsorban44

[philbaker4]

Really early and rough PR that starts to implement some of the functionality as described above. Would love thoughts or feedback @balazsorban44 @ThangHuuVu

[ThangHuuVu]

thanks @philbaker4 for the detailed comments & the PR! let's join force in shipping this new provider, either Token or OTP 😁

Should we allow for OTP generation override?
Similar to the existing email provider, should we provide built in common sendOTP providers and the engineer must pass in appropriate config?

Since there are so many ways to generate OTPs: time-synchronized OTPs, lockstep synchronized OTPs, or transmission-based OTPs, we should definitely allow overriding, or even enforcing it from the app side. In my PR, I made it throw an error by default - initially I didn't want to introduce a new security concern to the library. I thought its best to let the app developer to handle token generation & clean up altogether. How do you think?

Side note: The email provider is coupled with SMTP due to the underlying nodemailer library, so we might rename it to SmtpEmail (I think I've done this in my PR too). I didn't think we should rename it to magic link, since its just the default - the app developer can easily customize it to return a token. Later on, we might add other HTTP email providers like SendGrid, Twillio, etc. These providers can have a default token generation, by calling client.generateOTP() or so. (I guess)

What is the spec for errors returned by the sendOTP method that engineers must follow?

It can follow the current sendVerificationRequest method from the email provider.

[philbaker4]

I thought its best to let the app developer to handle token generation & clean up altogether. How do you think?

I think that it would be good to provide default OTP generation as we are already are doing so in the current Email provider, though the default token generation there is more robust from a security perspective than the expected OTP code a user would be asked to type in (e.g. a 6 digit number). I think setting sensible defaults with the ability to override makes a lot of sense.

Side note: The email provider is coupled with SMTP due to the underlying nodemailer library, so we might rename it to SmtpEmail (I think I've done this in my PR too). I didn't think we should rename it to magic link, since its just the default - the app developer can easily customize it to return a token. Later on, we might add other HTTP email providers like SendGrid, Twillio, etc. These providers can have a default token generation, by calling client.generateOTP() or so. (I guess)

In regards to this, I wonder if we are conflating means of message delivery with auth provider. In my mind, auth providers represent the user sign in flow (at least by flow provided out of the box by auth.js), rather than the medium that helps facilitate that flow. I'm not locked in on any language, but hopefully the the following helps illuminate how I am thinking about things:

• MagicLinkProvider (today's default Email provider) is a flow where a user receives a link via some medium (email, sms, whatsapp, etc) that will authenticate the user when they navigate to that link use, which uses query params under the hood
• OTPProvider is a flow where a user recieves an OTP code via some medium (email, sms, whatsapp, etc) that will authenticate the user when it is typed into the Verify OTP form

That is to say that I think it would be valuable to introduce a new paradigm that sits alongside Providers and Adapters in the auth.js ecosystem -- MessageSenders (hopefully someone else is better at naming things than I am). Continuing on this idea, SmtpEmail would be the first MessageSender in the ecosystem and would (could) be the default option that is configured for MagicLink and OTP providers. Other potential senders could include HttpEmail, SMSClient, etc. I think we would ideally provide a strong offering of MessageSenders out of the box for each Provider, but this would also enable reusable community supported senders such as a TwilioClient or [new company that sends messages]Client in addition to custom implementations (I.e. what happens possible today), all in a slightly more constrained way.

Given that auth.js allows for page overrides, there's no way to ensure that the Providers are used in the same manner that is provided out of the box (as is demonstrated by the ability to override options today) but I think establishing strong Provider patterns that are tied to desired flow rather than implementation details (like smtp) will limit the frequency of overrides that break out of the box flow.

[philbaker4]

Here is a PR (internal to my account) that contains a quick demo as to how we could enable users to build custom senders (same functionality but slightly different implementation as today) or use our preconfigured senders out of the box. I've only included a built in smtp and an sms sender, their associated types and some general utility types, and some custom senders for the purposes of the demo. Let me know what you think!

[philbaker4]

@ThangHuuVu Any additional thoughts here?

[benevbright]

email sign in is amazing in theory but unfortunately in reality it's not. Because in many mobile email apps, they open the link in web view....which is super temporary and not the browser that user initiated.. It's very frustrating because there is nothing you can do about it. So solution like OTP could be more practical solution.

[longlostnick]

100%. Surprised more folks aren’t talking about this (even outside next-auth in general). Magic link login is essentially DOA as far as I’m concerned. Which is why I had to customize next-auth to send a OTP magic code instead.

[benevbright]

seems like people are talking about it here: #709. And thankfully, implementing OTP is pretty straightforward! 👍