Configuring SAML 2.0
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
-
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.
-
Share your IdP Details with your IE representative so they can configure your client. Typically these are shared via the
IdP metadata XML file
. -
Configure your IdP server with the SP SAML configuration details provided by IE. Typically these are shared via the
SP metadata XML file
. -
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.
-
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
orAccount
pages anymore. These pages will require redirection to equivalent pages in your system, so share redirect URLs with IE to configure.
Changing your SSO configuration for a client with existing learners comes with some additional challenges. See details here.
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.
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.
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
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.
- 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.
- 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.
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.
-
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
- Comprehensive Example
A basic example might look like:
'authproc' => array(
// Add STATIC Attributes here...
30 => array(
'class' => 'core:AttributeAdd',
'LICENSE_ID_NAME_HERE' => array('ACTUAL_LICENSE_ID_HERE')
),
A more comprehensive example might look like:
$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'),
),
)
);
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 authenticationhttps://
<product-domain>
/access/saml/login/<client-slug>
?returnTo=<redirect-path>
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
- Authenticate from an incognito browser, using the SP login URL to authenticate into the IE platform through SSO.
- 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.