About HarvardKey Authentication Services

Harvard University's enterprise level authentication service is known as HarvardKey. The service is available to University IT service providers for securing online applications that support University activities including administration, instruction, collaboration and research.

During the interactive authentication process, a user supplies a unique login name (HarvardKey) in order to access online resources. Users create and manage their HarvardKey credential using the HarvardKey self-service application. All faculty, staff, student and non-employee affiliate users are required by information security policy to add a second factor to their password through the two-step verification service that is integrated with HarvardKey.

HarvardKey authentication services are available for web applications in two protocol standards: CAS and SAML 2.0. Both of these protocols support 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. Application owners decide whether to allow single sign-on to their applications. Unless there are security reasons to force a direct login, applications will typically take advantage of this auto-login to simplify access by eliminating the need to input the password as often.

HarvardKey system replaced the proprietary system (known as the PIN system) with the open-source Jasig Central Authentication Service (CAS) extended with a PIN2/CAS protocol bridge which acts as a protocol adapter. This bridge supports the legacy PIN2 protocol while leveraging CAS for authentication and single sign-on. There is also an option to integrate with a Shibboleth-based IdP for the SAML protocol. The IdP is integrated with the InCommon Federation. All protocols are integrated to provide a seamless single sign-on experience for HarvardKey users, regardless of which protocol specific applications are using. At this writing, the PIN2 protocol is still supported for a small set of existing applications; however, the protocol will be discontinued soon. Many applications have migrated to CAS or SAML to take advantage of additional authorization services that are only available with these two protocols.

The diagram below displays the system's current state:


Types of protocols for HarvardKey Authentication


HarvardKey Authentication using LDAP or AD

By policy, web applications that integrate with HarvardKey must use the CAS or SAML protocol and are prohibited from handling the user credentials directly. However, applications that require direct integration with a directory (v3 LDAP protocol) may request evaluation for integration with HarvardKey credentials using the HarvardKey LDAP instance or the University Active Directory instance. Security requirements pertain.

Authentication vs. Authorization

Authentication services provide 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 the user should have access to a particular application.

After authentication comes authorization — the process determining whether the user is granted access to areas within an application.

Note that simply authenticating a user with HarvardKey does not provide appropriate authorization for University-managed applications and services. The HarvardKey credential does not expire at the end of an individual user’s active/current affiliation. This is done so that applications can implement authorization policies that align with their policies which sometimes allow access after the affiliation end date.

Implementing authorization for a HarvardKey protected application can be done in a variety of ways:

  • Attributes about the authenticated user are eligible to be released as part of the authentication response in a process called assertion. The application can then use these attributes to decide about access.
    • Assertion can be used with both the CAS and SAML authentication protocols. Access to attributes is subject to an approval process.
    • The most commonly used attribute for authorization is group membership expressed as the ‘IsMemberOf’ attribute.
  • Alternatively, an application can query for user attributes from an attribute repository such as LDAP or the Group Service. Access to attributes is subject to an approval process.
  • An authorization filter can be applied using an application authorization group to filter the authentication response based on whether the user is a member of the specified group.
    • Authorization filtering can be used with both CAS and SAML protocols
    • Authorization filter design typically involves a consultation with an IAM specialist and may be subject to an approval process.
  • If necessary, authorization may be delegated entirely to the local application. The authentication response from HarvardKey will convey a unique user identifier which must be mapped to application-specific permissions that are in the exclusive control of the relying application.
Determining Which Protocol to Use

You may find that both CAS and SAML are suitable for your application. If that is 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.

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.


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.

  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 and HUIT IAM Product Team