If you cannot log into Handshake, this article should outlines the next steps to help you authenticate successfully.
Typical SSO Log in process
- Navigate to your institution's Handshake portal (yourschool.joinhandshake.com).
- Select the SSO login button, rather than entering your email:
3. Once you select the SSO button, you will either be:
- Prompted on the same page for a username and password (your school SSO credentials) OR
- Redirected to your institution's SSO portal to authenticate. Typically these credentials are the same you use for other SSO systems, email, etc.
I don't have access to SSO, how do I login? (Alumni process):
- Navigate to app.joinhandshake.co.uk (or your yourinstitution.joinhandshake.co.uk portal)
- Simply enter your school (.ac.uk) email address (rather than clicking the SSO Login button).
- If your institution pre-created an account for you, use that same email address to access. If you're unsure of that account/email address, please reach out to your Career Services team for more details.
Student Log In Errors:
If you receive any errors when you attempt to log in with SSO: reach out to your Career Services or IT teams to verify your access to Handshake. Connecting with the offices at your institution is important because your SSO log in details are managed by your institution, and they will be able to work with Handshake's Support Team to address.
Follow the same login flow as described for students above. For errors and troubleshooting, use this error guide to triage any SSO issues with your IT team and Handshake Support.
Please note: Any account (either Career Services or Student) that logs in via SSO in Handshake must have an auth_identifier in the account settings. This is the only value used for SSO auth/verification. Student accounts typically have an auth_identifier populated on their accounts via the student data import. Career Services staff, however, will these values manually entered on their profiles. You can usually get the correct auth_ID values for this field from your IT team if needed.
SSO Error Messages and Next Steps:
"You successfully logged in to your Single Sign On portal but we could not find your Handshake account. You either don't have an account yet or your account is not configured correctly. Please use the options below to configure your account to log in"
Why: You may see this message during login if the auth_ID field is blank or invalid on an individual account. If most or all of your Career Services and student users see this screen on login, there is likely a configuration issue with SSO between your institution and Handshake.
What you should do: you should open a tech support request and CC any IT or networking contacts at your institution in this request as well. If your institution is "live" (meaning you are no longer in implementation), mark this as an 'Urgent' issue.
"There was an issue communication with your institution. Try again later, or sign in using your Handshake email and password. Error code 2."
Why: This error can occur if any recent changes were made by your IT team. In some cases, a change that was made can be rolled back until your IT team can work with Handshake Support to align with the updates.
What you should do from Career Services: If you are already live with SSO and this issue occurs for most or all users at your institution, reach out to your IT team to see if any recent changes were made. A few things that you should share with them:
- List of email addresses and accounts that cannot log in
- Screenshots of error messages
- This article (and the steps to handle outlined below)
Please note: You can always login to Handshake with your email address and a Handshake-specific password if there is an SSO outage (If using email/password, on first login you will be taken through an email verification process and setup a new Handshake-specific password).
Handshake SSO Configuration is fully self-service - use this guide to access or troubleshoot your SSO settings in Handshake
How to Access SSO Settings:
- Log into your Handshake account
- Navigate to your Institution Settings
- Select the SSO Preferences tab
Note: If you do no have an account in Handshake, reach out to your Career Services team - they will be able to provision a Handshake user account with the 'Manage SSO Settings' role with this process
How to Setup SSO Setup and Test the Log in:
Fields You Can Update Within the SSO Settings:
- The fingerprint value when you roll over to a new x.509 certificate (SAML)
- The base URL if moving to a new CAS server (CAS)
- The bind username/password, BaseDN, or Search Filters for LDAPS
- (If you're changing LDAPS IP's, we do need to whitelist these on the backend prior to the change. More info here: https://documentation.joinhandshake.co.uk/docs/ldap)
Common LDAP Error Handling Steps for IT Teams:
Error:"There was an issue communicating with your school..." (Error 1 & 2)
What you can do from IT:
If a small subset of users:
- Check your Handshake SSO Preferences, and verify that the 'Host' you have set for LDAP users is correct.
- If using a hostname there, did you have every IP address associated with that host whitelisted by Handshake? Sporadic errors here typically indicates there is an additional/rotating or new IP being used.
- Did you whitelist BOTH of Handshake's LDAP IP's, or just one? Both are required or you will have sporadic errors like this. IP's found HERE.
If all users:
- Check your Handshake SSO Preferences, verify that the LDAP bind username and password are correct.
- Also check that the 'Host' you have set is correct, and that you've had Handshake whitelist ALL IP's associated with this host.
- Make sure you've whitelisted both of Handshake's IP's found HERE.
Error: Error 6 (Auth timeout when trying to reach your LDAP server)
What you can do from IT:
If a sporadic/small subset of users:
- This can occur sporadically after a large amount of failed logins in a short period (lockout period). This lockout period is not set/enforced by Handshake, but rather your local LDAP server, and typically goes away after a set period of 15-30 minutes.
- Verify that you have adequate auth timeouts set for initial login, as heavy load may create a delay in auth, and timeouts, for large amounts of users.
- Verify in your Handshake SSO Preferences that your LDAP Base DN and Filter are specific enough to prevent timeouts.
- Verify that users reporting the issue are in the correct OU based on your Base DN.
If all users:
- Verify that you have adequate local LDAP auth timeout set for initial login. Try increasing this by a few seconds.
- Verify that your LDAP server and connection are not having localised issues or outages.
- Wait a short period of time (30 minutes to an hour) and verify that this persists.
LDAP-specific fields for reference:
Common SAML Error Handling Steps for IT Teams:
Error: "Error 4: Failed to validate the SAML response. Errors: Invalid Signature on SAML Response"
What you can do from IT:
*This error indicates that the returned signature in your SAML response during auth did not match the Fingerprint (SHA-1 hash of your x.509 cert) value in your Handshake SSO Preferences.
This error commonly occurs:
- During initial setup and testing if the wrong Fingerprint value was entered (or blank).
- Once or twice a year after launch if you change or rotate your x.509 signing certificate, without updating the Fingerprint in Handshake SSO Preferences.
To fix this:
- Login to your Handshake account
- Navigate to your School Settings -> SSO Preferences section.
- Scroll to the very bottom and update the 'Fingerprint' field with the new value:
*Select 'Update SSO Preferences', and try another login shortly after.
Additional Error Guides by SSO Auth Type:
Review these in-depth guides in our technical documentation site to explore additional error codes and troubleshooting techniques