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 ¹ 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 Org 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.

Enable SAML Single-Sign On

Features

This provides authentication for Tehama users through Okta SSO.

Requirements

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

Step-by-Step Configuration Instructions

Overview: Create an Okta SSO application and configure it to provide authentication in Tehama in a four-step process.

• Step 1. Create a Tehama connected application in Okta:
  1. Sign in to your Okta Admin Account from a browser.
  2. Click on the Applications top level menu, to open it.
  3. Select "Applications" from the Applications drop down menu.
  4. Click the Browse App Catalog button.
  5. Enter "Tehama" in the search bar.
  6. Select the Tehama entry from the list of search results. (It should be the top entry.)
  7. Click the Add button.
  8. Change the Application label field value, if you wish to do so.
  9. Enter the subdomain for your Tehama organization in the Subdomain field.
  10. Click Done.
• Step 2. Obtain the required Federation Metadata XML from Okta:
  1. Navigate to your Tehama connected application in your Okta Admin Account. (If following on from the previous step, you already have it front and centre.)
     • Sign in to your Okta Admin Account from a browser.
     • Click on the Applications top level menu, to open it.
     • Select "Applications" from the Applications drop down menu.
     • Click on your Tehama connected application.
  2. Click on the Sign On tab.
  3. Scroll down until you see the following sentence:
     
     "Identity Provider metadata is available if this application supports dynamic configuration"
     
     
  4. Click on the linked text "Identity Provider metadata". An XML file will open up in a new tab.
  5. Copy and save this XML metadata to use in Step 3.
• Step 3. Enable SSO authentication in Tehama:
  1. Login to Tehama using the Org Admin Account.
  2. Click on the ORGANIZATION tab in the navigation bar. You will see the ORGANIZATION settings page.
  3. Select the AUTHENTICATION tab. You will see the AUTHENTICATION page.
  4. Check "Enable SAML Single-Sign on". Several fields will appear below the checkbox.
     
     NOTE: The only field you need to configure here is the Federation Metadata XML text box. You can ignore the Entity ID and Callback URL (Assertion Consumer Service URL) fields. The values displayed in these fields were previously used to configure the now deprecated Okta Tehama SAML (only) connected application. The current Okta Tehama application is able to derive the values for these fields from the subdomain you entered in Step 1, above. Tehama continues to display these fields for information purposes only.
     
     
  5. Paste the IDP metadata into the Federation Metadata XML box.
  6. 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 subsequent sections. Click on the following links to find out more about user provisioning.
  • Enable SAML User Provisioning
  • Enable SCIM User Provisioning
  • Enable 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, and only upon their first login to Tehama) 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 Org Admin privileges (i.e.: the Tehama account for the user with the Org Admin role for the account's organization)
• An Okta account with Application Admin privileges (Super Admin, App. Admin, API Access Management Admin)
• Access to the Okta Tehama connected application used to enable 'SAML Single-Sign On' for your organization in Tehama. (See Enable SAML Single-Sign On.)

Step-by-Step Configuration Instructions

Overview: Enable and set up the mapping for SAML user provisioning in a four-step process.

• Step 1. Add Custom Attributes to your Tehama connected application's User Profile:
  1. Sign in to your Okta Admin Account from a browser.
  2. Click on the Directory top level menu, to open it.
  3. Select "Profile Editor" from the Directory drop down menu.
  4. Click on the name of the User Profile for your Tehama connected application. You will see the Profile Editor with a list of all the attributes that are already available in your profile.
  5. Compare the list of attribute already available in your profile to the following list. Determine which attributes you need to add or edit.
     
     All strings are case-sensitive.

     Display Name	Variable Name	Type
     Tehama Initial Rooms IDs	roomIds	string
     Primary phone	primaryPhone	string
     Avatar URL	avatar	string
     Title	title	string
     Tehama Org Role	orgRole	enum of strings Display name: "MANAGER" Value: "MANAGER" Display name: "STAFF" Value: "STAFF" IMPORTANT NOTE: If the Custom Roles and Permissions feature is enabled for your organization, and you have added the role attribute, then all role setting must be done within Tehama, aside from initial provisioning. Read the section Custom Roles & Permissions and SSO User Provisioning in the Authentication User Guide for more information.
     Country code	country	string
     Street address	streetAddress	string
     Postal Code	postalCode	string
     Locality	locality	string
     Region	region	string
     Citizenship	citizenship	string
     Department	department	string

  6. For each attribute of type string you need to add, do the following:
     1. Click Add Attribute. The Add Attribute modal will appear.
     2. Leave the Data type as "string".
     3. Enter the "Display Name" for the attribute as shown in the table above.
     4. Enter the "Variable Name" for the attribute as shown in the table above. This auto-populates the "External Name" field.
     5. Enter the string "urn:ietf:params:scim:schemas:core:2.0:User" (without quotes) into the "External namespace" field.
     6. Enter the "Description" for the attribute. You can enter any description you wish.
     7. Click Save.
  7. For each attribute of type enum of string you need to add, do the following:
     1. Click Add Attribute. The Add Attribute modal will appear.
     2. Leave the Data type as "string".
     3. Enter the "Display Name" for the attribute as shown in the table above.
     4. Enter the "Variable Name" for the attribute as shown in the table above. This auto-populates the "External Name" field.
     5. Enter the string "urn:ietf:params:scim:schemas:core:2.0:User" (without quotes) into the "External namespace" field.
     6. Enter the "Description" for the attribute. You can enter any description you wish.
     7. Place a checkmark in the checkbox beside "Define enumerated list of values".
     8. Enter a display name and a value for the first enumerated value you want in the list. See the values in the table above.
     9. Click Add Another and repeat from the previous step until you have entered all the enumerated values for this attribute.
     10. Click Save.
• Step 2. Map Custom Attributes to the Okta User Profile:
  1. Sign in to your Okta Admin Account from a browser.
  2. Click on the Directory top level menu, to open it.
  3. Select "Profile Editor" from the Directory drop down menu.
  4. Click on the name of the User Profile for your Tehama connected application. You will see the Profile Editor with a list of all the attributes that are available in your profile.
  5. Click Mappings.
  6. Select the "Okta User to <your Tehama connected application>" tab.
  7. On the right side, find the entry for the Okta user attribute you want to map/unmap.
  8. For each attribute that you want to map, add the mapping as follows:
     1. In the left side of that entry, select the corresponding App user attribute you wish to map.
     2. In the middle of that entry, select the arrow icon. A dropdown menu will appear.
     3. Select the entry that you desire, to map on creation only, or on creation and update. (See the Troubleshooting and Tips section below for information on attributes that do not, in certain circumstances, support 'update'.)
  9. For each attribute that you want to unmap, undo the mapping as follows:
     1. In the middle of that entry, select the arrow icon. A dropdown menu will appear.
     2. Select "Do not map".
  10. Click Save Mappings.
  11. Click Apply Updates Now.
  12. You are done!
• Step 3. Enable SSO SAML User Provisioning in Tehama:
  1. Login to Tehama using the Org Admin Account.
  2. Click on the ORGANIZATION tab in the navigation bar. You will see the ORGANIZATION settings page.
  3. Select the AUTHENTICATION tab. You will see the AUTHENTICATION page.
  4. Verify that "SAML Single-Sign on" is enabled and set up. If not, do so now. See instructions at Enable SAML Single-Sign On.
  5. Scroll down until you see the User Provisioning section.
  6. Select "SAML" from the "Method" dropdown list. (Or "SAML and SCIM", if you are enabling both.)
  7. If you do not have any custom attributes to map, then Click SAVE. You are done. Otherwise, move on to Step 4.
• Step 4. Set up mapping of your Tehama connected application's User Profile Attributes to Tehama User Attributes in Tehama:
  1. Navigate to the Tehama AUTHENTICATION page's User Provisioning section. (If following on from the previous step, you already have it front and centre.)
     • Login to Tehama using the Org Admin Account.
     • Click on the ORGANIZATION tab in the navigation bar. You will see the ORGANIZATION settings page.
     • Select the AUTHENTICATION tab. You will see the AUTHENTICATION page.
     • Verify that "SAML Single-Sign on" is enabled and set up. If not, do so now. See instructions at Enable SAML Single-Sign On.
     • Scroll down until you see the User Provisioning section.
     • Verify that you have selected "SAML" from the "Method" dropdown list. (Or "SAML and SCIM", if you are enabling both.)
  2. Verify that you see a table of mapped attributes followed by a drop down list with an ADD button beside it.
  3. Determine which attributes you need to add to the table. This table should contain mappings for all the attributes that you added and mapped in Okta in Step 1 and Step 2.
     
     Note, the first three attributes in the table, Email, First Name and Last Name, are mandatory and thus are pre-populated in the table. You have to add the optional attributes manually.
     
     
  4. For each attribute you need to add to the table from the dropdown list:
     1. Select the name of the TEHAMA Attribute you want to add in the dropdown list.
     2. Click ADD.
     3. Enter the name of the Okta attribute into the field under the Attribute Name column.
     4. 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 your Tehama connected application's user profile for Tehama Room ids.
     5. Click SAVE. (You can wait to click save until all the attributes are added.)
  5. OPTIONAL If you have Custom Roles and Permissions enabled for your organization, and you have added the Role attribute (or if you have "SAML and SCIM" enabled), you will see the Acknowledgment: Authentication and Custom Roles & Permissions checkbox. You must place a checkmark in this checkbox, to acknowledge that all role setting must be done within Tehama from this point on. Aside from initial provisioning, the roles set within the identity provider will no longer be communicated to Tehama. Read the section Custom Roles & Permissions and SSO User Provisioning in the Authentication User Guide for more information.
  6. Click SAVE.

Troubleshooting and Tips

• One of the optional attributes is Tehama Initial Room Ids. If you added and mapped this attribute, be aware of the following limitations that exist for this attribute:
  
  
  1. The Tehama Initial Room IDs attribute is only propagated to Tehama when the user is created. Subsequent changes to this attribute in the user's Okta profile will not be reflected in Tehama.
     
     
  2. The Tehama Initial Room IDs attribute is a comma separated values (CSV) list of Tehama room IDs. 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.
     
     
  3. The Tehama Initial 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.
  
  
  
• Another of the optional attributes is Tehama Org Role. If you added and mapped this attribute, be aware of the following limitations that exist for this attribute:
  
  
  1. The Tehama Org Role attribute is, by default, propagated to Tehama when the user is created and subsequent updates to this attribute in the user's Okta profile are pushed to Tehama. BUT enabling custom roles in Tehama disables this role attribute updating capability. See the section Custom Roles & Permissions and SSO User Provisioning in the Authentication User Guide for more information.
     
     
  2. The values you can assign to this attribute are limited to "MANAGER", which Tehama interprets as "Org Manager" and "STAFF", which Tehama interprets as "Staff". If you want to assign your user the "Room Manager" role, or a custom role, then you must enable custom roles in Tehama and then manually assign it to your user through the Tehama Web UI after the user is created in Tehama.

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 Org Admin privileges (i.e.: the Tehama account for the user with the Org Admin role for the account's organization)
• An Okta account with Application Admin privileges (Super Admin, App. Admin, API Access Management Admin)
• Access to the Okta Tehama connected application used to enable 'SAML Single-Sign On' for your organization in Tehama. (See Enable SAML Single-Sign On.)

Step-by-Step Configuration Instructions

Overview: Enable and set up the mapping for SCIM user provisioning in a three-step process.

• Step 1. Enable SCIM User Provisioning in Tehama:
  1. Login to Tehama using the Org Admin Account.
  2. Click on the ORGANIZATION tab in the navigation bar. You will see the ORGANIZATION settings page.
  3. Select the AUTHENTICATION tab. You will see the AUTHENTICATION page.
  4. Verify that "SAML Single-Sign on" is enabled and set up. If not, do so now. See instructions at Enable SAML Single-Sign On.
  5. Select "SCIM" from the "Method" dropdown list. (Or "SAML and SCIM", if you are enabling both.)
  6. Click SAVE.
  7. Copy the SCIM Endpoint URL and the SCIM Authorization Bearer Token values. They are used in Step 2.
• Step 2. Enable SCIM User Provisioning in your Tehama connected application in Okta:
  1. Navigate to your Tehama connected application in your Okta Admin Account. (If following on from creating the Tehama connected application, you already have it front and centre.)
     • Sign in to your Okta Admin Account from a browser.
     • Click on the Applications top level menu, to open it.
     • Select "Applications" from the Applications drop down menu.
     • Click on your Tehama connected application.
  2. Click on the Provisioning tab.
  3. Click Configure API Integration.
  4. Check the Enable API Integration checkbox.
  5. Copy the SCIM Authorization Bearer Token (from Step 1) into the API Token field. Copy the SCIM Endpoint URL (from Step 1) into the Base URL field. (If the value contains a trailing slash, then remove it first. The trailing slash will cause the Base URL field to fail validation.)
  6. Copy the SCIM Authorization Bearer Token (from Step 1) into the API Token field.
  7. Click Save.
  8. Select the To app sidebar item under the Provisioning tab of your Tehama connected application in Okta.
  9. OPTIONAL: If you want SCIM to create users in your Tehama organization for you, click Edit, check the Enable checkmark for "Create Users", then click Save.
  10. OPTIONAL: If you want SCIM to update user attributes in your Tehama organization for you, click Edit, check the Enable checkmark for "Update User Attributes", then click Save.
  11. OPTIONAL: If you want SCIM to remove users from your Tehama organization for you, click Edit, check the Enable checkmark for "Deactivate Users", then click Save.
• Step 3. Customize Attributes provided by the SCIM User Provisioning in your Tehama connected application in Okta:
  In this step, 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.
  1. Navigate to the "To App" section of the Provisioning tab in your Tehama connected application in your Okta Admin Account. (If following on from the previous step, you already have it front and centre.)
     • Sign in to your Okta Admin Account from a browser.
     • Click on the Applications top level menu, to open it.
     • Select "Applications" from the Applications drop down menu.
     • Click on your Tehama connected application.
     • Click on the Provisioning tab.
     • Select the To app sidebar item under the Provisioning tab of your Tehama connected application in Okta.
  2. Scroll down the page until you see the "Attribute Mappings".
  3. Click Show Unmapped Attributes to see all attributes, mapped and unmapped.
  4. Check if any attributes you want are missing (i.e.: you need to create them). If not, you are done! Otherwise for each such attribute . . .
     1. Click on the Go to Profile Editor button.
     2. For each attribute you need to add/remove map/unmap, follow sub-steps F and G in the Enable SAML User Provisioning step Add Custom Attributes to your Tehama connected application's User Profile.
  5. Check if any attributes you want are unmapped, or if any are mapped and you wish to unmap them or edit the in mapping any way. If not, you are done! Otherwise for each such attribute . . .
     
     To map it:
     1. Click on the pen icon in the entry for the attribute.
     2. Select the appropriate value from the Attribute value dropdown field, and configure the value.
     3. Select the appropriate option for the "Apply on" field. "Create" or "Create and update". (Note, "Create and update" will not be selectable unless you have enabled "Update User Attributes". Also see the Troubleshooting and Tips section below for information on attributes that do not, in certain circumstances, support 'update'.)
     4. Click Save.
     To unmap it:
     1. Click on the X icon in the entry for the attribute.
     2. Click OK.
  6. Now you are done!

   

Troubleshooting and Tips

• If you have trouble connecting, go to the Tehama connected application's Provisioning tab and test your API with the Test API Credentials button.
  
  
• 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.
  
  
• One of the attributes mapped through SCIM User Provisioning is Tehama Initial Room Ids. Be aware of the following limitations that exist for this attribute:
  
  
  1. The Tehama Initial Room IDs attribute is only propagated to Tehama when the user is created. Subsequent changes to this attribute in the user's Okta profile will not be reflected in Tehama.
     
     
  2. The Tehama Initial Room IDs attribute is a comma separated values (CSV) list of Tehama room IDs. 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.
     
     
  3. The Tehama Initial 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.
• Another one of the attributes mapped through SCIM User Provisioning is Tehama Org Role. Be aware of the following limitations that exist for this attribute:
  
  
  1. The Tehama Org Role attribute is, by default, propagated to Tehama when the user is created and subsequent updates to this attribute in the user's Okta profile are pushed to Tehama. BUT enabling custom roles in Tehama disables this role attribute updating capability. See the section Custom Roles & Permissions and SSO User Provisioning in the Authentication User Guide for more information.
     
     
  2. The values you can assign to this attribute are limited to "MANAGER", which Tehama interprets as "Org Manager" and "STAFF", which Tehama interprets as "Staff". If you want to assign your user the "Room Manager" role, or a custom role, then you must enable custom roles in Tehama and then manually assign it to your user through the Tehama Web UI after the user is created in Tehama.

Enable SAML and SCIM User Provisioning

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

Features

Enabling both SCIM and SAML user provisioning 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.

Requirements

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

Step-by-Step Configuration Instructions

Overview: Enable and set up the mapping for both SAML and SCIM user provisioning in a two-step process.

Troubleshooting and Tips

• Enabling SCIM User Provisioning first will save you from having to manually add custom attributes in Okta.
  
  
• See the troubleshooting and tips sections for SAML User Provisioning and for SCIM User Provisioning.