Conceptual Overview of McAuth and its Components
The function of McAuth is to allow authorized applications on any McMaster web server to authenticate access using a MacID and Password and to pass authorization information if applicable.
There are two components to McAuth:
- A request service consisting of a login interface which accepts MacID and Password from an authorized client application.
- A collection of scripts to be used by the client application to be able to handle and process the response.
How McAuth Works
In normal circumstances, when an authorized application sends a login request to the McAuth service and if the login interaction has completed successfully, McAuth will return a ‘yes’ or ‘no’ response and provide authorization information if the client application has permission to receive the authorization data (normally called Authz). This process can be broken down into the following steps:
- User Login: The visitor enters a MacID and Password into a login page presented by the client application (can be JS page or static HTML).
- Information Goes to the Mcauth service: The user presses submit and the MacID+Password+client-application-id (This last one should be a hidden form variable) are sent to the McAuth authentication service. This interaction must happen via SSL or ther server will not take it. This is required because the MacID and Password are supposed to travel on the wire encrypted.
- Client Application is checked: Only authorized applications can use McAuth. The request service looks for the passed application-id and then checks to see if the URL of the caller is associated to that id in the client-application database. If the id is found and the caller application is expected then the authentication process proceeds; if not, an “authentication denied” message is returned to the browser.
- MacID and Password is validated: The McAuth service passes the MacID and Password to the backend Authentication service and this in turn checks if the MacID and Password are correct.
- AuthenticationToken is generated: The McAuth service takes the response (‘yes’ or ‘no’) and creates a token using the format “server-tag:session-id:time-stamp:user-id:answer” (expanded details below). The token is then gzipped, then encrypted via the Triple DES protocol using the encryption key specific to the client application and then Hex encoded.
- Authorization Token is generated: If the partner application is supposed to receive authorization information, an authorization token (Authz) is also created using the format of key/value pairs resembling something like this: “referenceNo:123456789;fgivenameName:Mike;”. There are 6 types of Authz tables available:
- General Authz Data
- Employee Authz Data
- Student Authz Data
- Student Course Authz Data
- Student Program Authz Data
- Alumni Authz Flag
In the same fashion as the authentication portion, The Authz token is also gzipped, then encrypted via the Triple DES protocol using the encryption key specific to the client application and then Hex encoded.
- Token is passed [as a response] to client script: The encrypted token is appended to the response URL specified in the client-information database (generally the same script that generated the original login form). A redirect command is then returned to the browser so that it immediately calls the client script. This operation is visually obvious to the user – e.g. that a server/script other than the client application was involved. A typical URL seen by the user after the login is:
If there are multiple rows found in the Authz table it will look something like this after it is decrypted (the real token would much larger):
authz=(authz=key:value;etc:etc ! authzStCrs=key:value;key:value ! authzStPgm=key:value;key:value ! authzEm=key:value ! authzSt=key:value ! authzIsAlumni=key:value)
Be aware that if there are multiple rows of any data from the same Authz table, they will have the same name. eg:
authz=(authz=key:value;key:value ! authz=key:value;key:value ! authz=key:value;key:value)
Notice that all rows will appear appended with ” ! ”
- Client Application Proceeds: Having passed the appropriate tokens, the McAuth service is at this point is no longer involved. The client application then uses the McAuth library/scripts [or one written by the client developer] to decrypt the token to get the MacID and the ‘yes’ or ‘no’ response and also the Authz token. Keep in mind that the obtained token can be passed from call to call (i.e. from page to page), using it each time to determine who the user is and if the original MacID and Password matched for the purposes of the authorization within the client application.
What is Contained in the Authentication Token
All authentication tokens will use the following format:
- server-tag is a string containing the McAuth version number of the authentication script (later versions of McAuth might use this to make sure the client and server scripts are using compatible versions).
- session-id is a unique string which can be used by the client script to identify a session (the token itself can change from page to page of a client script because the time stamp can be updated). This string is generated from the time (in seconds) and the process of the authentication script.
- time-stamp is the time in seconds that the token is created and can be used by the client scripts to time-out a session. The client script can optionally update the time stamp each time the token is used.
- ip is the IP number of the browser from which the MacID and Password were originally received.
- user-id is the MacID (student/employee/alumni) typed in by the user.
- answer is ‘yes’ if the MacID and Password are correctly matched by the authentication process, ‘no’ otherwise.
Note that only the last two fields, “user-id” and “answer”, are used for the primary function, namely, basic authentication.
What is Contained in the Authorization Token
startDateCode:200509;dayEveningFlag:E;sectionCode:C02;termCode:1;courseTitleText:CARER PLN. EXP LRN; subjectText:SOC
Client-Application Database Records
Information about the client applications is stored on a special table which is read by the McAuth service in order to validate clients and to determine the address to which the responses should be sent.
|app_id_no||This value must be passed in by the calling script. It is the primary key for this table. Provided by UTS IT Security.|
|app_description_tx||This is a description of the application. Provided by client.|
|source_url_tx||The URL of the calling script, which will be checked by validateCaller().Provided by UTS IT Security.|
|encryption_key_tx||The string used as the encryption key. Must be known by destination script. Provided by UTS IT Security.|
|destination_yes_tx||The URL to redirect to if the authenticated succeeds. If blank, getDestinationYes() will use source_expected. URL parameters which contain information useful to the client script may be included, e.g. http://myserver.mcmaster.ca/cig-bin/myscript?page=1 – This is provided by client.|
|destination_no_tx||The URL to redirect to if the authenticated fails. If blank, getDestinationNo() will use destination_yes or source_expected. This is provided by client.|
|app_status_cd||Set to “active” to enable use by caller; set to “inactive” or “disabled” to shut down.|
|token_version_no||version of encryption. It could be: 3DES ECB with space padding or 3DES CBC with PKCS 5 padding.|
|authz_cdm||Authz flag for getting authz data for employees, students, or both.|
|authz_st_pgm_cd||Authz student program flag for getting authz_st_pgm data.|
|authz_st_crs_cd||Authz student course flag for getting authz_st_crs data.|
|authz_em||Authz employee flag for getting authz_em data.|
|authz_overdue_cd||Authz overdue flag for getting overdue info.|
|authz_st_pgm_br_cd||Authz student program barcode flag for getting barcode info.|
|client_ref_no||The reference number of the author/maintainer of the calling script.|
|uts_cont_ref_no||The reference number of the UTS staff member who is liason for the contact above.|
|authz_st||Authz student flag for getting authz_st data.|
|authz_alumni_cd||Authz alumni student flag for getting authz_alumni data.|