Single Sign-on

• Introduction
• Administrator settings
• Automatic login
• Direct access to a module
• Adding accounts automatically
• Overriding the default language
• Live example

Argo allows external (web) applications to provide students direct access to the content. To do this, the external application should send the user name of the student, the desired content and a special time dependent access code to the Argo site. In this document example.electude.com is used as the sample Argo site.

The administrator of the site has to allow external access explicitly and enter a key (phrase). This key should be kept secret and is used to generate the access codes. This step is described in the section Administrator settings.

When a site allows direct access, Argo SSO can be implemented with a single HTTP request using the POST method. All data should be encoded in UTF-8. The fields in the data that are required, are described in the section Automatic login. Optional fields are described in the subsequent sections.

All settings are made via the main menu 'Settings' and the submenu 'External access' by the Argo administrator:

• Direct access: select 'Argo SSO'
• Key: enter a text, as an example in this document: 'G#037dk1fa323'
  You can use this code to test the live sample. Important note: do not use this key in a production environment.
• New students: select 'Not allowed' or, when automatic creation of new accounts is desired, select the name of the group the new student account should become members of.
  For more information see the section Adding accounts automatically.

To login automatically data (UTF-8 encode) should be send through the POST method to http://example.electude.com/launch. These fields are required:

• content
  This field contains 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 Argo. E.g. http://example.electude.com/lesson_50 is the information page of 'Kirchhoff's first law'.
  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 (http://example.electude.com/lessonall_1).
• name
  User name of the student, e.g. 'john'.
  This user name is unique for every Argo site.
• check
  This is the access code formed by the SHA1 hash of this string: "name content date domain key".
  The fields in the string are separated by a whitespace character (ASCII 32). These additional fields are used:
  
  • date
    The current date formatted as 'YYYYMMDD', e.g.: '20080923'
  • domain
    The name of the host to which the data are posted, e.g.: 'example.electude.com'.
  • key
    The key entered by the administrator: 'G#037dk1fa323'

  The access code should be the SHA1 hash of this string:

  john lesson_50 20080923 example.electude.com G#037dk1fa323

  This is:

  04f6ba6f9226156176e552670b6a20aafabb9eb5

This HTML form generates the sample request:

<form method="post" action="http://example.electude.com/launch" />
<input type="hidden" name="name" value="john" />
<input type="hidden" name="content" value="lesson_50" />
<input type="hidden" name="check" value="04f6ba6f9226156176e552670b6a20aafabb9eb5" />
<input type="submit" value="start" />
</form>

The form above logs the student automatically in to his personal Argo environment. Optionally you can hide the environment and directly launch the module by adding an extra field:

• direct
  When this field contains the value 1 and the requested content is a module, the module will be launched directly.
  This field is ignored when the requested content is not a module.

This HTML form generates the sample request:

<form method="post" action="http://example.electude.com/launch" />
<input type="hidden" name="name" value="john" />
<input type="hidden" name="content" value="lesson_50" />
<input type="hidden" name="check" value="04f6ba6f9226156176e552670b6a20aafabb9eb5" />
<input type="hidden" name="direct" value="1" />
<input type="submit" value="start" />
</form>

The procedure specified above, assumes the student account already exists.

The administrator of the Argo site can set the automatic creation of accounts. To do this, a group has to be defined where the new student accounts will be added.

When the administrator allows automatic creation of new accounts, extra fields have to be defined:

• firstname
  This field contains the first name of the student.
• surname
  This field contains the surname of the student.
• email
  This field contains the valid email address of the student.

This sample HTML form ensures a new account is created if the account does not exist yet:

<form method="post" action="http://example.electude.com/launch" />
<input type="hidden" name="name" value="john" />
<input type="hidden" name="firstname" value="John" />
<input type="hidden" name="surname" value="Doe" />
<input type="hidden" name="email" value="john@doe.com" />
<input type="hidden" name="content" value="lesson_50" />
<input type="hidden" name="check" value="04f6ba6f9226156176e552670b6a20aafabb9eb5" />
<input type="submit" value="start" />
</form>

If the account does not exist yet, the student is asked to enter a password. If the account does exist, nothing is done with the extra fields: e.g. you cannot change an email address of an existing account in Argo this way.

To suppress a password is asked when the account is created, an extra field can be added:

• nopassword
  This field should contain the value '1'.

<input type="hidden" name="nopassword" value="1" />

The student can select the language by himself. When the student account was created automatically, the default language of the site is used.

By adding an extra field, the default selected language will be ignored:

• language
  This field contains the two letter ISO 639 code of a language. Use 'us' for American English.

This HTML form generates the sample request:

<form method="post" action="http://example.electude.com/launch" />
<input type="hidden" name="name" value="john" />
<input type="hidden" name="content" value="lesson_50" />
<input type="hidden" name="check" value="04f6ba6f9226156176e552670b6a20aafabb9eb5" />
<input type="hidden" name="language" value="us" />
<input type="submit" value="start" />
</form>

A working example form can be requested on http://example.electude.com/sso_example.php (use your own domain instead of example.electude.com). In the sample the access code is generated for your domain and the current date. The other fields of the sample contain the values, like username and key, as used in this document.