SAML 2.0 SSO

TI supports SAML 2.0 SSO, which allows users to authenticate with an Identity Provider (IdP) that supports this standard.

Glossary

Identity Provider (IdP): The system of record for users and their attributes. Some examples of systems and services that can operate as an IdP are Shibboleth, Okta, OneLogin, Salesforce and ADFS.

Service Provider (SP): A system that provides a service which requires authentication and/or authorization. In this case, TI is the Service Provider.

Metadata: A standards-based XML document that describes a SAML-enabled system. Metadata is typically provided for both SPs and IdPs. TI provides metadata for your instance in the administration interface. The TI SP metadata can be imported directly by your provider if supported, or individual components can be entered manually.

Signed Responses: Allows the SP to verify a response actually came from the IdP by validating the response signature with the IdP certificate. This is not enabled by default in TI. If your IdP supports this option, you will need to ensure the X.509 certificates are exchanged between the SP and IdP, and you will need to turn on "Sign Requests" under SAML Advanced Settings in TI's SSO Settings interface.

Encrypted Assertions: The SAML format supports end-to-end encryption of responses to ensure that the SP is the only party capable of reading user information. This is enabled by default in TI. If your IdP supports this option, you will need to ensure the X.509 certificates are exchanged between the SP and IdP. If your IdP does not support this option, you will need to turn on "Allow Unencrypted Assertions" under SAML Advanced Settings in TI's SSO Settings interface. 

Configuration

In many cases the SAML 2.0 configuration in TI requires only a few key pieces of information to set up basic authentication. The IdP may require more in-depth configuration in order to meet the needs of your integration (e.g. Attribute mappings, encrypted assertions, etc.) Because this configuration can differ from IdP to IdP, we are unable to provide generic instructions here. You will need to refer to your IdP documentation for advanced configuration.

The following settings should be retrieved from your IdP, and can often be found in the administration console (if applicable) or extracted from the IdP metadata XML of your provider.

In your instance settings, specify the following options under the SAML 2.0 section under Single Sign-on. These options are available at a company level, and can be overridden at the Client level as needed.

  1. IdP Single Sign-on URL: TI supports SP-initiated SSO using the HTTP-REDIRECT binding.
  1. IdP Single Logout URL: Single logout is not currently supported, but you may still enter this value here for future use.
  1. IdP X.509 Certificate: The public key certificate from the IdP. This is required for security purposes in order to validate authentication requests. The X.509 Certificate should be entered in PEM format with a header. It should start with "-----BEGIN CERTIFICATE-----". If it does not, you can format the X.509 certificate with an external tool.
  1. Advanced Settings: There are several advanced options available, which depend on the support from your IdP. Check with your provider to determine if any of these options are required or desirable.

Once the settings have been added to your TI instance, you will also need to register TI as a SP with your IdP. This process is different for each provider, but generally you will need the following information which can be obtained from the SSO Settings page in the TI interface:

  • The TI SP metadata XML file itself. You can obtain this file by clicking "Download SP Metadata" from the SSO Settings page.
  • Assertion Consumer Service (ACS) URL (also called the Single Sign-on URL): The endpoint that receives HTTP-POST bindings from the IdP. The ACS URL can be found within the TI SP Metadata. If you have to type it in manually, it will be: https://<school domain>/access/saml/consumer -OR- https://<school domain>/access/saml/consumer/client-slug
  • Entity Id: unique identifier for your TI instance SP. The Entity Id can be found within the TI SP Metadata. If you have to type it in manually, it will be https://<school domain>/access/saml/metadata -OR- https://<school domain>/access/saml/metadata/client-slug
  • X.509 Certificate: TI's public certificate for signing and encryption. This certificate can be found within the TI SP Metadata. If you have to type it in manually, see the appendix of this article.
Attributes

TI supports the following attributes that can be mapped from your IdP. The attributes and attribute names returned in the authentication request will vary depending on the IdP. Check with your IdP to determine the available attributes.

The following list of TI attributes are available for mapping to any attribute returned from your IdP.

Base attributes recommended for all payloads:

email string Email address of the user being signed in.

firstName 

string  First name of the user being signed in.
lastName string Last name of the user being signed in.

Assigning Access

Access can be assigned in various ways depending on the TI functionality being used. 

Assigning access a la carte: If you are assigning access to individual pieces of content, you can use the following attributes. By default, we will add onto any existing access. For example, if you specify "course-a" in one payload, and "course-b" in another, the user will have access to both "course-a" and "course-b". You can use the replaceCourseAccess attribute to override this behavior. In order to find slugs, click 'View' from the content management list, then the slug is the part of the URL after "/learn/course/", but before the next slash. For example, if the URL of your course is /learn/course/this-is-a-test/first-section/first-lesson, then the slug is "this-is-a-test". This same logic applies to all content items, simply replacing "course" with the content item.

courseSlugs multi-valued string entity The unique slug identifier(s) of the course(s) the user has access to. To pass more than one, use an array. This applies to webinars, courses, articles, and videos. We recommend using bundleSlugs  instead of courseSlugs because you can easily add courses to a subscription and that addition will reflect on all previous SSO users and all new SSO users without any SSO integration changes.
bundleSlugs multi-valued string entity The unique slug identifier(s) of the subscription(s) the user should be given access to. To pass more than one, use an array. You will need to create the subscriptions within the TI interface, making sure to add courses to the subscription. The word "bundle" is an internal identifier for subscriptions and does not apply to collections. Use courseSlugs directly for a collection of courses.
learningPathSlugs multi-valued string entity The unique slug identifier(s) of the learning path(s) the user should be given access to. To pass more than one, use an array.
replaceCourseAccess boolean, default false Setting this to true will revoke access to any courses not specified in `courseSlugs`. For example, if you send `courseSlugs` over as ['a', 'b', 'c'], we will grant access to those three courses.  Afterwards, if you send `courseSlugs` over as ['a','b']  for the same learner, we will revoke access to course 'c.' You should not use this option if you are using TI-managed subscriptions. We will also revoke all access if `courseSlugs` is omitted or an empty array.


Assigning access to Panorama through License IDs:
 You can specify license IDs directly, and we will determine the client automatically. Student / Manager is part of the next generation of Panorama. Manager licenses are ignored for learners-- these only apply to client managers. To find a license ID, if you are using sublicense functionality, you will see a license ID when you click "Edit" on any sublicense. If you are not using sublicense functionality, you will see a license ID on the "Master License" tab. The list of licenses passed can only belong to one client.

studentLicenseIds multi-valued string entity containing UUIDs

The UUID(s) of the license(s) the user should have access to as a student. To pass more than one, use an array. The previous licenseIds attribute has been deprecated in favor of this attribute.

managerLicenseIds multi-valued string entity containing UUIDs The UUID(s) of the license(s) the user should have access to as a manager. To pass more than one, use an array. This attribute only applies if the user is a client manager.


Assigning access to Panorama through Client & License SKUs
: With the next generation of Panorama, you are now able to assign an arbitrary string "sku" to both Clients & Licenses. The license sku must be unique across a single client, but can be re-used across multiple clients. This allows you to setup a consistent license identification system across clients, and eliminates the need to pull license UUIDs out of TI.

clientId UUID The UUID of the client the user should belong to. To find the UUID of a client, simply navigate to it from the management interface and copy the UUID out of the URL. This can be used as an alternative to clientSlug & clientSku.
clientSlug string The slug of the client the user should belong to. To find the slug of a client, simply navigate to it from the management interface, click "view public site", and copy the path out of the URL. This can be used as an alternative to clientId & clientSku.
clientSku string The sku of the client the user should belong to. This can be configured in the client settings. This can be used as an alternative to clientId & clientSlug.
studentLicenseSkus multi-valued string entity containing UUIDs The sku(s) of the license(s) the user should have access to as a student. The SKU can be configured when editing a license. To pass more than one, use an array. This attribute must be specified alongside either clientId, clientSlug, or clientSku.
managerLicenseSkus multi-valued string entity containing UUIDs The sku(s) of the license(s) the user should have access to as a manager. The SKU can be configured when editing a license. To pass more than one, use an array. This attribute only applies if the user is a client manager. This attribute must be specified alongside either clientId, clientSlug, or clientSku.
replaceLicenseAccess boolean, default false Setting this to true will revoke access to any licenses not specified in either studentLicenseSkus or managerLicenseSkus. For example, if you send studentLicenseSkus over as ['a', 'b', 'c'], we will grant access to those three licenses.  Afterwards, if you send `studentLicenseSkus` over as ['a','b']  for the same learner, we will revoke access to license 'c.' We revoke all access if studentLicenseSkus is an empty array and there is no clientId / clientSlug / clientSku specified.


Other attributes: 
The following attributes can be used to store additional information about the user.

ref1 string, 32 character limit Any arbitrary information to be stored on the user. Can be used for any arbitrary information, e.g. student ID, company name, etc.
ref2 string, 32 character limit See ref1
ref3 string, 32 character limit See ref1
ref4 string, 32 character limit See ref1
ref5 string, 32 character limit See ref1
ref6 string, 32 character limit See ref1
ref7 string, 32 character limit See ref1
ref8 string, 32 character limit See ref1
ref9 string, 32 character limit See ref1
ref10 string, 32 character limit See ref1
role string, default "student" The role of the user, e.g. “admin”, “student”, “client-manager” etc. Can be a built-in TI role or a custom role. Similar to slugs, the role specified here should be a version of the role name with spaces replaced by dashes and all lowercase.

 

If your learner is being prompted for a first name, last name, or email address, or if your learner does not have access to the correct content items or is not part of the correct client/license(s), that means the attributes are not being sent correctly to TI. You will want to double check the attributes are being sent from your IdP and ensure they exactly match the SAML Attribute Mappings configured in TI. These are case-sensitive, so "firstName" is different than "firstname".

User Login

TI supports SP-initiated SSO with SAML, meaning that the login flow begins on the TI platform. In order to log a user into the TI instance from an external system, you can create a link to the following path:

  • https://<school domain>/access/saml/login
    -OR-
  • https://<school domain>/access/saml/login/client-slug

It is best practice to set the "External Login URL" SSO Setting to "/access/saml/login" or "/access/saml/login/client-slug" (if you are configuring SSO settings for a Client) in order for users to get directed to the correct sign in page when clicking "Sign in" from within TI.

Once a user visits this page, they will be redirected to your IdP for authentication. After authentication is successful, the IdP will send the user back to the TI platform with a SAML Response that includes any attributes per the configuration. The user will then be logged into TI and will have access to the content that have been specified in their attributes, if any.