Skip to main content

SSO

  • Updated

TABLE OF CONTENTS

 

Scope and target audience

This document describes the technical details of integrating an organization’s user management system with GO! LMS  to enable Single Sign On (SSO). The GO! LMS  SSO functionality automatically creates or updates user information, from the organisation’s user management system, every time a user logs on with SSO.   

 

Prerequisites

Contact TicTac support to enable SSO for your portal. 

 

Definitions

Your portal - the customized GO! LMS  portal for your organisation. In the examples below it’s described as https://x.onlineacademy.se where x is to be substituted by your portal’s name.

 

SSO - SAML2

This section describes how to enable SAML2 SSO in your portal.

  1. Send your SAML2 Identity Provider metadata to the designated support person at TicTac. The metadata must contain:
    • entityId - URI
    • X509cert - Base64 encoded X509 certificate (may be self-signed)
    • singleSignOnUrl - URL
    • singleSignOutUrl - URL (optional)
  2. TicTac will create the SAML2 service and provide you with a serviceId.
  3. Navigate to your portal at  https://x.onlineacademy.se/sso/metadata/serviceId (serviceId is the serviceId returned to you in step 2 above). The link will provide you with the SAML2 Service Provider metadata XML to be installed in your Identity Provider.

User Id

The user id to be presented at your portal must be unique within your organisation. The uid may be:

  • Email (string) - a unique email address within your organisation.
  • UserId (string) - a unique id (ex: employee id) of the user within your organisation.

GO! LMS will automatically detect if the provided user id is an email or a user id.

Note: If the GO LMS REST API is being used in the integration together with SSO it is good to be aware that the same user id mentioned above will correspond to what is referred to as the username in the GO! LMS REST API documentation. So both API and SSO will handle unique management and login of users based on either email or user id (username).

 

User attributes

To fully take advantage of SSO the Identity Provider must map attributes for the user to be updated in your portal. Supported attributes are defined in Appendix 1.

 

The tag tree and how to use the groups attribute

It is important to understand the API id format and group tag names and how it connects to the users student tags. Below is a description how to use it in SSO and how it correlates to what you see in the admin UI inside the portal.

Internally the portal transforms tag names into unique ids under each tag tree that can be used to refer to the tag. In the groups attribute the tag tree id and the tag id are used in order to identify it. However, note that it is actually also possible to use the actual tag name in the group attribute field as well since the portal will transform the name into a format that only use a-z, 0-9 and '-'. All letters in the names will be transformed into this range and spaces will be replaced with '-'.

As a super admin you can see the value of apiid for a tag by checking 'show advanced settings' under the tags page in your portal.

If a tag id does not exist that is passed in the sso login it will be created in the root of the specified tag tree. The tag value will be used as tag name and then the name is transformed into a valid api id as well and stored in the portal. You can then at a later stage in the admin UI manually move it down into a sub node in the tag tree if needed. It will keep the api id even if it is moved.

 

Testing the installation

Navigate to your portal https://x.onlineacademy.se. Depending on your setup you will be automatically forwarded to the SSO Identity Provider or a link will be presented for you to be forwarded to the SSO Identity Provider. After having authenticated you should be automatically logged in.

 

SSO - Access URL with shared secret

Access URL based SSO is a non-standard GO! LMS solution to enable SSO. 

This section describes how to enable Access URL SSO in your portal.

  1. Send the following information to your designated support person at TicTac:
    • login Url - the URL that users should be forwarded to perform SSO (typically an URL to your intranet). 
    • Secret - One or more secrets (string) that should be used to authenticate the Access Url.
  2. TicTac will inform you when the Access Url service is installed and provide you with a serviceId for the SSO service.
  3. Navigate to your portal at  https://x.onlineacademy.se/sso/init/serviceId (serviceId is the serviceId returned to you in step 2 above) and you will automatically be forwarded to loginUrl given in step 1a above.

Implementation

The Access Url must be implemented since it’s based on dynamically generated URLs that are validated in your portal to perform SSO.

The access Urls format is: https://x.onlineacademy.se/sso/login/serviceId?data=DATA&sig=SIG.

The data implementation is a JSON encoded object with supported attributes defined in Appendix 1.

Additional required attribute is ‘timestamp’ (int). The timestamp attribute is required to define a validity time frame window for the access url. The timestamp is defined as seconds from epoch time (1st January, 1970 00:00:00 UTC).  AccessUrls are only valid ∓ 1 hour from the timestamp.

 

Pseudo code for creating DATA and SIG values 

A = jsonEncode(attributes);

SIG = base64Encode(HMAC(“sha256”,A,Secret);

DATA = base64Encode(A);

 

Testing the installation

Navigate to your portal https://x.onlineacademy.se. Depending on your setup you will be automatically forwarded to the SSO Identity Provider or a link will be presented for you to be forwarded to the SSO Identity Provider. After having authenticated you should be automatically logged in.

 

Implementation: example PHP

$attributes = [

“email” => “some.onesson@somedomain.com”,

“id” => “employeeId”,

“firstName” => “Some”,

“lastName” => “Onesson”,

“timestamp” => time(),

“groups” => “org:HR,org:Admins”

];




$json = json_encode($attributes);

$sig =  base64_encode(hash_hmac("sha256", $json, $secret));

$data = base64_encode($json);




$url = “https://x.onlineacademy.se/sso/login/serviceId?data={$data}&sig={$sig}”

 

Appendix 1 - SSO attributes

The following SSO attributes are supported by GO! LMS SSO. The user account, within GO! LMS, is synchronized/created with the attribute values each time a user has logged in via SSO. 

Attribute

Type

Required

Comment

id

String

If email is omitted.

User Id is unique for all users within your portal. Could as an example be used to model employee number or a username.

email

String

If id is omitted.

  

firstName

String

If fullName is omitted.

  

lastName

String

If fullName is omitted.

  

fullName

String

If firstName and lastName are omitted.

If the fullName attribute is used it is separated internally into firstName and lastName value by the first space separator. It is recommended to use first and last name instead if it is available in your system.

company

String

No

  

city

String

No

  

country

String

No

  

phone

String

No

The phone number shall be using the E.164 format. E.164 is a standard for the phone number structure used for international telecommunication. Phone numbers that follow this format can have a maximum of 15 digits, and they are preferably prefixed with the plus character (+) and the country code.


NOTE: country code is required if using SMS service in the portal.

language

String

No

Iso code of user’s language. Supported languages are ‘sv’, ‘dk’, ‘en’, ‘no’, ‘de’. If omitted the portal’s default language will be used.

groups

String

No

The group attribute is a comma separated list of the user’s student tags in format tagSetApiId:tagApiId1, .. , tagSetApiId:tagApiIdN

The tag groups govern which courses the user shall have access to.


Ex: org:production, role:team_leader


Api id:s for tags and tag sets can be edited in the Tags section in admin view of the portal when the “Show advanced settings” option is checked.


Please Note: Tagset and tagApiId must not contain ‘,’ or ‘:’ as it is used as separators of the groups string.

redirectUrl

String

No

Optional url if you want to direct the user to a specific GO!LMS page after they have successfully logged in.

 

Contact information

For technical questions please contact Development at TicTac Interactive AB.

Mail: tictac@tictacsupport.se

 



Related articles