SAML Single Sign On Integration

Transcription

1 SAML Single Sign On Integration (Document for FluidReview Clients) November 29, 2016, Revision #2, Heather McBride Jessica Doyle, Sean Clancy, Nate Beacham, Adam Di Tota, Jonathan Waldron Abstract: Single Sign-On (SSO) is a session and user authentication service that permits a user to use one set of login credentials (e.g., name and password) to access multiple applications. In the context of FluidReview, SSO implementation allows clients to leverage their existing user authentication framework to permit and provision access to a FluidReview site. By the end of this document you will know how to set up such an integration using SAML protocol. The key topics covered in this document are: How SAML SSO works with FluidReview Configuration Instructions Testing Procedures Best Practices Resources Who should read this: This document was created to assist FluidReview clients, FluidReview Customer Engagement Representatives, and FluidReview Support Staff in setting up a SAML SSO integration with FluidReview. 1

2 How SAML SSO works with FluidReview: Entities Involved There are 4 key entities to an SSO integration: User who signs in Identity Provider (IdP) Service Provider (SP) SSO Protocol User who signs in The user is an applicant or reviewer, who is trying to login and access FluidReview. Identity Provider (IdP) The Identity Provider is an instance of an SSO issuing server that is responsible for housing and validating a user s account credentials as well as provisioning access. It has a few main purposes: 1) Provides unique identifiers (UID) for users looking to interact with a system or software. 2) Emits other user account information (attributes), as allowed by the the third party, along with any other account metadata necessary for the integration to FluidReview. 3) Provisions user account access to FluidReview. 4) Establishes a trust with FluidReview. Service Provider (SP) The Service Provider is the software or system, in this case FluidReview, establishing a trust relationship with an IdP and requesting user account provisioning from that IdP. It is also responsible for consuming information (attributes/metadata) that may be passed from the IdP. SSO Protocol The protocol is what facilitates the integration between the IdP and SP. It defines the handshake (sequence of events/data passing) for the integration. How It Works SSO works by creating an integration between an IdP and FluidReview via the SSO protocol. The handshake passes along key user information, including the UID. The key role of the IdP is to verify that a user s information is known and that correct account details have been provided. Once FluidReview has received the verification, the user is then able to access FluidReview. A new FluidReview account will be created for a user if one does not already exist. If an account 2

3 already exists for this user, FluidReview will match the incoming user to the pre-existing account using the address received from the IdP. SSO can be initiated in two ways: SP-initiated and/or IdP-initiated. SP-initiated Service provider initiated SSO is when a user comes first to the FluidReview site, clicks the SSO sign-in button and inputs their username and password. This then starts the authentication process with FluidReview sending out a call for authentication to the IdP. IdP-initiated Identity provider initiated SSO begins when a user signs into the client s main hub, not FluidReview. The user clicks an option on the company s page that brings them into FluidReview. In this case the IdP is initiating the sign-on to FluidReview. NOTES: FluidReview s SAML integration feature has two iterations, SAMLv1 and SAMLv2. FluidReview only support IdP-initiated SSO using SAMLv2. If you require compatibility with Federation Services such as CAF or InCommon please speak to your Customer Engagement Representative to discuss options. Know IdP-initiated SSO is not available if compatibility with Federation Services is required. Due to the technical nature of implementing an SSO Integration, and the vast number of authentication services, FluidReview requires there to be a technical expert experienced with SSO integrations to be facilitating the integration aspects on your end. Configuration Instructions: Before getting started with the integration we recommend that you read through the Best Practices section of this document. The instructions below focus on the steps necessary for setting up an SSO integration within FluidReview. Please note that an SSO integration also requires setup/configuration of the IdP on the client s side. To begin setup, access FluidReview s Admin Interface. Navigate to the Edit your site tab The basics Registration tab click Configure advanced options. 3

4 This will bring you into the SSO configuration page on the FluidReview end. There are four tabs, facilitating different SSO integration options. The first tab (the default) is for SAML. The first step is to grab FluidReview s SAML metadata found in the blue bar at the bottom of the SAML integration tab: 4

5 The link will open a screen full of our SAML metadata. This metadata is to be saved and copied into your IdP server. When configuring this metadata in your IdP, please ensure you have set it up to automatically consume our metadata. 5

6 6

7 The next step is to complete the required configuration of your IdP. Once the setup/configuration has been completed on the IdP end, the next step is to return to FluidReview to complete the integration. To do this, navigate to the Edit your site tab The basics Registration tab click Configure advanced options. In the SAML tab click the Add IdP button. This will then bring you to a page with three tabs; Information, Attribute Mapping, and Lookup. The bulk of the setup happens in the Information tab. 7

8 8

9 In order to complete/save the integration, the following fields are required: Name, Entity ID, Logo, and Metadata. Additional explanations for the fields are as follows: Name: Provide a title for this SSO integration Metadata URL: URL to access FluidReview metadata for the site (does not need to be changed) Entity ID: ID of their IdP UID: This field should not be adjusted. It is a set piece in FluidReview s SAML metadata that is used as the unique identifier in our system (i.e. the user's ). If the IdP is correctly consuming FluidReview s metadata this attribute is set up to release to FR, using that ID. Logo: This is required. This logo will appear on the login page for those doing SP initiated SSO. Help Text: Help message that can be edited if desired. Metadata: Where the metadata generated from the IdP goes. Logout redirect (if applicable): This field can be used to redirect a user to a page other than FluidReview after Single Log Out has been performed. The next tab in the integration is Attribute Mapping. This is where additional user attributes from the IdP can be mapped to fields in FluidReview upon a user successfully signing in through the SSO. We highly encourage and recommend the attributes of a user s name are released and mapped to FluidReview. 9

10 Attribute name is where to insert the Friendly name of an attribute that is being passed to FluidReview from your IdP. The Destination, is a dropdown list, of all available fields for those attributes being passed from your IdP to be mapped in FluidReview. The destination has default fields of First Name, Last Name, and Full Name. These map to the user s information in the manage users page of FluidReview. Ideally, a user s name should be mapped to the individual First Name and Last Name Destination fields to ensure the user's name is broken up correctly. If you do not have users first name and last name stored separately on your IdP, you can map the user s name to Full Name in the Destination. FluidReview will then break the name up into firstname/lastname. Additional attributes can be pulled into FluidReview. To set this up you will need to add Metadata fields in FluidReview by going to Configure your site tab Metadata. Make sure you set the Metadata field to target Users and the type as text entry. For more information on setting up Metadata fields in your site please visit the following document: Once the metadata field(s) has been created it will show up in the Destination dropdown of the SSO SAML configuration. 10

11 The final tab Lookup is meant to be used in a few specific cases only. We do not encourage editing this tab unless you have been instructed to by your Customer Engagement Representative during the implementation process. Testing Procedures In order to properly test the SSO integration, login credentials for test accounts are required (at minimum, one per user group that is established with SSO). It is recommended that you have test users for each group in your site. These test users must be shared with your Customer Engagement Representative to help in testing and troubleshooting. Only applicants and reviewers should be coming into the FluidReview site via the SSO; there should not be any co-applicants or recommenders. The SSO integration should be configured at least two weeks before the site goes live. Two weeks allows time to sufficiently test as well as troubleshoot issues. During this time 11

12 FluidReview requires the SSO technical expert implementing the integration on your side, to be on hand to promptly adjust SSO integration configurations on the IdP as issues appear. Key scenarios you want to test for are: Applicants are able to successfully sign-in through the SSO. Upon signing in as a test applicant through the SSO you will want to check in the administrative end of FluidReview that they were successfully added in to Manage Users. You also want to check in Manage Users that all information is being pulled into FluidReview correctly. I.E. the name of the user, and their are pulled over and put into the correct fields in FluidReview. If further user attributes have been mapped you will want to check they have also successfully mapped over upon the user singing-on. The columns option in the manage user section can be used to add those additional user metadata fields to your manage users page. To check the fields have been mapped click Manage your site tab Manage users. In the table you will see columns for , First Name and Last Name. If mapping additional attributes to FluidReview you can add those metadata fields to the column table by clicking the columns option in the top toolbar metadata check off the fields you wish to add click done. 12

13 Unique ID (UID) is working to correctly match a returning user to their existing account. Once you have succesfully signed-on with a test user, and created/started a submission, sign-out of the site and then sign back in as that same individual. Check to make sure it brings you back into that specific FluidReview account, with a submission already started. If it brings you in, and the work you had previously done as that applicant is not available you will want to check in the administrative end of FluidReview if there are now two user account profiles for the same test user. If this is the case there is an issue with the UID. Reviewers are able to sign-in successfully through the SSO (if configured). SSO integration defaults all new users your FluidReview site to one group, the Applicant Group. As such, in order to ensure your reviewers have the right access in FluidReview you will first need to have them added into FluidReview prior to their first SSO sign-on. You can do this by going to Manage your site tab Add user. Ensure the reviewers are added into their correct Reviewer group (if there are multiple reviewer groups for the site). Upon signing in as the Review check they are brought in under the correct reviewer group. They should be brought to the reviewer summary page, not the applicant main screen. Single Logout is working correctly (if configured). Testing Single Logout is only required if you have configured it through your IdP. Single-Logout allows a user to terminate all SSO sessions opened via one log-out, i.e. signing out of FluidReview signs the user out of FluidReview, and ends their SSO session so they have to sign back into the SSO/be re-authenticated by the IdP. When a user chooses to log out of FluidReview, ideally it should also log them out of the IdP, ending the authentication session. When testing Single Sign Off, the easiest way to tell if it is configured correctly is that the user will be forced to sign back in after signing out through FluidReview. If the user manages to logout of FluidReview, but is able to return to the FluidReview site and access their submission without having to re-enter their credentials, Single-Logout has not been correctly configured through the IdP. Note: If your SSO configuration keeps a session open upon the user logging on, we highly recommend that Single-Logout is configured as there are security concerns if it is not. 13

14 Logout Redirect is working correctly As discussed on page 7 of this document, one option for configuration inside of FluidReview is to set up a logout redirect. This redirect should only be used if you are not able to configure Single Logout correctly. To test this, click the user's name in the top right select Sign out. Upon selecting Sign out the user should be brought to the url that was added in the logout redirect. In addition to testing that the sign-in and sign-off components are working correctly, full tests though complete applications should be run using users coming in through the SSO, testing all potential submissions, links, tasks and resources ensuring everything is working as desired. If issues are discovered during initial testing of the SSO there are some key pieces of information required to help resolve the issue: the type of user being tested, the login credentials for that user, and the error message (if one is displayed). Screenshots of error messages are always encouraged. 14

15 Best Practices 1. Registration settings: Once the site is launched, and the SSO integration is set up, you will want to ensure Registration is OPEN for the site in general by going to the Dashboard and adjusting the Registration option under Quick Controls to read Open. If you do not open registration in the Quick Controls, users not already added to FluidReview will not be successfully added to manage users and registered as an applicant, nor will they be able to create applications. This happens because when a user signs in for the first time using the SSO, if FluidReview finds they do not already have a user account in the Manage Users section of FluidReview, FluidReview registers them with an account. You will also want to ensure registration is open for the applicant group(s) allowing users signing in to create applications for that group(s). You can do this by going to the Edit Your Site tab Groups. 15

16 For applicant group(s) where registration is closed but needs to be open, click the check box to the left of the group's name in the table, click registration in the top toolbar and select Open Registration. 2. Homepage Sign In buttons: Once the integration is fully configured in FluidReview you will notice an additional button showing up on the landing page/home page of the site. 16

17 The first highlighted section above starting with Sign In is the FluidReview sign on. The Sign in or Register button below it is the button to sign-on through the SSO. The final section highlighted, Need an Account? is the button for users to be brought to a FluidReview Registration page. It is best practice to only have users entering the site through the SSO. As such you will want to hide the FluidReview registration/sign in button. This is done by ensuring the only available option to sign-in is through the SSO. You do this by navigating to the Edit your site tab The basics Registration uncheck Allow users to sign in via FluidReview under the Single Sign On Section. Ensure no other options are selected here. 17

18 Once you have saved this change you will only see a button to sign in through the SSO on the homepage. *Note: Administrators without an SSO account login, can still sign on to the site through the FluidReview login. To access the signon page you will need to add /admin/ to the end of the sites url. For example: testsite.fluidreview.com/admin/ 3. Contact Details: Key contact details for the main individual implementing the SSO integration on the your end should be provided to your Customer Engagement Representative. 4. General Settings: In General settings, under the other stuff tab you will want to disable the ability for users to change their address as FluidReview s SSO integration default is to use the address as the UID. To do this navigate to the Configure your site tab General Settings Other Options tab. Check off prevent users from changing their address and then in 18

19 the section that pops up right below, select all groups that are using the SSO to sign in to FluidReview. 5. SAML Integration: Consumption of FluidReview Metadata With SAML SSO integrations you want to ensure the integration has been set up to automatically consume FluidReview s SAML metadata, if possible. This is to ensure that if the FluidReview SAML metadata updates (happens very rarely), your IdP will automatically pull and accept the update. This is to ensure you are always consuming the most up-to-date FluidReview SAML metadata, mitigating risk of SSO issues should FluidReview s SAML metadata change. 19

20 6. SAML SSO integration for sites with CNAME s Sites wishing to use a CNAME, should have the CNAME in place prior to configuring the SSO. If the CNAME is not added to the site prior to the SSO being setup issues might occur as FluidReview s metadata and url to post attributes/responses to will update to the CNAME url. If you are automatically consuming FluidReview s SAML metadata there should not be an issue if the CNAME is added after the SSO configuration. However not all integrations can be setup to automatically consume our metadata. If that is the case, if the CNAME is added after the SSO has been configured it is likely that the integration will need to be adjusted to ensure it is pulling the correct metadata. 7. FluidReview User Groups for sites with SSO SSO integration should only be used for sites where recommenders and co-applicants are not used. Sites using SSO for recommenders and co-applicants always experience issues caused by incorrect s address being entered, causing multiple user accounts for the same individual, and accounts that are not connected to the SSO. Note:If they absolutely have to have co-applicants or recommenders, it is recommended that you substitute the sign-on/confirmation URL in the s in Text and Translation to be the URL for the SSO. 8. Issue with your IdP having more than one address for each SSO account: If your users signing-on through the SSO have more than one address tied to their SSO account, and the username they use to log-in is not that of their , FluidReview needs to ensure and verify which address you are passing to FluidReview. This is important for your Reviewer s as they are added into the FluidReview site prior to their first log-in of the SSO. Since FluidReview only allows for one address to be passed, and we look up if a user already exists in FluidReview based on the UID (their ), we need to ensure that the reviewers have been added to the site using the that is being passed from the IdP to FluidReview. If reviewers have been added to FluidReview using a different than what is passed from the IdP upon login, a new user will be created for them as an applicant, instead of them being matched to their already existing reviewer account. 20

21 Resources SSO documentation found on Help desk To report a bug/issue or to ask a Support question, please log into your site as an administrator or if you have a vanity URL. 21