Configuring SSO with Okta

Prerequisites

Before beginning, the following are required:

1. SAML 2.0.
2. Logged in to a Tarsal account with administrator privileges.
3. 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.

1. Go to Account > Settings from the left navigation.
2. Click the Security/SSO tab at the top.
3. Under Single Single-On (SSO)
   1. Turn on the toggle switch to Enable SSO.
   2. 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).

1. Switch to the Okta browser window.

2. Go to Applications > Applications.

3. Click the Create App Integration button.

4. In the modal window, select SAML 2.0 as the Sign-In Method.

5. Click the Next button.

6. Under General Settings

   1. For App Name, enter Tarsal.
   2. (Optional) Enter an App Logo.
   3. Set the desired App Visibility.
   4. 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.

1. Login URL
   1. Switch to the Tarsal browser window.
      1. Under SSO Login URL, locate Login URL.
      2. Click the clipboard icon () on the right to copy the value to your clipboard.
   2. Switch to the Okta browser window.
      1. Under Configure SAML > SAML Settings > General, locate Single Sign-on URL.
      2. Paste the Tarsal Login URL from your clipboard.
      3. Uncheck the checkbox for Use this for Recipient URL and Destination URL.
2. ACS URL
   1. Switch to the Tarsal browser window.
      1. Under Tarsal IDP Service Settings, locate Assertion Consumer Service (ACS).
      2. Click the clipboard icon () on the right to copy the value to your clipboard. You’ll use this value for two Okta fields.
   2. Switch to the Okta browser window.
      1. Under Configure SAML > SAML Settings > General, locate Recipient URL and paste the Tarsal Assertion Consumer Service (ACS) from your clipboard.
      2. Locate the Destination URL and paste the Tarsal Assertion Consumer Service (ACS)
3. Entity ID
   1. Switch to the Tarsal browser window.
      1. Under Tarsal IDP Service Settings, locate Entity ID.
      2. Click the clipboard icon () on the right to copy the value to your clipboard.
   2. Switch to the Okta browser window.
      1. Under Configure SAML > SAML Settings > General, locate Audience URI (SP Entity ID).
      2. Paste the Tarsal Entity ID from your clipboard.
4. Signed Requests
   1. Switch to the Tarsal browser window.
      1. Click Next to move to next tab "(2) Provider".
      2. Turn on "Want AuthnRequests Signed"
   2. Switch to the Okta browser window.
      1. Check the "Signed Requests" checkbox

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.

1. Switch to the Tarsal browser window, and go back to tab 1 Essentials.
   1. Under Tarsal IDP Service Settings, locate Public Certificate.
      1. Click the clipboard icon () on the right to copy the value to your clipboard.
      2. For macOS users
         1. In the TextEdit application, open a new blank document.
         2. Paste the certificate from your clipboard.
         3. From the menu, select Format > Make Plain Text.
         4. Select OK when prompted to convert to plain text.
         5. Go to File > Save
            1. For Save As, enter tarsal.crt.
            2. Uncheck If no extension is provided, use ".txt" (if it’s an option).
            3. Remember the saved location and click the Save button.
            4. If presented with a choice of extensions, select Use .crt. Don’t use .txt or .crt.txt.
      3. For Windows users
         1. In the Notepad application, open a new blank document.
         2. Paste the certificate from your clipboard.
         3. Go to File > Save As
            1. For File Name, enter tarsal.crt.
            2. Remember the saved location and click the Save button.
2. Switch to the Okta browser window.
   1. Under Configure SAML > SAML Settings > General, locate Signature Certificate.
      1. Click the Browse Files button to the right.
      2. In the file window, select the tarsal.crt file you created. Click the Open button to upload it to Okta.

Add SAML Group Attributes in Okta (optional)

Member and Admin role information can be passed into Tarsal as part of the SAML exchange. These can be defined to meet your organizations best practices, but as an example we'll name our Okta groups:

• Tarsal_Member
• Tarsal_Admin

Assign users to these groups accordingly. A user should be assigned to only one group, otherwise there could be mapping precedence conflicts in the SAML exchange.

1. In the SAML Settings navigate to Group Attribute Statements (optional)
2. Add each role to the group attribute statement for each role type:
   1. member :: Equals :: Tarsal_Member
   2. admin :: Equals :: Tarsal_Admin

Preview and Verify the SAML Assertion

Confirm Okta’s SAML assertion file based on the entered data by checking three values.

1. Scroll down the page and locate Preview the SAML Assertion Generated From the Information Above.
2. Click the Preview SAML Assertion button to open a new browser window.
3. Switch to the Preview SAML browser window.
   1. Search for the node named saml2:SubjectConfirmationData.
   2. Note the value for the Recipient attribute.
4. Switch to the Tarsal browser window. Verify that the value for ACS matches the value for Recipient in the SAML Assertion preview file.
5. Switch to the Preview SAML browser window.
   1. Search for the node named saml2:Audience.
   2. Note the URL in the node value.
6. 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.
7. Click the Next button.

Finalize the Okta Setup

Finish the AIW to create the Okta SAML app.

1. Switch to the Okta browser window.
2. Click the Next button.
3. For Are you a customer or partner, select the radio button value I’m an Okta customer adding an internal app
4. 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.

1. Switch to the Okta browser window.
   1. Under Sign-On Methods, locate Metadata Details.
   2. Under Metadata URL, click Copy.
2. Open a new browser window and paste the copied URL.
   1. Save this as metadata.xml.
   2. Remember the saved file location to upload it to Tarsal next.
3. Switch to the Tarsal browser window.
   1. To the right of the Metadata File field, click Choose File.
   2. In the file window, select the metadata.xml file you created.
   3. Click the Open button to upload it to Tarsal.
4. Click the Next button.

Map User Attributes in Tarsal

Add user attributes in Tarsal to match Okta.

1. Switch to the Tarsal browser window.
2. For Email, enter the value email.
3. For First Name, enter the value firstName.
4. For Last Name, enter the value lastName.
5. (Optional) For Picture URL, enter the value profileUrl.
6. Click the Next button.

Configure Roles in Tarsal

Add a default user role and role mappings for Okta users.

1. 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!
   
   

2. Under Role Mappers (required if Group Attributes were set in Okta)
   To configure the User Group/Role Attributes configred in the saml exchange, under Role Mappers you will need to direct Tarsal how to map those to roles within the tarsal applicate. Using our example above (Tarsal_Member and Tarsal_Admin) we would map the following:
   1. For Role, select Member from the drop-down list.
   2. For SAML Attribute Key, enter member.
   3. For SAML Attribute Value, enter Tarsal_Member.
   4. Click + on the right to add another row.
   5. In the new row, select Admin from the drop-down list for the Role.
   6. For SAML Attribute Key, enter admin.
   7. For SAML Attribute Value, enter Tarsal_Admin.
3. 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.