○ SSO - Workflow and troubleshooting
For the SSO process, you will need an API integration. When a learner wants to log in using SSO, you should start with the following API call:
GET /getLoginToken/{userID}
You will have to use the external ID or the UID of the user for this. For example:
Example of getLoginToken by external ID
GET http(s)://<domain>/api/getLoginToken/1234
Example of getLoginToken by UID
GET http(s)://<domain>/api/getLoginToken?userUID=c21f7c68-7682-11eb-b67e-06575dd7e8c5
The login token can only be used once, so make sure that learners are not redirected with the same login token more than once as this will result in an error for the learner. A good practice to prevent this, would be to request the login token after the learner clicks a link that should trigger SSO.
Only the most recent login token of a user is valid.
When you have retrieved the login token, you can start SSO by sending a redirect to the browser: http(s)://<domain>/do?action=sso
<domain> should be replaced with the domain of the learning environment.
You can add the following parameters (* is required):
- user*: This is the external ID of the user. It is only mandatory if userUID is not included.
- userUID*: This is the UID of the user. It is only mandatory if user is not included.
- token*: This is the login token that you retrieved from the API.
- course: By adding this parameter, you can automatically open the course overview of one of the courses that the learner is subscribed to, after logging in with SSO. You would need to use the external ID of the course.
This parameter cannot be combined with the redirect parameter. - activity: By adding this parameter, you can automatically open a specific activity of a course that the learner is subscribed to, after logging in with SSO. You would need to use the external ID of the activity. This only works if you also include the course parameter.
- redirect: By adding this parameter, you can automatically open a (relative) URL of the learning environment, after logging in with SSO. This can be used to redirect users to the right page after clicking a link in an email notification. (More information)
This parameter should not be combined with the course and activity parameters.
Example:
GET https://<domain>/do?action=sso&user=1234&token=24345226-ec3a-4d90-a5d0-aa99c80ec491
Example with parameters course and activity:
GET https://<domain>/do?action=sso&user=1234&token=24345226-ec3a-4d90-a5d0-aa99c80ec491&course=course01&activity=activity01
Example with parameter redirect:
GET https://<domain>/do?action=sso&user=1234&token=24345226-ec3a-4d90-a5d0-aa99c80ec491&redirect=%2Fdo%3Faction%3Dplayer%26type%3DLesson%26id%3D1234%26courseId%3D1234
Troubleshooting
These are common errors that your learners might experience if something goes wrong when trying to log in with SSO:
- Incorrect token
This error means that the login token is not the same as the most recently generated token for the user. A good practice would be to request the token shortly before SSO is going to happen and to not store old tokens. - Parameter 'token' is empty
This means that the login token is not present in the SSO URL. - User has no login token
This means that the most recently generated login token has already been used and that the integration first needs to request a new login token. A good practice would be to request the token shortly before SSO is going to happen. - User is not subscribed to course
This means that the user is not subscribed to the course that is being referred to in the SSO URL. This can be prevented by checking if the subscription exists with the API call /isSubscribed/{userID}/{courseID}. You can also use the API to subscribe the user to the course: /subscribe/{userID}/{courseID}