Skip to content
Migrating from NextAuth.js v4? Read our migration guide.
API reference
workos

providers/workos

Built-in WorkOS integration.

WorkOSProfile

Extends

  • Record<string, any>

Properties

connection_id

connection_id: string;

connection_type

connection_type: string;

email

email: string;

first_name

first_name: string;

id

id: string;

idp_id

idp_id: string;

last_name

last_name: string;

object

object: string;

organization_id

organization_id: string;

raw_attributes

raw_attributes: {
  email: string;
  firstName: string;
  id: string;
  lastName: string;
  picture: string;
};
email
email: string;
firstName
firstName: string;
id
id: string;
lastName
lastName: string;
picture
picture: string;

default()

default<P>(options): OAuthConfig<P>

Add WorkOS login to your page.

Setup

Callback URL

https://example.com/api/auth/callback/workos

Configuration

import { Auth } from "@auth/core"
import WorkOS from "@auth/core/providers/workos"
 
const request = new Request(origin)
const response = await Auth(request, {
  providers: [
    WorkOS({
      clientId: WORKOS_CLIENT_ID,
      clientSecret: WORKOS_CLIENT_SECRET,
      issuer: WORKOS_ISSUER,
    }),
  ],
})

Resources

Notes

By default, Auth.js assumes that the WorkOS provider is based on the OAuth 2 specification.

WorkOS is not an identity provider itself, but, rather, a bridge to multiple single sign-on (SSO) providers. As a result, we need to make some additional changes to authenticate users using WorkOS.

In order to sign a user in using WorkOS, we need to specify which WorkOS Connection to use. A common way to do this is to collect the user’s email address and extract the domain. This can be done using a custom login page. To add a custom login page, you can use the pages option:

pages: {
  signIn: "/auth/signin",
}

We can then add a custom login page that displays an input where the user can enter their email address. We then extract the domain from the user’s email address and pass it to the authorizationParams parameter on the signIn function:

pages/auth/signin.js
import { useState } from "react"
import { getProviders, signIn } from "next-auth/react"
 
export default function SignIn({ providers }) {
  const [email, setEmail] = useState("")
 
  return (
    <>
      {Object.values(providers).map((provider) => {
        if (provider.id === "workos") {
          return (
            <div key={provider.id}>
              <input
                type="email"
                value={email}
                placeholder="Email"
                onChange={(event) => setEmail(event.target.value)}
              />
              <button
                onClick={() =>
                  signIn(provider.id, undefined, {
                    domain: email.split("@")[1],
                  })
                }
              >
                Sign in with SSO
              </button>
            </div>
          )
        }
 
        return (
          <div key={provider.id}>
            <button onClick={() => signIn(provider.id)}>
              Sign in with {provider.name}
            </button>
          </div>
        )
      })}
    </>
  )
}
 
export async function getServerSideProps(context) {
  const providers = await getProviders()
  return {
    props: { providers },
  }
}
💡

The WorkOS provider comes with a default configuration. To override the defaults for your use case, check out customizing a built-in OAuth provider.

Disclaimer If you think you found a bug in the default configuration, you can open an issue.

Auth.js strictly adheres to the specification and it cannot take responsibility for any deviation from the spec by the provider. You can open an issue, but if the problem is non-compliance with the spec, we might not pursue a resolution. You can ask for more help in Discussions.

Type parameters

Type parameter
P extends WorkOSProfile

Parameters

ParameterType
optionsOAuthUserConfig<P> & { connection: string; }

Returns

OAuthConfig<P>

Auth.js © Balázs Orbán and Team - 2024