Next-auth: 🚨 NextAuth.js 2.0 - Release Candidate

[iaincollins]

I am considering next-auth@beta (the current version in master) as a release candidate for 2.0 and that it 2.0 will be released in the next few days, depending on feedback.

_Latest beta release: [email protected] (2020-06-21)_

Features

Authentication

• Designed to work with any 0Auth service, it supports 0Auth 1.0, 1.0A and 2.0
• Built-in support for many popular 0Auth sign-in services
• Supports email / passwordless authentication
• Supports both JSON Web Tokens and database sessions

Own your own data

• An open source solution that allows you to keep control of your data
• Supports Bring Your Own Database (BYOD) and can be used with any database
• Built-in support for for MySQL, MariaDB, Postgres, MongoDB and SQLite
• Works great with databases from popular hosting providers

Secure by default

• Designed to be secure by default and promote best practice for safeguarding user data
• Attempts to implement the latest guidance published by Open Web Application Security Project

Security focused features include CSRF protection, use of signed cookies, cookie prefixes, secure cookies, HTTP only, host only and secure only cookies and promoting passwordless sign-in.

Acknowledgement

NextAuth.js 2.0 is possible thanks to its contributors.

I would in particular like to thank the following people for their help with 2.0:

• Lori Karikari
• Nico Domino
• Fredrik Pettersen
• Gerald Nolan

I think this is fantastic feature set for a first release. We have so far smashed everything that was planned for 2.0 and gone beyond that by some margin.

I know there are many more people who have offered to help and I know there are features that many of you would like to see that didn't make the cut; unfortunately my time is limited and I feel it's important to cut a release so v1 can be finally be retired!

I'm am looking forward to working with more of you and figuring out the roadmap for 2.1 to build on this release and extend authentication mechanisms, adding features to JSON Web Token support, auditing / logging, database migration support and lots of other exciting stuff.

I'd ask if you would raise any bug reports or feature requests (including what you might see as incomplete features) as separate issues and just link back to this ticket mentioning this ID.

Please do ask questions in this thread! I'm sure you have a question someone else has it too.

Documentation

Please checkout the excellent documentation site (with link to live demo) that the folks in the team have worked on https://next-auth.js.org

[iaincollins]

I'm going to repost a question here from @emmenko asked in #167 as it is a very good question and I think people other may also be interested in it and may have feedback:

I have a question about using JWT. Does it mean that we don't need a DB anymore?
Thanks

That's a great question! The answer is "sort of" and that it will be improved.

• If you want right now, you could use an SQLite in memory database in production when using JWT, so you don't need a hosted database anywhere if you are using an authentication provider that you trust (e.g. email sign in, the Google provider that verifies email addresses, or some other OAuth provider you trust).
• The flip side is the User ID value in the JWT would be meaningless in this scenario (and should be ignored), but otherwise you could use this approach.
• However how I would like it to be work is that I would like the option not to be able to provide a database at all and have everything still work.
• I think to be useful, it would need to have an additional option, such as callback function which allowed you to evaluate a user on sign in and decide if they were valid and allowed to sign in (e.g. based on the service / account they were using, or the email address they were sign in with if used with an authentication provider you trust).
• This function could potentially also return data (e.g. credentials, roles) to be added to the JWT.

This is not terribly complicated and could potentially be something that goes in before 2.0 is released, depending on feedback.

[LoriKarikari]

I've been a bit afk lately but I've read some pull requests and issues. I can help with the OAuth provider docs somewhere this week if you want. I saw that you wanted separate docs per provider like Passport does it I guess? Also, I have to look into the Reddit profile stuff and had the same issue with some other providers that I haven't included yet.

[LoriKarikari]

I'm am looking forward to working with more of you and figuring out the roadmap for 2.1 to build on this release and extend authentication mechanisms, adding features to JSON Web Token support, auditing / logging, database migration support and lots of other exciting stuff.

Maybe we could have some place like Discord or whatever you like to discuss this stuff? It's easy to miss stuff being said in issues and pull requests and it's less clutter too.

[iaincollins]

I've been a bit afk lately but I've read some pull requests and issues. I can help with the OAuth provider docs somewhere this week if you want. I saw that you wanted separate docs per provider like Passport does it I guess? Also, I have to look into the Reddit profile stuff and had the same issue with some other providers that I haven't included yet.

+1 been super busy recently too, sorry about to anyone if I have missed anything.

Yeah, I think I've changed my mind from my original view of consolidating all the providers into one page and allowing them each to have a separate page.

I think the guide you wrote is wonderful and we should keep that exactly as is, as it works for most providers (and explains what is going on).

I think having dedicated pages for each authentication provider (ala Passport) is the way to go after all, especially for the special cases like Apple authentication provider that @geraldnolan put together are is super useful.

Even in simple cases like Facebook it's nice to have a place to confirm how straightforward it is, as well as list any caveats in detail.

I haven't really thought about the format of the page though, so if anyone has better ideas for a template for them would welcome that! (Appreciate there will always be exceptions like the Apple one too, which is more involved.)

[iaincollins]

I'm am looking forward to working with more of you and figuring out the roadmap for 2.1 to build on this release and extend authentication mechanisms, adding features to JSON Web Token support, auditing / logging, database migration support and lots of other exciting stuff.

Maybe we could have some place like Discord or whatever you like to discuss this stuff? It's easy to miss stuff being said in issues and pull requests and it's less clutter too.

I've been thinking this too!

I'd really like a dedicated place for us to chat about proposed stuff (myself, you, Nico and Gerald…) before I do it. I appreciate I've just been "doing stuff" as we don't really have a way to do that right now, beyond just writing stuff in PRs.

A better place where folks can self help would also be good I think.

I think Discord is a great suggestion and would fit really well!

[mathewtrivett]

Firstly to say thanks to you as a team for putting this release together it looks really exciting. I work for a design company and we are focussing on Next.js for most of our Frontend work. Having a trusted Auth mechanism has long been a bug bear. This release looks great and impressive how rapidly it has evolved.

It is likely that we'll be piloting Next-Auth 2.0 in a live project for a very security conscious client. We'll be evaluated against the OWASP Application Security Verfication Standard and its likely that the system we produce will be pen tested.

It might be a really good opportunity to take Next-Auth for a stress test. I'd be interested in contributing back to Next-Auth if that would be of interest?

[iaincollins]

@mathewtrivett Thank you, I would really welcome that.

I've been considering reaching out to people who are specialists in this area and who might be willing to conduct a review.

1. Right now we don't have an explicit disclosure policy, so that's probably a first action we can take. If you would like to reach out to me privately in the interim about anything sensitive (and that it might be sensible to have patch ready to install for before disclosing) you can also reach me on [email protected]

2. After that, I would expect to drop a decent set of regression tests for all flows, which run against multiple databases (and none). That should at least ensure we maintain standards for issues we are already aware of.

JWT support might also be worth mentioning in this context, given it's very new:

When enabled, JSON Web Tokens are signed but not encrypted. When functions for people to add their own data to them that will change to encrypted then signed - as NextAuth.js is _currently_ the only thing that sets data on them - there is no API for this - signed only is good enough as the JWT does not contain any sensitive data the user should not have access to, and it is not readable from client side JavaScript.

Of course, I'm also sure there are lots of things we don't know about and I would really welcome a review and recommendations.

I'd be happy to provide additional documentation related to this, to help clarify intended behaviour.

[shufflemattdev]

Hey @iaincollins, once again thank you for all of your work on this project. I know you have touched on this briefly but are you planning on this 2.0 release being ready for production use cases. Many of the docs mention the fact that this is still in beta but wanted to get some clarity on that if possible?

[iaincollins]

Hey @iaincollins, once again thank you for all of your work on this project. I know you have touched on this briefly but are you planning on this 2.0 release being ready for production use cases. Many of the docs mention the fact that this is still in beta but wanted to get some clarity on that if possible?

Sure! So the beta notices will be removed from the docs when it's cut for release.

Things will move much slower after release to ensure stability and to avoid breaking things once v2.0 i sout (with moving fast and breaking thing being something of a luxury of being pre-release), but there will be beta or canary releases at about the same pace.

Version 2.0 has been re-written, with a new approach and entirely new code, from the ground up in about a month. However, the next big update will probably take the same time again but will be a much more modest update - likely with a focus on testing - but there will likely be many bug fixes in the meantime as reports come in.

The feature set for 2.0 is pretty fixed at this point, but I one thing that might happen that is by nature relatively safe, is that database support may become optional when using JWT - for those that don't want or need to persist user accounts, because they are using an OAuth service they trust. I am still waiting to see what other issues come before I make a call on that though.

We've had some great bug reports and fixes since this post went up, but will see what the sort of rate of them in and will want to be confident it's suitable for mainstream use cases in a production environment, before making a call on moving out of beta.

(On that note, positive reports also welcome!)

[shufflemattdev]

@iaincollins Great, that is helpful thank you!

[eknowles]

@iaincollins re: community discord/slack https://github.blog/2020-05-06-new-from-satellite-2020-github-codespaces-github-discussions-securing-code-in-private-repositories-and-more/#discussions looks like it'll be coming soon. I'd advise against creating another silo of information, only because searching is really important and keeping it in GitHub would make life much easier for noobies

[emmenko]

I agree to wait for the GitHub Discussion feature to be available. That would be my preference as well.

[LoriKarikari]

Discord would be to discuss the roadmap and behind the scenes stuff for contributors. Discussions are to answer questions from the community. These are two separate things. I didn't mean to move the community to Discord. Just internal discussions.

[iaincollins]

Discord would be to discuss the roadmap and behind the scenes stuff for contributors. Discussions are to answer questions from the community. These are two separate things. I didn't mean to move the community to Discord. Just internal discussions.

This was my thinking too, although I was just looking at it and I think there might be some team discussion features on GitHub that might let us have private discussions?

We should probably move the discussion on this to dedicated ticket as some good options to be discussed there! Will do that over lunch and link back to it unless anyone beats me to it (please feel free! :-)

[mathewtrivett]

@iaincollins sorry for the delayed reply but yes will drop you a message next week to give you a bit more context to the project.

But essentially we will be using Google Auth. I’m hoping to use JWT and avoid having a db if at all possible. So the docs you mentioned about JWT behaviour would be super useful.

As you suggested happy to flag anything we find privately via email. But also happy to work on fixes and improvements if we can.

[digizen]

I want to say I'm absolutely floored at how easy it was to set up authentication using this library. Huge kudos!

Quick question - is there a way to hook into the database so that there session can return more than just the username/email? I'm trying to figure out how to fetch the roles that a user belongs to without having to do a second round trip.

[iaincollins]

I want to say I'm absolutely floored at how easy it was to set up authentication using this library. Huge kudos!

Thanks! I'm really happy to hear that!

Quick question - is there a way to hook into the database so that there session can return more than just the username/email? I'm trying to figure out how to fetch the roles that a user belongs to without having to do a second round trip.

No, but there should be. There is a @TODO to expose a callback function to allow you to customise what /api/auth/session returns.

I might add that over the weekend before we release, as it's a very simple / low risk change and quite a few folks have asked about it.

[iaincollins]

JWT sessions

We've been getting a few questions about JWT support, so thought I'd update folks on that and let them know to follow Encrypt JWT after signing which is planned to be wrapped up this weekend (hopefully later today) – the final implementation may differ from outline in the ticket.

As described in the ticket, it will be a minor breaking change to some of the options (to the jwt and session* options specifically) to rename things, but will make it possible to:

1. Read from the JWT more easily

   There will be an explicit method for this you can use to access JWT sessions in API routes.

2. Inject additional data into JWT

   i.e. on initial sign in and when re-signing, which is triggered when the client checks a session

3. Define custom signing / verification / encryption / decryption routines for JWT

   This will allow you to any use mechanism you want for the JWT, so you can easily use an existing pragma, whether that is signed payload inside a signed JWT or signed then encrypt mode, or signed but not encrypted.

   Note: By default the JWT will be both signed and encrypted and just as easy to use as it is now; but it will be possible to customise the handling if you want to.

Database sessions

It is likely the option to customise the contents of the session object that is returned when using database sessions will also be included in the same update, to allow for feature parity between the two approaches.

Things seem stable and could have launched without this, but this is a breaking change so it would be harder to release after v2 without breaking things for people, so I think it's worth holding on and releasing until after it's done as we are otherwise going to have to field a lot of tickets about it; but the impact on delay of v2 release should be fairly minimal.

[iaincollins]

Based on feedback and the sorts of issues that were coming, some features from 2.1 were brought forward and a large cumulative update has now been released to next-auth@beta as PR #223.

This introduces some breaking changes to the current options, including some small changes to the database schema, but I think the feature list will make a lot of people happy. All the changes are reflected in the updated documentation.

This is the last feature update I intended to work on personally before we release v2. It is a larger update than I had planned and probably pushes the release of v2 till later this week to allow time for wider testing and any bug fixing as required before we cut the release.

There is some great additional provider documentation that is in progress too.

Change log

NextAuth.js beta releases haven't normally included a change log, but as we are so close to release and it's such a big update I thought it was worth detailing the changes.

Database

• [x] Databases are now optional - useful with OAuth + JWT if you only need access control
• [x] Updated documentation and added example code for custom database adapters

JWT

• [x] JWT option is now an object that groups JWT related options together (was a boolean)
• [X] Refactored JWT lib and add AES encryption / decryption as well as signing / verification
• [x] Allows JWT encode/decode methods to be overridden as options
• [x] Contents of JWT can easily customised - without needing to use custom encode/decode
• [x] Exported JWT methods so they can be called from custom API routes
• [x] Updated documentation for new JWT options

Sessions

• [x] All session options (eg. maxAge, updateAge) now grouped under single session option
• [x] Using JWT for sessions is now enabled from session object (session.jwt: true)
• [x] All options involving time now use seconds (instead of milliseconds) for consistency
• [x] Added option to customise the Session object that is returned from /api/auth/session
• [x] Update documentation for new Session options

Other improvements

• [x] Added allowSignin() option to control what users / accounts are allowed to sign in
• [x] Refactored callbackUrlHandler() - this option is now called allowCallbackUrl()
• [x] Minor improvements to NextAuth.js client API methods
• [x] Minor to NextAuth.js API routes
• [x] Minor improvements to built-in error pages
• [x] Refactored database models
  All tables now include a created column for each row which contains the datetime of when the row (e.g. User / Account / Session) was created.
  Additionally, sessions now use the name 'expiry' for the expiry datetime value for consistency with other models.

[LoriKarikari]

@iaincollins any reason why you don't use the release notes on Github? I always tend to go look there for updates haha but you don't post them there.

[iaincollins]

@iaincollins any reason why you don't use the release notes on Github? I always tend to go look there for updates haha but you don't post them there.

I haven't been using releases yet to allow beta development to go faster, but that is not really sustainable with so many contributors (or post launch).

I'd like to automate things more and structure it better starting from the release of 2.0.

Have captured this in some related issues:

• Team to decide what platform to use for internal discussions
• Add GitHub hook to publish to NPM when a new release is created
• Automate testing; add code coverage
• Decide on roadmap for 2.1

[iaincollins]

Update: Scope creep has gotten to us 🧟‍♂️

The good news is great new features have dropped, and more are on the way and, based on the feedback we've been getting, I think they are cohesive and relevant to a large number of people.

JWT and being able to use NextAuth.js without a database are already covered above, another feature that recently was released was that email addresses are now optional (but can still be required), to allow signing in with providers that don't provide them. The range of providers supported out of the box (and compatibility with custom providers) continues to grow too.

Currently in progress:

• #245 - Update and document models, schemas and database structure
• #247 - New Callback / Events system

The bad news is the previous release candidate is no longer a release candidate and obviously this pushes the release back another week.

We could have pushed back the changes in to a future release, but it would be a lot harder to do them in a responsible way after launch and would have taken many more weeks to get there if we had released; and I think a lot of folks would not have been very happy with the quality if we had released the current default database models in the current state.

I am trying to draw a line here though. You can track the milestones on GitHub to see how we are doing. There are new issue templates for features / bug reports / question too, to help with structure. Please do use those to report bugs, ask questions and request features.

[iaincollins]

Your feedback on the data model is requested!

Request For Comments - Database Schema

Please leave comments related to the schema on the issue linked to above and not here. Thanks!

[iaincollins]

You are probably all sick of updates at this point, but the last of the features for 2.0 are released!

• PR #253 added new Models and Schemas
• PR #260 added new Callbacks and Events
• PR #262 added limited support for credentials sign in

The first two were critical breaking changes to the beta, and were made so that we don't have to make breaking changes after 2.0 is released (even as we add new features).

Included with both these updates are improved documentation and error handling.

If you are already using an earlier release of the beta be sure to checkout the new options documentation - and the Pull Requests above - to see how things have changed.

[iaincollins]

Extremely happy to announce that NextAuth.js v2.0 has been released. 🥳

Thanks everyone for the amazing contributions!

The release notes and web site contains all the information and documentation about this release, but if you interested in some of the work that's been going on, you can take a look at recent pull requests that have been merged.

If you want to see what's in store for the future you can keep an eye on the milestones.