Configuring SAML 2.0

info

For clarification on terms in these docs, please refer to the Definition of Terms page

Introduction

In many cases the SAML 2.0 configuration for the SP 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). You will need to refer to your IdP documentation for any advanced configuration. Because this configuration can differ from IdP to IdP, we are unable to provide specific instructions for every IdP.

Implementation Overview

1. Have a running Identity Provider (IdP) that supports SAML SSO protocols to integrate with IE as the Service Provider (SP). See docs for some specific IDPs here.

2. Share your IdP Details with your IE representative so they can configure your client. Typically these are shared via the IdP metadata XML file.

3. Configure your IdP server with the SP SAML configuration details provided by IE. Typically these are shared via the SP metadata XML file.

4. Test Authentication making configuration adjustments as needed. This entails you attempt logging in via SSO (Login URL provided by IE as needed) and your IE rep will consult the SP logs and make / suggest changes if required.

5. Share your SP Redirect URLs for a better user experience. With SSO enabled and accounts controlled by the IDP, learners have no need for the SP Logout or Account pages anymore. These pages will require redirection to equivalent pages in your system, so share redirect URLs with IE to configure.

Have Existing Learners?

Changing your SSO configuration for a client with existing learners comes with some additional challenges. See details here.

Using a Federated IdP?

Using a federated Identity Provider (district level, 3rd party etc) comes with some additional considerations. See details here.

Service Provider Configuration

What IE needs from you

Please provide your IE representative the following, so they can configure your SP client.

1. IdP XML Metadata file This tends to be the easiest way to share the details required for SP configuration. If more convienient, you may provide these details individually instead.

Required IdP Metadata details

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

• IdP Single Sign-on URL: TI supports SP-initiated SSO using the HTTP-REDIRECT binding.

• IdP Single Logout URL: Single logout is not currently supported, but you may still enter this value here for future use.

• 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. When entered, it should start with -----BEGIN CERTIFICATE-----. If it does not, you can format the X.509 certificate with an external tool.

2. Account Redirect URLs With SSO enabled for your client, learners will have no need for the Login, Register or Account pages on the SP side. These pages should be redirected to relevant pages on the IdP side. Please provide the following types of redirect URLs to your IE representative to configure.

Account Details URL (required)

Usage:

The account details page is replaced by an "Account Details" button which links to the URL provided.

Details:

We recommend this URL to point to a corresponding page on the IdP side where learners can adjust their account or profile settings, such as name, email, or password if available. With SSO enabled, any changes made on the IdP side will be reflected on the SP side the next time the user authenticates.

Types of pages on the IdP side to consider:

• Profile Settings Page
• Password Reset Page
• Home Page

Example:

https://www.yourdomain.com/settings

Logout URL (required)

Usage:

This redirects the logout button (in the profile dropdown menu) to the URL provided.

Details:

This, on it's own, only logs the learner out of the SP platform and not out of SSO or the IdP side. For circumstances like a shared computer terminal, it's important that learners know they aren't logged out of IdP accounts when they log out of the SP platform via this URL.

Types of pages on the IdP side to consider:

• Home Page
• Internal Dashboard Page
• A Logout URL (if available) to log the user out of the IdP
• Specific Page letting learners know they're not logged out of their IdP yet (if applicable)

Example:

https://www.yourdomain.com/logout

3. Date to begin enforcing SSO Once SSO is complete, when would you like to turn off (redirect) native registration. This is mostly relevant for clients who already have learners utilizing native registration. If you don't have any learners using native registration, this redirect can be configured immediately.

Identity Provider Configuration

Once the settings have been added to your instance client or directly to your instance (not common), you will also need to register the SP with your IdP. This process is different for each provider.

What you need from IE

Generally you will need the following information which can be obtained for your IE representative.

1. The SP Metadata XML file which includes the relevant configuration details to use. Often IdP systems can import this file to save you the hassle of configuring manually.

Required SP Metadata details

The easiest way to get these details is directly from the SP Metadata XML file you received from IE. If more convienient, you can request these details individually:

• 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://<product-domain>/access/saml/consumer/<client-slug>
  • Or https://<product-domain>/access/saml/consumer if in your own instance (uncommon).

• 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://<product-domain>/access/saml/metadata/<client-slug>
  • Or https://<product-domain>/access/saml/metadata if in your own instance (uncommon).

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

2. The licenseId for your specific IE client. (this is a static attribute that IE will provide that needs to be passed for each user).

Configure the externalCustomerID

The Name Identifier or NAME_ID is the unique ID that will identify SAML users coming from the IdP. This value is stored internally as externalCustomerId, and when a learner authenticates, it is used to determine whether to connect them to their pre-existing account or provision them a new one, if this is the learner's first time authenticating. The attributes passed by the IdP will be used to create the new account, or if connecting to a pre-existing account, the attributes passed by the IdP will be used to update it.

Important

To avoid account clashes, the externalCustomerId value must be unique amongst all learners from all clients in the same instance. With sometimes hundreds of clients in the same instance, this can mean 100s of thousands of users. See below for recommendations on how to configure this value.

Claim	Type	Description	Required?
NAME_ID	string	Instance wide unique identifier for the learner	Required

Requirements

• Must be unique across the instance: The value of the externalCustomerId must be unique across all learners of every client in an instance. This means that if you share an instance with other clients (almost everyone), then your ID must not clash with other client's learners.

• Some good options include:

  • Email Addresses
  • An ID random enough to be sufficiently collision resistant
  • Appending the school domain name to an ID like this [email protected]

Recommendations

• An ID that doesn't change: Since this value used to sync learner to their accounts or create a new account if one doesn't exist for a learner, it's recommended that this value be from a source that doesn't change. If the value does change, then the learner will receive a fresh account upon authenticating and will lose all previous progress.

  • Email Address: Sending an email as the externalCustomerId can occasionally cause this if learner's email is tied to their name in a way where any changes to their name causes a change to their email. That said, email addresses are used by many clients without much headache. Though it isn't the perfect solution, a majority of our clients consider it good enough.

  • Unique IDs: If available, an ID with sufficient randomness to be collision resistant, or appending a domain or school name to less random ID like this [email protected], has the benefits of being both unique and unchanging. This tends to be the optimal approach and is what we recommend first if available.

tip

Check the other SSO integrations we support for more specific approaches to configuring the NAME_ID.

Configure Attributes

We support the following attributes that can be mapped from your IdP. The attributes returned in the authentication request, as well as the attribute names, will vary depending on the IdP. Check with your IdP to determine the available attributes.

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

Attribute	Type	Description	Required?
firstname	string	The first name of the learner	Recommended
lastname	string	The last name of the learner	Recommended
email	string	The email address of the learner	Recommended
licenseIds	string	One or more license IDs to associate the content with the learner. This is a single value that must be sent for all learners and is best configured as a static attribute.  See below for more detials. * licenseIds is requied except in a single client instance (not common)	Required*
ref1	string	Data to be associated with the user in reports. examples: role, department, major, title, year, studentId	Optional
ref2	string	Data to be associated with the user...	Optional
ref3	string	Data to be associated with the user...	Optional

For learners that should be associated with a client (almost every case), you must include one or more licenseIds in the SAML attributes.

LicenseId as a Static Attribute

To avoid the need for an extra column for every user in your system, you can utilize a static attribute to send over the required licenseIds if your IdP allows configuring one. This is set up in your configuration as opposed to a table somewhere. The specific implementation will depend your IdP, but below is an example in SimpleSAMLphp that may or may not be directly adaptable to your specific SAML IDP.

A SimpleSAMLphp Example

This is a potential solution to sending the required licenceId in the SAML payload without needing to adjust user records in SimplePHP.

The recommended strategy is to use an "Auth Proc Filter" (documentation here).

From those docs, modify saml20-sp-remote.php and in the existing 'authproc' => array section (add it missing), add static attributes using the core:AttributeAdd functionality like so:

Basic Example

A basic example might look like:

saml20-sp-remote.php

'authproc' => array(
  // Add STATIC Attributes here...
  30 => array(
    'class' => 'core:AttributeAdd',
    'LICENSE_ID_NAME_HERE' => array('ACTUAL_LICENSE_ID_HERE')
  ),

Comprehensive Example

A more comprehensive example might look like:

saml20-sp-remote.php

$metadata['https://example.com'] = array(
  'AssertionConsumerService' => 'https://example.com/',
  'SingleLogoutService' => 'https://example.com/',
  'simplesaml.attributes' => true,
  'attributes' => array('mail', 'givenname', 'sn', 'memberOf'),
  'authproc' => array(
    // Add STATIC Attributes here...
    1 => array(
      'class' => 'core:AttributeAdd',
      'LICENSE_ID_NAME_HERE' => array('ACTUAL_LICENSE_ID_HERE'),
    ),
  )
);

tip

Please refer to our other SSO integration support for other approaches to this configuration.

Learner Access Restrictions

All access restrictions, or lack there of, are handled on the IdP side of things. So if applicable, make sure sufficent role permissions have been granted to the learners who'll need access to the IE platform before they need it.

From IE's perspective, there's not much downside to providing access to all accounts in the IdP side (ie no restrictions) as learners who need access to the IE content may change, and any learners who no longer need access or who never needed it will typically avoid.

Authentication

Logins with IE are SP-initiated SSO with SAML, meaning that the login flow begins on the the SP platform.

• In order to log a user into their IE client from an external system, you can direct learners to the following URL as a link, a dashboard button, or however else you see fit:

  • https://<product-domain>/access/saml/login/<client-slug>
  • Your <client-slug> will be provided by IE. There will be none if you have your own instance (not common)

• 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 IE platform with a SAML Response that includes any attributes per the configuration. The user will then be logged into thier SP client and will have access to the content that has been provisioned per the licenseId configured in their attributes.

• Optionally, a redirectTo query parameter can be added to the login URL to redirect a learner after authentication

  • https://<product-domain>/access/saml/login/<client-slug>?returnTo=<redirect-path>

note

IdP-initiated Login and Single IdP Logout are not supported at this time. Logging out currently logs the learner off the platform only.

Testing Authentication

It's important to test the authentication flow before going live. This will ensure that the integration has been configured successfully before learners attempt to access their content.

To test, simply

1. Authenticate from an incognito browser, using the SP login URL to authenticate into the IE platform through SSO.
2. Notify your IE representative Once notified, IE will consult the SSO logs and verify the correct user details are being sent over.

Troubleshooting

If authenitcation was successful, you should be redirected to the IE platform and logged in. If you are not logged in, and are still located on the IdP side, there's most likely an issue with the configuration on the IdP side.

If on the other hand you are seeing an error, notify your IE representative for next steps. Please include any error messages you see, as well as the page URL used to authenticate and the page URL of the error.