Single Sign-On (SSO)Technical Specification Audience: Business Stakeholders IT/HRIS
Table of Contents Document Version Control:... 3 1. Overview... 4 Summary:... 4 Acronyms and Definitions:... 4 Who Should be Involved?... 4 2. Delivery... 5 How does SSO work?... 5 Benefits:... 5 Unique Identifier:... 5 Troubleshooting SSO Configuration... 5 IT Skillset Required... 5 Review SAML 2.0 SSO:... 6 Client Responsibilities:... 6 SAML SSO WORK FLOW... 6 SAML Requests:... 8 Appendix... 9 Appendix A Frequently Asked Questions (FAQ)... 9 Single Sign-On (SSO) Technical Specification 2
Document Version Control: Change Date Version Change Description Updated by Feb 2016 1.0 Created Final Version Bernard Brazeau Single Sign-On (SSO) Technical Specification 3
1. Overview Summary: The purpose of this document is to describe, in functional and technical details, the out-of-thebox Single Sign-On solutions to the BirdDogHR platform (application). For discussions around any custom SSO solution not detailed in this document, please contact your Sales Representative, or Account Manager. Acronyms and Definitions: The following are definitions of Acronyms identified in the project. Term BirdDogHR or BDHR Client IdP SAML SP SSO Definition The BirdDogHR team or platform (application). Prospective Clients and Clients implementing Single Sign On to BDHR. Identity Provider (On client side.) Security Assertion Markup Language. Service Provider (on BDHR). Single Sign-On. Who Should be Involved? This document is intended for two primary audiences: Business Stakeholders who have in-depth knowledge of the overall business requirements and objectives IT/HRIS individuals tasked with implementing SSO on the client-side interface. This technical specification will assist your organization in the planning and implementation of a SAML SSO between the client-side interface and BDHR. Single Sign-On (SSO) Technical Specification 4
2. Delivery How does SSO work? The Single Sign-On (SSO) solution allows BDHR to authenticate users into the platform upon user s request to access BDHR. (https:\\<domain Prefix>.portal.bdhr.com). This affords user s access to BDHR without having to log-in; once the user has been authenticated on client side. BirdDogHR supports an out-of-the-box SAML 2.0 SSO solution. Benefits: Some benefits of integrating SSO with BDHR include: Ability to leverage existing security and authentication policies. Simplify the User log-in experience without requiring additional authentication (no need for users to know their BDHR credentials). Prevent simultaneous log-in by a User into BDHR from multiple locations Prevent login replay with time-based tokens Unique Identifier: User authentication process uses a user s unique identifier value. The default unique identifier is the SAML Username. To facilitate a successful login, client is responsible to make sure: 1. The unique identifier value is indeed unique (no two users share the same Username). 2. Only one instance of the user record in BDHR has a given identifier value, for example one user s email address is not another user s username or vice versa. Troubleshooting SSO Configuration If client faces any issue with configuring the SSO, client must provide a fiddler trace to the project manager, please see appendix C on how to capture a fiddler trace. BirdDogHR will evaluate the fiddler trace and provide feedback the client to identify the source of the issue. IT Skillset Required SAML SSO: requires a Tech Savvy IT resource familiar with SAML Server setup BirdDogHR can provide very limited tech support on the tasks that are defined as client s tasks, due to security concerns. Single Sign-On (SSO) Technical Specification 5
Review SAML 2.0 SSO: SAML is a XML-based standard for exchanging authentication and authorization data between security domains, that is, between an identity provider (IdP), producer of assertions on the Client side, and a service provider (SP), a consumer of assertions on the BirdDogHR side. Note 1: Clients that implement SSO using the SAML solution typically have a SAML/IdP server in place and have used it to integrate SSO with other applications. Note 2: Utilizing SAML 2.0 allows the Client to send a logout assertion to BirdDogHR to log a User out of BirdDogHR if he/she has logged out of the Client network. Note 3: BirdDogHR supports both IdP initiated and SP initiated SSOs. Client Responsibilities: The Client is responsible for: 1. Submitting their AD FS Metadata URL. 2. Configuring their server: a. Create Trust Relationship (from BDHR s Metadata URL) b. Add Claim Note: The nature of SAML authentication necessitates technical implementation on the client side. BirdDogHR will assist by answering basic questions and/or providing an FAQ document as a resource. If the Cclient Name requires additional technical resources from BirdDogHR, additional fees will be assessed on an hourly basis at $175/hour with a minimum of 1 hour each engagement. Single Sign-On (SSO) Technical Specification 6
SAML SSO WORK FLOW Upon user s request to access BirdDogHR, the IdP Server at Client s end exchanges Authentication Data with Authentication Server at BirdDogHR s end. The process flow is as illustrated below: 1. User initiates the request to login to BDHR 2. BDHR generates a SAML request 3. BDHR redirects the user s browser to the Single Sign On (SSO) URL 4. Client s IdP parses the SAML request to authenticate the user 5. Client s IdP generates the SAML response Yes they are user or No they are not a user 6. Client s IdP returns to the browser an encoded SAML response that is passed to BDHR 7. BDHR verifies the SAML response 8. BDHR allows or denies access to the user based on response Single Sign-On (SSO) Technical Specification 7
SAML Requests: With SAML 2.0, the Client is able to send Login requests to BDHR. The below table describes the parameters of the SAML 2.0 response message BirdDogHR expects to receive from the Client to request User log-in and the validation steps performed by BDHR: Element Definition BDHR validation steps NameID This element contains the User's identifier information to log-in to BDHR. Verify the User information in BDHR s database. The User must be an existing, Active User in both the Client's User Provisioning AND BDHR s platform. Otherwise, access is denied to the User. Single Sign-On (SSO) Technical Specification 8
Appendix Appendix A Frequently Asked Questions (FAQ) 1. When deploying SSO, can it be rolled out on a user by user basis, or is it only applied to all users at once? a. Either really, it depends on how you want to roll this out to your team. 2. Is the UserID used to authenticate a user in Windows (or Active Directory) the same as the UserID in BirdDogHR for that user? a. Not necessarily. SSO solution needs a unique Identifier value to authenticate a user which is the NameId in the claim. This usually is mapped back to the Windows UserId but not always. Different LDAP Attributes could be used instead of the Windows (Active Directory) UserId. For Example: i. Email Addresses: Email Addresses ii. SAM A CCOUNT Name: kenos iii. User Principle: kenos@industrypeople.local 3. How can I find the Metadata URL? a. One reference can be found here to help get you started: https://knowledgecenter.zuora.com/cf_users_and_administrators/administrator _Settings/Configure_Single_Sign- On_for_Zuora/Configure_Active_Directory_Federation_Services_for_SSO_SAM L b. In AD FS Management Console, browse to Service > Endpoints > Metadata > Type: Federation Metadata to find your federation metadata URL. Browse to that location or Copy and paste that location and send via email. Depending on which version of server you are in - https://server/federationmetadata/2007-06/federationmetadata.xml (this is an example of what it might look like). 4. Will setting up SAML authentication with BirdDogHR interfere with any other authentications we have set up in our organization? a. Set up of your AD FS server to work with SAML SSO login should not affect any other authentication you already have in place. You will be adding a new entry not changing any existing entries. HOWEVER, our best practice recommendation is to make changes of this nature after hours. Single Sign-On (SSO) Technical Specification 9
5. I m having trouble connecting, are there specific things I should look at to troubleshoot? a. It could be a lot of things but start by making sure the following settings are configured correctly. Single Sign-On (SSO) Technical Specification 10