Connect Okta
Learn how to configure a connection to Okta via SAML
Introduction
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.
4
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.
