HOME / GET STARTED /

About HarvardKey Authentication Services

Harvard University's enterprise authentication service is known as HarvardKey. The service is available for securing online applications that support University activities including administration, instruction, collaboration and research. To make a request to register an application with HarvardKey, submit this form. 

During the interactive authentication process, a user supplies their unique credential (HarvardKey login name and password) 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 use a second factor with their password through the two-step verification service that is integrated with HarvardKey.

HarvardKey authentication services are available for web applications with two standard protocols: CAS and SAML 2.0. Both of these protocols support single sign-on (SSO), relieving users of the need to enter their HarvardKey credential each time they access a different web application. Application owners can 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 SSO to simplify access for their users.

The HarvardKey system replaced the proprietary system (known as the PIN system) with the open-source Jasig Central Authentication Service (CAS) in 2015. However this replacement was 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 Identity Provider (IdP) for the SAML 2.0 protocol. The HarvardKey IdP is integrated with the InCommon Federation. Both protocols are integrated to provide seamless single sign-on for HarvardKey users, regardless of which protocol is being used. The PIN2 protocol is still supported for a small set of legacy applications; however, the protocol has been deprecated. 

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 either the CAS or SAML 2.0 protocol. Applicationsare 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 or the University Active Directory. 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.

It is important to 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 affiliation. This continuation is in place so that applications can implement authorization rules aligning with their policies. Some applications continue to allow access after the user's actual end date for active affiliation.

Implementing authorization for a HarvardKey protected application can be done in a variety of ways (in either protocol):

  • Attributes about the authenticated user are eligible to be sent as part of the authentication response  in a process called assertion. The application can then use these attributes to decide about access. 
    • 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 enterprise Group Service (Grouper). Access to query for 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 a specified group. 
    • Authorization filter design typically involves a consultation with an IAM specialist and may also 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 2.0 are suitable for your application. If that is the case, the determining factors will include the environment of your application (operating system, web server, application server, etc.), software frameworks, and the programming language that your app uses.

For example:

SAML 2.0 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.

Please get in touch with the IAM team if you have further questions via mailto: iam@harvard.edu

 

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 iam_help@harvard.edu or submit a ServiceNow ticket under the subcategory of Authentication Services: Consulting.

Using SAML 2.0 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 iam_help@harvard.edu or submit a ServiceNow ticket under the subcategory of Authentication Services: Consulting.

Harvard Metadata

 

Source: Marlena Erdos and HUIT IAM Product Team