Skip to McMaster Navigation Skip to Site Navigation Skip to main content
McMaster Logo McMaster logo

McAuth Service

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:

  1. A request service consisting of a login interface which accepts MacID and Password from an authorized client application.
  2. 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:

    1. 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).
    2. 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.
    3. 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.
    4. 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.
    5. 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.
    6. 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:
      1. General Authz Data
      2. Employee Authz Data
      3. Student Authz Data
      4. Student Course Authz Data
      5. Student Program Authz Data
      6. 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.

  1. 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:

    http://myserver.mcmaster.ca/something.jsp&token=a52c1084c…..1b6a6a58bd5bf&authz=24b42hbh234b…..sf782r2hg

    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=sdf28390j83faf32234232j34520j52nlsnf982hn52ljknn0g8ifwj0h243n5kon234029inmg0wjnm2k34lnm5r20nmfw0jn235rn2
    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 ” ! ”

  2. 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:session-id:time-stamp:ip:user-id:answer

Where:

  • 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

 

  • authz

 

referenceNo:999999999;applicIdNo:9999999;applicTypeCode:ST;macIdNo:abcde;
aidActiveFlag:Y;aidDormantFlag:;aidPreactiveFlag:Y;surnameName:0162466-TESTSURNAME;
initialsName:G;fgivenameName:GIMMIAN;lgivenameName:;contactActiveFg:Y;overdueAcctFlag:N

 

  • authzStPgm

 

name=authzStPgm, value=referenceNo:999999999;studentNo:9999999;adminGroupCode:U;
startDateCode:200509;programCode:1273;levelCode:5;altProgramFlag:;programText:HEALTHST;
adminFacultyCode:12;adminFacultyText:SOC SCI;fullPartFlag:P;financialRegFlag:Y

 

  • authzStCrs

 

referenceNo:99999999;studentNo:9999999;adminGroupCode:U;subjectCode:525;courseCode:2EL0;
startDateCode:200509;dayEveningFlag:E;sectionCode:C02;termCode:1;courseTitleText:CARER PLN. EXP LRN; subjectText:SOC
SCI;labSectionCode:;tutSectionCode:;lecSectionCode:C02

 

  • authzEm

 

referenceNo:99999999;positionCd:;macDeptCd:;macDeptDescTx:;jobCode:;jobDescriptionTx:;
barcodeNo:;indvroletpCd:;emptpCd:;compGrpCd:

 

  • authzSt

 

referenceNo:000382555;barcodeNo:29005007555105;initStartDateCd:200105;residenceOffFg:N;
fullPartFlag:F;financialRegFlag:Y;overdueAcctFlag:N;unpaidAccountFg:N
authzIsAlumni
alumni:false

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.

Records
Field Description
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.