Single sign-on for LMS

SSO is used to authenticate the LMS connecting to the Diglib server

Requirements

  • Diglib requires the public certificate from the LMS to verify that the signature is valid. 
  • A signature based on all the transmitted parameters and their values.
  • A timestamp for the signature.

The Diglib SSO login url:
 http://www.Diglib.no/LoginSSOLMS.ashx

The Diglib SSO login urls for testing purposes;

To test interaction with Diglib, visit http://stable.Diglib.com/LoginSSOLMS.ashx

Parameters

The following parameters must be included in the query string. The parameters marked as Optional must be part of the query string, but can have an empty value. The Required parameters need a value.

In addition to these, there are some extra parameters that may be added to the query string, but these may be omitted altogether for the single sign-on to work correctly.

The Sequence of the required and optional parameters in the query string cannot be changed, and they are case-sensitive.

The correct sequence is as follows:

  1. SchoolLevel
  2. UserID
  3. LearningLocation
  4. SiteName
  5. CustomerID
  6. AccessLevel
  7. Email
  8. UserFirstName
  9. UserLastName
  10. UserLanguageID
  11. CountryCode
  12. AddUrl
  13. TimeFormat
  14. TimeZoneId
  15. FolderID
  16. CancelUrl
  17. DiglibConnector
  18. CourseID
  19. Debug
  20. GUID

Required

  • CustomerID
  • SiteName
  • UserID
  • AccessLevel
  • CountryCode
  • AddUrl
  • DiglibConnector
  • GUID

Optional

  • SchoolLevel
  • LearningLocation
  • UserFirstName
  • UserLastName
  • EmailUser
  • LanguageID
  • TimeFormat
  • TimeZoneId

Extra parameters

  • ChildSites

SchoolLevel (int)

The user’s education level. This parameter is used to redirect the user to the correct start page.

The different types are:

0 - Default (the user is redirected to the start page)
1 - Primary
2 - Secondary
3 - Higher
4 - Further

CustomerID (string)

This is a unique id for a Site for the LMS. This is used to identify a Site and is important for:

  • site agreements
  • licenses on resources

  • Statistics on Site level

UserID (int)

This is a UserId that has to be unique within the Site for the LMS. This is used to map the LMS user to the Diglib user.

LearningLocation (string)

The name of the learning location (within a site) for the user. Example: Askøy VGS (which is located in the Site "Hordaland Fylkeskommune").

SiteName (string)

The name of the user’s site. Example: "Hordaland Fylkeskommune".

AccessLevel (string)

Defines the role of the user. Valid AccessLevel values are:

  • Student
  • Teacher
  • Admin

Email (string)


The user’s e-mail address

UserFirstName (string)

The user’s first name

UserLastName (string)

The user’s last name

UserLanguageID (int)

The preferred language of the user. The available languages are:

0 – Norwegian
1 – English (UK)
3 – Swedish
4 – Dutch
9 – Danish
11 – French
12 – Italian
13 – English (US)

AddUrl (string)

This is the URL to which the user will be redirected when adding a package.

Example: www.lms.com/addpackage.php

TimeFormat (string)

Specifies the time format of the user. The different types are:

  • TwentyFourHour
  • TwelveHour

TimeZoneID (int)

The TimeZoneID defines where in the world the user is located

312 - Norway/Oslo

DiglibConnector (string)

An unique id for the LMS. Example: Blackboard. This string is supplied by Diglib to the VLE during the test-phase.

CourseID (int)

An integer id that represents a course to which the resource belongs

GUID (int)

The timestamp of the signature. It is derived from the seconds since the year 1970, month 01, day 01, hour 00, minutes 00, seconds 00 and must be UTC time.

ChildSites (string)

The ChildSites parameter is a list in JSON format like in the following example:

[{"Name":"Bergen Kommune","Type":1,"LegalId":"98034343","OrgId":"10","Country":"NO"},
{"Name":"Viken Skole","Type":2,"LegalId":"9334343443","OrgId":"11","Country":"NO"}]
It should be url encoded as well, so the example above will look like:
 […]&ChildSites= %5b%7b%22Name%22%3a%22Bergen+Kommune%22%2c%22Type%22%3a1%2c%22LegalId%22%3a%2298034343%22%2c%22OrgId%22%3a%2210%22%2c%22Country%22%3a%22NO%22%7d%2c%7b%22Name%22%3a%22Viken+Skole%22%2c%22Type%22%3a2%2c%22LegalId%22%3a%229334343443%22%2c%22OrgId%22%3a%2211%22%2c%22Country%22%3a%22NO%22%7d%5d

Name is a string that describes the school/faculty/other kind of organisation below a site level.

Type is an integer value from the following list:

1 - Site
2 - School
3 - Faculty
4 - University
5 - District

LegalId is the business number the organisation in question uses.

OrgId is the VLE’s internal Id of the organisation. This must be unique within a site.

Country is a two character country code for the organisation.

It is important to supply this parameter if the VLE needs to enable the usage of SiteLicenses that users have on different organisations (child sites) in addition to the site they log on with (for example, if a school within a county has as license but the county has not). Internally, Diglib provides the user with access to all the site licenses that are in both the parent site and in child sites.

The SSO URL

The above parameters are needed when building up the SSO redirect URL to Diglib. The process of how this is done is described here.

Requirements

The parameters must be in the same order as listed above.

The parameter values must be URL encoded (UTF8).

Timestamp (GUID)

Used to set a time period for how long the signature is valid. It's derived from the seconds since the year 1970, month 01, day 01, hour 00, minutes 00, seconds 00 and must be UTC time.

Timeout period for the signature is 35 seconds. If the login request takes more time, it will fail.

Code example of how the timestamp is constructed in .NET (C#):

DateTime t = DateTime.UtcNow;
DateTime REFERENCE_TIME =  new  DateTime( 1970,01,01,00,00,00,01, cultureInfo.Calendar );
TimeSpan dt = t - REFERENCE_TIME;
long totalSeconds = (long)dt.TotalSeconds;
string timestamp =  Convert.ToString(totalSeconds);

Signature (string)

The signature is generated based on the query string. All the parameters defined earlier must be included and in the same order. Example: SchoolLevel=1&UserID=123&.......

The format of the query string:

Parameter1={UrlEncode(value, UTF8)}&Parameter2={UrlEncode(value, UTF8)}&

Code example from .NET (C#) how the signature is constructed:

string querystring = "SchoolLevel=2&UserID=38&LearningLocation=Sandefjord+v.g.s.
&CustomerID=10&AccessLevel=teacher&Email=morten%40brudvik.com&UserFirstName=Morten
&UserLastName=Teacher&UserLanguageID=1&CountryCode=NO
&AddUrl=http%3a%2f%2flocalhost%2fcourse%2fcontent%2fAddContent.aspx
&TimeFormat=TwentyFourHour&TimeZoneId=1&FolderID=6464&DiglibConnector=itsl&CourseID=133&guid=1197895855";
     
byte[] msg = Encoding.UTF8.GetBytes(querystring);
    
RSACryptoServiceProvider rsaCSP = (RSACryptoServiceProvider)_certificate.Key;
      
byte[] signatureBytes = rsaCSP.SignHash(ComputeHash( msg ), OidHash );
      
string signature = Convert.ToBase64String(signatureBytes);
url = "http://www.Diglib.no/LoginSSOLMS.aspx?" + querystring + "&signature" + signature;

SSO redirect example URL

http://www.Diglib.no/loginssolms.ashx?SchoolLevel=2&UserID=38&LearningLocation=Sandefjord+v.g.s.&CustomerID=10&AccessLevel=teacher&Email=morten%40itslearning.com&UserFirstName=Morten&UserLastName=Teacher&UserLanguageID=1&AddUrl=http%3a%2f%2flocalhost%2fcourse%2fcontent%2fAddContent.aspx&TimeFormat=TwentyFourHour&TimeZoneId=1&DiglibConnector=itslearning&ResourceID=1254&GUID=1197895345&signature=PU0ng7Gt8Q4qwtgm%2f2e7VcpGwCkzMa4wlDN8fx3dTdhdhvjc5SoQKoh9doWPDet117aP9WQwOhGi6Z0TN9p075I2AT354%2fHPaFvWU5j5AHdPyYXsnxRaR74moZU4G4lvPV%2bBOcxY87o8t5BEvlwWatxc47NYGTjfZJW2hIU04II%3d