Single Sign On Profiles

Home > Administration > Single Sign On Profiles

Introduction

A Single Sign On Profile (SSO Profile) is where you complete the integration with your identity provider (IdP) such as Active Directory Federated Services (ADFS). With Single Sign On configured, authentication into Hornbill will be securely managed by your preferred authentication service.

Prerequisites

Before creating a Single Sign On Profile in Hornbill Administration, you must have completed the configuration of your identity provider. For details on how to obtain information about your Hornbill instance, compatible identity providers, and some example configurations, please click here: Single Sign On with SAML 2.0

Creating a SSO Profile

Click the + button to begin creating a new SSO Profile

A SSO profile is created and configured in Hornbill Administration, Home > System > Security > SSO Profiles. To create and begin the configuration of a new SSO Profile, click the "+" button located at the top right of the list. The information below will explain how to take the meta data produced during the configuration of your IdP (which contains the signing certificates) and store it in the Hornbill SSO Profile.

How many SSO Profiles do I need?

The configuration of your IdP will either produce one signing certificate (catering for all the Hornbill Service URL's - ADFS works in this manner) or an individual signing certificate for each of the Hornbill Service URLs (e.g. in the case of Azure). As a single SSO profile can contain multiple signing certificates, typically you will only require one SSO Profile. However, if you have multiple identity providers associated to separate directory sources, then you will need one SSO Profile per identity provider i.e. one SSO Profile is required for each authentication service.

Clicking the cloud icon will prompt you to upload your IDP meta data

Uploading Your IdP Meta Data into the Hornbill SSO Profile

Populating the entity ID, signing certificate(s) and service bindings of the SSO Profile is completely automatic based on the meta data that is generated during the configuration of your IdP. For details on how to obtain information about your Hornbill instance, compatible identity providers, and some example configurations, please click here: Single Sign On with SAML 2.0.

URL or XML?

Either copy and paste the appropriate URL referring to the location of your Identity Provider meta data OR copy and paste the meta data from the relevant file

Clicking on the cloud icon on the top right of the Profile Details form will present you with a pop-up containing two fields; URL and XML. Only one of these needs to be populated.

URL - If your IdP can present it's certificate meta data via a URL, then that URL should be pasted in the URL field, and then click "Process". Referencing the Microsoft ADFS 2.0 example, the URL that is required here is: https://<yourserver.yourdomain.com>/Federationmetadata/2007-06/FederationMetadata.xml where "<yourserver.yourdomain.com>" is replaced by the name of your federation server. Other IdP's will be different or may not offer this facility.

XML - If your IdP is not able to present it's certificate meta data via a URL, the file containing this should be opened in a text editor (e.g. Notepad ++) and copy and paste the contents into the "XML" field and then click "Process". If you IdP has produced separate meta data files for each of the Hornbill Service URL's, repeat this step as many times as required.

Review and Set the Profile Details

Name - specify a suitable name for your SSO profile
Enabled - when you are ready to switch on SSO, toggle this to the "ON" position (leave this until last).
Validate Time - toggle this to the "ON" position, this will tell Hornbill to validate that the assertion is valid at the time of issue - we recommend this is always "ON".
Validate Certificate - toggle this to the "ON" position, this will tell Hornbill to validate that the signing certificate is known and valid, - we recommend this is always "ON".
Realm - for a SSO Profile facilitating single sign on for live.hornbill.com (the User App), admin.hornbill.com (Hornbill Administration), or service.hornbill.com (the Service Portal), this should be set to "User". For a SSO Profile facilitating SSO for customer.hornbill.com (Customer Portal), this should be set to "Guest".
Type - This is the secure protocol used in the SSO authentication mechanism. Only SAML 2.0 is used and supported by Hornbill.
Name Id - If the NameID provided by the idP matches the account ID on Hornbill then this should be left blank. If however, the name ID from the idP is opaque (either static or transient) then you can use this parameter to tell Hornbill to override the NameID with a value from one of the SAML assertions attributes. This way the idP can provide a value that matches the account ID on hornbill for the user and Hornbill will use that to identify the user being authenticated

Auto Provisioning

With Auto Provisioning enabled, a user account will be automatically created for the user provided they have been authenticated by the IDP.

Name
Template
Enable
Mapping

Troubleshooting Single Sign On Configurations

If the SSO is enabled and is not working correctly, this could effectively prevent any user being able to login. As a system administrator, a Hornbill user can log into admin tool/interface using this URL: https://admin.hornbill.com/<instance_id>/?ESPBasic=true. The <instance_id> needs to be replaced with the ID of your instance. The user will have the option to log into Hornbill using the Hornbill user ID and password thus bypassing the SSO profile.

Common Issues

I can no longer access Hornbill

A common symptom of the error message below is the expiry or renewal of an ADFS Server signing certificate. By default, the ADFS AutoCertificateRollover property is set to true so the certificates could change without any direct action.

This can be rectified by supplying the new certificate key for the Hornbill SSO Profile. Please contact the security or administration team within your company to request for a refreshed ADFS Server certificate key.

In the example below, clicking on + icon under Certificates section allows you to supply a new ADFS signing certificate. This can be achieved through the Admin Tool:

Admin Tool > System > Security > SSO Profile (e.g. https://admin.hornbill.com/instance-name/security/profiles/)

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 the expiry of them.

Please refer to "Related Articles" in this page for information relating to SSO Profiles.