Okta Migration Info for HarvardKey-integrated Applications

• Log in to the HarvardKey Application Registry (HKAR) and navigate to the Migration Tracking Dashboard.
• Review the list of existing HarvardKey registrations.
• For each registration where the Data Source is “Legacy”, decide whether to migrate or retire it. If retiring a registration, refer to the steps in the Registration Retirement Checklist below.
• Add migration plans, timing, and helpful planning notes in the Migration Plan, Timeline,  Migration Notes columns.   
• For access support, contact Emily Heck (emily_heck@harvard.edu).

• Okta supports SAML and OIDC protocols only.
  • Applications currently using SAML or OIDC may continue to use these protocols, but will need to be updated to integrate with Okta.
  • Applications currently using the CAS protocol must be updated to use SAML or OIDC as part of the transition to Okta.
• Resources to help determine which protocol is right for an application:
  • Okta Supported Protocols
  • Selecting a HarvardKey Authentication Protocol

Questions about protocol selection should be directed to iam_help@harvard.edu.

• Review registration authorization groups in the HKAR Migration Tracking Dashboard.
• With the move to Okta we are implementing new best practices for authorization. Please familiarize yourself:
  • Authorization Group Best Practices with Okta.
  • Application Authorization using HarvardKey and Grouper
• Key takeaways:
  • The concept of a single authorization group in our legacy infrastructure is being replaced with multiple authorization groups in Okta.
  • Large authorization groups should only be used in production environments. For non-production environments, use smaller custom groups unless there is a legitimate business need for broader access.
  • Since a single application may have multiple authorization groups, we have flexibility to be more granular than our legacy authorization filters. For teams using broad authorization groups in our legacy infrastructure we’re asking them to consider whether authorization groups in Okta can be narrowed. 

Upon submitting a migration request, IAM’s Product Team may reach out to you to discuss changes to your authorization groups

• Complete the HarvardKey Okta Application Migration Form and email it to iam_help@harvard.edu
• Submit one form per application. List multiple registrations if applicable.
• Only submit the form when ready to migrate your first application registration. The final step will be to delete all legacy registrations associated with an application.

• After the Okta registration(s) are created, an IAM engineer will send an email.
• Use the configuration values (e.g., Entity ID, Client ID, Secret Key) to configure the registration(s), as detailed in Step 5.
• Review wthe proposed legacy registration disable delate dates. The default timeline is:
  • 1 week after IAM’s email, legacy registrations will be disabled
  • 2 weeks after disablement, legacy registrations will be deleted

• Update application settings based on the chosen protocol. All required details will be provided in the email from IAM.
• For SAML, update:
  • Entity ID
  • Assertion Consumer Service (ACS) URL
  • If your application has a logout/sign out mechanism and you currently call HarvardKey to end the HarvardKey session, update your app to call the new Okta logout URL: https://login.harvard.edu/signin/logout (calls to the legacy URL will not end the HarvardKey session)
• For OIDC, update:
  • OIDC issuer URI: https://login.harvard.edu
  • Discovery endpoint: https://login.harvard.edu/.well-known/openid-configuration
  • Client ID and Secret (sent via encrypted email)
  • Redirect URI: (Respond in ServiceNow with this information)

• For each registration, verify:
  • Authentication to the associated environment is successful, after the application settings have been updated.
  • Authorization groups listed for the registration in the HarvardKey Application Registry are correct. Note that group authorization works slightly differently with Okta than with our legacy infrastructure. See our guidance around best practices for group authorization with Okta for more information.
  • That user attributes (such as name, email, and roles) are correctly displayed/handled by the application after authentication, if applicable.
• On the HarvardKey sign-in page (login.harvard.edu), verify the expected application name appears at the top of the screen under the settings image.
  • If successful, the text will appear as: "Sign in with your account to access <Application Common Name & Environment>" (as provided on the migration request form.)
  • If not successful, and the registration is still using delegated authentication, the text will appear: "Sign in with your account to access HarvardKey."

• Confirm successful authentication or provide details of any issues encountered. If there are issues encountered, the IAM team will help troubleshoot and resolve them.
• Confirm the legacy registration disable and delete dates or propose alternate dates.

As soon as an IAM engineer sends notice that the legacy registrations are disabled, validate that authentication still works as expected for all environments.

IAM will delete the retired registration(s) two weeks after disabling them.

• Log in to the HarvardKey Application Registry (HKAR) and navigate to the Migration Tracking Dashboard.
• Review the list of existing HarvardKey registrations.
• For each registration where the Data Source is “Legacy”, decide whether to migrate or retire it. If retiring a registration, refer to the steps in the Registration Migration Checklist above.
• Add migration plans, timing, and helpful planning notes in the Migration Plan, Timeline,  Migration Notes columns.   
• For access support, contact Emily Heck (emily_heck@harvard.edu).

Email a list of Registration IDs and Service Name/Entity IDs to iam_help@harvard.edu to generate a ServiceNow ticket.

As soon as an IAM engineer sends notice that the legacy registrations are disabled, verify there’s no negative impact and reply to the ServiceNow ticket to confirm that the engineer can proceed with deleting the registrations.

An IAM engineer will delete the retired registration(s) after receiving confirmation. If no confirmation is received, they will delete the registrations one week after disabling them.