Single Sign On Profiles
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.
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
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?
If you have multiple identity providers supporting multiple directory sources, then you will need one SSO Profile per identity provider i.e. one SSO Profile is required for each authentication service.
An SSO profile can contain multiple signing certificates, therefore if your Identity Provider generates multiple signing certificates (e.g. in the case of Azure, where a certificate is generated for each of the Hornbill Service URL's) you will still only need one SSO Profile.
In the situation where you have multiple SSO Profiles, when a user navigates to Hornbill they will be presented with a drop-down menu containing the SSO Profiles that have been configured. It is then up to the user to select the authentication service applicable to them. A good SSO Profile naming convention can help in this scenario. Alternatively, it is possible to supply your users with a URL that contains reference to the SSO Profile relevant to them. This is in the following format: https://live.hornbill.com/[instance]/?entityId=[entityId] where [entityId] should be replaced with the entity ID found within the relevant SSO profile.
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?
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.
NOTE: If the configuration in your Identify Provider results in separate certificate metadata for each of the Hornbill service URLs, either of the steps above can be repeated multiple times. Each time some certificate metadata is processed, the new certificate will be appended into the SSO Profile. Existing certificate metadata is never overwritten.
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
Enabling an SSO Profile
Once you have confgiured the SSO profile, you can easily enable or disable the profile using the toggle switch available within the SSO Profile or located in the list of SSO Profiles.
Auto Provisioning (Optional)
The creation of Hornbill user accounts can be automated as part of the Single Sign-on (SSO) configuration. With auto-provisioning configured and enabled within the SSO Profile, your users are self-provisioned automatically (using the attributes delivered from your IdP in the SAML payload) when they first navigate to your Hornbill instance. Providing the user has been authenticated by the IDP, a Hornbill account will be automatically be created. When it comes to creating user accounts, auto-provisioning is not the only mechanism available. For more information on how user accounts can be created please see the following page: Users - Creating User Accounts
- Enable - Turn this on to enable the auto-provisioning of User Accounts
- Auto Provisioning User Templates - While the user properties are delivered to Hornbill in the SAML payload during authentication, the Hornbill Auto Provisioning user template allows you to specify the Hornbill Security Roles (among other things) that will be associated to a user when they are auto-provisioned.
- Mapping - The mapping defines where the information contained in the SAML payload (coming from your IdP) will be put (or targeted) in a Hornbill user profile i.e. the user attribute delivered in the SAML payload containing the user's job title should be mapped to the appropriate Hornbill user account property "account:jobTitle".
The Hornbill user account properties available to map via auto-provisioning are as follows:
|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|