Troubleshooting Single Sign On

From Hornbill
Jump to navigation Jump to search

Home > Integration > Essential Integrations > Single Sign On with SAML 2.0 > Trouble Shooting Single Sign On


Hornbill's Single Sign On implementation is designed to present you with helpful error messages in situations where something may not be quite right. This page outlines the common scenarios and what to do to overcome them.

Related Articles

If the SSO is enabled and not working correctly, this will manifest itself as one or more users being unable to login. If it becomes necessary to disable a single sign on profile, it is possible to do this using the Hornbill "admin" account. To login to Hornbill without using single sign on, simply select "Hornbill Direct Login" when presented with your login options at the Hornbill Login Screen.

Common Issues

"The public certificate used for signing the assertion is not known to the service provider...."

A common cause of this error message is that the signing certificate stored in your Identity provider has been renewed and therefore no longer matches the SSO certificate you have stored in Hornbill. Some Identity Providers (such as ADFS) automatically renew signing certificates periodically. By default, the ADFS AutoCertificateRollover property is set to true so the certificates will change automatically without any direct action. Simply put, this error message indicates that the signing certificate given to Hornbill by your identity provider does not match any of the certificates currently stored in the Hornbill SSO Profile.

Corrective Action

This can be rectified by uploading a new certificate key to the Hornbill SSO Profile. Please contact the security or administration team within your company to request for a refreshed ADFS Server certificate key.
As a general principle, we advise that the team responsible for security or administration within your company can schedule a task to update the Hornbill SSO profile with the new certificates, prior to their expiry.

For instructions on uploading your IdP meta data into the Hornbill SSO Profile (which includes signing certificates) click the following link: Single Sign on Profiles

Also this error may occur if you attempt to use multiple SSO profiles with the Customer Portal at one time. Although not currently possible this feature should be configurable from the admin tool in a future release.

This error message indicates that the certificate given to Hornbill by your identity provider does not match any of the certificates currently stored in the Hornbill SSO Profile.

"Unable to Validate User Credentials"

This error occurs when Hornbill was unable to find a match for the user information sent from the identity provider. When the identity provider successfully authenticates a user, it sends information to Hornbill which Hornbill processes to determine which user account to use in order to establish a session for that user (i.e. log them in).

Corrective Action

There are several possible reasons for this error:

  1. The user that has been successfully authenticated does not have a Hornbill user account.
    The solution here is to create a Hornbill user account for this user. However, it's important to understand why one did not exist as it could indicate a problem with a user import.
  2. The Hornbill user account is either archived or suspended.
    The solution is to set the status of the account to active. However it's important to understand why the account was suspended or archived as this may be intentional or could indicate a problem with a user import.
  3. The Unique Identifier sent from your Identity Provider does not match what is stored in the Logon ID field of the Hornbill User Account.
    The unique user identifier being sent from the Identity Provider must match the Logon ID of a Hornbill user account.
    The Unique Identifier is configurable in the Identity Provider. The unique identifier will be a unique directory attribute such as "userPrincipleName". The attribute used can vary between identity providers so it will be necessary for you to understand what is being sent to Hornbill. This is usually configurable in the section responsible for the "user attributes and claims" (again, exactly where this is configured will depend on your identity provider).
    Alternatively, align the Logon ID field of all user accounts to match what your identity provider is sending. For more information on creating and managing users, including Hornbill user account properties, begin at the following page: Users

Unable to verify user credentials could be due to one of several reasons. Check each of the possible causes in turn