Terra Dotta has the built-in ability for both applicant and admin users to login using local authentication. Local authentication means that any user could have an account in Terra Dotta that is based on an email address as their username and a password they set themselves. Since the local authentication functionality is native to the software, this option is maintained even for clients who set up an integration with a campus (remote) authentication system. This means that a Terra Dotta site always has the possibility to have non-integrated user accounts.
Important Note: An integration with Terra Dotta requires that the client also provide a campus-wide authentication solution. This means that users who are associated with your institution will be able to log in to Terra Dotta using the same username and password combination that they use to access other campus systems. Setting up campus authentication makes logging into Terra Dotta easy and straightforward for your institution's users. Someone who logs into the site using campus/remote authentication is called an integrated user.
Terra Dotta can integrate with a wide variety of authentication and Single Sign-On (SSO) systems, including LDAPS, Shibboleth/Shibboleth InCommon, ADFS, CAS or any SAML 2.0-based system.
Most types of authentication setups will require that the user choose either the remote/campus authentication option or the local authentication option when logging in. This means that there will either be two login options visible on the site (a split login), one for integrated/campus users and one for non-integrated users. When logging in, the user must choose the option that is most appropriate for them.
LDAPS authentication setups do not have a split login, and the native Terra Dotta login form is used by both integrated and non-integrated users.
Single-Sign On (SSO)
If your campus uses a Single-Sign On (SSO) authentication system, that will also work with your Terra Dotta site. For SSO authentication systems, a user only needs to enter their username and password once per browser session. This means that if a user has previously logged in to another campus site previous to visiting your Terra Dotta site, the user attributes from this successful authentication will be stored in the browser and passed to Terra Dotta when the user selects the campus login option on the main page. They will not need to enter their username and password again when logging into Terra Dotta.
For most SSO setups, when the user clicks 'Logout' in Terra Dotta, they will be logged out of your Terra Dotta site, but their attributes will not be cleared from their browser. This means that if they are on a public or shared computer, they will need to close their browser session to have these attributes cleared, so that no one else using that computer could log into their Terra Dotta account. For clients implementing an SSO solution, we recommend posting a reminder to close the browser on the Terra Dotta logout page.
Important Note: Some SSO authentication systems allow for the configuration of a logout link that clears the user's information from the browser session on logging out of Terra Dotta.
Technical information
Terra Dotta requires only one attribute upon successful authentication: a unique, universal, unchanging identifier (UUUID). This UUUID must also be included in the SIS/HR data file that is sent to Terra Dotta.
When the campus system confirms a successful authentication, it releases the user's UUUID to Terra Dotta. Terra Dotta will then use this UUUID to look up the user's information and either create the account from the information previously submitted as part of the SIS/HR data file (for a first-time applicant), or allow the user access to their pre-existing account in Terra Dotta.
Shibboleth InCommon
We set up a separate InCommon Service Provider for each Terra Dotta client site. If your institution has multiple Terra Dotta sites, each one will have a separate Service Provider in InCommon.
In order to set up Shibboleth InCommon authentication, please provide us with the following:
1. Confirmation of the name of the IdP listed in InCommon.
2. Create a custom attribute called uuuid. This attribute should contain the unique, universal, and unchanging identifier for a user. This should be the same value you send in the UUUID column of the sis flat file. Click here for more details regarding attribute formats.
3. The username and password for a dummy/test user, and the UUUID attribute value that we will receive back for the test user.
4. (optional) The SSO logout URL.
SAML 2.0 SSO
Terra Dotta can integrate with any SSO that uses the SAML2.0 protocol, including ADFS, OKTA, Azure, or native Shibboleth, among others. Our process is to set up a Shibboleth Service Provider to receive the SAML2.0 response from your system.
Submit the following via the integration case:
1. Identity Provider metadata XML: this XML contains the IDP URL, which protocol is supported (SAML2, SAML1, etc.) as well as other things.
2. Create a custom attribute called uuuid. This attribute should contain the unique, universal, and unchanging identifier for a user. This should be the same value you send in the UUUID column of the sis flat file. Click here for more details regarding attribute formats.
3. The username and password for a dummy/test user so that we are able to test the authentication system while setting up the integration. Also, provide the UUUID attribute value that we will be receiving back for this test user.
4. (optional) The SSO logout URL.
After TD receives this information, we will provide you with our Shibboleth metadata.
CAS
In order to set up CAS authentication, we will request the following:
1. CAS login URL
2. CAS validation URL
3. CAS logout URL
4. Authentication credentials for a dummy/test user of the authentication system, and the attribute value of the UUUID for that test user.
5. The public SSL certificate chain for your CAS server(s). We are unable to retrieve SSL certificates automatically. NOTE: Moving forward, it will be the client’s responsibility to notify Terra Dotta of any forthcoming change in the SSL certificate.
6. List the specific attribute that will contain the agreed upon UUUID. This is sometimes <cas:user/>, but often it is an attribute released within <cas:attributes/>. As long as we know the name of the UUUID attribute, we can create a custom mapping to any attribute included in the response.
LDAPS
In order to set up LDAP authentication, please provide the following:
1. Access to Terra Dotta's systems for query ("bind") on the campus LDAP server.
- Open access to your LDAP to the Terra Dotta hosting server IP addresses provided by your integration specialist.
- Establish a service login for Terra Dotta to authorize LDAP queries from our application. This service user must, at minimum, have access to the full dn attribute as well as the attributes containing the UUUID, First Name, Last Name and Email. The user will also need to be able to filter on the 'login username'.
**Please let us know a phone number and a good time to contact someone to collect the service user's dn and password. Please do not submit the service user password via email.**
2. LDAP system information:
A. LDAP server details:
- The public IP address of your LDAP server(s) and the server name(s)
- Base DN
- Secure Port (usually 636)
B. Attributes
- Login username
- UUUID (unique, universal and unchanging ID to be used for record identification)
In most cases the UUUID attribute is NOT the same as the login username (i.e. uid). Only in some cases the login username field may be used as the UUUID, provided that it is sufficiently unique and permanent. If a person ever changes their login username, and especially if usernames are recycled, then the login username is not a secure and reliable identifier, and a different identifier should be used for the UUUID.
NOTE: the UUUID attribute must be obtained through any successful LDAP user bind.
3. The entire SSL certificate chain for your LDAP server(s). We are unable to retrieve public SSL certificates automatically. NOTE: Moving forward, it will be the client’s responsibility to notify Terra Dotta of any forthcoming change in the SSL certificate chain.
4. The user name and password for a dummy/test user, and the UUUID attribute value that we will be receiving back for the test user.
SAML Attribute Formats
Below is the list of required attributes and the accepted formats for SAML SSO. Please choose only one format for each attribute.
UUUID field: (Required)
<Attribute name="uuuid">
<Attribute name="uuuid" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
<Attribute name="uuuid" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
<Attribute name="uuuid" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecifed">
<Attribute name="UUUID">
<Attribute name="UUUID" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
<Attribute name="UUUID" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
<Attribute name="UUUID" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecifed">
Email Address field: (Required for usercreation from SAML data)
<Attribute name="email">
<Attribute name="email" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
<Attribute name="email" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
<Attribute name="email" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
<Attribute name="EMAIL" id="email" />
<Attribute name="EMAIL" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
<Attribute name="EMAIL" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
<Attribute name="EMAIL" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
First Name field: (Required for usercreation from SAML data)
<Attribute name="givenName">
<Attribute name="givenName" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
<Attribute name="givenName" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
<Attribute name="givenName" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
<Attribute name="GIVENNAME">
<Attribute name="GIVENNAME" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
<Attribute name="GIVENNAME" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
<Attribute name="GIVENNAME" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
Last Name field: (Required for usercreation from SAML data)
<Attribute name="surname" >
<Attribute name="surname" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
<Attribute name="surname" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
<Attribute name="surname" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
<Attribute name="SURNAME">
<Attribute name="SURNAME" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
<Attribute name="SURNAME" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
<Attribute name="SURNAME" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
Date of Birth field: (Required for usercreation but can be manually provided by end user on firsttime login)
<Attribute name="dob" >
<Attribute name="dob" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
<Attribute name="dob" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
<Attribute name="dob" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
<Attribute name="DOB">
<Attribute name="DOB" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
<Attribute name="DOB" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
<Attribute name="DOB" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
User Sex field: (Required for usercreation but can be manually provided by end user on firsttime login)
<Attribute name="gender" >
<Attribute name="gender" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
<Attribute name="gender" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
<Attribute name="gender" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
<Attribute name="GENDER">
<Attribute name="GENDER" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
<Attribute name="GENDER" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
<Attribute name="GENDER" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
Return to implementing Terra Dotta for