Overview

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.


Step One: Direct your user to a WorkOS authorization URL

There are two types of authorization URLs to initiate single sign-on; with a domain parameter:

Authorization URL

file_copy
https://api.workos.com/sso/authorize?
  response_type=code&
  client_id={projectId}&
  redirect_uri={redirectURI}&
  domain={foo-corp.com}

and with a provider parameter:

Authorization URL

file_copy
https://api.workos.com/sso/authorize?
  response_type=code&
  client_id={projectId}&
  redirect_uri={redirectURI}&
  provider=GoogleOAuth

It is common to use the domain parameter when authenticating a user by their domain. However the provider parameter exists so you may authenticate all users with same Connection. For example a "Sign in with Google" button generally does not take into account a user's domain and a provider=GoogleOAuth would be used.

When possible, the domain and provider parameters can be used together to customize the login experience. For example, the following authorization URL:

Authorization URL

file_copy
https://api.workos.com/sso/authorize?
  response_type=code&
  client_id={projectId}&
  redirect_uri={redirectURI}&
  domain=workos.com&
  provider=GoogleOAuth

will generate the following "Sign in with Google" prompt:

A state parameter is also optional. If included, the exact state parameter will be provided when a user is redirected to your application, as detailed in Step Two below.

Authorization URL

file_copy
https://api.workos.com/sso/authorize?
  response_type=code&
  client_id={projectId}&
  redirect_uri={redirectURI}&
  domain={foo-corp.com}&
  state=dj1kUXc0dzlXZ1hjUQ==

Step Two: Receive the redirect from WorkOS

Once a user authorizes with their Identity Provider, we issue a redirect to your Redirect URI with a code parameter to use in Step Three. A state parameter will also be included if it was provided in Step One.

Redirect URI Request

file_copy
{redirectURI}?
  code=01E2RJ4C05B52KKZ8FSRDAP23J&
  state=dj1kUXc0dzlXZ1hjUQ==

To learn how to configure and setup a Redirect URI, visit our Redirect URI Guide.

Step Three: Request the Profile

Now you need to exchange the code value received in the previous step for both an access token, and the user's profile. To make this exchange, POST the code, along with the following application identification parameters, to the WorkOS /sso/token endpoint.

  • client_id: Your project's identifier. Can be found in the SSO Configuration page.
  • client_secret Your project's secret API key. Can be found in the API Keys page.
  • authorization_code: The exact code you received in Step Two.

Example Request

Profile Request

file_copy
curl -G --request POST \
--url https://api.workos.com/sso/token \
-d client_id="{projectId}", \
-d client_secret="{secretKey}", \
-d grant_type="authorization_code", \
-d code="01E2RJ4C05B52KKZ8FSRDAP23J"

Example Response

JSON

file_copy
{
  "access_token": "01DMEK0J53CVMC32CK5SE0KZ8Q",
  "profile": {
      "email": "todd@{foo-corp.com}",
      "first_name": "Todd",
      "id": "prof_01DMC79VCBZ0NY2099737PSVF1",
      "identity_provider": "okta",
      "idp_id": "00u1a0ufowBJlzPlk357",
      "last_name": "Rundgren",
      "object": "profile",
      "workos_id": "d653fee6207ba8616ad0b2251b204e31"
  }
}