Selecting a HarvardKey Authentication Protocol

Overview of Authentication with HarvardKey

Authentication is the core service provided by the HarvardKey Identity Provider (IdP) and serves as the first step in granting users access to integrated web applications.

When a login attempt is made, authentication verifies whether the user is the individual being claimed. Authentication is done using an authentication protocol, which defines how an application and HarvardKey exchange information. After successful authentication, HarvardKey sends a response (called an "assertion") back to the application confirming the user’s identity and providing user attributes.

For many Harvard users, this process also includes multifactor authentication using Okta.

The standard process includes:

  1. Entry of HarvardKey credentials (username and password)
  2. IdP verifies credentials against Harvard’s IAM user directory.
  3. For required users, completion of multifactor verification via Okta.
  4. Upon successful authentication, the IdP issues an authentication response (also called an assertion or token) to the application

This response serves as a trusted claim, assuring the application that the user’s identity has been confirmed by HarvardKey.

HarvardKey supported authentication protocols

  • SAML (Security Assertion Markup Language)
  • OIDC (OpenID Connect)

Prior to October 1, 2024 HarvardKey also supported the CAS protocol. This protocol is being retired and no new integrations are being accepted. Applications currently using CAS will need to migrate to SAML or OIDC by July 2026 as part of the Okta Migration project. 

Understanding Authentication Protocol Options

Each of these protocols is compatible with the HarvardKey IdP, but certain protocols may align better with specific application types or technical architectures. The sections below provide descriptions and guidance to support selection of the most appropriate protocol for a given use case.

SAML2 (Security Assertion Markup Language)

How it works:

  • Identity Provider (IdP): Verifies the user by issuing authentication assertions – messages sent to the Service Provider (SP) to confirm successful authentication. HarvardKey uses Shibboleth IdP.
  • Service Provider (SP): Protects the application that a user is trying to access. SPs receive the authentication assertion from the IdP and uses it to grant access.

Key Features:

  • Widely adopted by SaaS vendors and web applications
  • Works with InCommon Federation for inter-institutional access
  • Ideal for traditional, server-rendered web applications

When to use SAML

SAML is a strong fit for applications that meet one or more of the following criteria:

  • External access is required
    • 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.
  • Integration with third-party SaaS products:
    • Many commercial SaaS platforms and off-the-shelf frameworks support SAML, making it a common choice for vendor-managed integrations.
  • Conventional web architecture is used:
    • SAML aligns well with applications built using standard, server-based web technologies.
  • Requires a rich set of user attributes, such as:
    • Affiliation, School, Role, Department, Group Membership, and other entitlement or authorization-related data


OIDC (OpenID Connect)

How it works:

  • OpenID Connect Provider (OP): Implements OIDC protocol for authenticating end users and providing authentication response (or OIDC claims) to applications (known as Relying Party or RP).
  • Relying Parties (RP): Software component that protects the OIDC protocol using applications and retrieves the identity of the granted users from the OIDC OP.
  • Learn more about how OIDC works.

Features

  • Based on the OAuth 2.0 framework
  • Designed for modern application needs
  • Suitable for single page applications (SPA), mobile applications, and traditional web applications
  • Requires a registered relationship between RP and OP

When to use OIDC

OIDC is recommended for applications with the following characteristics:

  • Built as a Single Page Application (SPA)
  • Designed for mobile platforms
  • Uses modern frameworks or architectures, including JavaScript front-end clients
  • Requires token-based access and integration with other OAuth-based systems
  • Requires only a basic set of user attributes. Supported attributes include First Name, Last Name, Display Name, Nickname, Email, Profile URL, and Preferred Username
    • Applications that require a richer set of identity attributes (such as affiliation, group membership, or custom entitlements) may be better suited to SAML.
       

Summary

Protocol Best For Attributes Released Federation Support Mobile Friendly
SAML
SaaS apps, traditional web apps
Rich set of attributes, including Affiliation, School, Role, Department, Group Membership, and other entitlement or authorization-related data
Yes (InCommon)
No
OIDC
SPAs, mobile, modern apps
Basic set of attributes limited to First Name, Last Name, Display Name, Email, Profile URL, Preferred Username (which can be NetID, UUID, EPPN, or HUID) and some location data
No
Yes

Related Resources