Overview
CyberGrants supports several different methods to automate the login of client employees into the CyberGrants employee programs website. This document describes a general method of implementing Single Sign-On (SSO), in which a server within the client’s network is responsible for authenticating the user and passing the user information to CyberGrants, via GET or POST over HTTPS. Client employees not logging in via the SSO mechanism must register at CyberGrants with their employee identifiers and establish a CyberGrants password in order to log into the employee programs modules.
Parameters
CyberGrants requires the following information in order to successfully authenticate the user:
- Client Identifier
- Employee Identifier (e.g. employee ID, SSN, etc)
- Destination Program Type
- Session ID
- Current Time Stamp in GMT
- Cryptographic Initialization Vector
These pieces of information serve several specific purposes:
- Identify the user
- Determine the destination of the user in CyberGrants
- Bind the user’s session on the client’s site to the CyberGrants session
- Validate the identity
- Initialize the cryptographic algorithms
Client Identifier is a static value that CyberGrants assigns to each party upon implementation. This parameter is included in the CyberGrants URL and is not encrypted.
Employee Identifier is used to identify the user to CyberGrants. Users logging into CyberGrants via the SSO mechanism must already exist in the CyberGrants database. Typically a regular data feed from the client’s Human Resources department is used to ensure the validity and eligibility of the employee. This parameter is passed to CyberGrants encrypted and hex encoded.
Destination Program Type is used to identify the CyberGrants employee program type (e.g. Matching Gifts, Volunteerism, etc) that the user is trying to access. This parameter is optional; if unspecified, the user will be redirected to a page listing the available programs. If only one program is available, the user will be redirected directly into the appropriate program. This parameter is included in the CyberGrants URL and is not encrypted.
Session ID is established when the user attempts to log into any protected application via the client’s authentication mechanism (e.g. Netegrity SiteMinder). This unique session ID is used to provide an auditable link between the user’s session on the client site and on the CyberGrants site. This parameter is passed to CyberGrants encrypted and hex encoded.
Time Stamp is used to reduce the possibility for session reuse by establishing the beginning of a specific lifetime on the information passed to CyberGrants. The client’s server should compose a time stamp in Greenwich Mean Time from the current system time. This time stamp will have the format:
YYYY/MM/DD hh:mm:ss GMT
CyberGrants will compare this time stamp to its own system time to verify that the credentials contained in the request are still valid. Please note that both the client’s servers and CyberGrants servers must be synchronized against Internet based government and university time standards. This parameter is passed to CyberGrants encrypted and hex encoded.
Initialization Vector
Initialization Vector is used to initialize the encryption algorithm and to provide variance in output. This parameter is passed to CyberGrants unencrypted and hex encoded.
Encryption Algorithm
The client’s server should encrypt all data using the Triple DES or DES-EDE algorithm, in CBC (cipher block chaining) mode. Any incomplete cipher text blocks should be padded using the PKCS5 Padding algorithm.
The triple DES algorithm utilizes a variable 8 byte initialization vector (IV) to initialize the algorithm and to ensure variance in the cryptographic output regardless of input. The server performing the authentication should randomly generate an IV for each request and will pass it to CyberGrants as non-encrypted, hex encoded data.
Encryption Key
The client’s authentication server will encrypt using a randomly generated 192 bit binary key. This key should be encoded, preferably in hex or Base 64, and shared with CyberGrants via a secure channel prior to the implementation of the single sign-on mechanism on production.
Encoding Scheme
Because encrypting the user information results in binary data, the authentication server must encode the encrypted output in some URL compatible ASCII format. CyberGrants prefers that the binary data be hex encoded.
Error Conditions
If CyberGrants cannot decrypt the data received or if the timestamp provided exceeds the pre-determined allowable interval, CyberGrants will redirect the user to the client’s website to re-establish a valid session.
If CyberGrants cannot locate the record for the specified user, the user will be instructed to contact the appropriate person for assistance.
Example
Sample 192 bit binary test key (hex encoded):
3d19fe5d453d7991ecb92fe60762d5e55bef648f9e38df9b
Sample parameter names:
Non-specific parameter names are used to conceal the purpose of the individual parameters passed on the URL.
- erfx – Corresponds to the user’s employee identifier
- vbkh – Corresponds to the user’s session ID
- q9m1 – Corresponds to the current system GMT time stamp
- 3bna – Corresponds to the cryptographic initialization vector (IV)
Sample 8 bit invitation vector (hex encoded):
b8cb07faea3b8a4f
Sample Client Identifier (unencrypted):
1234
Sample Program Type Identifier (unencrypted):
1000
Assume that authentication server has authenticated the employee and is preparing to send that following information to CyberGrants:
- Employee ID: 123456789
- Session ID: 2LV5VvvZI+eON+b
- Time Stamp: 2004/01/01 01:23:34 GMT
The authentication server will encrypt the above three parameters and encode into hex:
- erfx (Employee ID): 495B6F5A56A7BE525BBBC01C79098DA8
- vbkh (Session ID): 586CF5EB479FF60D5B91FA43CB58C386
- q9m1 (Time Stamp): 0FD4A74FD8FB3193DE83C9790882A2C09E823EDB87883625
The authentication server will then redirect the user to the following URL:
https://www.cybergrants.com/servlet/LPortal/1234/1000? erfx=495B6F5A56A7BE525BBBC01C79098DA8&vbkh=586CF5EB479FF60D5B91FA43CB58C386&q9m1=0FD4A74FD8FB3193DE83C9790882A2C09E823EDB87883625&3bna=B8CB07FAEA3B8A4F
CyberGrants will then decrypt the information provided, and redirect the user to the appropriate area of the CyberGrants system.
References
Security Assertion Markup Language (SAML) v1.0
http://www.oasis-open.org/specs/index.php#samlv1.0
OpenSAML – an Open Source Security Assertion Markup Language Implementation
http://www.opensaml.org
OpenSAML CVS Java Source Code Repository
http://anoncvs.internet2.edu/cgi-bin/viewcvs.cgi/opensaml/java
Shibboleth – OpenSAML based Web Single Sign-On Implementation
http://shibboleth.internet2.edu
What else do you need help with?
Not what you're looking for? Navigate to Understanding User Login Account Configuration
