TOPYX SAML Service Provider Documentation

This guide outlines how to integrate TOPYX with your Single Sign On (SSO) infrastructure via SAML 2.0.

Overview

Single Sign On (SSO) via SAML lets you securely share user identity across systems. This means your users sign in only once through a single authentication system and they can access other systems in the organization without having to login again. Specifically, your users will be able to login into TOPYX without the need to create and use a separate user account for access. Your users, therefore, will not have to remember an additional username and password to login to TOPYX. Easing this friction means your users are mote likely to use TOPYX and get value from it.

SAML us a standard protocol that lets one central system, called the Identity Provider, securely assert and share user identities with other systems, called Service Providers. This means that a user only needs to authenticate once against this central system to access all the others.

TOPYX implements SAML according to the SAML v2.0 specification.

What TOPYX needs from you

There are a few things that TOPYX (or any SAML Service Provider) will need in to make SSO work:

The SAML SSO Service URL for your Identity Provider
An x509 certificate containing an RSA/DSA public key used to encrypt SAML communication
Logout URL for the SSO service
Time out URL for the SSO service

What you need from TOPYX

There are a few things you (or any Identity Provider) will need from TOPYX. This is what you need from us:

SAML Trusted Endpoint URL
Assertion Consumer Service (ACS) URL
SAML Certificate
Response format
Login URL
```
https://<your-org-name>.interactyx.com
```

ACS URL

https://<your-org-name>.interactyx.com/SAML/AssertionConsumerService.aspx

Response Format. The SAML response must provide identity information using the following ID format:
```
Urn:oasis:names:tc”SAML:2.0:nameid-format:persistent
```

Fields that can be sent via SAML

The following fields are required to create a user in TOPYX and therefore must be sent through SSO. Please note all fields must be sent without spaces and lowercase:

username (please note this must be unique for each user)
firstname (please note this can only contain letters)
lastname (please note this can only contain letters)
email

Optional User Fields

TOPYX accepts the following optional user fields. Please note all fields must be sent without spaces and lowercase:

organization
identification
jobtitle
usergroup
role
country (full name spelling is required – i.e. United States

User Groups
When adding user groups to SSO please be aware users will only belong to the groups specified in SSO. If a user is manually added to a group in TOPYX and this group is not contained within SSO they will be removed from the user group accessing TOPYX via SSO.

Roles
If role is not specified via SSO users will be assigned a learner role. If the field is specified, the user will be assigned to the roles specified. Users may have multiple roles including learner, manager, instructor, and administrator.

Optional Content Fields

TOPYX accepts the following optional fields via SSO for content. Please note all fields must be sent without spaces and lowercase:

cid
coursename
coursed
programname
programid

CID

The cid is the content ID of a material. If this field is specified, the login user will be registered to this material and directed to the player page playing the content that cid specified.

To obtain the content ID of a material, please go to Edit Basic Material Information for a material. You will see in the URL include cid=xxx, for example, cid=30DCF064-6F56-BE6E-5AE2CS5DC4DF.

Course Name

This is the course name. If this field is specified, the user will land directly on the course home page for the specified course. They will not be registered to this course.

Course ID
This is the course ID of a course. If this field is specified, the user will be registered to this course and redirected to the course material page.

To obtain the course ID of a course, please go to Edit Base Course Information for a Course, you will see in the URL courseid=xxx, for example, CourseId=203

Program Name
This is the program name. If this field is specified, the user will land directly on the program description page, they will not be registered to the program.

Program ID

This is the program ID of a program. If this fields is specified, the user will be registered to this program and redirected to the program home page.

To obtain the program ID of a program, please go to Edit Basic Program Information for a program. You will see in the URL programId=xxx, for example, programid=203

Please note: this workflow is for Service Provider SSO. For Identity Provider initiated SSO this process starts with the user logging in and the SAML response being sent to the ACS URL.

Common Pitfalls

The following is a short list of common pitfalls. Keep in mind this is not meant to cover all the problems you may encounter setting up SAML, but it may help you uncover some common mistakes when trying to integrate with TOPYX.

Running Locally
If you are running locally, there is no way to test against TOPYX. You need to set up a public URL for the login otherwise TOPYX will not be able to send a response.

Running HTTP

For security reasons, TOPYX only supports SSO from systems using HTTPS.

Inconsistent Usernames

Keep in mind that the usernames provided by your Identity Provider are saved in TOPYX. Each separate username will be considered a separate user to TOPYX. As such, it is recommended to avoid changing the values for the usernames provided. If you do change it, the user will not retain any of the settings of the old user and may collide/be rejected if they both use the same email address.