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.
- 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.
Step 1. Create an application in Okta:
Sign in to your Okta Admin Account from a browser.
Select Applications from the top level menu.
Select Add Application.
Enter "Tehama" in the search bar.
This will bring up the Tehama application.
Click Add on the Tehama application.
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.
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.
Save this IDP (XML) metadata.
Step 3. Enable SSO authentication in Tehama:
Login to Tehama using the Admin Account and click on the SETTINGS tab in the navigation bar.
Select the AUTHENTICATION tab.
Check "Enable SAML Single-Sign on".
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.
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.
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:
-
Open a new tab in a browser and navigate to the following URL: https://saml-doc.okta.com/SAML_Docs/How-to-Configure-SAML-2.0-for-Tehama.html
-
Alternately, view these instructions from your Okta Tehama connected application by clicking the Sign On tab and clicking View Setup Instructions, which will open in a new tab in your browser.
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:
Select the "SAML" option in the Method dropdown list under USER PROVISIONING.
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 |
|---|---|
| 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:
- 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.
- 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:
Select the "SCIM" option in the Method dropdown list under USER PROVISIONING.
Click SAVE.
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.
Select your Tehama connected application.
Click on the Provisioning tab.
Click Configure API Integration and check the Enable API Integration checkbox.
Remove the trailing slash from the SCIM Endpoint URL, then copy it into the Base URL field. (The trailing slash will cause the Base URL field to fail validation.)
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. 
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:
- Having both SCIM and SAML user provisioning enabled provides redundancy.
- 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.
- 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.