Authentication User Guide

In this user guide, you will see how to log in to the Tehama Web UI.

You will be shown how to set up the two available flavours of authentication to the Tehama Web UI offered by Tehama, both of which are available to all organizations:

You will see how to set up SSO User Provisioning for your Tehama user accounts (available if your organization has set up SSO authentication).

You will also learn how Tehama enforces acceptance of its Terms of Service and find out how you can explore the option of Custom Terms of Service for your organization.


Login instructions

Log in to the Tehama Web UI as follows:

  • Open a browser and
    • either:
      1. Navigate directly to your organization's URL for Tehama.
        e.g.: https://mysubdomain.tehama.io
    • or
      1. Navigate to the URL https://app.tehama.io.
        You will see the SIGN IN TO YOUR ORGANIZATION dialog.
      2. Enter your organization's subdomain into the empty field to complete your organization's URL for Tehama.
      3. Click CONTINUE.

        If you do not know your organization's url, select the text "Can't remember your Organization's URL?", enter your email address and a link to your organization's login page will be emailed to you.
  • Next:
    • For non-users of Single Sign On (SSO):
      1. You will see the LOGIN TO <your subdomain name> dialog for the Tehama Web UI.
      2. Log in using the account that you set up when you joined Tehama. That is:
        • either:
          • a Tehama account, which uses Two-Factor Authentication.
            • Enter your username and password.

              If you do not know your password, select the text "Forgot your password?", enter your email address and a link to reset your password will be emailed to you.

              NOTE:
              The admin user in an organization that has enabled Single Sign On (SSO) must create a support ticket through Tehama Support in order to reset their Tehama password and MFA code.


            • Click SIGN IN. You will see the Two factor authentication dialog.
            • Get the current 6-digit verification code (MFA code) from the entry you set up for this Tehama user account in your Google Authenticator application on your mobile device and enter it into the field in the dialog.

              If you cannot retrieve your 6-digit verification code, contact Tehama Support for assistance in resetting your MFA.
            • Click LOG IN.
        • or
          • a Google account
            • Click SIGN IN WITH GOOGLE.
            • Log in as you normally would to your google account.
    • For users of Single Sign On (SSO):
      1. Your identity provider will determine if you are already logged into its service.
        • If you are already logged into your identity provider's service:
          • you will be connected directly to the Tehama Web UI.
        • Else if you are not already logged into your identity provider's service:
          • you will see the login mechanism provided by your identity provider. Log in as you normally would.

            NOTE:
            For organizations that have enabled Single Sign On (SSO), staff members and managers will log in through the chosen identity provider, as described here, but the admin user in an organization that has enabled SSO can log in using their Tehama credentials, the same as a non-user of SSO by clicking on the text Organization admins can login here found on the Tehama SSO login dialog.

            If a staff member or manager is promoted to be the admin user for an organization that has enabled SSO, they will be prompted to enter backup Tehama credentials, if they have not already done so.

Once logged in, you will see the ROOMS page of the Tehama Web UI and you may proceed to interact with the Tehama Web UI.


Two-Factor Authentication (2FA)

Two-Factor Authentication (2FA) is used as part of the Tehama Web UI login process to provide extra security.

2FA has every Tehama user (except for those who join through SSO) set up a Multi-Factor-Authentication (MFA) code generator on a secondary device (tablet, phone etc) when they first join Tehama. The user must access the current MFA code from this secondary device each time they log in to the Tehama Web UI.

How to set up 2FA:

As a user of Tehama, unless joining through SSO, you will set up 2FA authentication when you first log in to the Tehama Web UI from the invite link in your "Welcome to Tehama" email as follows:

  1. Click on the invite link in your "Welcome to Tehama" email. The link will bring you to a JOIN TEHAMA dialog.
  2. In the dialog, enter:
    • your name
    • your email
    • your password (and password confirmation)
  3. Click the Register button. You will be presented with a new dialog asking you to install the Google Authenticator software on your mobile device.
  4. Go ahead and install it (Google Authenticator), if you haven't already.
  5. From the same dialog, choose:
    • either:
      • the Google Play button if your mobile device is an android device
    • or:
      • the App Store button if your mobile device is an Apple device
  6. Click Next. The next dialog will contain a QR code.
  7. Create a new entry in the Google Authenticator application on your mobile device and scan the QR code into this new entry.
  8. Click NEXT on the dialog. The LOGIN TO ... dialog will open. (On subsequent attempts to log in to the Tehama Web UI, this is the first dialog you will see.)
  9. In the dialog, enter:
    • your email same as you entered into the JOIN TEHAMA dialog
    • your password same as you entered into the JOIN TEHAMA dialog
  10. Click SIGN IN. You will see the Two factor authentication dialog.
  11. Access the Google Authenticator application on your mobile device and retrieve the current MFA code for the entry you created above.
  12. Enter this code in the Authentication Code field.
  13. Click LOG IN. You will now be logged in to Tehama.

You have now:

  • configured your Tehama user account with an email, which is the user name for the account, and a password.
  • set up an entry in the Google Authenticator application on your mobile device for your Tehama user account. This entry will provide you with the MFA code needed to log in each time you log in to Tehama using this account.

If you need to reset your MFA code (or your password), reach out to the Tehama Concierge for support at (Tehama Support).


Single Sign On (SSO)

Tehama provides the option to use Single Sign On (SSO) for its login process.

Each organization that wishes to enable SSO must first set up a relationship between its Tehama account 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.

SAML (Security Assertion Markup Language) is an XML based standard that supports users only having to provide their authentication data (e.g.: username/password) once when logging in to a series of servers (applications/websites) that are affiliated with the same 'identity provider'.

Once SSO is enabled for an organization, staff members and managers will log in through the chosen identity provider, following the instructions for SSO users in the Login instructions section above. The admin user for the organization can continue to log in to Tehama using their Tehama credentials, the same as a non-user of SSO by clicking on the text Organization admins can login here found on the Tehama SSO login dialog. (If a staff member or manager is promoted to be the admin user for an organization that has enabled SSO, they will be prompted to enter backup Tehama credentials, if they have not already done so.)

Each user needs:

  • a login to the organization's Tehama account, and
  • a login to the SSO service.

The following instructions walk you, the organization's admin user (the user with the admin role), through setting up the SSO service for your organization and linking it with your organization's Tehama accounts.

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

Begin Tehama SAML Configuration

  1. Open a tab in the browser of your choice and log in to Tehama as the organization's admin user following the Login Instructions above.
  2. Go to your organization's settings page by selecting Organization from the top-right dropdown.

    top-right-dropdown

  3. Click on the AUTHENTICATION sidebar item. authentication page with enable-saml-single-sign-on disabled

  4. Check "Enable SAML Single-Sign On"

    authentication page with enable-saml-single-sign-on enabled

  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.

Configure the Identity Provider

You may use any SAML-based identity provider.

Examples include:

  • Salesforce
  • Okta
  • many others.

If you do not already have accounts for your users in your chosen identity provider, set those up following the identity provider's documentation.

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 you 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.)

SCIM based connected applications:
Some identity providers, like Okta for example, support "System for Cross-domain Identity Management" (SCIM).

If you want to enable SCIM-based user provisioning, you will need to create a SCIM-based connected application for Tehama in your identity provider.

Follow the identity provider's instructions for creating a SCIM-based connected application. Just as for a non-SCIM-based connected application, you will need the Entity ID and the Callback URL values. You will also need two other values that can be found on the AUTHENTICATION page under the USER PROVISIONING section when either "SCIM" or "SAML and SCIM" is selected:

  • SCIM Endpoint URL
  • SCIM Authorization Bearer Token

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

Finish Tehama SAML Configuration

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

    authentication page with enable-saml-single-sign-on enabled and XML metadata added to page

  3. Click SAVE.

Tehama Team Member SAML Configuration

Now that the Tehama SAML configuration is completed, each existing team member in your organization will receive an email inviting them to configure their SSO login by clicking on the provided link, CONFIGURE SSO LOGIN, and to follow the instructions.

Each subsequently added team member will receive the same email.

SCIM based connected applications:
If you created a SCIM-based connected application for Tehama in your identity provider, the email received by the team members will not contain a link requiring them to configure their SSO logins, but instead will contain a link to the Tehama login page.

For SSO to work each Tehama Team Member must 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.

Backup Tehama Credentials

If a staff member or manager is promoted to be the admin user for an organization that has enabled SSO, they will be prompted to enter backup Tehama credentials, if they have not already done so.

A newly appointed admin user of an SSO enabled organization who does not already have backup Tehama credentials will go through the following process the first time they log in to Tehama after their promotion:

  1. Log in as normal with your SSO identity provider credentials.
  2. After a successful login, a dialog entitled Backup Authentication required will appear.
  3. Enter a password and confirmation.
  4. Click SUBMIT.

From now on the new admin user will be able to log in to Tehama using their email and the backup password by clicking on the text Organization admins can login here found on the Tehama SSO login dialog.

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 login process, 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.

Note: Room membership is proposed only and must be approved by the connected organization. If the Room has membership auto-approval turned on, then this approval is automatic.

More specifically, SAML-based user provisioning sets up a relationship, a mapping, between the 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 a 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 admin user and navigate to the organization's Authentication page.
    Follow the first three steps under "Begin Tehama SAML Configuration" above.
    You will see the Authentication page with or without the Enable Single-Sign on checkbox checked. (Image shows it unchecked.) authentication page with enable-saml-single-sign-on disabled

  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. authentication page with enable-saml-single-sign-on enabled and XML metadata added to page

  3. Select "SAML" from the dropdown list of user provisioning options.

    authentication page with enable-saml-single-sign-on enabled and XML metadata added to page and with SAML user provisioning selected

  4. Take note of the table of Tehama Attributes found below the checkbox. You will need them for the next step. These attributes make up the user profile of a Tehama organization member. This table is used to define associations between a Tehama member profile and the profile of a user in your connected SAML application for Tehama 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.


  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 UI's Authentication page later.

    Note, step C is not necessarily required when using an identity provider such as Okta that is capable of directly sending attributes from the identity provider's own user profile.

    D. Map the attributes from the identity provider's user profile to the attributes in the connected SAML application.

    Note, step D may be slightly different when using an identity provider such as Okta that is capable of directly sending attributes from the identity provider's own user profile. In these cases, follow the identity provider's documentation to see how to send these attributes through SAML to Tehama.

  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 your connected SAML application in your identity provider (or from the identity provider's user profile, if, as in the case of identity providers similar to Okta, you opt to use those attributes). This provides the mapping needed between your connected SAML 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.

Note: Room membership is proposed only and must be approved by the connected organization. If the Room has membership auto-approval turned on, then this approval is automatic.

More specifically, SCIM-based user provisioning sets up a relationship, a mapping, between the 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 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.

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 admin user and navigate to the organization's Authentication page.
    Follow the first three steps under "Begin Tehama SAML Configuration" above.
    You will see the Authentication page with or without the **Enabled Single-Sign on" checkbox checked. (Image shows it unchecked.) authentication page with enable-saml-single-sign-on disabled

  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.) authentication page with enable-saml-single-sign-on enabled

  3. Select "SCIM" from the dropdown list of user provisioning options.

    authentication page with enable-saml-single-sign-on enabled and XML metadata added to page and with SCIM user provisioning selected

    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:
  4. Click SAVE.

  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 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 the remove your existing connected application and construct a new, SCIM-based one.

  6. 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

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.


Terms of Service

The following is not applicable if your organization has enabled custom terms of service.

While you are using Tehama, Tehama continuously checks to see if you have accepted the latest Terms of Service (ToS). If a version of the ToS that is newer than the last one you accepted exists, you will be prompted to view and accept it. You are required to accept the latest ToS before you may proceed to interact with Tehama through the Web UI.

WARNING:: Failure of the admin user for the organization (the user with the Admin role for the organization) to accept the latest ToS within fifteen days of issuance may result in the suspension of the organization's account.

When a change is made by Tehama to the ToS, Tehama organization owners receive an email and a notification:

  • as soon as the change is available for acceptance.
  • after five days have passed with no acceptance.
  • after ten days have passed with no acceptance.

After fifteen days have passed with no acceptance of the ToS by the organization owner, a suspension may be placed on the organization's account, at Tehama's discretion.

A suspended Tehama organization's account restricts access to the Tehama Web UI for members of the organization and pauses Rooms owned or connected to by the organization for all members of that Room (for members of other orgs in the Room as well).

(See the 'Suspended Status' section in the Organization User Guide for a more in depth explanation of what it means for an organization's account to be suspended.)

To lift a suspension for non-acceptance of the latest ToS, the organization owner must log in to the organization and accept the ToS. The suspension will be lifted automatically. If this is not possible, contact Tehama Support for assistance.


Custom Terms of Service

Your organization may contractually opt out of Tehama's default Terms of Service and instead mutually agree upon a custom Terms of Service. If that is something your organization would like to explore, contact Tehama Support for assistance.

Once a custom Terms of Service has been established for your organization, your members will no longer be required to accept Tehama's default Terms of Service while logged in to the Tehama Web UI.