Single Sign On with SAML 2.0
Home > Integration > Essential Integrations > Single Sign On with SAML 2.0
Introduction
The Hornbill platform supports single-sign-on as well as policy-based transparent auto provisioning and data updates of both user and guest accounts thus providing enterprise-class user identity integration with your organisations core IT directory services.
What is SAML?
Security Assertion Markup Language ('SAML, pronounced "sam-el") is an open standard XML-based framework developed by the Security Services Technical Committee of OASIS and is designed for communicating user authentication, entitlement, and attribute information between parties, in particular between an Identity Provider (IdP) and a Service Provider i.e. Hornbill.
External References:
Oasis-Open.org: https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=security, Wikipedia: http://en.wikipedia.org/wiki/Security_Assertion_Markup_Language,
SAML and Hornbill
Hornbill makes use of the SAML framework to facilitate two things:
- Single Sign On (SSO) - this is the method of access control that enables a user to log in to their organisations network one time, but then have transparent authorisation to access resources of multiple software systems without being prompted to log in to each system separately. In the context of Hornbill, once configured, users may access their Hornbill instance pre-authenticated based on their enterprise desktop or browser login.
- Auto-provision Hornbill User Accounts - along with the authorization information needed for SSO, SAML has the ability to transport additional directory attributes of a user. Hornbill is capable of processing this additional information contained in the SAML payload and use it to automatically create a user accounts on your Hornbill instance. This mechanism can remove a significant overhead in terms of system administration.
PLEASE NOTE: While SSO must be set up to utilise auto-provisioning, the auto-provisioning of user accounts in Hornbill is an optional mechanism that can be disabled independently of SSO. Hornbill provides a range of user import utilities that can be used instead of auto-provisioning. More information on the available user imports can be found via the following wiki page: Open Integration Tools
How it Works
There are three key actors in any SAML implementation, these are the "user" trying to access the Hornbill Cloud Application (via their Web Browser), the "Identity Provider (idP)" which knows and has identified the user, and the Service Provider (Hornbill Cloud Service) which provides the application and/or resources that the user wishes to access. Your Hornbill instance is the service provider, and typically your enterprise directory system, very often Microsoft Active Directory Federated Services (ADFS) acts as your identity provider.
Once SSO is configured, when an unauthenticated user navigates to your Hornbill instance via one of the Hornbill URLs, the browser will be re-directed to the identity provider with the information needed to request access to the service, this is known as a SAML AuthnRequest. The idP will look at the AuthnRequest and if the user is authorized will return an Assertion back to the browser with a redirect to the service provider (in this case the Hornbill Instance). The Hornbill instance will validate the Assertion checking its authenticity against a known Hornbill SSO profile and if valid will create a session and allow the user to access Hornbill as required.
Download the Hornbill Meta data
In order to successfully configure your Identity Provider (IdP) you will need details of your Hornbill instance. The Service Provider meta data files contain such things as the Service Provider Entity Id and Assertion Consumer Service (ACS) binding that your IdP needs to communicate during the authentication process.
To get your meta data files, log into Hornbill Administration and navigate to Home > system > Security > SSO Profiles. Located towards the top right of the list are buttons labelled "Mobile Catalog", "User", "Admin", "Service", and "Customer". Clicking each of these will download the Hornbill meta data file for the associated Service URL.
USER - contains information for https://live.hornbill.com/[your instance name]
ADMIN - contains information for https://admin.hornbill.com/[your instance name]
MOBILE CATALOG - contains information for https://mcatalog.hornbill.com/[your instance name]
CUSTOMER - contains information for https://customer.hornbill.com/[your instance name]
SERVICE - contains information for https://service.hornbill.com/[your instance name]
This is the URL relating to the Hornbill Service Portal and is due to be retired during 2020. All new implementations of Hornbill do not require this.
What Meta data files do I need to download?
When configuring your IdP, you will need to create entries to represent each of the Hornbill URL's that will be used to access your Hornbill instance and you will need the corresponding meta data files to support the creation of the trusts.
- "User" is always necessary. Therefore as a minimum you will have one entry in your IdP.
- "Admin" is optional as access can be gained via a link from the user app once successful login has been achieved. However, many choose to configure this in their IdP for added convenience.
- "Mobile catalog" is required to facilitate access via a mobile device.
- "Customer" represents the self service portal used in the delivery of an external support function. This is only required if you need a portal to provide services to those outside of your organisation.
Configure your Identity Provider
The Hornbill SSO implementation follows the SAML 2.0:2005 specification so will work with any commercial or home-grown identity provider that correctly supports this standard. We have tried to make our system as flexible as possible in terms of configuration and compatibility with the standard. Here is a link to the official standards documentation: - SAML 2.0 2005
The following identity providers are known to have been configured and work with the Hornbill platform (we will expand this list as we integrate successfully with other systems).
- Microsoft Active Directory Federation Services (ADFS 2.0)
- Microsoft Active Directory Federation Services (ADFS 3.0)
- Ping Identity
- SSO Circle
- Microsoft Azure Directory Services
- Shibboleth Identity Provider
- OpenAthens (EduServ)
As you might expect, different vendors may use different terminology to describe the configuration required in the IdP but typical examples are "Service Provider Profile" or "Relying Party Trust" (see below for Example IDP configurations and references). It is likely that you will need an entry in your IdP to represent each of the Hornbill Service URL's (i.e. admin, live, and service).
Example IdP Configurations
- Microsoft ADFS 2.0
- Microsoft Azure - There's a Hornbill app in the Azure Gallery to help with the setup of Hornbill single sign-on using Azure AD as its identity provider.
PLEASE NOTE: Although we have expertise around our own platform and its SAML implementation, configuration and behaviour, we use the language associated with the SAML 2.0 standard and not the language/terminology of any specific vendors identity provider platforms. Hornbill's technical staff are not experts with the various identity provider technologies and platforms in use. It is important to understand that Hornbill support the SAML 2.0 standard to the letter, so if it's in the standard we support it.
Each organisations identity provider implementation can be unique to their organisation and it will be necessary for you to have someone internally with expertise and a working knowledge of your identity provider and directory services within your own organisation. You should refer your technical network expert to this document which should provide them with sufficient information to allow the planning and configuration of Single Sign-On for your organisation.
Configure a Single Sign On Profile in Hornbill
The final step in setting up SSO for Hornbill is to create a Single Sign On Profile in your Hornbill instance. The following page will provide detail on how to complete this step: Configuring a Single Sign On Profile in Hornbill.
Enabling Single Sign On in your Web Browser
Depending on your policy, it may be necessary to make changes to your browser settings to ensure a seamless SSO experience. The following page outlines the steps for some common browsers: Enabling Single Sign On in Your Web Browser.
Troubleshooting 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. For information in relation common scenarios and what to do to overcome them please see the following page: Troubleshooting Single Sign On.
Preparing for Auto-Provisioning (Optional)
The necessary configuration to facilitate auto-provisioning can be considered a small extension of the Single Sign On configuration. In the case where only SSO is needed, there is a single one-to-one mapping between the Hornbill User ID and the "nameID" returned in the SAML communication that identifies the user, typically this is tied into the users login ID. For Hornbill to successfully auto-provision a user account, it will be necessary to specify additional information to be transported in the outgoing claim from your Identity Provider. This information is carried in the additional attributes that are transported during the authentication of a user.
Obvious information such as first name, last name and e-mail address would be especially important when creating a Hornbill user account, but you may wish to bring over other information into the Hornbill instance at the point of auto-provisioning.
Hornbill User Account Properties
The Hornbill instance understands a definitive set of user account target properties. The available properties can be used as a starting point in determining what information you wish to bring into Hornbill via your IDP for auto-provisioning. For each user account property you wish to populate in Hornbill, you will need a directory attribute configured in the outgoing claim coming from your iDP. The mapping is defined in the Hornbill Single Sign On Profile The following table lists the user account properties that can be populated during auto-provisioning.
| Name | Required | Description |
|---|---|---|
| account:name | No | The users display name/handle. If not specified then the name will be derived from account:firstName a space and the account:lastName. If these two attributes are not defined either, the name will be the same as the nameID (the users login id) |
| account:firstName | No | The users given/first name |
| account:lastName | No | The users given/last name |
| account:jobTitle | No | The users job title within the organisation |
| account:phone | No | The users phone number |
| account:email | No | The users e-mail address |
| account:mobile | No | The users mobile phone number |
| account:availabilityStatus | No | The users availability status - there is generally not a good mapping for this so you would not normally include it |
| account:availabilityMessage | No | The users availability message - there is generally not a good mapping for this so you would not normally include it |
| account:timeZone | No | The users timezone, see the list of supported times zones in Hornbill Administration |
| account:language | No | The users language, see the list of supported languages in Hornbill Administration |
| account:dateTimeFormat | No | The users dateTime format, see the API documentation for admin::userCreate for the format information |
| account:dateFormat | No | The users date format, see the API documentation for admin::userCreate for the format information |
| account:timeFormat | No | The users time format, see the API documentation for admin::userCreate for the format information |
| account:currencySymbol | No | The users default currency symbol |
| account:countryCode | No | The users country code |
Auto-provisioning User Templates
If you have chosen to use auto-provisioning, you may want to explore the creation of an auto-provisioning User Template in Hornbill. Details can be found at the following page: Auto Provisioning User Templates.
Hornbill Contact Record (Guest) Properties
Like Hornbill user accounts, contact records can be created through auto-provisioning. The following table lists the contact record properties that can be populated during auto-provisioning.
| Name | Required | Description |
|---|---|---|
| contact:firstName | No | The users given/first name |
| contact:lastName | No | The users given/last name |
| contact:jobTitle | No | The users job title within the organisation |
| contact:phone | No | The users phone number |
| contact:email | No | The users e-mail address |
| contact:company | No | The name of the company the user works at |
| contact:timeZone | No | The users timezone, see the list of supported times zones in Hornbill Administration |
| contact:language | No | The users language, see the list of supported languages in Hornbill Administration |
| contact:countryCode | No | The users country code |
Auto-provisioning Contact (Guest) Templates
If you have chosen to use auto-provisioning, you may want to explore the creation of an auto-provisioning Contact (Guest) Template in Hornbill. Details can be found at the following page: Auto Provisioning Guest Account Templates.