Skip to main content

Authentication

Authentication object example

{
"School": "03014",
"UserName": "Jsmith",
"Password": "Password1",
"LissVersion": 10002,
"UserAgent": "Edval"
}

All calls except liss.hello will begin with an "authentication object".

An authentication object is a struct with the following fields:

FieldTypeNotesExample
Schoolstring mandatoryIf you are an Australian school, then this is the DEEWR school number of the school. If you are an Irish school, then this is the 5-digit Department of Education school number. If you wish to use an alternative identification system for schools, then you can if negotiated between the client and server organisations. A single connection can theoretically send/receive data for multiple schools, but only one school for each XmlRpc call.03014
UserNamestring mandatoryThe username of the person running the client program. Usually this is someone in an administrator role...it’s not envisaged that (username, password) pairs will be issued to all staff in a school. The SIS can link the username and password to LDAP or alternatives, or not, as they think best.Jsmith
Passwordstring mandatoryA password, in plaintext. There was some discussion about whether we should require the password be SHA-256 hashed, with or without a salt. The consensus was that (a) this is unnecessary when LISS is used over HTTPS; (b) most sites will be using HTTPS and our recommendation is HTTPS; (c) when LISS is used over HTTP, this hashing would provide not much more than a false sense of security because an eavesdropper can use the hashed password to effect changes.Password1
LissVersioninteger mandatoryThe LISS protocol version used by the client. For example, LISS version 1.0 (i.e. this version) will be 10000, and LISS version 1.23.2 will be 12302.10000
UserAgentstring mandatoryThe name of the satellite software system, e.g. “Edval”.Edval

If the version number of the client and server do not match, then the server should try to complete the RPC call notwithstanding. All versions of the LISS protocol are designed with forwards and backwards compatibility in mind, so most enhancements will be in the form of additional fields (which can be ignored by either system) or additional functions. If a client is calling a function which has been newly added to LISS, and the server does not recognise this function, then an error will be returned by the server. In some cases the server might want to use the LissVersion to decide what to send the client.

It is the server’s responsibility to decide what data the client has permission to receive when sending its responses, and likewise the client must decide what data it will send to the server. ACL’s (access control lists) are the responsibility of each system.