SSO Okta Setup

The following instructions set up an identity provider in Okta.

Introduction

Okta is a Single Sign-On (SSO) Provider and application portal that supports SAML 2.0, Secure Web Authentication and OpenID Connect. Tehama can be integrated with Okta through SAML 2.0 and SCIM 1 and presented as a managed application alongside other Okta integrated applications.

Once enabled, authentication to Tehama must be made through Okta - local authentication through https://app.tehama.io is no longer possible except by using the Tehama Admin account.

You can also opt to enable user provisioning from Okta to Tehama. Note that unless you enabled user provisioning, Okta/Tehama Integration is limited to authentication only.

A user account is required for Okta. If you do not enable user provisioning, then a user account is also required for Tehama. Both the Okta account and the Tehama account must be configured with the same email address for SSO to work, and the user must accept the Tehama Welcome email before they will be able to launch a connection via Okta SSO.

  1. It was possible in the past to integrate Tehama with Okta through a managed application that did not use SCIM. This has been deprecated.

Create a Tehama connected application

Features

This provides authentication for Tehama users through Okta SSO.

Requirements

  • A Tehama Account with Admin privileges (i.e.: the Tehama account for the user with the Admin role for the account's organization - AKA the organization owner)
  • An Okta account with Application Admin privileges (Super Admin, App. Admin, API Access Management Admin)

Step-by-Step Configuration Instructions

Overview: Creating an Okta SSO application and configuring it to provide authentication in Tehama is a four step process as follows.

  1. Create an application in Okta
  2. Obtain the required Federation Metadata XML from Okta
  3. Enable SSO authentication in Tehama with the XML
  4. Optional - Enable User Provisioning

Step 1. Create an application in Okta:

Sign in to your Okta Admin Account from a browser.

Select Applications from the top level menu.

Okta Applications Page

Select Add Application.

Enter "Tehama" in the search bar.

This will bring up the Tehama application.

Okta Add Applications Search for Tehama Page

Click Add on the Tehama application.

Okta Tehama Application General Settings Page

Change the Application label field value, if you wish to do so.

Enter the subdomain for your Tehama organization in the Subdomain field.

Click Done.

Step 2. Obtain the required Federation Metadata XML from Okta:

Click on the Sign On tab.

Okta Settings Page

To complete the Tehama SSO setup obtain the Federation Metadata XML as follows:

Select the Sign On tab.

Scroll down to the Optional configuration data and copy the IDP metadata to the clipboard.

Okta Optional Configuration Data Section

Save this IDP (XML) metadata.

Step 3. Enable SSO authentication in Tehama:

Login to Tehama using the Admin Account and select Organization from the Admin menu.

Tehama User Dropdown Menu

Select the AUTHENTICATION tab.

Check "Enable SAML Single-Sign on".

Tehama Organization Authentication Page with SAML-enabled

NOTE: You can ignore the Entity ID and Callback URL (Assertion Consumer Service URL) values. Okta's Tehama application is able to derive them from the subdomain you entered. These are for information and use in the deprecated SAML (only) connected application.

Paste the IDP metadata into the Federation Metadata XML box.

Tehama Organization Authentication Page with SAML-auth-enabled and XML metadata added to page

Click SAVE.

Now that you have completed building a connected application in Okta and setting up SAML Single-Sign On through a Tehama connected application, each existing team member in your organization will receive an email containing a link to the Tehama login page.

Each subsequently added team member will receive the same email.

Configuration of your connected application is now complete.

Step 4. Optional - Enable User Provisioning:

You can now, optionally, choose to enable user provisioning. This is covered in the next sections of this document. Click on the link to find out more about these options for user provisioning.

  1. SAML User Provisioning
  2. SCIM User Provisioning
  3. SAML and SCIM User Provisioning

Troubleshooting and Tips

Contact Tehama Support if you have any issues with your Okta Tehama connected application.


Enable SAML User Provisioning

The Okta Tehama connected application that provides authentication for Tehama through Okta can be further configured to provide SAML user provisioning.

Features

SAML user provisioning sets up a relationship, a mapping, between the Okta user profile and the Tehama user profile that enables the following 'auto-provisioning' behaviour:

  • Your organization's users can join Tehama without an explicit invitation link.
    i.e.: A Tehama user account is automatically created for a user the first time they attempt to log in to Tehama using the credentials of their Okta account. Their Tehama account's user profile is populated using values from their Okta account's user profile.

  • Your organization's users can manage their Tehama account's user profile through their Okta account.
    i.e.: Update the user's information in their Okta account's user profile, and it will be automatically updated in their Tehama account's user profile (only for those user profile attributes that are mapped).

  • Your organization's users can (optionally) be proposed for membership in your organization's Rooms through their Okta account.
    i.e.: A Tehama-specific attribute can be added to your Okta user profile where you can specify Tehama Room ids for Rooms in your Tehama organization for the user to be added to.

Requirements

  • A Tehama Account with Admin privileges (i.e.: the Tehama account for the user with the Admin role for the account's organization - AKA the organization owner)
  • An Okta account with Application Admin privileges (Super Admin, App. Admin, API Access Management Admin)
  • An Okta Tehama connected application. (See Create a Tehama connected application.)

Step-by-Step Configuration Instructions

Follow the online instructions provided by Okta to configure SAML 2.0 for Tehama, from Step 5 to Step 7.

Navigate to these instructions as follows:

The new browser tab containing the instructions should have the name Setup SSO.

These Okta online instructions, Setup SSO, cover:

  • in Steps 1 to 4: how to enable SSO authentication in Tehama with the IDP (XML) metadata from your Okta Tehama Okta connected application.

    The equivalent instructions in this document can be found in step three of the previous section:
    'Step 3. Enable SSO authentication in Tehama'.

  • in Steps 5 to 8: how to configure 'Just in Time' (JIT) User Provisioning - AKA SAML User Provisioning.

Be aware that at the time of writing this documentation, these Okta provided instructions refer to an older version of the Tehama Authentication tab.

Follow along below to see how to execute the steps with the current Tehama Authentication tab.

Go to Step 5 in Setup SSO. This step says to check Enable User Provisioning.

The equivalent step for the current Tehama Web UI is as follows:

Navigate to the Tehama AUTHENTICATION tab. You will see:

Tehama Organization Authentication Page with SAML-auth-enabled and XML metadata added to page

Select the "SAML" option in the Method dropdown list under USER PROVISIONING.

Tehama Organization Authentication Page with SAML-enabled and XML metadata added and SAML selected and saved

Go to Step 6 in Setup SSO. This step sets up the mapping of attributes from Okta to Tehama. A table with Tehama/Okta attribute mappings is provided.

copy of attribute-mapping table in Setup SSO Step 6:

TEHAMA Attribute Attribute Name
Email email
First Name firstName
Last Name lastName
Role orgRole
Default Room Ids roomIds
Title title
Phone Number primaryNumber
Avatar avatar
Title title
Country country
Address streetAddress
City locality
Zip/Postal Code postalCode
State/Province region
Country of Citizenship citizenship

The first three are mandatory and are pre-populated in the table. You have to add the optional attributes manually.

In the current Tehama Web UI, add attributes to the SAML attribute mapping table in the AUTHENTICATION tab as follows:

  • Select the name of the TEHAMA Attribute you want to add in the dropdown list.
  • Click ADD.
  • Enter the name of the Okta attribute into the field under the Attribute Name column.

IMPORTANT: Pay attention to the note at the end of this step in Setup SSO that says that in order to use optional attributes you will need to add them to the Okta application profile. You must add all of the custom attributes that you map that are not already in the Okta User Profile and mapped to the User Profile of your Okta Tehama connection application. Follow the instructions found at the end of Setup SSO in the Adding Custom Attributes section.

Read the note in Setup SSO that explains the purpose of the button FIND ROOM IDS button in the 'Possible Values' column for the entry for the 'Default Room Ids' attribute.

  • Click FIND ROOM IDS to bring up a dialog from which you can select Tehama Rooms from your organization. This produces a copyable comma separated value (CSV) string that you can use to populate the value of the custom attribute you added to the Okta application profile for Tehama Room ids.

Go to Step 7 in Setup SSO. This step saves the configuration you have done on the AUTHENTICATION page.

This step is the same in the current Tehama Web UI: Click SAVE.

You have now set up SAML user provisioning for your organization from your Okta connected app.

Troubleshooting and Tips

  • One of the optional attributes is Default Room Ids. Be aware of the following limitations that exist for this attribute:
  1. The Default Room IDs attribute is only looked at when the user's Tehama account is first created. For example, if this attribute has value '2,7' when the user's Tehama account is created, then the user will be added to the Room with ID 2 and the Room with ID 7 within your organization.

  2. The Default Room Ids attribute is used to propose the user for Room memberships. If a Room has auto-approvals enabled, then the user will be added to that Room automatically. Otherwise, the user's proposed membership must be manually approved by the connected organization for the Room from the Tehama Web UI before the user is added to the Room.

Enable SCIM User Provisioning

The Okta Tehama connected application that provides authentication for Tehama through Okta can be further configured to provide SCIM user provisioning.

Features

SCIM user provisioning sets up a relationship, a mapping, between the Okta user profile and the Tehama user profile that enables the following 'auto-provisioning' behaviour:

  • Your organization's users can join Tehama without an explicit invitation link.
    i.e.: A Tehama user account is automatically created for a user the as soon as their identity provider accounts are assigned/added to the SCIM Tehama application in their identity provider. They can log in to Tehama using the credentials of their account in the identity provider. Their Tehama account's user profile is populated using values from their identity provider account's user profile.

  • Your organization's users can manage their Tehama account's user profile through their identity provider account.
    i.e.: Update the user's information in their identity provider account's user profile, and it will be automatically updated in their Tehama account's user profile (only for those user profile attributes that are mapped within the SCIM Tehama application).

  • Your organization's users can be removed from your Tehama organization by removing/deactivating their identity provider account.
    i.e.: Remove or deactivate the user's identity provider account, and the user's Tehama account will be removed at the same time, causing the user's single-user Desktops and other Room assets to be removed also.

  • Your organization's users can (optionally) be proposed for membership in your organization's Rooms through their identity provider account.
    i.e.: A Tehama-specific attribute can be added to your identity provider's user profile where you can specify Tehama Room ids for Rooms in your Tehama organization for the user to be added to.

Requirements

  • A Tehama Account with Admin privileges (i.e.: the Tehama account for the user with the Admin role for the account's organization - AKA the organization owner)
  • An Okta account with Application Admin privileges (Super Admin, App. Admin, API Access Management Admin)
  • An Okta Tehama connected application. (See Create a Tehama connected application.)

Step-by-Step Configuration Instructions

Navigate to the Tehama AUTHENTICATION tab. You should see the following:

Tehama Organization Authentication Page with SAML-enabled and XML metadata added to page

Select the "SCIM" option in the Method dropdown list under USER PROVISIONING.

Click SAVE.

Tehama Organization Authentication Page with SAML-enabled and XML metadata added and SCIM selected and saved

Make a note of the SCIM Endpoint URL and the SCIM Authorization Bearer Token values.

Open a second browser tab and sign in to your Okta Admin Account.

Select Applications from the top level menu.

Okta Applications Page

Select your Tehama connected application.

Click on the Provisioning tab.

Okta Tehama Application Provisioning not-enabled Page

Click Configure API Integration and check the Enable API Integration checkbox.

Okta Tehama Application Provisioning enabled Page

Copy the SCIM Endpoint URL into the Base URL field.

Copy the SCIM Authorization Bearer Token into the API Token field.

Click Save.

Navigate to the To app sidebar item under the Provisioning tab of your Tehama connected application in Okta. Okta provisioning to-app table

If you want SCIM to create users in your Tehama organization for you, check the Enable checkmark for "Create Users" on this page.

If you want SCIM to update user attributes in your Tehama organization for you, check the Enable checkmark for "Update User Attributes" on this page.

If you want SCIM to remove users from your Tehama organization for you, check the Enable checkmark for "Deactivate Users" on this page.

Also on this page, check out the set of attributes that your Tehama connected application will send to Tehama for you.

This default set of attributes may be sufficient for you, but most likely you will need to make some additions and adjustments. You can adjust the set of attributes you see here to be a subset of those listed in the SCIM Attribute Mapping table that you can find under the SCIM User Provisioning section of Tehama's Authentication User Guide.

You can find instructions to add and to map custom attributes in the Adding Custom Attributes section of Okta's online instructions to configure SAML 2.0 for Tehama found at https://saml-doc.okta.com/SAML_Docs/How-to-Configure-SAML-2.0-for-Tehama.html.

Follow these instructions to adjust the list of attributes to your liking.

You are done.

Troubleshooting and Tips

  • If you have trouble connecting, go to the Tehama app's Provisioning tab and test your API with the Test API Credentials button.

  • The Tehama Room IDs attribute, used to specify the IDs of the Tehama Rooms the user is automatically put up for membership in, only takes effect when the user's Tehama account is first created. Any further updates to this attribute within Okta will not persist and will not be applied in the user's Tehama account. Note that this attribute is not part of the SCIM protocol's 'fetching users' API.

  • Deactivating then reactivating a user in Okta will always result in the creation of a completely new user in Tehama. This is because deactivating a user in Okta causes the user and all their data to be completely removed from Tehama. The reactivation of the user's deactivated Okta account results in a new user being created for them in Tehama.

Enable SAML and SCIM User Provisioning

You may choose to enable both SCIM and SAML user provisioning.

Follow the steps to configure both

selecting "SAML and SCIM" from the Method dropdown list under USER PROVISIONING instead of just "SAML" or "SCIM", in both cases.

This provides a few benefits:

  1. Having both SCIM and SAML user provisioning enabled provides redundancy.

  2. You can choose to use SAML for some functionality and SCIM for other functionality. For example, you could set up SAML to create users and set up SCIM to update the users' attributes only.

  3. Only those attributes mapped in the SAML user provisioning will be blocked from editing in the Tehama Web UI. Any attributes Tehama receives from the standard set sent by SCIM that you did not map in the SAML set up will not be blocked from editing in the Tehama Web UI. Setting up SAML as well as SCIM will let you block these attributes from being edited in Tehama.