chore(docs): update WorkOS docs

[MoritzKn]

☕️ Reasoning

The domain used in the authorization param used in the example is deprecated and no longer supported. If it is still used, WorkOS returns the error code domain_connection_selector_not_allowed with the description:

'The domain connection selector is deprecated and may no longer be used. Use the connection or organization connection selectors instead.'

See reference: https://workos.com/docs/reference/sso/get-authorization-url/error-codes#:~:text=domain_connection_selector_not_allowed

🧢 Checklist

• Documentation
• Tests (does not apply)
• Ready to be merged

🎫 Affected issues

Couldn't find any open WorkOS related issues.

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
auth-docs	❌ Failed (Inspect)			Apr 28, 2024 2:34pm
next-auth-docs	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Apr 28, 2024 2:34pm

[MoritzKn]

The docs on the main branch (docs/pages/getting-started/providers/workos.mdx) probably need to be updated too but I do not know what your process is for this:

[ndom91]

@MoritzKn the main / v5 docs have been updated with WorkOS to point out that one needs to pass a connectionId (check out: https://authjs.dev/getting-started/providers/workos#environment-variables)

[ndom91]

@MoritzKn also why did you remove the rest of the example code?

[MoritzKn]

@ndom91 Regarding your second comment:

The whole point of the example code is to create a login page that splits the domain name from the email address, and then use that "domain" so that WorkOS can tell which connection you want to use. If you simply specify the connection using the organization or connection id, this logic is not needed.

Further, while working, the example was a little bit contrived. It's a bit strange to prompt your users to enter an email address and then only use the domain part of that email. It was simply necessary to work around the shortcoming in the WorkOS API. Just specifying the organization seems like the easiest to me.
Note: In most cases, organization and connection have a 1 to 1 relation in WorkOS. It seems that in some rare cases, an organization can have multiple connections.

Regarding your first comment:
In this version, the signIn function still uses the deprecated domain param. The necessary connection param gets mentioned but (to my knowledge) used incorrectly in the provider options. At last according to TypeScript you can not use connection as provider option like it is used here. But maybe this is because I'm on v4 and this is an v5 API..?

In my opinion, the entire "notes" section in the v5 docs is confusing and should be omitted. But maybe this is because in my use case I'm using WorkOS with just one backend providers, simply as a SAMl <> OAuth bridge.
To my understanding, for this section to make sense with the current API for multi provider user, it would need to include some logic to map from the email address to the connection ID (instead of simply using the domain).
Another option would be to just show multiple login buttons that all call the signIn("workos", undefined, { connection: "con_123" }) function but with a different connection ID.
However, I think it's fine to leave it to the developers to figure out what solution makes sense to them.

[ndom91]

Okay yeah that makes a lot of sense. I've removed that part from the current (v5) docs as well since we support the connection param directly when using the provider there.