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.
Start by logging in to your WorkOS dashboard and browse to the 'Organizations' tab on the left hand navigation bar.
Select the organization you'd like to conifgure an Okta SAML Connection for, and add a Connection under 'Single Sign-On Connections'.
You'll be prompted to enter the Organization's Domain and Company Name and additionally you'll want to select "Okta" from the Identify Provider dropdown. Once this is filled out, click "Create Connection".
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:
Scroll down to the "Attribute Statements" section and use the "Add Another" button to add the following key-value pairs:
- id -> user.id
- email -> user.email
- firstName -> user.firstName
- lastName -> user.lastName
This portal is shown either when creating the application within Okta for the first time or can be returned to by clicking into the application, selecting the 'General Tab', and clicking 'Edit' next to 'SAML Settings'.
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.
Log in to the Okta admin dashboard and select "Applications" in the navigation bar.
NOTE: These Okta screenshots reflect the new Okta Admin UI, Okta plans to deprecate the Classic UI in October 2021.
2Select your application
Select your application from the list of applications.
3Enter Setup Instructions
Select "Sign On" from the application tabs, and then click "View Setup Instructions" in the Sign On Settings.
4Obtain Identity Provider Details
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.
Finally, upload the X.509 Certificate in your WorkOS Connection Settings. Your Connection will then be verified and good to go!
You may need to rename the downloaded X.509 certificate from okta.cert to okta.cer.