The Electude LMS allows external (web) applications to provide students and teachers direct access to the content. This simple SSO method is implemented with a single HTTP POST request from the user to the Electude LMS.
1. Administrator settings
First the administrator of the Electude LMS site has to allow external access. The settings are made via the main menu 'Settings' and the submenu 'External access'.
From the drop down list for 'Direct access' select 'Electude SSO v.2'
Then enter a strong key (passphrase) and confirm. The key should be kept secret and used to generate the HMAC specified in the section below.
2. Implementation
Key-value pairs should be send using the POST method as
'application/x-www-form-urlencoded' data. The data should be submitted
to the URL /launch relative to the Electude LMS site (e.g.
https://yoursite.electude.com/launch).
All characters should be encoded in UTF-8.
All keys are listed in the table below. The third column shows which are required. Other key-values are optional and may be omitted from the request.
| key | example value | required | format |
|---|---|---|---|
| account | student | "student" or "teacher" | |
| user | johndoe001 | yes | |
| firstname | John | yes | |
| surname | Doe | yes | |
| john.doe@example.com | yes | ||
| time | 2016-01-01T14:00:00+00:00 | yes | ISO 8601 date and time |
| hmac | d0071772.......ea9065a4f5 | yes | lowercase HMAC SHA256 |
| group | Group 1 | to create student account | |
| parentgroup | Groups 1-10 | ||
| phone | 0123456789 | ||
| mobile | 9876543210 | ||
| address | 321 Main Street | ||
| postalcode | 12345 | ||
| city | Anytown | ||
| region | NY | ISO 3166-2 (last part only) | |
| country | US | ISO 3166-1 alpha-2 | |
| birthdate | 2000-01-15 | ISO 8601 date | |
| birthplace | Birthtown | ||
| language | en-US | IETF language tag | |
| content | lesson_1000 | ||
| return | http://yoursite.com | HTTP URL | |
| browse | 0 | 0 (false) or 1 (true) | |
| profile | main teacher |
If a required value is omitted or if a non specified key-value pair is added, the user will get an 'Access denied' error.
2.1 Remarks on key-value pairs
account
This describes the type of user. The user can be a "student" or a "teacher". If no value is given then the account is "student" by default.
user
This is the unique username of the user. If the username does not exist, a new account is automatically created using the submitted key-value pairs.
Note that if the account already exists, the data associated with the account (e.g. first name and address) is not updated.
If an invalid email address is provided, the user will get an 'Access denied' error.
time
The value specified in the request may differ 1 hour from the current time, otherwise the user will get an 'Access denied' error.
hmac
The message to generate the HMAC consists of all submitted values (except
hmac itself) sorted alphabetically by key, separated by comma's.
Using the sample values from the table above, this is:
321 Main Street,2000-01-01,Birthtown,Anytown,lesson_1000,US,john.doe@example.com,John,Group 1,en-US,9876543210,0123456789,12345,NY,https://yoursite.com,Doe,2016-01-01T14:00:00+00:00,johndoe001
The HMAC is calculated using the SHA-256 algorithm with the key set by
the site administrator. If for example the string 'secret key' is
used, the resulting HMAC value is:
d007177231c9b30f0ebd84bd79b7955de845804377bbfcc10bd4cdea9065a4f5
group
This is the exact name of a group in the LMS. If a parentgroup is given, this field is required.
for students
If the student is not yet a member of this group, (s)he will be after the SSO request. All content assigned to the group will the accessible to the student. If the group does not exist yet, it is created. During the SSO session the student only has access to content of the specified group. If no group is specified, the student is not added to any group and the student can access all groups (s)he is already member of.
This field is required when the student account is created, as students have to be a group member to access content.
for teachers
If a group is specified, the teacher has only access to that group and its subgroups. If the group does not exist yet, it is created. If no group is specified, the teacher has access to all groups and subgroups, unless a group was specified during account creation.
parentgroup
This is the exact name of a group in the LMS. If a group (explained above) does not exist, it will be created inside this parentgroup. If no parentgroup is given, a new group will be created as a main group.
language
When no language is specified, the default language of the Electude LMS site is used. Supported IETF tags are:
| IETF tag | language |
|---|---|
| ar | العربية (Arabic) |
| bg | Български (Bulgarian) |
| bn | বাংলা (Bengali) |
| bs | Bosanski (Bosnian) |
| ca | Català |
| cs | Čeština (Czech) |
| da | Dansk |
| de | Deutsch |
| el | Ελληνικά (Greek) |
| en | English |
| en-US | American English |
| es | Español |
| es-419 | Español de America |
| et | Eesti (Estonian) |
| eu | Euskara (Basque) |
| fa | فارسی (Persian) |
| fi | Suomi (Finnish) |
| fr | Français |
| fr-CA | Français canadien |
| he | עברית (Hebrew) |
| hi | हिन्दी (Hindi) |
| hr | Hrvatski (Croatian) |
| hu | Magyar (Hungarian) |
| id | Bahasa Indonesia |
| it | Italiano |
| ja | 日本語 (Japanese) |
| ka | ქართული ენა (Georgian) |
| kk | Қазақша (Kazakh) |
| km | ភាសាខ្មែរ (Khmer) |
| ko | 한국어 (Korean) |
| lt | Lietuvių kalba (Lithuanian) |
| lv | Latviešu valoda (Latvian) |
| ms | Bahasa Melayu |
| my | မြန်မာဘာသာ (Burmese) |
| nl | Nederlands |
| no | Norsk |
| pl | Polski |
| pt | Português europeu |
| pt-BR | Português do Brasil |
| ro | Română |
| ru | Русский (Russian) |
| sk | Slovenčina (Slovak) |
| sl | Slovenščina (Slovenian) |
| sq | Shqip (Albanian) |
| sr | Српски (Serbian) |
| sv | Svenska |
| th | ไทย (Thai) |
| tr | Türkçe |
| uk | Українська мова (Ukrainian) |
| ur | اُردُو (Urdu) |
| vi | Tiếng Việt (Vietnamese) |
| zh | 简体中文 (Simplified Chinese) |
| zh-HK | 香港繁體 (Traditional Chinese Hongkong) |
| zh-TW | 台灣正體 (Traditional Chinese Taiwan) |
content
For teachers, this is a reference to any page accessible for the teacher.
For students, this is a reference to the desired content, e.g. 'lesson_50'.
Valid values are 'lesson_X' (for a single module) or 'bundle_X' (for
a series of modules arranged in a course). 'X' is a placeholder for
a numerical value.
This value corresponds with the last part of the URL the teacher sees in
the LMS. E.g. https://yoursite.electude.com/lesson_1000 is the
information page of the 'Combustion Leak Detector' module. A complete
and current list of modules can be downloaded in CSV format by the
teacher by selecting 'Modules' in the main menu, 'All / new' in the
submenu and clicking the 'all modules' link
(https://yoursite.electude.com/lessonall_1)
If content is specified, access for students is limited to that content only.
If no content is specified, all content assigned to the student is
shown instead. If a group was specified, the page with
content assigned to that group is shown.
Note that if the content is not available in the requested language the user will not see any the content.
return
The user is directed to this URL when (s)he leaves the Electude LMS.
browse
If this value is set to 1 (true) then the student can browse through the modules. Results of the student will not be stored.
profile
This is the exact name of the teacher profile to use. This value is only used when a new teacher is created.
3. Example request
An example request can be generated using the key-value pairs above by submitting this HTML form:
<form method="post" action="https://yoursite.electude.com/launch">
<input type="hidden" name="address" value="321 Main Street">
<input type="hidden" name="birthdate" value="2000-01-01">
<input type="hidden" name="birthplace" value="Birthtown">
<input type="hidden" name="city" value="Anytown">
<input type="hidden" name="content" value="lesson_1000">
<input type="hidden" name="country" value="US">
<input type="hidden" name="email" value="john.doe@example.com">
<input type="hidden" name="firstname" value="John">
<input type="hidden" name="group" value="Group 1">
<input type="hidden" name="language" value="en-US">
<input type="hidden" name="mobile" value="9876543210">
<input type="hidden" name="phone" value="0123456789">
<input type="hidden" name="postal" value="12345">
<input type="hidden" name="region" value="NY">
<input type="hidden" name="return" value="https://yoursite.com">
<input type="hidden" name="surname" value="Doe">
<input type="hidden" name="time" value="2016-01-01T14:00:00+00:00">
<input type="hidden" name="user" value="johndoe001">
<input type="hidden" name="hmac" value="d007177231c9b30f0ebd84bd79b7955de845804377bbfcc10bd4cdea9065a4f5">
<input type="submit" value="start">
</form>A minimal request can be generated using only the required key-value pairs:
<form method="post" action="https://yoursite.electude.com/launch">
<input type="hidden" name="email" value="john.doe@example.com">
<input type="hidden" name="firstname" value="John">
<input type="hidden" name="surname" value="Doe">
<input type="hidden" name="time" value="2016-01-01T14:00:00+00:00">
<input type="hidden" name="user" value="johndoe001">
<input type="hidden" name="hmac" value="15b009864180ca2085a30f805570bde434690d3247266340b789e996c3c13f43">
<input type="submit" value="start">
</form>To create an HTML page that automatically directs the user to the desired content without user interaction, the form could be submitted automatically using JavaScript on page load.
A working example form is here.