Okta 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 three pieces of information: an ACS URL, a SP Entity ID, and an IdP Metadata URL.

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 configure an Okta SAML Connection for, and select “Manually Configure Connection” under “Identity Provider”.

Select “Okta” from the Identity Provider dropdown, enter a descriptive name for the connection, and then select the “Create Connection” button.

WorkOS provides the ACS URL and the SP Entity ID. It’s readily available in your Connection Settings in the WorkOS 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.

The SP Entity ID is a URI used to identify the issuer of a SAML request, response, or assertion. In this case, the entity ID is used to communicate that WorkOS will be the party performing SAML requests to the Enterprise’s Okta instance.

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

Next, provide the IdP Metadata URL. 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, the next steps will show you how to obtain it.

Log in to Okta, go to the admin dashboard, and select “Applications” in the navigation bar.

These Okta screenshots reflect the new Okta Admin UI, Okta plans to deprecate the Classic UI in October 2021.

If your application is already created, select it from the list of applications and move to Step 7.

If you haven’t created a SAML application in Okta, select “Create App Integration”.

Select “Create New App”, then select “SAML 2.0” as a Sign on method, then click “Next”.

Enter a descriptive App name, then click “Next”.

Input the ACS URL from your WorkOS Dashboard as the “Single sign on URL” and input the SP Entity ID from your WorkOS Dashboard as the “Audience URI (SP Entity ID)”.

Scroll down to the “Attribute Statements” section and use the “Add Another” button to add the following key-value pairs. Then, click “Next”.

• id → user.id
• email → user.email
• firstName → user.firstName
• lastName → user.lastName

Select “I’m an Okta customer adding an internal app” from the options menu. Complete the form with any comments and select “Finish”.

To give users permission to authenticate via this SAML app, you will need to assign individual users and/or groups of users to the Okta SAML app.

Click on the “Assignments” tab, and select either “Assign to People” or “Assign to Groups”.

Find the individual user(s) and/or group(s) that you would like to assign to the app, and click “Assign” next to them. Click “Done” when you are finished.

Click on the “Sign On” tab of the SAML app you just created.

Click the “Actions” dropdown for the correct certificate and select “View IdP Metadata."

A separate tab will open. Copy the link in the browser.

Back in the WorkOS Dashboard, click on “Edit Metadata Management” in the “Metadata Configuration” section of the Connection. Input the Metadata URL and click “Save Metadata Configuration”. Your Connection will then be linked and good to go!