Single Sign-On

The Single Sign-On API has been modeled to meet the OAuth 2.0 framework specification. As a result, authentication flows constructed using the Single Sign-On API replicate the OAuth 2.0 protocol flow.

To automatically respond to changes in your SSO connections, use the Connection events.

Generates an OAuth 2.0 authorization URL to authenticate a user with SSO.

import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

const authorizationUrl = workos.sso.getAuthorizationUrl({
  connection: 'conn_01E4ZCR3C56J083X43JQXF3JK5',
  clientId: 'client_123456789',
  redirectUri: 'https://your-app.com/callback',
  state: 'dj1kUXc0dzlXZ1hjUQ==',
});

You’ll have to specify the user’s connection, organization, or OAuth provider as a parameter. These connection selectors are mutually exclusive, and exactly one must be provided. The generated URL automatically directs the user to their identity provider. Once the user authenticates with their identity provider, WorkOS then issues a redirect to your redirect URI to complete the sign-in flow.

In the OAuth 2.0 protocol, a redirect URI is the location that the user is redirected to once they have successfully authenticated with their identity provider.

When redirecting the user, WorkOS will generate an authorization code and pass it to your redirect URI as a code query parameter, your app will use this code to get the user’s profile. Additionally, WorkOS can pass a state parameter back to your application that you may use to encode arbitrary information to restore your application state between the redirects.

https://your-app.com/callback?code=01E2RJ4C05B52KKZ8FSRDAP23J&state=dj1kUXc0dzlXZ1hjUQ==

You’ll need to configure the allowed redirect URIs for your application via the Redirects page in the dashboard. Without a valid redirect URI, your users will be unable to sign in. Make sure that the redirect URI you use as a parameter to get the authorization URL matches one of the redirect URIs you have configured in the dashboard.

Redirect URIs follow stricter requirements in production environments:

• HTTPS protocol is required in production environments
• HTTP and localhost are allowed in staging environments
• Wildcard characters are not allowed in production environments

Wildcards

WorkOS supports using wildcard characters in Redirect URIs. The * symbol can be used as a wildcard for subdomains; however, it must be used in accordance with the following rules in order to properly function.

• The wildcard must be located in a subdomain within the hostname component. For example, http://*.com will not work.
• The wildcard must be located in the subdomain which is furthest from the root domain. For example, https://sub.*.example.com will not work.
• The URL must not contain more than one wildcard. For example, https://*.*.example.com will not work.
• A wildcard character may be prefixed and/or suffixed with additional valid hostname characters. For example, https://prefix-*-suffix.example.com will work.
• A URL with a valid wildcard will not match a URL more than one subdomain level in place of the wildcard. For example, https://*.example.com will not work with https://sub1.sub2.example.com.
• In production environments, wildcards cannot be used with public suffix domains. For example, https://*.ngrok-free.app will not work.
• The wildcard will match a sequence of letters (A through Z, and a through z ); digits (0 through 9), hyphens (-), and underscores (_). For example, https://user:secret@foo.example.com will not work with https://*.example.com.
• A URL with a wildcard cannot be set as the default redirect URI.

If there is an issue generating an authorization URL, the API will return the original redirect URI with error and error_description query parameters. If provided, the state value will also be included.

https://your-app.com/callback?error=organization_invalid&error_description=No%20connection%20associated%20with%20organization&state=123456789

Possible error codes and the corresponding descriptions are listed below.

A Profile is an object that represents an authenticated user. The Profile object contains information relevant to a user in the form of normalized attributes.

After receiving the Profile for an authenticated user, use the Profile object attributes to persist relevant data to your application’s user model for the specific, authenticated user.

To surface additional attributes on the Profile, refer to the SSO custom attributes guide.

const profile = {
  id: 'prof_01DMC79VCBZ0NY2099737PSVF1',
  connectionId: 'conn_01E4ZCR3C56J083X43JQXF3JK5',
  organizationId: 'org_01EHWNCE74X7JSDV0X3SZ3KJNY',
  connectionType: 'OktaSAML',
  email: 'todd@example.com',
  firstName: 'Todd',
  idpId: '00u1a0ufowBJlzPlk357',
  lastName: 'Rundgren',
  role: { slug: 'admin' },
  customAttributes: {
    department: 'Engineering',
    jobTitle: 'Software Engineer',
  },
  object: 'profile',
  rawAttributes: {},
};

Get an access token along with the user Profile using the code passed to your Redirect URI.

import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

const { access_token, profile, oauth_tokens } =
  await workos.sso.getProfileAndToken({
    code: '01DMEK0J53CVMC32CK5SE0KZ8Q',
    clientId: 'client_123456789',
  });

Exchange an access token for a user’s Profile. Because this profile is returned in the Get a Profile and Token endpoint your application usually does not need to call this endpoint. It is available for any authentication flows that require an additional endpoint to retrieve a user’s profile.

import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

const profile = await workos.sso.getProfile({
  accessToken: '01DMEK0J53CVMC32CK5SE0KZ8Q',
});

A connection represents the relationship between WorkOS and any collection of application users. This collection of application users may include personal or enterprise identity providers. As a layer of abstraction, a WorkOS connection rests between an application and its users, separating an application from the implementation details required by specific standards like OAuth 2.0 and SAML.

See the events reference documentation for the connection events.

const connection = {
  id: 'conn_01E4ZCR3C56J083X43JQXF3JK5',
  organizationId: 'org_01EHWNCE74X7JSDV0X3SZ3KJNY',
  type: 'OktaSAML',
  name: 'Foo Corp',
  state: 'active',
  createdAt: '2021-06-25T19:07:33.155Z',
  updatedAt: '2021-06-25T19:07:33.155Z',
  domains: [
    {
      id: 'org_domain_01EHZNVPK2QXHMVWCEDQEKY69A',
      object: 'connection_domain',
      domain: 'foo-corp.com',
    },
  ],
};

Get the details of an existing connection.

import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

const connection = await workos.sso.getConnection(
  'conn_01E4ZCR3C56J083X43JQXF3JK5',
);

Get a list of all of your existing connections matching the criteria specified.

import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

const connectionList = await workos.sso.listConnections();

console.log(connectionList.data);

Permanently deletes an existing connection. It cannot be undone.

import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

await workos.sso.deleteConnection('conn_01E2NPPCT7XQ2MVVYDHWGK1WN4');

The Logout endpoints enable the RP-initiated logout functionality for users in your application. Refer to Single Logout section for more details on how to handle RP-initiated or IdP-initiated logout.

You should call this endpoint from your server to generate a logout token which is required for the Logout Redirect endpoint.

curl --request POST \
  --url https://auth.workos.com/sso/logout/authorize \
  --header "Authorization: Bearer sk_example_123456789" \
  -d profile_id="prof_01GWQ1G0H2FM6ASEF0HS13HCW9304kg03g"

Logout allows to sign out a user from your application by triggering the identity provider sign out flow. This GET endpoint should be a redirection, since the identity provider user will be identified in the browser session.

Before redirecting to this endpoint, you need to generate a short-lived logout token using the Logout Authorize endpoint.

curl --request GET \
  --url https://auth.workos.com/sso/logout? \
  token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwcm9maWxlX2lkIjoicHJvZl8wMUdXUTFHMEgyRk02QVNFRjBIUzEzSENXOS0zMDRrZzAzZyIsImV4cCI6IjE1MTYyMzkwMjIifQ.Wru9Qlnf5DpohtGCKhZU4cVOd3zpiu7QQ-XEX--5A_4