Corporate Single Sign On (SSO) Authentication and User Provisioning

Tehama provides the ability for an organization to use Single Sign On (SSO) both to authenticate (verify the identity of) their users when they access Tehama, and to provision their users, (create/delete users, add them to Rooms and Desktops and update their profile information).

Corporate Single Sign On (SSO) Authentication

Corporate Single Sign On (SSO) Authentication is one of the three authentication methods offered by Tehama.

With this type of authentication, Tehama verifies your identity through your corporation's identity provider (IP), (for example Okta, or Azure). If you are logged in to the IP, Tehama will grant you access.

This option is set at an organization level by the Org Admin user.

Once SSO is enabled for an organization:

• Staff members and Org/Room Managers will log in to Tehama through the chosen identity provider. See instructions in the Authentication User Guide article, section Log in with Corporate SSO.

• The Org Admin user for the organization can log in the same way, or they can opt to log in to Tehama using their backup Tehama credentials, (the authentication method they set up when they joined Tehama) by clicking on the text Organization admins can log in here found on the SSO sign-in page for Org Admin users.^*

Set up Corporate SSO authentication

The Org Admin user for the organization can enable or disable SSO authentication at any time.

Each organization that wishes to enable SSO must first set up a relationship between its Tehama account/organization and an identity provider. This relationship enables the exchange of authentication and authorization data between Tehama and the identity provider through the 'Security Assertion Markup Language' (SAML) standard or through the 'System for Cross-domain Identity Management' (SCIM) standard.

Once SSO is enabled, you can opt to set up user provisioning between your Tehama organization and the identity provider either through SAML or through SCIM, or a combination of both.

For SSO to be successfully set up for existing users in your Tehama organization, each existing user must, at the time that corporate SSO authentication is enabled, have a corresponding user account in the identity provider (IP), with user accounts in both systems (identity provider and Tehama) configured with the same email address.

• NOTE: You can set up user provisioning such that adding new users to the connected application for your Tehama organization in your IP, automatically creates accounts for them in your Tehama organization. (For SAML-based user provisioning, this occurs the first time the user logs in to Tehama. SCIM-based user provisioning creates the account for the user in Tehama immediately.)

The following instructions walk you, the organization's Org Admin user (the user with the Org Admin role), through setting up the SSO service for your organization and linking it with your organization in Tehama, and configuring your organization's users to log in with SSO.

The following steps, divided into four parts, walk you through configuring the Tehama SAML (Security Assertion Markup Language).

• Begin Tehama SSO Configuration
• Configure the Identity Provider
• Finish Tehama SSO Configuration
• Tehama Organization User SSO Configuration

Begin Tehama SSO Configuration

1. Open a tab in the browser of your choice and log in to Tehama as the organization's Org Admin user following the Login Instructions in the Authentication User Guide.
   
   
2. Go to your organization's settings page by clicking the SETTINGS tab in the navigation bar.
   
   
3. Click on the AUTHENTICATION sidebar item. You will see the Authentication page.
   
   
   
   
4. Check "Enable SAML Single-Sign On"
   
   
   
   
5. Take note of the values in the Entity ID and the Callback URL (Assertion Consumer Service URL) fields. These will be used during the configuration of the identity provider.
   
   
6. Do not click on the SAVE button at this point.
   
   
   • The Federation Metadata XML field still requires completion. You will retrieve this information during the configuration of the identity provider and add it to this page while finishing the Tehama SSO Configuration.

Configure the Identity Provider

This step is where you create a "connected application" in your identity provider for your Tehama organization.

You may create either a SAML-based or SCIM-based connected application.

Examples of identity providers that support SAML or SCIM include:

• Salesforce
• Okta
• many others.

First, if you do not already have accounts for the existing users in your Tehama organization in your chosen identity provider, set those up in the identity provider following the identity provider's documentation. Be sure to use the same email address for a user in both Tehama and in the identity provider.

Then, again following the identity provider's documentation, add your Tehama organization as a "connected application" with the Entity ID and Callback URL values that were presented to you when you enabled SAML SSO for your organization in Tehama. (Note: Identity providers do not always use the same names for these values. Entity ID may be referred to as Audience URI, Identifier, Issuer, SP Entity ID, etc. Similarly, Callback URL may be referred to as Assertion Consumer Service (ACS), Reply URL, Single sign on URL, etc.)

Once your identity provider configuration is complete, retrieve the Federation Metadata XML for use in finishing the Tehama SSO Configuration. Identity providers may refer to this variously as IDP metadata, metadata, or simply XML, etc.

Finish Tehama SSO Configuration

1. Go back to the Tehama browser window that is showing the Authentication page, with the Enable Single-Sign On checkbox checked.
   
   
2. Paste the XML contents into the "Federation Metadata XML" text box field.
   
   
   
   
3. Click SAVE.

Tehama Organization User SSO Configuration

When SSO setup is completed, each existing user in your organization will receive an email.

• If a SAML-based connection application was used, the email will invite the user to configure their SSO login by clicking on the provided link, CONFIGURE SSO LOGIN.

• If a SCIM-based connected application was used, the email will alert the user to the change in authentication and will contain a link to the Tehama login page.

Each subsequently added team member will receive the same email.

For SSO to work each existing Tehama organization user must, at the time that corporate SSO authentication is enabled, have a corresponding user account within the identity provider’s directory, with user accounts in both systems (identity provider and Tehama ) configured with the same email address.

Identity Provider Documentation

Each identity provider has its own documentation explaining how to set up connections with applications like Tehama. In addition, Tehama supplements the identity provider documentation for setting up connected applications for a number of well-known identity providers. See Tehama's SSO Identity Providers User Guide.

---

SSO User Provisioning

If your organization uses Single Sign On (SSO) for its authentication method, you may also opt to enable SSO user provisioning.

Tehama offers two versions of SSO user provisioning.

1. SAML-based User Provisioning
2. SCIM-based User Provisioning

Note, you may choose to set up both SAML-based and SCIM-based user provisioning.

SAML-based User Provisioning

With SAML-based user provisioning enabled, members of your organization who have valid accounts with the identity provider used for SSO are automatically added as members of your Tehama organization the first time they log in to your Tehama organization when using their identity provider account. The member's profile is populated, provisioned, with values from their identity provider account. Optionally, members can be simultaneously proposed for membership in a specified set of Rooms in the organization.

More specifically, SAML-based user provisioning sets up a relationship, a mapping, between your identity provider's 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 account in the identity provider (through the 'configure SSO login' link in an invitation/welcome email sent to the user). 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).
  
  
• 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.

Enable SAML-based SSO user provisioning as follows:

1. Log in to Tehama as the organization's Org Admin user and navigate to the organization's Authentication page.
   Follow the first three steps under "Begin Tehama SSO Configuration" above.
   You will see the Authentication page with or without the Enable Single-Sign on checkbox checked. (Image shows it unchecked.)
   
   
2. If it is not already enabled, enable SAML single-sign on (SSO) (or at least check the checkbox for now). When SSO is enabled, the Authentication page will show the user interface for USER PROVISIONING.
   
   
3. Select "SAML" from the dropdown list of user provisioning options. (If you are also enabling SCIM User Provisioning, then select "SAML and SCIM".)
   
   
   
   
4. Take note of the table of Tehama Attributes that is displayed when you have "SAML" or "SAML and SCIM" selected. You will need them for the next step. The table shows attributes in the user profile of a Tehama organization member that you have mapped to attributes in the profile of a user in your Tehama connected application in your identity provider. The attributes that you map will be blocked from editing in the Tehama Web UI.
   
   The first three attributes are mandatory, and you must provide a mapping for them. All other attributes are optional. Add the optional attributes you want to map to the table.
   
   Add/remove attributes from the table as follows:
   • Add: Select an optional attribute from the dropdown list and then click on the ADD button to add it to the table.
   • Remove: Click on the 'X' in the row of an optional attribute to remove it from the table.
     
     Tehama User Profile Attributes

     Tehama Attr Name	Value Type	Info
     Email	String	The email used by the user to log in to the identity provider account Allowed values: an email address (this becomes the username for the Tehama account) Default value if no mapping: mapping is mandatory - no default
     First Name	String	The user's first name Allowed values: any string Default value if no mapping: mapping is mandatory - no default
     Last Name	String	The user's last name Allowed values: any string Default value if no mapping: mapping is mandatory - no default
     Role	String	The user's role in Tehama. Allowed values: "MANAGER", for the Org Manager role; and "STAFF", for the Staff role. If the string is not one of the above, then Tehama defaults the role value to the Staff role. If the Custom Roles & Permissions feature is enabled for your organization, and you have added the role attribute to the table, then you must place a checkmark in the Acknowledgment: Authentication and Custom Roles & Permissions 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. See 'Roles', 'Custom Roles and Permission' and 'Custom Roles & Permissions and SSO User Provisioning' for more information.
     Default Room Ids	CSV	A list of Tehama Room ids, for Rooms in your organization, to add the user to (to propose to add the user to) when the user is created. Allowed values: a comma separated list of numbers, where the numbers are Room-IDs in your Tehama organization. e.g.: 2,9,34 Find Room-IDs for your organization by clicking on FIND ROOM IDS. Default value if no mapping: an empty list
     Phone Number	String	The user's phone number Allowed values: any string Default value if no mapping: an empty string
     Avatar	String	The url to the user's avatar Allowed values: any string Default value if no mapping: an empty string
     Title	String	The user's job title Allowed values: any string Default value if no mapping: an empty string
     Country	String	The user's country of location (part of their address, where they are working from) Allowed values: any string Default value if no mapping: an empty string
     Address	String	The user's street address (first line) Allowed values: any string Default value if no mapping: an empty string
     Zip/Postal Code	String	The user's zip or postal code, if address is in USA or Canada, respectively Allowed values: any string Default value if no mapping: an empty string
     City	String	The user's city Allowed values: any string Default value if no mapping: an empty string
     State/Province	String	The user's state or province, if address is in USA or Canada, respectively Allowed values: any string Default value if no mapping: an empty string
     Country of Citizenship	String	The user's country of citizenship Allowed values: any string Default value if no mapping: an empty string
     Department	String	The user's department in the organization's company Allowed values: any string Default value if no mapping: an empty string

5. Configure your identity provider in another tab or browser.
   The steps here will depend on your choice of identity provider, but in general there are four steps:
   
   • A. Set up Single Sign On (See SSO set up instructions above), if it is not already set up. You can choose to create either a SAML-based connected-application or a SCIM-based connected-application in your identity-provider. Both types of connected application will support SAML-based user provisioning.
     
     
   • B. Identify existing and add custom attributes to your identity provider's user profile for all the Tehama profile attributes you wish to auto-provision. (Be sure to set values for any new custom attributes.)
     
     
   • C. Add custom attributes to your identity provider's connected SAML application for Tehama for all the Tehama profile attributes you wish to auto-provision.
     
     Take note of the names of these custom attributes. You will need them to fill out the table in the 'Enable User Provisioning' section on the Tehama Web UI's Authentication page later.
     
     Note, if you are also enabling SCIM User Provisioning, then your identity provider may, like Okta does, add these custom attributes automatically for you, as part of the SCIM User Provisioning setup.
     
     
   • D. Map the attributes from the identity provider's user profile to the attributes in the connected SAML application.
     
     Note, if you are also enabling SCIM User Provisioning, then your identity provider may, like Okta does, map these custom attributes automatically for you, as part of the SCIM User Provisioning setup.
6. Return to the Tehama Authentication page in your other tab/browser.
   
   
7. Fill out the table under the "SAML" option in the USER PROVISIONING section in the Authentication page. Use the names of the custom attributes you added to the user profile in your Tehama connected application in your identity provider. This provides the mapping needed between your Tehama connected application and Tehama.
   
   
8. Click SAVE.

SCIM-based User Provisioning

With SCIM-based user provisioning enabled, members of your organization who have valid accounts with the identity provider used for SSO are automatically added as members of your Tehama organization as soon as their identity provider accounts are assigned/added to the SCIM-based Tehama application in their identity provider. The member's profile is populated, provisioned, with values from their identity provider account. Optionally, members can be proposed for membership in a specified set of Rooms in the organization at the time of their first login to Tehama.

More specifically, SCIM-based user provisioning sets up a relationship, a mapping, between your identity provider's 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-based 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-based 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 as well.
  
  
• 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.

Tehama's SCIM implementation targets version 2.0 of the SCIM protocol. The SCIM API endpoint is given in the Authentication page under the "SCIM Endpoint URL" field. The SCIM endpoint requires an OAuth Token Bearer header on every request, which you can also find in the Authentication page, under the field "SCIM Authorization Bearer Token".

Enable SCIM-based SSO user provisioning as follows:

1. Log in to Tehama as the organization's Org Admin user and navigate to the organization's Authentication page.
   Follow the first three steps under "Begin Tehama SSO Configuration" above.
   You will see the Authentication page with or without the Enabled Single-Sign on checkbox checked. (Image shows it unchecked.)
   
   
2. If it is not already enabled, enable SAML single-sign on (SSO) When SSO is enabled, the Authentication page will show the user interface for USER PROVISIONING. (Image shows the interface before SAML single-sign on is completely set up - notice the absence of the Federation Metadata XML.)
   
   
3. Select "SCIM" from the dropdown list of user provisioning options.
   (Note that the Acknowledgment: Authentication and Custom Roles & Permissions checkbox will only be visible if your organization has the "Custom Roles & Permissions" feature enabled, or if you have previously acknowledged this statement.)
   
   You don't need to add any information to this section. Just use it to get the two values it shows when you are configuring your SCIM-based connected-application in your identity-provider in step 5 below:
   • SCIM Endpoint URL
   • SCIM Authorization Bearer Token
     • IMPORTANT: Tehama generates a value for the SCIM Authorization Bearer Token only after you have completely set up SAML single-sign on (SSO) authorization, including entering the Federation Metadata XML in the Tehama application and clicking SAVE. (See SAML single-sign on (SSO).)
4. If the Custom Roles & Permissions feature is enabled for your organization, then you must place a checkmark in the Acknowledgment: Authentication and Custom Roles & Permissions 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. See 'Roles', 'Custom Roles and Permission' and 'Custom Roles & Permissions and SSO User Provisioning' for more information.
   
   
5. Click SAVE.
   
   
6. Configure your identity provider in another tab or browser.
   The steps here will depend on your choice of identity provider, but in general there is just one step:
   
   Set up Single Sign On (See SSO set up instructions above), taking care to create a SCIM-based connected application for Tehama using the SCIM Endpoint URL and SCIM Authorization Bearer Token values found in the previous step.
   
   IMPORTANT: If you had already set up SSO, look to see if your connected application for Tehama in your identity provider is SCIM-based and constructed with the values from the SCIM Endpoint URL and SCIM Authorization Bearer Token fields. If it is not, then you will have to remove your existing connected application and construct a new, SCIM-based one.
   
   
7. Optionally, also set up SAML-based SSO user provisioning, with at least the minimal required attributes mapped.
   
   There are two reasons for doing this. One, it provides a backup if SCIM is slow or goes down. Two, only those attributes mapped through SAML-based SSO user provisioning will be blocked from editing in the Tehama Web UI. SCIM-based user provisioning syncs a standard set of attributes and any in that set that you did not map in the SAML-based SSO user provisioning will not be blocked from editing in the Tehama Web UI.

SCIM Attribute Mapping

Tehama SCIM supports the standard SCIM User schema, but also uses a Tehama User schema for fields such as roomIds (Tehama RoomIDs) and orgRole (Tehama Organization Role). These are as listed in the table below. Note the following short form for the SCIM Namespace column:

SCIM_USER_NS = urn:ietf:params:scim:schemas:core:2.0:User
TEHAMA_USER_NS = urn:ietf:params:scim:schemas:extension:tehama:2.0:User

Tehama Field	SCIM Attribute	SCIM Namespace
Email	emails	SCIM_USER_NS
First Name	name {givenName}	SCIM_USER_NS
Last Name	name {familyName}	SCIM_USER_NS
Role	orgRole	TEHAMA_USER_NS
Initial Room Ids	roomIds	TEHAMA_USER_NS
Phone Number	phoneNumbers	SCIM_USER_NS
Avatar	photos	SCIM_USER_NS
Avatar	avatar	TEHAMA_USER_NS
Title	title	SCIM_USER_NS
Country	addresses {country}	SCIM_USER_NS
Address	addresses {streetAddress}	SCIM_USER_NS
Zip/Postal Code	addresses {postalCode}	SCIM_USER_NS
City	addresses {locality}	SCIM_USER_NS
State/Province	addresses {region}	SCIM_USER_NS
Country of Citizenship	citizenship	TEHAMA_USER_NS
Department	department	SCIM_USER_NS

For further details on which attributes are supported as well as information about their types and metadata, perform an HTTP GET on the https://app.tehama.io/scim/v2/ Schemas API.

---

Custom Roles & Permissions and SSO User Provisioning

Tehama provides a Custom Roles & Permissions feature, which allows your organization to define custom roles for your users. A custom role is a role composed of one or more permission sets.

See the Custom Roles and Permissions User Guide for more information about custom roles.

Tehama SSO User Provisioning is unable to map custom roles. It is restricted to two of Tehama's predefined roles, "Org Manager" and "Staff".

If the Custom Roles & Permissions feature is not enabled in your organization, then Tehama allows provisioning of a user's role, limited to those two predefined roles.

If the Custom Roles & Permissions feature is enabled in your organization, then Tehama does not allow any provisioning of a user's role. All role setting must be done within Tehama. Aside from initial provisioning, the roles set within the identity provider will not be communicated to Tehama.

The custom roles and permissions feature is not initially enabled in your organization. It will be enabled the first time your Org Admin user attempts to use the feature, through clicking on the CREATE ROLE button on the ROLES page, after acknowledging the implications the feature has for role setting in Tehama's SSO User Provisioning.