Next-auth: [v2] Document providers

[iaincollins]

Thanks to @LoriKarikari (who has provided most of these) and node-oauth (by @ciaranj) we have a rapidly growing list of supported providers.

What they are and how to pass in your own need to be documented somewhere, in addition to the README (docs/providers.mdx?)

Currently Supported

• Discord
• GitHub
• Google
• Mixer
• Slack
• Twitter
• Twitch

Planned

• Reddit (in PR)
• Facebook

In addition, support for the following 'built in' providers (which can be enabled/disabled) is also planned, although they may not drop at the same time.

• Email (e.g. via sign in link) - Either in v2.0 or v2.1 (TBD)
• Credentials (e.g. email + password, 2FA, etc) - Likely to drop in v2.1 or later

These were both supported in v1, but only email sign in was supported out of the box and the token / email verification system could have been better.

[LoriKarikari]

Do you want something similar to this file in v1?

[iaincollins]

I was thinking that but actually I think that is too annoying to maintain for a long list of providers, as I found it got out of date quickly when providers change their dev / admin pages. :-/

While I guess we could preserve these if still useful (do you think they are, or does it seem pointless info now?) I was thinking the list of providers with maybe an example of a 'custom' dummy oAuth provider with a list of all possible supported fields might be enough this time.

Specific notes known for each provider to help folk avoid gotchas might be nice.

e.g. GitHub only allows one callback URL per application, Facebook doesn't allow callbacks to localhost URLs (I think both of these are true, but not 100% certain).

What do you think would be useful?

Maybe instead of the existing step by step guides, a blog post type example with one or two popular providers could be a follow up for the future, to help folks new to build apps get started?

[LoriKarikari]

Yeah, maybe just a list of providers with links to where to get the credentials, because some websites tend to hide this very well. 😅 And as you said notes for each provider. All seems okay to me. I can make the first draft of this.

[iaincollins]

Ooh, linking to the URL of the configuration pages for providers sounds like a good idea.

That would be great if you get time!

[LoriKarikari]

I'm currently documenting but I'm stuck at the email provider. In your example app, you are using EMAIL_SERVER which is a connection string but when I look at the provider file itself it has this config:

server: {
    host: 'localhost',
    port: 25,
    auth: {
     user: '',
     pass: ''
    }
},

I haven't looked through all the commits yet but has it changed?
Edit: okay, I see you edited it 😉

[iaincollins]

Oh thanks for asking! I thought I'd updated it as figured was confusing!

I'm happy to add some example connection string formats (e.g. protocols, ports, options) for common mail providers (AWS, SendGrid, MailGun, etc), as it's not always easy to work out what they should be (and what options are needed, like SSL, TLS, ports, etc seem to vary a lot)

I wasn't sure about what to call the parameter for this and ended up calling it 'server'.

If you have any thoughts about better names or terminology for options like this (including for Providers, Adapters) or anything in the codebase would really welcome that!

I'm very happy to completely rename things to something that makes it easier to understand, and I guess makes sense to do that before launch.

[LoriKarikari]

I came across this nodemailer page and it says you can configure with only the provider name. Is that an option too?

[iaincollins]

Oh! I thought you had to load a module to do that but I guess they are built in to nodemailer now!

Yeah that is better, we should definitely link to that!

[LoriKarikari]

Maybe we can rename email to magic link or passwordless? I think it's more clear that way.

[iaincollins]

Hmm I think passwordless seems like not a bad option; although I wonder if end users might be more familiar with seeing terminology 'email sign in' on the front end, and if there is value in using the same language? I appreciate 'email' as a type might not seem clear though.

If we think passwordless is clearer though, am all for changing it!

PS: I know that provider 'type' can also be 'oauth' or 'oauth2' in code currently; intended gonna remove all the 'oauth2' stuff as not needed (as the 'oauth' type can be either) and to clean that internal oauth code up a bit.

[LoriKarikari]

Going to clean up these docs tomorrow because now that it's deployed on the site I can see some code and text that is not aligned properly and the table is too wide so going to split that up in two separate ones. Also add some better styling and fancy colors to makebit more consistent with the other docs 🤩

[LoriKarikari]

Docs now have a providers section which will be updated when new providers are added.