Configuration Guide - Single-Sign On for OneDesk Introduction Single Sign On (SSO) is a user authentication process that allows a user to access different services and applications across IT systems and organizations. OneDesk supports SSO over Security Assertion Markup Language version 2 (SAML2) protocol as well as OAuth version 2. SAML 2.0 defines 2 roles for the parties involved in the single sign on process: the service provider (SP) role and the identity provider (IdP) role. The SP grants access to the services and resources that it hosts to users authenticated by the IdP. OneDesk Single Sign On (SSO) implements the Service Provider (SP) role and can use security tokens issued by SAML2 compatible Identity Providers (IdP). OneDesk accepts both SP initiated and IdP initiated logins. SAML2 protocol is supported and implemented by the major players in the Identity and Access Management field, including: Active Directory Federation Services 2 (ADFS2) or newer, and many others. Prerequisites A SAML 2.0 enabled Identity Provider. In case of Active Directory it needs to be at least Active Directory Federation Services 2.0 (available as a separate installer for Windows Server 2008 R2 or newer). For Windows Server 2008 R2 the default ADFS role is not SAML2 compatible (the default role is ADFS version 1.0). For Windows Server 2012 and newer the default ADFS role is SAML2 compatible. You also need the metadata file from your IdP. The IdP metadata can be uploaded in OneDesk either as a URL, if your IdP server is accessible from the internet, or as a file, if your server is not accessible from the internet. The metadata URL for an ADFS server is located at an address like the following: https://<your_adfs_server_address>/federationmetadata/2007 06/FederationMetadata.x ml (please replace <your_adfs_server_address> with the correct address for your ADFS server).
Configuration of SSO in OneDesk In this section we ll configure OneDesk to accept SAML tokens from your IdP. Log in with an account that has administrative privileges. Go to Administration > Integrations > Single Sign On. Expand the Configure Single Sign On section. Check the enable sso box. OPTIONAL: If you want your IdP authenticated users to automatically get created and granted access when they attempt to access the OneDesk application, check enable user provisioning. Provide your IdP s metadata to OneDesk: if you have a metadata file please click choose file and select the file that contains the metadata if you have an URL, fill in the your identity provider metadata url You will notice that OneDesk Single Sign On present you 2 links: 1. onedesk metadata url: you will need this link to configure your IdP 2. onedesk sso login url: this is the link to provide to your users for SP initiated login (this link might not appear until you set the correct parameters in the Advanced Settings ) Depending on your IdP, there might be some Advanced Settings that need to be set before SSO can work.
As these details are dependent on your specific IdP, they will be provided in the next sections where we address the configuration of specific IdPs. Configuration of SSO in your Identity Provider In this section we ll configure your IdP to send SAML tokens to OneDesk. There are a multitude of IdP solutions available, but the principles are the same for all. We will address the configuration details for two of them: A generic Identity provider (genericidp), and ADFS2. Please contact your server administrator or our support team for help with other IdP s. Example Configuration of standard IDP generic IDP Your identity provider metadata url is https://idp.genericidp.com. In the Advanced Settings in OneDesk Single Sign On configuration you need to set the your identity provider entity id to http://idp.genericidp.com. In a new browser, log in in your genericidp account and add a New Service Provider. Name the new SP entry something meaningful for you (ex: app.onedesk.com ) and ensure that the outgoing security claims include the following information: email address mandatory first name optional last name optional The metadata required when adding a new SP entry can be obtained by navigating in a new browser to the link displayed in the onedesk metadata url in your OneDesk Administrative window.
You are now ready to use your genericidp SSO with OneDesk. If this IdP supports only SP initiated login, you will need to log in using the link provided in the OneDesk interface in the onedesk sso login url. If this IdP supports IdP initiated log ins then use the supplied link to login.
Configuration of ADFS2 When using ADFS2 you will need the following settings in the Advanced Settings in OneDesk Single Sign On configuration: fill in the email attribute with http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress fill in the first name attribute with http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname fill in the last attribute with http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname Please note that you need Active Directory Federation Services 2.0 or newer, as ADFS 1.0 does not support SAML 2.0. ADFS 2.0 comes as a separate installer for Windows Server 2008 R2. The newer versions of Windows Server (2012, 2012R2 etc) come with newer (and compatible with OneDesk s implementation) versions of ADFS. Your IT department should be able to provide you with the correct address for your entity provider metadata. In general, the address looks like this: https://<your_adfs_server_address>/federationmetadata/2007 06/FederationMetadata.x ml If your server is accessible over the internet, then simply paste this address in the your identity provider metadata url. If it is not accessible from the internet, download the metadata file to your computer and use the upload metadata file. For the next steps you will need to have administrative rights on your ADFS server. Open the AD FS management console. Go to Trust Relationships > Relying Party Trusts and add a new Relying Party Trust. Click Start, fill in the Federation metadata address (hostname or URL): with the value from onedesk metadata url.
Click next and ignore the warning message that advises that some of the metadata content has been skipped. Fill in a Display name and, optionally, the Notes with something meaningful for you. Choose if all your users are allowed or denied to access OneDesk. If you choose to deny all your users from accessing this relying party you will need to add specific authorization rules for specific users or groups later. This aspect is not covered by this configuration guide. Click Next 2 times and leave the Open the Edit Claim Rules box checked. Click Close. A new window Edit Claim Rules will open. Select the Issuance Transform Rules tab and add a new rule by clicking the Add Rule button. Select the Claim Rule template as Send LDAP Attributes as Claims and click Next.
Fill in the Claim rule name with something meaningful for your (ex: Claim rules for OneDesk SSO). Select Active Directory as an Attribute Store and add the following mappings: LDAP Attribute User Principal Name User Principal Name Given Name Surname Outgoing Claim Type E Mail Address Name ID Given Name Surname Click Finish and the OK. Now in the list of Relying Party Trusts double click on the one that you just saved. Go to the Advanced tab and select SHA 1 as the Secure hash algorithm.
Click OK. Your are now ready to use the OneDesk SSO with your ADFS. ADFS 2.0+ supports both SP initiated and IdP initiated logins. For the SP initiated log in use the link provided in your OneDesk administration under the label onedesk sso login url. For the IdP initiated log in use a link similar to the following: https://<your_adfs_server_address>/adfs/ls/idpinitiatedsignon.aspx and replace <your_adfs_server_address> with the correct address for your ADFS server. Versions tested: OneDesk SSO has been successfully tested for both IdP initiated and SP initiated logins from ADFS 2.0 (Windows 2008 R2 with ADFS RTM), ADFS 2.1 and ADFS 3.0 (Windows 2012 R2 with the default ADFS role).