Add API endpoints at /api/auth/link and /api/auth/unlink

[iaincollins]

Add API endpoints at /api/auth/link and /api/auth/unlink for linking and unlinking OAuth accounts. This was a feature of v1 but did not make the cut for v2.0.

Note:

The /api/auth/signin endpoint currently lets you link accounts securely (i.e. if signed in and then you sign in with a different account).

Once a page at /api/auth/link is implemented /api/auth/signin should probably direct users there if the user is signed in. It would effectively be the same as the sign in page, but would only list OAuth providers, and would have 'Unlink' options for providers that are already linked.

[LoriKarikari]

Does this let users link social OAuth accounts that don't return an email address?

[iaincollins]

That's a great question!

So (unless there is an additional check somewhere I have missed) yes it does allow this, which was also the case with version 1. Like version 1, version 2 currently requires an email address to create a user account, but is limited in that it only stores one email address per user.

Once you have a user account, you can link as many accounts as you like (or unlink them all, which is safe because you can still always log in via email).

Not allowing people to unlink all accounts unless an email is specified is good example of an edge case that comes up if you don't require an email address.

There is probably a good discussion to be had around how multiple email addresses could be tracked per user.

e.g. Perhaps it could even use the existing account database (e.g. with provider: 'email', type: 'email' and the email address for the account ID), as it would already enforce uniqueness, but we'd probably want to add a 'verified' flag and also we'd want to consider what we do with the existing user object (would it then be used to store a primary email address?)

[LoriKarikari]

Cool, might be a good idea to add to the each OAuth provider's docs which one returns an email address and can be used for both signup and linking and which ones don't return an email address and can only be used for linking.

[nsafai]

Curious what the status is of this issue?

Ideally I'd like the following experience:

• User can sign up with email, Google, Spotify or Soundcloud
• After signing in, prompt user to connect the rest of their music accounts, e.g. Google (Youtube), Spotify and Soundcloud

[michaelhays]

For anyone that wants to allow users to link an OAuth account to a user, but not register with one, try this advanced initialization (getUser is just a function to retrieve the user from the database):

import type { NextApiRequest, NextApiResponse } from 'next'
import type { NextAuthOptions } from 'next-auth'
import NextAuth from 'next-auth'
import EmailProvider from 'next-auth/providers/email'
import GoogleProvider from 'next-auth/providers/google'
import { getSession } from 'next-auth/react'

export function getNextAuthOptions(req?: NextApiRequest): NextAuthOptions {
  return {
    providers: [
      EmailProvider({ ... }),
      GoogleProvider({ ... }),
    ],

    callbacks: {
      async signIn({ user, account }) {
        if (account.provider === 'email') {
          // Allow login by email if the User already exists
          return Boolean(await getUser({ email: user.email }))
        }

        if (account.provider === 'google') {
          // Allow connecting a Google account to an authenticated User
          if (await getSession({ req })) {
            return true
          }

          // Allow login by an already connected Google account
          if (await getUser({ id: user.id })) {
            return true
          }

          return false
        }

        return false
      },
    },
  }
}

export default async function auth(req: NextApiRequest, res: NextApiResponse) {
  return await NextAuth(req, res, getNextAuthOptions(req))
}

The use case for me here was that users can only register through an email invitation from another user, but should be able to connect their Google account once logged in.

The key was being able to access the user session from within the signIn callback, which took me embarrassingly long to figure out how to do. So hopefully this helps someone save some time!

[forresthopkinsa]

To clarify – is there no way to link multiple accounts right now? Linking is mentioned a few times in the documentation but I haven't seen it directly addressed.

[balazsorban44]

Account linking is an automatic process right now.

Say you logged the user in with signIn("email"). Then if you run signIn("github") and it has the same e-mail address, the accounts will be connected. Otherwise, it will throw an error, as we use the e-mail as the connecting identity of the accounts.

We also don't connect users when you are logged out as a security measure. You must be logged in.

This feature request is about creating a better API, and allowing unlinking accounts when you no longer need one.

Adapters usually have a linkAccount, unlinkAccount method which this API will probably use.

[forresthopkinsa]

This is particularly confusing as it seems to contradict the FAQ:

Automatic account linking on sign in is not secure between arbitrary providers - with the exception of allowing users to sign in via an email addresses as a fallback (as they must verify their email address as part of the flow).

When an email address is associated with an OAuth account it does not necessarily mean that it has been verified as belonging to account holder — how email address verification is handled is not part of the OAuth specification and varies between providers (e.g. some do not verify first, some do verify first, others return metadata indicating the verification status).

With automatic account linking on sign in, this can be exploited by bad actors to hijack accounts by creating an OAuth account associated with the email address of another user.

For this reason it is not secure to automatically link accounts between arbitrary providers on sign in, which is why this feature is generally not provided by authentication service and is not provided by NextAuth.js.

...

Automatic account linking is not a planned feature of NextAuth.js, however there is scope to improve the user experience of account linking and of handling this flow, in a secure way. Typically this involves providing a fallback option to sign in via email, which is already possible (and recommended), but the current implementation of this flow could be improved on.

I was relieved to see this in the FAQ because automatic linking would be a significant security issue in my application, for exactly the reasons listed there. But now it sounds like accounts are automatically linked?

I must be missing some differentiating detail to reconcile these seemingly opposed answers, could you highlight it for me?

Edit - I think the key is in your statement that "We don't connect users when you are logged out" – are you saying that accounts are only linked if signIn is called on an already signed-in user? If that's the case, then I think I'm understanding the situation now.

[forresthopkinsa]

I read the source and it's crystal clear now, thanks for the help

[JonParton]

I've just spent this evening implementing this "Auto functionality" in a gracefull way when you are already signed into a custom auth/signin page. Showing what is already linked and also handling the OAuthAccountNotLinked error when it occurs; asking them to use magic link first then linking the conflicting O-Auth account etc 👍.

It's working well but just one clarification to what has already been said. I see it mentioned that the email of the OAuth account need to match up with the signed in user to be auto linked but this doesn't seem to be the case. I can link 2 GitHub accounts with different email addresses to the same user record when logged in to it...

Not a problem for me and actually an advantage but thought I'd clarify.

As per the queries above from others, is this feature to implement API's for Linking / Unlinking still on a roadmap? Do we have any rough timescales?

Would love to take this further and have Unlink capability too! (Guess I could now if I manually manipulate the "Account" table and delete records but for it to be usefull I need to be able to store some extra info like what email address is against each account etc (possible multiple account's per user record).

Anyways enough natter, thanks for creating an awesome project for all to use!!! 👍👍🥳

[JonParton]

Just an additional note that this does seem to be a known behaviour (linking accounts with different email addresses) mentioned in this issue #3300 .

[AJax2012]

Although I think the API endpoints would still be a huge help, I did find a bit of a workaround if you're using an adapter:

• Client: https://github.com/AJax2012/gardner-web-tech/blob/main/apps/recipes-web/src/pages/auth/accounts.tsx#L36-L76
• API: https://github.com/AJax2012/gardner-web-tech/blob/main/apps/recipes-web/src/pages/api/auth/unlink/%5Bprovider%5D.ts

signIn now apparently allows linking of accounts if the user is already signed in: https://github.com/nextauthjs/next-auth/blob/main/packages/next-auth/src/core/lib/callback-handler.ts#L154-L162

All that was left was to figure out how the adapter used the unlinkAccount method and adapt it to my API endpoint. I used Prisma, so I just looked here: https://github.com/nextauthjs/next-auth/blob/main/packages/adapter-prisma/src/index.ts#L19-L20

I believe most of the adapters have unlinkAccount implemented at this point, so hopefully, it shouldn't be too bad to figure out for anyone using a different adapter.

I'm not exactly a security expert, so please let me know if you see issues with my implementation, but I think it looks safe and straightforward. I don't want to be advertising unsafe code for others to copypasta.

Hope this helps!