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, break down as follows:
- Steps 1 to 4: These steps cover how to enable SSO authentication in Tehama with the IDP (XML) metadata from your Okta Tehama Okta connected application.
You can find the instructions that accomplish the same thing in step three of the previous section in this page: 'Step 3. Enable SSO authentication in Tehama'. - Steps 5 to 8: These steps cover how to configure 'Just in Time' (JIT) User Provisioning - otherwise known as SAML User Provisioning.
Be aware that at the time of writing this documentation, the Okta SAML for Tehama setup instructions provided at this link - https://saml-doc.okta.com/SAML_Docs/How-to-Configure-SAML-2.0-for-Tehama.html - have not yet been updated with the following changes:
- Tehama's Authentication page has been updated. The instructions refer to an older version of this page. Follow along below to see how to execute the steps with the current Tehama Authentication page.
- Tehama now supports a new custom attribute mapping that you can add to your SAML attribute mapping in steps six and seven of the instructions. The "Tehama Attribute" value is 'department' in Okta, and the "Attribute Name" is 'Department'. It maps to the attribute of the same name in the user's Tehama profile.
The following provides updated instructions in steps 5, 6 and 7 that accommodate these changes:
― ― ― ―
Updated instructions for Step 5 in Setup SSO
The purpose of this step is to enable SAML user provisioning.
The step does not give instructions needed to enable SAML user provisioning in the current Tehama Web UI. To enable SAML user provisioning using the current Tehama Web UI, do the following:
- Navigate to the Tehama AUTHENTICATION tab. You will see:
- Select the "SAML" option in the Method dropdown list under USER PROVISIONING.
- Click SAVE. (You can wait to click save until Step 7 if you are proceeding with the rest of the steps right away.)
― ― ― ―
Updated instructions for Step 6 and Step 7 in Setup SSO.
The purpose of these steps is to set up the mapping of attributes from Okta to Tehama.
Firstly, the table provided in Step 6 that shows the Tehama/Okta attribute mappings does not include the 'Department'/'department' attribute mapping.
Here is a copy of attribute-mapping table in Setup SSO Step 6 with the addition of the "Department/department" attribute mapping:
| 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 |
| Department | department |
Secondly, Step 6 and Step 7 in Setup SSO fail to provide instructions for setting the mapping in the current Tehama Web UI, though Step 7 does contains an outdated image of the Tehama Web UI's AUTHENTICATION page that shows the completed mapping.
A. Add attributes to the Tehama Web UI's SAML attribute mapping table in the AUTHENTICATION tab as follows:
Perform the following steps for each attribute you wish to map:
Note, the first three attributes in the table in Step 6, Email, First Name and Last Name, are mandatory and are pre-populated in the Tehama Web UI's SAML user provisioning table. You have to add the optional attributes manually.
From the Tehama Web UI:
- Navigate to the Tehama Web UI's AUTHENTICATION page, where you enabled SAML user provisioning in Step 5.
- 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.
- Enter possible values for the attribute.
Note, the "Default Room Ids" attribute entry provides a button called FIND ROOM IDS button in the 'Possible Values' column. 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 will have added to the Okta application profile for Tehama Room ids. - Click SAVE. (You can wait to click save until all the attributes are added.)
B. Add those attributes that you added to the Tehama Web UI's SAML attribute mapping table that are custom, like, for example, 'Room Ids' or 'Department', to your the Okta User Profile and map them to the User Profile of your Okta Tehama connection application as follows: (The non-custom attributes should already be mapped.)
Perform the following steps for each custom attribute you wish to map:
From Okta:
- Navigate to the section titled Adding Custom Attributes found at the end of the Setup SSO page.
- Follow the instructions in that section.
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.