Configuring SSO with Okta
Prerequisites
Before beginning, the following are required:
- SAML 2.0.
- Logged in to a Tarsal account with administrator privileges.
- Logged in to an Okta account with administrator privileges and SSO support.
Overview
SSO configuration for Tarsal and Okta requires these steps:
- Enabling SSO
- Creating a SAML app
- Copying SAML attributes
- Creating and uploading a public certificate
- Previewing and verifying a SAML assertion
- Finalizing the IDP Setup
- Adding a metadata file
- Mapping user attributes
- Configuring roles
Reconcile Tarsal and Okta Accounts
After the SSO configuration is complete, delete any existing Tarsal accounts that will now use Okta SSO. These accounts can’t log in to Okta until removed from Tarsal. Okta will recreate the account when a user logs in for the first time.
Post-Okta SSO Access to Tarsal
Account administrators can still access the default Tarsal login URL; it’s not tied to Okta. To retain access to the Tarsal SSO configuration, keep an administrator account in Tarsal that doesn’t use Okta.
Enable SSO in Tarsal
Activate SSO in Tarsal to get started.
- Go to Account > Settings from the left navigation.
- Click the Security/SSO tab at the top.
- Under Single Single-On (SSO)
- Turn on the toggle switch to Enable SSO.
- In the modal window, select the Enable button.
Parallel Configuration with Tarsal and Okta
Leave the Tarsal and Okta browser windows or tabs open for side-by-side reference, allowing you to copy and paste values between them easily. This icon () indicates when you need to switch windows.
Create a SAML App in Okta
Define a SAML custom app integration through Okta’s App Integration Wizard (AIW).
-
Switch to the Okta browser window.
-
Go to Applications > Applications.
-
Click the Create App Integration button.
-
In the modal window, select
SAML 2.0
as the Sign-In Method. -
Click the Next button.
-
Under General Settings
- For App Name, enter Tarsal.
- (Optional) Enter an App Logo.
- Set the desired App Visibility.
- Click the Next button.
The Tarsal logo is available for download in the media assets at https://tarsal.co/in-the-news/.
Copy SAML Attributes from Tarsal to Okta
Copy and paste the required SAML attributes from Tarsal to Okta. Add the Tarsal values for Assert Consumer Service (ACS), Single Sign-On URL, Entity ID, and Public Certificate.
- Switch to the Tarsal browser window.
- Under SSO Login URL, locate Login URL.
- Click the clipboard icon () on the right to copy the value to your clipboard.
- Switch to the Okta browser window.
- Under Configure SAML > SAML Settings > General, locate Single Sign-on URL.
- Paste the Tarsal Login URL from your clipboard.
- Uncheck the checkbox for Use this for Recipient URL and Destination URL.
- Switch to the Tarsal browser window.
- Under Tarsal IDP Service Settings, locate Assertion Consumer Service (ACS).
- Click the clipboard icon () on the right to copy the value to your clipboard. You’ll use this value for two Okta fields.
- Switch to the Okta browser window.
- Under Configure SAML > SAML Settings > General, locate Recipient URL and paste the Tarsal Assertion Consumer Service (ACS) from your clipboard.
- Locate the Destination URL and paste the Tarsal Assertion Consumer Service (ACS)
- Locate the Requestable SSO URL and paste the Tarsal Assertion Consumer Service (ACS)
- Switch to the Tarsal browser window.
- Under Tarsal IDP Service Settings, locate Entity ID.
- Click the clipboard icon () on the right to copy the value to your clipboard.
- Switch to the Okta browser window.
- Under Configure SAML > SAML Settings > General, locate Audience URI (SP Entity ID).
- Paste the Tarsal Entity ID from your clipboard.
Create the Public Certificate File from Tarsal for Okta Upload
Copy the Tarsal public certificate and save it to a local file. Upload it to Okta for SAML validation.
Certificate Format
Don’t modify the certificate contents after pasting. The certificate string should be enclosed between
-----BEGIN CERTIFICATE-----
and
-----END CERTIFICATE-----
exactly as copied.
The certificate file should contain no formatting with a .crt file extension.
- Switch to the Tarsal browser window.
- Under Tarsal IDP Service Settings, locate Public Certificate.
- Click the clipboard icon () on the right to copy the value to your clipboard.
- For macOS users
- In the TextEdit application, open a new blank document.
- Paste the certificate from your clipboard.
- From the menu, select Format > Make Plain Text.
- Select OK when prompted to convert to plain text.
- Go to File > Save
- For Save As, enter
tarsal.crt
. - Uncheck If no extension is provided, use ".txt" (if it’s an option).
- Remember the saved location and click the Save button.
- If presented with a choice of extensions, select Use .crt. Don’t use
.txt
or.crt.txt
.
- For Save As, enter
- For Windows users
- In the Notepad application, open a new blank document.
- Paste the certificate from your clipboard.
- Go to File > Save As
- For File Name, enter
tarsal.crt
. - Remember the saved location and click the Save button.
- For File Name, enter
- Switch to the Okta browser window.
- Under Configure SAML > SAML Settings > General, locate Signature Certificate.
- Click the Browse Files button to the right.
- In the file window, select the
tarsal.crt
file you created. Click the Open button to upload it to Okta.
- Locate Signed Requests and check the box to Validate SAML Requests With Signature Certificates.
Preview and Verify the SAML Assertion
Confirm Okta’s SAML assertion file based on the entered data by checking three values.
- Scroll down the page and locate Preview the SAML Assertion Generated From the Information Above.
- Click the Preview SAML Assertion button to open a new browser window.
- Switch to the Preview SAML browser window.
- Search for the node named
saml2:SubjectConfirmationData
. - Note the value for the
Recipient
attribute.
- Search for the node named
- Switch to the Tarsal browser window. Verify that the value for ACS matches the value for Recipient in the SAML Assertion preview file.
- Switch to the Preview SAML browser window.
- Search for the node named
saml2:Audience
. - Note the URL in the node value.
- Search for the node named
- Switch to the Tarsal browser window. Verify that the value for Entity ID matches the node value for
saml2:Audience
in the SAML Assertion preview file. - Click the Next button.
Finalize the Okta Setup
Finish the AIW to create the Okta SAML app.
- Switch to the Okta browser window.
- Click the Next button.
- For Are you a customer or partner, select the radio button value
I’m an Okta customer adding an internal app
- Click the Finish button.
Add the Metadata File to Tarsal
Download the metadata file from Okta and upload it to Tarsal to ensure communication between the services.
- Switch to the Okta browser window.
- Under Sign-On Methods, locate Metadata Details.
- Under Metadata URL, click Copy.
- Open a new browser window and paste the copied URL.
- Save this as
metadata.xml
. - Remember the saved file location to upload it to Tarsal next.
- Save this as
- Switch to the Tarsal browser window.
- To the right of the Metadata File field, click Choose File.
- In the file window, select the
metadata.xml
file you created. - Click the Open button to upload it to Tarsal.
- Click the Next button.
Map User Attributes in Tarsal
Add user attributes in Tarsal to match Okta.
- Switch to the Tarsal browser window.
- For Email, enter the value
email
. - For First Name, enter the value
firstName
. - For Last Name, enter the value
lastName
. - (Optional) For Picture URL, enter the value
profileUrl
. - Click the Next button.
Configure Roles in Tarsal
Add a default user role and role mappings for Okta users.
- Under User Role, locate Default User Role. Select
Member
from the drop-down list.Use Roles for Testing
The Member role has read access, while the Admin role has read/write access.
Okta uses the Default User Role if it doesn’t find a role mapping for an IDP user.
The Default User Role should be Member for increased security, but you can set it to Admin in non-production environments to aid the configuration testing.
Don’t forget to check the Default User Role before launching your app!
- Under Role Mappers
- For Role, select
Member
from the drop-down list. - For SAML Attribute Key, enter
member
. - For SAML Attribute Value, enter
Tarsal_Member
. - Click + on the right to add another row.
- In the new row, select
Admin
from the drop-down list for the Role. - For SAML Attribute Key, enter
admin
. - For SAML Attribute Value, enter
Tarsal_Admin
.
- For Role, select
- Click the Save button.
Next Steps
Your Tarsal and Okta SSO integration is complete!
Users can log in via Okta using your unique Tarsal SSO login URL, which is located in the Tarsal SAML Single Sign-On Settings.
Updated about 1 month ago