Shared Authentication Interface

Background

In general, EBS's systems requires each user to be authenticated before providing access. This is almost always done with login credentials such as a user id and a password.

Often, this is redundant because the user may already be logged into a system at the client's site. Shared authentication enables the client to authenticate a user in their system, and securely pass EBS some credentials that enable us to identity the users. The advantage to the user is they get to bypass the initial login page, making the two systems (yours and EBS's) appear 'seamless'.

EBS supports shared authentication via an MD5 hashing scheme. Other hash and encryption methods may be available, but this document assumes MD5.

Shared authentication shifts the login responsibility to the client's authentication system. All other security measures (encryption, access permissions, data availability, etc.) are still enforced from the EBS site.

Considerations

  • Access to systems with any personal or confidential information require 128-bit SSL connections (https). Unencrypted (http) and low-bit connections (e.g., 40/56-bit) will not be permitted for any reason. Any references in this document that refer to http are understood to imply https.
  • Communication between client and EBS is accomplished via a secure HTTP form 'post'.
  • Both server's clocks must be synchronized to the NIST time servers. This will prevent hash errors due to time differences. Be aware of the DST changes in 2007. If you are using a windows machine, consult the Microsoft article: at http://support.microsoft.com/kb/914387.

Process

Below is the process flow for sharing authentication credentials.

Client Steps

  1. Assemble the hash key (see table 1).
    1. Prefix and suffix are literals assigned by EBS.
    2. The Account identifier portion of the key must be the same value used in the html form's password field (see table 2).
    3. Day of the month is the 2-digit day number of the current date (yyyymmdd).
    4. Time (hours/minutes) is the current time in military format (e.g., 2359). This must be represented in eastern time.
  2. Pass the hash key to your MD5 routine which will return a hash digest.
  3. Convert the binary hash digest to a hex string (2-character value for each byte). The result will be a 32-byte string (16-byte digest, hex representation of two-characters per byte).
  4. The password form field must contain the hex version of the hash digest.
  5. Submit the form from the user's browser (see Table 2, the onload statement in the body tag).

EBS Steps

  1. Convert the hex representation of the hash digest to binary
  2. Assemble the hash key, same as step 1 above.
  3. Create the hash digest, same as step 2 above.
  4. Compare the two hash digests. If the same, authentication is accepted (continue step 11).
  5. Subtract 1 from the minute in the hash key. repeat steps 8 through 9. This step is performed only once. If the match fails a second time, present a "Failed Login" page and exit.
  6. Emulate the existing login process (via a special forced-login function) to establish an EBS session.

At this point, the user is logged into the EBS system, as if they manually typed their login credentials. Once the session is established, there is no difference between the two types of users.

Table 1 - Hash Key Composition

The hash key consists of a 32-byte field, constructed as follows.

  • Prefix: four character prefix assigned by EBS
  • Account Identifier: 18 byte
  • Day: 2 digits, day of the month
  • Hour: 2 digits, 0-24 (military time), eastern time zone
  • Minutes: 2 digits
  • Suffix: four character suffix assigned by EBS

Notes:

  1. Prefix and suffix are assigned by EBS. The value consist of a combination of upper-case letters, lower-case letters, numbers, and special characters. The value you use must match exactly to the value we assigned.
  2. Account identifier must match the primary identifier that EBS and client have agreed upon. This primary id uniquely identifies a user and is usually a SID, SSN, Account Number/Code, etc. Alternate identifiers may not be used for authentication.
  3. Numeric Acount Identifier composition. EBS considers the Account Identifier as an alpha-numeric field, up to 18 characters in length. If your identifier is numeric and less than 18 characters, there are special formatting rules that are noted here. If you want to use a nine-digit ID, the format of the Account ID is 9-digits, followed by nine spaces. The 9-digits you reserve as the Account ID can be formatted according to your rules. Examples of your rules are:
    1. right-justified, zero-filled to the left;
    2. right-justified, space-filled to the left;
    3. left-justified, space filled to the right.
    You can select any format, but all references must be consistent E.g., if you pick 9-digits, left-justified, all references in the system including all interface files must refer to the account id as a 9-digit left-justified field.

Table 2 - Hash Key Example

Assuming the following:

  • Client = XYZ
  • Prefix = pppp
  • Suffix = ssss
  • Primary ID = 111223333
  • Date = 1/22/2009
  • Time = 5:03 pm (eastern)

Then the buffer passed to the hash routine would be (NOTE: periods imply spaces):

		pppp111223333.........221703ssss

The hash output of the sample string above is:

		d0d7208582d282aef75924efc30b7b21

Table 3 - Sample HTML Form

		<body onload="document.form01.submit()">
		<form name="form01" method=POST action="https://www.ecsi.net/cgi-bin/webt.exe">
		<input type="hidden" name="formid" value="webx001h">
		<input type="hidden" name="client" value="XYZ">
		<input type="hidden" name="user" value="111223333">
		<input type="hidden" name="password" value="d0d7208582d282aef75924efc30b7b21">
		<input type="hidden" name="action" value="LogIn">
		</form>
		<noscript>If you see this message, your browser is not configured to use Javascript.
		Javascript must be enabled in order to use this web site.</noscript>

Notes:

  1. The form action is either webt.exe for the WebX test system or webx.exe for WebX production, bcgin1.exe for borrower test system, bcgi.exe for borrower production system. Other systems require EBS approval.
  2. The formid value will be assigned.
  3. The client value will be assigned by EBS and must match exactly (including case)
  4. The user value is the Account Identifier. This is the 2nd component of the auth token (see Table 1 and 2)
  5. The password value is the calculated hash value.