Difference between revisions of "Single Sign On Profiles"

From Hornbill
Jump to navigation Jump to search
(20 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 +
<div style="border:1px solid #90C0FF; background:#D0E0FF; width:99%; padding:4px; margin-bottom:10px;">
 
__NOTOC__[[Main Page|Home]] > [[Administration]] > Single Sign On Profiles
 
__NOTOC__[[Main Page|Home]] > [[Administration]] > Single Sign On Profiles
 +
</div>
 +
{|style="width: 100%"
 +
|- valign="top"
 +
|style="width:73%"|
 
==Introduction==
 
==Introduction==
−
The Single Sign On Profiles let you define integration with an identity provider such as Active Directory Federated Services (ADFS).  With Single Sign On configured, authentication into Hornbill will be securely managed by your preferred authentication service.
+
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.
  
−
An 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.
+
===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|'''Single Sign On with SAML 2.0''']]
  
−
==Profile Details==
+
|style="width:5%"|
 +
|
 +
|style="width:22%; border-style: solid; border-width: 1px; border-color:#e6e6e6; background-color:#f2f2f2;"|
  
−
Populating the Profile Details and Service Bindings, aside from the Profile Name and toggle options, is completely automatic based on the Identity Provider (IdP) meta data that is generated during the configuration of your IdP. Therefore the prerequisite here is to have already performed this work within your organisations environment. An example configuration using the Microsoft ADFS 2.0 identity provider can be found [[SSO_Example_Config_Microsoft_ADFS_2.0_for_Guest_Accounts|'''here''']].
+
== Related Articles ==
 +
:* [[Single Sign On with SAML 2.0]]
 +
:* [[Troubleshooting_Single_Sign_On|Troubleshooting Single Sign On]]
 +
|}
  
−
===Processing Your IdP Meta Data===
+
==Creating a SSO Profile==
 +
[[File:Create_New_SSO_Profile.PNG|400px|thumb|<div align="center">'''Click the + button to begin creating a new SSO Profile'''</div>]]
 +
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.
 +
<br>
 +
===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.
 +
<br>
 +
<br>
 +
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.
 +
<br>
 +
<br>
 +
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: '''<nowiki>https://live.hornbill.com/[instance]/?entityId=[entityId]</nowiki>''' where [entityId] should be replaced with the entity ID found within the relevant SSO profile.
 +
<br>
 +
<br>
 +
[[File:Upload_IDP_Meta_Data.PNG|400px|thumb|<div align="center">'''Clicking the "Import IDP Meta Data" button will prompt you to upload your IDP meta data'''</div>]]
 +
 
 +
===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|'''Single Sign On with SAML 2.0''']].
 +
<br>
 +
====URL or XML?====
 +
[[File:URL_or_XML.PNG|400px|thumb|<div align="center">'''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'''</div>]]
 
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.
 
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.
 +
<br>
 +
<br>
 +
:* '''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: ''<nowiki>https://<yourserver.yourdomain.com>/Federationmetadata/2007-06/FederationMetadata.xml</nowiki>'' 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.
 +
<br>
 +
:* '''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.
 +
<br>
 +
'''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
 +
[[File:EnablingSSOProfiles.PNG|400px|thumb|<div align="center">'''A SSO Profile can be enabled/disabled via the toggle switch available in the SSO profile (shown above) or via the list of SSO profiles'''</div>]]
 +
<br>
 +
===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.
 +
<br>
 +
<br>
 +
<br>
 +
<br>
 +
 +
==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|'''Users - Creating User Accounts''']]
 +
 +
* '''Enable''' - Turn this on to enable the auto-provisioning of User Accounts
 +
* [[User Templates |'''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:
 +
{| class="wikitable"
 +
 +
|-
 +
! Name
 +
! Required
 +
! Description
 +
 +
|- style="vertical-align:top;"
 +
| style="font-family: courier new;" | 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)
 +
 +
|- style="vertical-align:top;"
 +
| style="font-family: courier new;" | account:firstName
 +
| No
 +
| The users given/first name
 +
 +
|- style="vertical-align:top;"
 +
| style="font-family: courier new;" | account:lastName
 +
| No
 +
| The users given/last name
 +
 +
|- style="vertical-align:top;"
 +
| style="font-family: courier new;" | account:jobTitle
 +
| No
 +
| The users job title within the organisation
 +
 +
|- style="vertical-align:top;"
 +
| style="font-family: courier new;" | account:phone
 +
| No
 +
| The users phone number
 +
 +
|- style="vertical-align:top;"
 +
| style="font-family: courier new;" | account:email
 +
| No
 +
| The users e-mail address
 +
 +
|- style="vertical-align:top;"
 +
| style="font-family: courier new;" | account:mobile
 +
| No
 +
| The users mobile phone number
 +
 +
|- style="vertical-align:top;"
 +
| style="font-family: courier new;" | account:availabilityStatus
 +
| No
 +
| The users availability status - there is generally not a good mapping for this so you would not normally include it
 +
 +
|- style="vertical-align:top;"
 +
| style="font-family: courier new;" | account:availabilityMessage
 +
| No
 +
| The users availability message - there is generally not a good mapping for this so you would not normally include it
  
−
* '''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.
+
|- style="vertical-align:top;"
 +
| style="font-family: courier new;" | account:timeZone
 +
| No
 +
| The users timezone, see the list of supported times zones in Hornbill Administration
  
−
* '''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".
+
|- style="vertical-align:top;"
 +
| style="font-family: courier new;" | account:language
 +
| No
 +
| The users language, see the list of supported languages in Hornbill Administration
  
−
Upon clicking "Process", the Entity Id and Bindings will be automatically populated. All that remains is to complete the following:
+
|- style="vertical-align:top;"
 +
| style="font-family: courier new;" | account:dateTimeFormat
 +
| No
 +
| The users dateTime format, see the API documentation for admin::userCreate for the format information
  
−
===Profile Details===
+
|- style="vertical-align:top;"
 +
| style="font-family: courier new;" | account:dateFormat
 +
| No
 +
| The users date format, see the API documentation for admin::userCreate for the format information
  
−
* Name - specify a suitable name for your SSO profile
+
|- style="vertical-align:top;"
−
* Enabled - when you are ready to switch on SSO, toggle this to the "ON" position.
+
| style="font-family: courier new;" | account:timeFormat
−
* Validate Time - toggle this to the "ON" position.
+
| No
−
* Validate certificate - toggle this to the "ON" position.
+
| The users time format, see the API documentation for admin::userCreate for the format information
−
* Realm - for a SSO Profile facilitating single sign on for the User App, Hornbill Administration, or the Service Portal, this should be set to "User". For a SSO Profile facilitating SSO for the 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
 
  
−
===Bindings===
+
|- style="vertical-align:top;"
−
For Web Browser Single Sign On, the bindings are used to transmit requests and responses between a service provider and an identity provider. Although these will be populated automatically based on the processing of your IdP meta data, it is possible to manually configure the following bindings:
+
| style="font-family: courier new;" | account:currencySymbol
 +
| No
 +
| The users default currency symbol
  
−
* HTTP-Post
+
|- style="vertical-align:top;"
−
* HTTP-Redirect
+
| style="font-family: courier new;" | account:countryCode
−
* HTTP-Artifact
+
| No
 +
| The users country code
  
−
Click the "'''+'''" located towards the right of the "bindings" section. Select the type of binding and specify the location and click "OK".
+
|}
  
−
==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
 
−
* [[User Templates | Template]]
 
−
* Enable
 
−
* Mapping
 
 
[[Category:Administration]]
 
[[Category:Administration]]

Revision as of 14:48, 22 December 2020

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

Related Articles

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?

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.

Clicking the "Import IDP Meta Data" button 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.


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
A SSO Profile can be enabled/disabled via the toggle switch available in the SSO profile (shown above) or via the list of SSO profiles


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:

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
Retrieved from "https://wiki.hornbill.com/index.php?title=Single_Sign_On_Profiles&oldid=25582"