About Harvard's Authentication System

The Harvard authentication system, HarvardKey, is a service that authenticates users of online applications created by or affiliated with Harvard. The authentication process verifies users' identities in order to allow them to access applications; to do this, the user provides a unique login name and confirms that identity with the authentication service by sending the login name's correct password. The system then matches the username and password provided with data stored in a directory server, usually LDAP or Active Directory.

HarvardKey also offers application owners the option to participate in a University-wide single sign-on (SSO) service — relieving users of the need to enter usernames and passwords each time they access a different web application. Participation in the SSO service is determined by each application owner, and is not required by HUIT, but it can make the user's overall experience significantly easier.

When attempting to authenticate a user, a user agent — the application being accessed — and Harvard's authentication system communicate via a defined sequence of messages known as an authentication protocol. In 2013, the IAM program made significant enhancements to the authentication system to support a growing number of commonly used authentication protocols as well as improve the overall infrastructure. One of the most significant enhancements was to replace Harvard's proprietary system (PIN2) with the open-source Jasig Central Authentication Service (CAS), a more commonly accepted authentication protocol. IAM extended CAS to support all former PIN2 features, and migration to CAS was transparent to all PIN2 applications due to IAM implmenting a PIN2/CAS protocol bridge to act as a protocol adapter. This bridge supports the PIN2 protocol while leveraging CAS for authentication and single sign-on. In late 2013, HUIT deployed a Shibboleth-based IdP and integrated it with Harvard's authentication system, in the process adding support for the SAML protocol.

At present, authentication at Harvard supports the CAS and SAML protocols, though some applications using PIN2 also remain. These protocols seamlessly integrate into the single sign-on option provided by the enhanced Harvard authentication system. The diagram below displays the system's current state:

Authentication vs. Authorization

The Harvard authentication system provides user authentication, but not user authorization. This distinction is important. Authentication verifies that a user is who they say they are, but it cannot confirm whether or not the user should have access to a particular application. After authentication comes authorization — the process determining whether the user is actually granted access to areas within an application.

Implementing authorization for an application can be done in a variety of ways, and the authentication protocol being used can also dictate the choice of authorization method. Here are the details:

  • Authorization can rest entirely within the local application, just relying on the given identifier. This approach is an option with all authentication protocols offered.

  • After authentication, an application can query for user attributes from different available sources — including HU-LDAP — and those attributes can be used to make an access decision. This approach is also an option with all authentication protocols offered.

  • Attributes about an authenticated user can be released as part of the authentication response in a process called assertion. The application can then use these attributes to make a decision about access. Assertion can be used with both the CAS and SAML authentication protocols.

Choosing an Authentication Protocol

So which protocol is the best choice for your application? See below for a flowchart and protocol comparison chart that may help you make a decision.

General notes Most suitable for applications used exclusively by Harvard users. We strongly recommend not using PIN2 in new applications. CAS offers a simpler alternative, since it does not involve cryptography operations. If it is truly necessary for you to use PIN2, please contact Provides a good fit for internal user applications if the app is from an SaaS vendor or is an out-of-the-box product/tool/framework that supports SAML.
Federation support No. No. Supports InCommon identity federation. If a future need for external users may arise, use this protocol.
Support for all HarvardKey login types All. All. All except XID.
Authentication response to application Username, login type, and attributes. PIN2 token containing username and login type. eduPersonPrincipalName (or uid in some cases) and attributes of the authenticated user. (Note that these are attributes/opaque identifiers specifically associated with the SAML protocol.)
Environment and tools support A large number of open-source libraries available for almost all commonly used environments and languages. IAM provides libraries and sample configuration for most common environments used at Harvard. Usually installed as web server module and a daemon process independent of application.
Configuration Very simple. No cryptography work involved. Cryptography work involved. Application must validate the signed token. SAML Service Provider (SP) configuration is more involved.
Supported Version CAS 1.0 and 2.0. PIN token version 1 and 2. SAML 2.0.
Authorization None. Coarse-grained centralized authorization service is available. None.
Attribute Release Releases attributes to facilitate authorization in application. Releases attributes to facilitate authorization in application. Releases attributes to facilitate authorization in application.

After you've reviewed this information, you may find that both CAS and SAML are suitable for your application. If that's the case, the determining factors will include the environment (operating system, web server, application server, etc.), software frameworks, and programming language that your app uses — for example, SAML integration involves installing a service provider (SP) software package that sits inside your web server, isolated from the application. This package delivers authentication and attribute information to the application using the web server’s environment variable or custom HTTP headers. On the other hand, CAS offers additional integration options via software packages known as CAS clients; these can provide SAML SP-like integration options, APIs, or libraries for integration that can be used directly within your application.

Need more information to help you make a decision? Click below for additional details on how each protocol works.

Using CAS as Your Protocol

The Central Authentication Service (CAS) protocol, originally developed at Yale University and currently developed and maintained by the Jasig consortium, uses a simple but robust authentication protocol that is widely deployed in higher education.

How CAS Works

  1. When a user accesses a CAS-enabled application by typing in a URL or clicking a link in their browser, the application redirects the user's browser to the CAS authentication system, passing along the target application's URL (which has been previously registered with the authentication system).

  2. CAS validates that the authentication request came from a legitimate application, and then prompts the user for username and password.

  3. If the username/password pair are recognized, CAS redirects the user's browser back to the application, attaches a unique ticket number to the redirect URL, and saves a cookie in the user’s browser. The unique ticket is good only for one use, and is valid for a short period of time. The cookie also contains the information needed to identify the user to CAS for any subsequent authentication requests from other applications.

  4. The application receives the ticket and sends it to CAS over a direct, secure SSL connection without involving the browser for validation. This process is sometimes referred to as "backdoor ticket validation."

  5. CAS validates the ticket and, if valid, sends the application the username (and possibly other attributes) in a validation response.

  6. Finally, the application provides access to the user.

Is CAS Right For Your Application?

If your application will be accessed only by internal Harvard users, then we recommend using CAS. The application receives user identity information securely without having to perform any cryptographic operations, keeping implementation lean and simple.

Configuring Your Application

While CAS is a simple protocol, and it is certainly possible to write code integrating an application with a CAS-based authentication system, the Jasig CAS community also offers a wide variety of pre-built, well-tested and well-documented "CAS clients" — "client" meaning the layer of software that sits within an application and interacts with the authentication system. No matter what integration method you choose, more information on setting up your app to work with the Harvard authentication system is available at our How-To Guide for CAS Integration.

If you need additional assistance, please email or submit a ServiceNow ticket under the subcategory of Authentication Services: Consulting.

Using SAML as Your Protocol

The Security Assertion Markup Language (SAML), originally developed by the OASIS Security Services Technical Committee, is an XML-based framework for communicating user authentication and attribute information. Harvard's authentication system supports version 2.0 of the SAML protocol, which specifies an information exchange sequence and formatting among the following roles: an Identity Provider (IdP), a Service Provider (SP), and a user on a web browser.

How SAML Works

  1. When a user connects to an application by typing in a URL or clicking a link in their browser, the application redirects the user's browser to the Harvard IdP.

  2. In Harvard's implementation, the IdP then redirects the user's browser to the CAS authentication system.

  3. CAS prompts the user for their username and password.  

  4. If the user supplies a valid username/password pair, CAS redirects the user's browser back to the IdP, sending along the user's identity.

  5. The IdP looks up attributes about the user that may be helpful to the application's access control decision, filtering these attributes in order to allow only the transmission of the attributes that the application is configured to receive. The IdP then sends a digitally signed package containing the attributes and identity information — called an assertion — back to the application. (To learn more about the standard list of attributes that can be provided, please contact us.)

  6. Finally, the SP "consumes" this assertion and, if it is valid, allows the user access to the application.

At first glance, this process may seem complicated — but in action, the SP typically does most of the work. The SP is implemented as a web server module located in front of your application, and most of the implementation work consists of deploying the SP and configuring it to send attributes to your app in the way that is easiest for the application to consume. Applications will typically access these attributes as environment variables or, in some cases, as request headers.

IAM recommends using the Shibboleth SP with your application. Shibboleth is a technical package based on SAML 2.0, and it works with the InCommon identity federation, making it the best choice of method if your application needs to accept users from outside Harvard.

Is SAML Right For You?

If you are interested in accepting users from outside Harvard, SAML may be the best choice. Using SAML, an application, with the help of the SP, accepts authentication assertions from the user’s IdP. The SP trusts assertions from many IdPs. Similarly, an IdP may provide assertions to multiple SPs. SAML provides the specifications to build cross-institution or cross-domain authentication through access control infrastructures known as "identity federations." Applications can join an identity federation such as InCommon using the SAML protocol, making it easier to allow access to users from other institutions that are also part of InCommon.

SAML may also be a good choice if you're using a Software as a Service (SaaS) solution from an outside vendor, since many of these — as well as many other out-of-the-box frameworks and products — support SAML for authentication.

Configuring Your Application

More detailed information on integrating your app with SAML is available in our How-To Guide for SAML/Shibboleth Integration. If you need additional assistance, please email or submit a ServiceNow ticket under the subcategory of Authentication Services: Consulting.

Source: Marlena Erdos