#  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.



 

 

 

 ##  

  expand\_more  

 
  

 

## Who can Integrate

To be eligible to integrate with HarvardKey:

- The application must be sponsored by a benefits-eligible employee of Harvard University and their associated administrative unit or academic department.
- Applications developed, maintained, or owned by students must be sponsored by an administrative unit or academic department that agrees to assume technical ownership when the student leaves Harvard.
- Applications must be managed by Harvard employees or contractors under approved vendor agreements. Contracts should be reviewed by the [Contract Management Office](https://internal.procurement.harvard.edu/contracts), a local Harvard procurement team, and/or the [Office of the General Counsel](https://ogc.harvard.edu/).

Please review the [HarvardKey Application Integration Policy](https://www.huit.harvard.edu/harvardkey-application-integration-policy) to understand the full requirements for integration and the roles and responsibilities of various parties in the integration process.

## Integration Overview 

Integrating your application with HarvardKey involves:

1. Preparing your integration team
2. Reviewing integration requirements and choosing your approach
3. Submitting the [Application Integration Form](/resource/harvardkey-application-integration) and required materials

See below for detailed steps.



 

##  Step 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 SAML and OIDC protocols.
    - Harvard will be retiring support for CAS in 2026 and no longer accepts requests to integrate with HarvardKey using the CAS protocol as of October 1, 2024.
- Have access to configure authentication on the application end
- Know which attributes and unique identifier your application requires
- 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 connect IAM with a technical representative can provide the required information (SP metadata, entity IDs, endpoint URLs, etc.). The IAM team is happy to meet with knowledgeable vendor technical representatives to facilitate the integration process.

Before requesting integration with HarvardKey, please make sure your procurement processes have been completed and a signed contract is in place. See the [Strategic Procurement site](https://internal.procurement.finance.harvard.edu/) for more information about the contracting process at Harvard. The Strategic Procurement Contracts team is available for assistance.



 

##  Step 2: Review Integration Requirements & Choose Your Approach 

Before completing the integration form, clikc on the tabs below to review the following:

1. HarvardKey Application Integration Form
2. Information about HarvardKey Services
3. Reference Materials

Harvard IAM is part of the [InCommon Federation](/resources/introduction-assurance "InCommon Federation") (we are an InCommon IdP) and can grant application access to users from other member institutions.

 

 



 HarvardKey Services Integration Form Reference Materials 

## HarvardKey Services

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

- **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.

### 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. Authentication determines whether a user is who they claim to be when they attempt to log into an application.

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 ](/selecting-harvardkey-authentication-protocol "Selecting a HarvardKey Authentication Protocol ")knowledge article.

### Authorization

Authentication alone is not enough, particularly because when someone leaves the University their HarvardKey will continue to function. All applications must apply one or more **authorization groups** to ensure only eligible users gain access.

- [Authorization Group Best Practices with Okta](https://harvard.service-now.com/ithelp?id=kb_article&sys_id=0fe49a2b2b7f26d0e401f84cfe91bfd4)
- Choose from [Generic Authorization Groups](/harvardkey-generic-authorization-groups "HarvardKey Generic Authorization Groups") or set-up an app-specific group.
- Populations granted access must align with the [risk level](https://privsec.harvard.edu/) of your application.
- Authorization exceptions require Security team approval.

Compliance insures individuals and the University are sufficiently protected from material harm.

### Attribute Release

HarvardKey can pass selected attributes to your application during login. All attribute requests are reviewed for necessity and privacy compliance.

- Use the [Available Attributes Table](https://docs.google.com/spreadsheets/d/1Fbv8HldQ0a9VGwEyMZevyAuqNtpv0qCJ0-iwzCOXC0c) to choose from available data elements.
- We strongly recommend using NetID as your unique identifier.
- Use Preferred Name when possible to support inclusion.
- Describe how attributes will be used and stored in your system.

Privacy of Harvard user information must be ensured by complying with [data privacy guiding principles](https://www.huit.harvard.edu/privacy), [directory listing policy](/resource/listing-policy "Listing Policy"), and [FERPA requirements](https://provost.harvard.edu/sites/g/files/omnuum3356/files/provost/files/ferpa_overview.pdf).

 

 

 

## Integration Form

Please review all parts of the [HarvardKey Application Integration form](/resource/harvardkey-application-integration).

 

 

 

## Reference Materials

Please review the following information about application integrations.

- **Overview**
    - [Application Authorization using HarvardKey and IAM Group Services](https://harvard.service-now.com/ithelp?id=kb_article&sys_id=3811d84ddb4597cc83a2f3f7bf9619e5)
- **Policy**
    - [Roles and Responsibilities of Application Teams vs. IAM in the Integration Process](/roles-and-responsibilities-application-teams-vs-iam-integration-process "Roles and Responsibilities of Application Teams vs. IAM in the Integration Process ")
- **Guides**
    - [Selecting an Authentication Protocol](/selecting-harvardkey-authentication-protocol "Selecting a HarvardKey Authentication Protocol ")
    - [Attributes Available for Applications using HarvardKey Authentication Services](/attributes-available-applications-using-harvardkey-authentication-services "Attributes Available for Applications using HarvardKey Authentication Services ")
    - [Request Approval to Allow Alumni Access to your HarvardKey-protected Application](https://harvard.service-now.com/ithelp?id=kb_article&sys_id=12dd722c1bba49d0485411b6bc4bcb5a)
    - [HarvardKey Integration Services- Authentication Session Timeouts](/harvardkey-integration-services-session-timeouts "HarvardKey Integration Services - Session Timeouts")
    - [Request a New Environment for an Existing Application](https://harvard.service-now.com/ithelp?id=kb_article&sys_id=476957dc47374d50566cf147536d436c)
    - [SAML Signing and Encryption Certificates](/saml-signing-and-encryption-certificates "SAML Signing and Encryption Certificates ")
    - **Group Authorization**
        - [Group Authorization Best Practices with Okta](https://harvard.service-now.com/ithelp?id=kb_article&sys_id=0fe49a2b2b7f26d0e401f84cfe91bfd4)
        - [HarvardKey Generic Authorization Filters](/harvardkey-generic-authorization-groups?tab=t.0#heading=h.gbp2nru5x9oe "HarvardKey Generic Authorization Groups")
        - [Application Authorization using HarvardKey and Grouper](https://harvard.service-now.com/ithelp?id=kb_article&sys_id=3811d84ddb4597cc83a2f3f7bf9619e5)
        - [Guide to create application authorization groups in Grouper](https://harvard.service-now.com/ithelp?id=kb_article&sys_id=ff9787d8dbdb9f047399fb661d96198e)
        - [Guide to create a non-standard application authorization group](https://harvard.service-now.com/ithelp?id=kb_article&sys_id=9e52d7f4938c32d4bf14bbcd1dba10bb)
        - [Add a membership requirement attribute to a Grouper group](https://harvard.service-now.com/ithelp?id=kb_article&sys_id=1623c3ab2b73a6d0e401f84cfe91bf78)

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

 

 

 

 

 

##  Step 3: Submit the HarvardKey Application Integration Form 

Submit the [HarvardKey Application Integration Form](/resource/harvardkey-application-integration-form "HarvardKey Application Integration Form") to start your request. Before filling in the document, right-click and select "Save Link As" or "Save Target As" and give the form a meaningful name that includes the application, then fill in the saved form.

**Important notes:**

- Ensure you have completed the procurement process as outlined in Step 2.
- By default, applications are registered with the HarvardKey production environment. If there is a business requirement, you may register an application with the HarvardKey stage environment by special request.
- All local host application must be integrated with HarvardKey Stage.

**Include:**

- Completed form
- Metadata file (for apps using SAML protocol)
- Application CI (for HUIT-supported apps)
    - If your app already has a CI, search for it in [ServiceNow](https://prod-iam.drupalsites.harvard.edu/get-started/app-integration#:~:text=your%20application%20in-,ServiceNow,-under%20the%20HUIT) under HUIT Config → Application
    - If it's a new app, request a CI via the [IT Help Portal](https://prod-iam.drupalsites.harvard.edu/get-started/app-integration#:~:text=CI%20in%20the-,IT%20Help%20Portal.,-Timeline%20for%20New)



 

##  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. 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. [Check out the Upcoming Events page](https://prod-iam.drupalsites.harvard.edu/news) for information regarding the Authentication and Authorization Office Hours.