HOME / GET STARTED /

HarvardKey Application Integration

HarvardKey is Harvard University's enterprise authentication and authorization service. The integration service is available for securing online applications that support University activities including administration, instruction, collaboration and research.


Eligibility

To be eligible to integrate with HarvardKey a benefits-eligible employee of the University must sponsor the application. Applications developed, maintained, or owned by students must be sponsored by an administrative unit or academic department that agrees to assume technical ownership of the application upon the student’s departure from Harvard. 

The application must be under the management of Harvard University employees. For applications managed by contingent staff officially contracted by the University or acquired through a third-party with a reputable vendor the contract for the application must be reviewed and approved by the Strategic Procurement Office and/or the Office of the General Counsel.


Steps for Integration

  1. Assemble your Application Team 
  2. Review the HarvardKey Services, HarvardKey Integration Registration form and reference materials on this site and determine your preferred protocol, authorization method and what attributes, if any, you would like included in your authentication assertion.
  3. Submit the HarvardKey Application Integration form and other required materials
    • Note: If your application already has one or more environments registered with HarvardKey, you do not need to complete the registration form to request integration of another environment. Instead, follow the steps outlined in Registering a New Environment knowledge article.


1) Assemble an Application Integration Team

Application owners are responsible for providing technical resources to collaborate with the IAM team during the application integration process. Technical resources should:

  • Become familiar with authentication and authorization practices and CAS/SAML protocols
  • Have the necessary access to configure authentication on the application end
  • Understand attributes required by the application and determine the unique identifier
  • Answer questions required to finalize authentication design (e.g., whether the application can handle an encrypted token, does the application require a name ID)

If a vendor is handling the technical configuration of this integration, have them identify a technical representative who can provide the required information (SP metadata, entity IDs, endpoint URLs, etc.) needed for integration with HarvardKey. The IAM team is happy to meet with knowledgeable vendor technical representatives to facilitate the integration process.

Before requesting integration with HarvardKey Services, please make sure your procurement processes have been completed and a signed contract is in place. Check out Section V of the Strategic Procurement Manual (link opens in a new window) for more details. The Strategic Procurement Contracts team can provide further assistance and training as needed.


2) Review the HarvardKey Services, Integration Form and Reference Materials

Please read through this information before completing the registration form. Gaining an understanding of the concepts outlined here will help with the integration of your application with HarvardKey services.

Harvard IAM is part of the InCommon Federation (we are an InCommon IdP) so we can support users from other member institutions if you require them to be able to log into your application. More information is available on our website: https://iam.harvard.edu/resources/incommon.


HarvardKey Services

HarvardKey services include:

Authentication

Commonly called “logging in”, it’s the process of validating that someone accessing the service is who they say they are.

Authorization

Process confirming the credentials presented have an active affiliation that allows the user access to your application

Attribute Release

Process passing specific data about the user to be consumed by the application

Every HarvardKey-protected application will use both authentication and authorization. Attribute release is optional.


Authentication
Authentication is the first step towards enabling users to access an application. When a user attempts to log in to an application, Harvard Identity Provider (IdP) redirects the user to the HarvardKey sign-in page and verifies their credentials in the form of a unique username and password. It is important to note that authentication merely determines whether a user is the entity they claim to be when they attempt to log into an application; authorization (below) ensures that the individual has the appropriate affiliations.
 
Every application requires an authentication protocol to configure the authentication process. Guidance on choosing an authentication protocol can be found in the Selecting an Authentication Protocol knowledge article.

Authorization
An important concept for any application owner to recognize is that authentication credentials do not expire when affiliation with Harvard ends-- meaning, when someone leaves the University their HarvardKey will continue to function. Therefore, in order to protect your online resource, an application must both authenticate and authorize users. All applications using HarvardKey services must apply a generic or application-specific group authorization filter. Authorization through a group filter prevents users without an active affiliation (based on group membership) from logging into your application. In rare instances, authorization can be waived with a valid reason approved through IT Security. A list of generic authorization filters can be found in the HarvardKey Generic Authorization Filters knowledge article.

The authorization filters selected should match the application’s data and system risk levels. Complying ensures that the authorization approach adopted will be sufficient to protect both individuals and the University from material harm. 


Attribute Release 
HarvardKey can provide attributes to applications in the authentication assertion. The attributes available and the process for release varies based on the authentication protocol. This HarvardKey Authentication Available Attributes Table provides the complete list of the data elements that can be included in your authorization assertion.

Attributes to be released are reviewed and approved for every application. Harvard requests that you use Preferred Name attributes (not Official Name) to support our commitment to Diversity & Inclusion. We also will confirm how the attributes will be stored and used in your application. Privacy of Harvard user information must be ensured by complying with data privacy guiding principles, directory listing policy and FERPA requirements. 

We strongly recommend using NetID as a unique identifier.
 

HarvardKey Application Integration Form

Please review all parts of the HarvardKey Application Integration Form. 


Reference Materials

If you have any questions after reviewing these materials, the IAM team will work with you to get them resolved. 


3. Submit your New Registration with HarvardKey 

Please complete the HarvardKey Integration Registration form to start the process to integrate your application with HarvardKey Services. (Before filling in the PDF, right-click and select "Save Link As" or "Save Target As", then fill in the saved form.)

  • Before submitting the HarvardKey Integration Registration form, please make sure your procurement processes have been completed and a signed contract is in place. Check out Section V of the Strategic Procurement Manual for more details. The Strategic Procurement Contracts team can provide further assistance and training as needed.
  • If you are requesting integration using the SAML Authentication protocol, please generate and attach metadata when you send in your form.
  • If you are requesting to integrate a HUIT-supported application, you must include the Application CI for your application on the request form.
    • If the Application CI already exists, it can be found by searching for your application in ServiceNow under the HUIT config→ Application path.  
    • If it is a new application, you can request an Application CI in the IT Help Portal.


Timeline for New Registrations

Under most circumstances you can expect your request to integrate an application with HarvardKey to be completed within 10 business days after all required information has been provided to IAM including metadata for applications using SAML Authentication. HarvardKey Integration updates are typically performed on Tuesdays and Thursdays. If you have specific timing needs, for example, your application is going live on a specific date, the sooner you submit your request, the better.
 

Need help?

IAM hosts weekly Office Hours on Tuesdays from 1-2 pm to answer any questions related to Authentication and Authorization services including how to integrate with HarvardKey. Register for an upcoming session of IAM Authentication and Authorization Office Hours.