Single Sign On with SAML 2.0

From Hornbill
Jump to navigation Jump to search

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:

  1. 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.
  2. 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.

Saml-flow.png

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

The Service Provider (Hornbill) meta data files needed for configuring your IdP can be downloaded from your Hornbill instance

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).

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


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.