Single Sign-On

Connect Okta

Learn how to configure a connection to Okta via SAML

Each SSO Identity Provider requires specific information to create and configure a new Connection. Often, the information required to create a Connection will differ by Identity Provider.

To create an Okta SAML Connection, you'll need four pieces of information: an ACS URL, an Identity Provider Issuer (also known as an Entity ID), an Identity Provider SSO URL, and an X.509 Certificate.

WorkOS provides:

  • ACS URL

You provide:

  • Identity Provider Issuer (Entity ID)
  • Identity Provider SSO URL
  • X.509 Certificate

WorkOS Provides:

WorkOS provides the ACS URL. It's readily available in your Connection's Settings in the Developer Dashboard.

The ACS URL is the location an Identity Provider redirects its authentication response to. In Okta's case, it needs to be set by the Enterprise when configuring your application in their Okta instance.

Specifically, the ACS URL will need to be set as the "Single sign on URL" and "Audience URI (SP Entity ID)" in the "Configure SAML" step of the Okta "Edit SAML Integration" wizard:


You Provide:

And then, you provide the Identity Provider Issuer (Entity ID), Identity Provider SSO URL, as well as the X.509 Certificate.

Normally, this information will come from your Enterprise customer's IT Management team when they set up your application's SAML 2.0 configuration in their Okta admin dashboard. But, should that not be the case during your setup, here's how to obtain them.

Step 1. Log in

Log in to the Okta admin dashboard and select "Applications" in the navigation bar.

Note: If the Okta dashboard does not contain "Applications" in the navigation bar, or appears different than the example above: select "Developer Console" in the top-left corner of the dashboard and select "Classic UI".

Step 2. Select your application

Select your application from the list of applications.

Step 3. Enter Setup Instructions

Select "Sign On" from the application tabs, and then select "View Setup Instructions" in the Sign On Settings.

Step 4. Obtain Identify Provider Single Sign-On URL, Identity Provider Issuer, and X.509 Certificate

Copy and Paste the "Identify Provider Single Sign-On URL" and "Identity Provider Issuer" into the corresponding Connection fields in your WorkOS Developer Dashboard. Then select "Download certificate" to obtain the X.509 Certificate, and save it to your preferred directory.

Step 5. Upload Certificate

Finally, upload the X.509 Certificate in your WorkOS Connection Settings. Your Connection will then be verified and good to go!

Note: You may need to rename the downloaded X.509 certificate from okta.cert to okta.cer.