Authentication User Guide
Tehama offers two flavours of authentication:
2FA and SSO are both available to all organizations.
Two-Factor Authentication (2FA)
Two-Factor Authentication (2FA) is used as part of the login process for Tehama to provide extra security.
After you fill in the fields on the JOIN TEHAMA page, and click the Register button, you are presented with a page where you can install Google Authenticator software.
Choose either the Google Play button or the App Store button and then click Next. The next page contains a QR code which you'll need to scan on your mobile device. After you click Next, the final login page opens.
Once you enter your email address and password, you'll need to access the Google Authenticator on your mobile device to enter this code in the Authentication Code field. When you click Login you will have access to Tehama.
If you need to reset your password , reach out to the Tehama Concierge for support (Tehama Support).
Choose one of the options listed to assist you get the help you require.
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.
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 Owner, 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
- Configure the Identity Provider
- Finish Tehama SAML Configuration
- Team Tehama SAML Configuration
Begin Tehama SAML Configuration
- Open a tab in the browser of your choice and log in to Tehama as the Organization Owner.
- Address: https://<your organization-id>.tehama.io
or, if you do not know your organization-id:
- Address: https://app.tehama.io and enter your organization's url when prompted.
(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.)
- Go to your Organization's settings page by selecting Organization from the top-right dropdown.
- Click on the AUTHENTICATION sidebar item.
- Check "Enable SAML Single-Sign On"
- 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.
- Do not click on the SAVE button at this point.
Configure the Identity Provider
You may use any SAML-based identity provider.
- Active Directory Federation Services (ADFS)
- many others.
After setting up your chosen identity provider, 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. 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 SAML Configuration. Identity providers may refer to this variously as IDP metadata, metadata, or simply XML, etc.
You can find detailed instructions for setting up an identity provider in the SSO Identity Providers User Guide
Finish Tehama SAML Configuration
- Go back to the Tehama browser window that is showing the Authentication tab
- Paste the XML contents into the "Federation Metadata XML" text box field.
- Press 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.
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.
SSO User Provisioning
If your organization uses Single Sign On (SSO) for its login process, you may also opt to enable SSO user provisioning.
With 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 organization1.
1. 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, 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. 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 SSO user provisioning as follows:
- Enable SSO, if it is not already enabled.
- Log in to Tehama as the Organization Owner and navigate to the organization's Authentication page.
Follow the first three steps under "Begin Tehama SAML Configuration" above.
- Scroll down until you see the "Enable User Provisioning" checkbox.
- Check "Enable User Provisioning".
- Take note of the attributes in the table of Tehama Attributes found below the checkbox. You will need them for
the next step. These are attributes that make up the user profile of a Tehama organization member. This table is
used to define associations between a Tehama member profile and attributes on your connected SAML application for
Tehama, which are in turn mapped to attributes on the profile of a user in your identity provider.
- 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 three steps:
A. 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.)
B. 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.
C. Map the attributes from the identity provider's user profile to the attributes in the connected SAML application.
- Return to the Tehama Authentication page in your other tab/browser.
- Fill out the table in the 'Enable 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. This provides the mapping needed
between your connected SAML application and Tehama.
- Click SAVE.
Log in to the Tehama Web UI as follows:
- Open a browser and
- Navigate to the URL: https://app.tehama.io,
- You will see the SIGN IN TO YOUR ORGANIZATION dialog.
- Enter your organization's subdomain into the empty field to complete your organization's URL and click CONTINUE. (e.g.: enter 'mysubdomain' to complete the URL: mysubdomain.tehama.io)
- If you have forgotten your organization's subdomain, you may request it be emailed to you.
- Navigate directly to your organization's URL for Tehama. (e.g.: https://mysubdomain.tehama.io)
If using SSO and your identity provider determines that you are already logged in, then you are logged in.
Otherwise, you will see the LOGIN TO ... dialog. Log in using the account that you set up when you joined Tehama. That is, either a Google account or a Tehama account.
Now you may proceed to interact the Tehama Web UI.
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 an organization owner (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).
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.