SAML Single Sign On

Implementation Overview

1. Have a SAML Identity Provider (IdP), or one that supports SAML protocols.

• • See here for others

2. Provide SP SSO configuration settings to your IE representative to configure you.

• • IDP Single Sign-On URL

  • IDP Single Sign-Out URL (optional)

  • IdP X.509 Certificate

3. Configure your IdP SAML 2.0 settings. From IE you'll need:

• • licenseIds (this is a static attribute that IE will provide that needs to be passed for each user)

  • TI SP metadata XML file

4. IE will provide you with you Login Link:

Continue for more details...

Resources

• Definition of Terms

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.

1. Configuring the SP

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. Please provide the following IdP configuration details to your IE representative so they can add configure the SP.

• The IdP metadata XML file: Which contains the following required values

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

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

If you have access to your instance settings (rare), options are configurable under the SAML 2.0 section under Single Sign-on.

2. Configuring the IdP

Once the settings have been added to your instance, you will also need to register the SP with your IdP. This process is different for each provider, but generally you will need the following information which can be obtained for your IE representative.

• • The SP metadata XML file: Which contains the following required values

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

If you have access to your instance settings (rare), they can be obtained from the SSO Settings page by clicking "Download SP Metadata".

3. Attributes

TI supports 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.

For licenseIds, it is expected that these values are provided as a multi-valued string entity in the response. Support for multi-valued attributes may vary depending on your provider. Also, see below for potential solution to configuring licenseIds as a static attribute in your SAML config.

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

• • • externalCustomerId - this comes from the NameID which needs to be unique amongst all learners for all clients in the same instance (see details below)

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

• • • firstname - user first name

    • lastname - user last name

    • email - user email address

    • ref1 - optional data to be associated with the user

    • ref2 - optional data to be associated with the user

    • ref3 - optional data to be associated with the user

    • licenseIds - one or more licenses to associate the user with, by ID (required if your setup on as an instance client)

4. 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://<product domain>/access/saml/login -OR-

  • https://<product 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.

• Also, redirectTo query parameter can be added redirect a learner after authentication

• Note: TI does not support IdP-initiated SSO at this time.

5. User Logout

TI supports logging out of the TI platform only. We do not support SAML SLO. If you would like to redirect the user after they are signed out of TI, you can fill in the "Account Logout Link" SSO setting. For example, you could show the user a message saying they are logged out, or the login form should they choose to login again.

Configuring the NameId (Name Identifier)

The Name Identifier is the unique ID that will identify SAML users coming from the IdP (identity provider).

Requirements

• Must be unique across the instance: This value of the NameId 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

  • Appending the school domain name to a name or ID

  • Or utilizing an ID random enough to sufficiently collision resistant

Recommendations

• Use 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 as NameId will suffice : Sending an email as the NameId can cause the problem mentioned above when a learner's email changes due to a name change. That said, email addresses are used by many clients without much headache. Though it isn't the "perfect" option, we considered it "good enough".

  • Unique IDs are a better option: If available, an ID with sufficient randomness to be collision resistant, or appending a domain or school name to less random ID, has the benefits of being both unique and unchanging.

LicenseId as a Static Attribute

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

Note: Adding a static attribute will depend on your configuration. Any examples given here will be generic and may need adjustment for your specific setup. This section in particular is addressed in a SimpleSAMLPhp environment, but hopefully is adaptable to your specific SAML IDP.

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:

'authproc' => array(

// Add STATIC Attributes here...

30 => array(

'class' => 'core:AttributeAdd',

'LICENSE_ID_NAME_HERE' => array('ACTUAL_LICENSE_ID_HERE')

),

A more comprehensive example 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'),

),

);

Appendix

TI SP X.509 Public Certificate

-----BEGIN CERTIFICATE-----

MIIDgzCCAmqgAwIBAgIBADANBgkqhkiG9w0BAQ0FADBbMQswCQYDVQQGEwJ1czEL

MAkGA1UECAwCVVMxGzAZBgNVBAoMElRob3VnaHQgSW5kdXN0cmllczEiMCAGA1UE

AwwZd3d3LnRob3VnaHRpbmR1c3RyaWVzLmNvbTAeFw0xNzA3MTIyMDEyNTBaFw0y

NzA3MTIyMDEyNTBaMFsxCzAJBgNVBAYTAnVzMQswCQYDVQQIDAJVUzEbMBkGA1UE

CgwSVGhvdWdodCBJbmR1c3RyaWVzMSIwIAYDVQQDDBl3d3cudGhvdWdodGluZHVz

dHJpZXMuY29tMIIBIzANBgkqhkiG9w0BAQEFAAOCARAAMIIBCwKCAQIArqB4whkc

URE1DhmsxwBUdY4epWE3KWl6kEmhdtDg1GJo0Bmkt5SU/1Yawja4YvxvR82hpcjk

o+bXJdo3T44Lwq9Y8NQA6DKSZ3duvvx50gUhD3y66ka0AmlayyGDegtHwjz7Px6Q

orRg5aEUMFGGnNZ0AA0+sW0skbfVZsJ+wV5EU8VsXmgqL8mhH8squWXZCOCY+/8M

KW7f1Lf7qBrERRLmVZpgQklx7v8/hxU8K9CMQJR95YG5rLYQjBm1oseaMZmYp2pK

5bKyJCuKiu7nF2eYSnxIAZZKA7Xw1gZRYvnOGguip0yvyHuZMCRmLdg8Fl6Yi4/h

5C1Z/asj1e459/ECAwEAAaNQME4wHQYDVR0OBBYEFNkdMQ/bCwVR0dtyrohqCtZ3

XhmTMB8GA1UdIwQYMBaAFNkdMQ/bCwVR0dtyrohqCtZ3XhmTMAwGA1UdEwQFMAMB

Af8wDQYJKoZIhvcNAQENBQADggECAD4J7tQHK/pkoO5KNrMz/K/rN36cCJ+AP6eK

2Y/WmtC/0WsRuw7DQSTXNLo6CDVi0N8drzF0X9TfpU9LKqIqMNJ8GahyRjNjjHGC

13ET39V/rKUIU4KgiP6MyB5Oqus0u49lpeEPBokUVegH+VLFSxUzWwvVQD9D4j1g

vgYRS9fWAcEihtYUdJyZlOpAQenIw4POrZozk528LEoAupRPjkR6JcqbjoVWeAn7

R+jis+59pbyZJTtmnJFVagyJmqwEE171yU86Eo4TpBmXXwN/fdJA3qr+UKPHgALH

Lfu/UBsugSE3wb5o7BUD1T1xqf1t7JKkuKMKjFxTJm13vC+C4yGc

-----END CERTIFICATE-----