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 CAS protocol. The key topics covered by this document are:
- How CAS SSO works with FluidReview
- Configuration Instructions
- Testing Procedures
- Best Practices
Who should read this:
This document was created to assist FluidReview clients, FluidReview Customer Engagement Representatives, and FluidReview Support Staff in setting up a CAS SSO integration with FluidReview.
How CAS SSO works with FluidReview:
There are 4 key entities to the SSO integration:
- User who signs in
- Identity Provider
- Service Provider
- SSO Protocol
The user is an applicant or reviewer, who is trying to login and access FluidReview.
IdP (Identity Provider)
Is responsible for housing and validating a user’s sign-on credentials, as well as passing the approval notification to the authorized service providers. It has a few main purposes:
- Provides unique identifiers (UID) for users looking to interact with a system or software.
- 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.
- Provisioning user account access FluidReview.
- Establishing a “Trust” with FluidReview.
There are numerous IdPs that your client can have. As such the specific IdP will vary on a client by client basis.
SP (Service Provider)
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
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 a client's IdP and FluidReview via the CAS protocol. The handshake passes along key user information, including the UID. The key role of the IdP is to verify, for FluidReview, that the users information is known, and correct account details have been provided.
With CAS integration there is a direct connection created between FluidReview and the authentication service (IdP). When configuring the CAS integration with FluidReview, site administrators enter their CAS Service URL into FluidReview. This URL is used to automatically redirect users to a CAS login server. Once the user inputs their credentials an authentication token/ticket is provided back to FluidReview approving the user's login to the FluidReview site. This ticket that is passed from the CAS login server contains some key user information such as the Unique ID.
Once FluidReview has received the user’s information, it proceeds to create an account for that user, if one does not already exist inside of FluidReview. If a user account in FluidReview already exists, FluidReview will match the user signing in to the already existing account using the email address that has been passed along from the IdP.
SSO integration using the CAS protocol can only be initiated by FluidReview, it cannot be initiated from the IdP. FluidReview’s CAS integration currently supports v2 and up.
Due to the technical nature of implementing an SSO Integration, and the vast number of authentication services that clients can have, FluidReview requires there to be a technical expert on the client’s end who has a background or strong knowledge of SSO.
Before getting started with the integration we recommend that you read through the Best Practices section of this document.
The first step in building a CAS SSO integration with FluidReview and an authentication service (IdP) is to set up a certificate for FluidReview, input it into the store of trusted certificates on the IdP. Once this initial configuration on the IdP is done the configuration inside of Fluidreview should be as follows:
Navigate to the “Edit your site” tab → “The basics” → “Registration” tab → click “Configure advanced options”.
Once you click configure advanced options, you will be defaulted to our recommended SSO protocol offering of SAML. You will see the third tab is titled “CAS”. Click that tab to be brought to the CAS integration page.
Before you save, the following fields are required: Service Name and Service URL. It is highly recommended that you input your desired attribute in the UID Attribute Name field, but it is not required. Additional explanations for the fields are as follows:
- Service Name: The service name is a required text field. This text is what is used to title the CAS sign-in button.
- Service URL: This should be the url that leads to the current protocol service (the IdP).
- Path: This field should not be adjusted.
- Entry Group: This is the group in FluidReview that all new users signing in through the SSO will be defaulted to. Usually this is set to be the applicant group.
- Note: the SSO can be used for your Reviewers and Administrators as well. These users need to be added to your FluidReview site, and added to their correct reviewer or administrator group, prior to their first log-in. This ensures they are matched to the already-existing account with reviewer or administrator privileges instead of a new account being created for them in the defaulted entry group.
- UID Attribute Name: This is the attribute that is being sent over from the IdP as the unique ID. If it is not id, uid, or user then the name of the attribute here being used as the UID should be input here. If left blank FluidReview will default to looking for the attributes of id, uid, and user.
User Account Details in FluidReview:
For SSO integrations using CAS, FluidReview handles payloads automatically. As such, FluidReview defaults to looking for the standard attribute names for First Name, Last Name, and Email of a user to complete their user profile information in FluidReview. FluidReview requires the following attributes to be passed:
FluidReview Required Attribute
Accepted Standard Attribute Names
firstName, first_name, or givenname
lastName, last_name, or sn
email, or mail
id, uid, or user*
*Note: for UID only, FluidReview looks for the default standard attributes of id, uid, or user unless a different attribute name has been input in the “UID Attribute Name” field in the CAS Integration setup page in FluidReview.
Additional Attribute Release via CAS:
Additional attributes can be released to FluidReview. With CAS the integration of attribute release is set up through the IdP. For CAS “Return Mapped Attribute release” is the attribute release policy that will facilitate attributes being released from the IdP to FluidReview. The attributes released from the IdP are placed into metadata fields in FluidReview. FluidReview User metadata fields are automatically created when additional attributes are sent to FluidReview.
To add metadata fields in FluidReview navigate 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: https://fluidreview.zendesk.com/hc/en-us/articles/221688628-Understanding-Metadata
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 prior to the site going live. Two weeks allows time to sufficiently test as well as troubleshoot issues. During this time 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 email 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. 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 “Email”, “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.
- 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.
SSO integration defaults all new users to the 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 through the “Add user” option in the “Manage your site” tab. Ensure the reviewers are added into their correct Reviewer group (if there are multiple reviewer groups for the site), as well as added as team members to their correct teams if applicable.
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.
In addition to testing that the sign-in components are working correctly, full tests through 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.
- 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. Adjust 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”.
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”.
- 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.
* Note: The CAS SSO Sign-In button title is editable. The title is pulled from what was entered as the “Service Name” in the CAS tab of FluidReview.
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.
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/
- 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.
- General Settings:
In General settings, under the “Other Options” tab you will want to disable the ability for users to change their email address as FluidReview’s SSO integration default is to use the email 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 email address” and then in the section that pops up right below, select all groups that are using the SSO to sign in to FluidReview.
- 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 email addresses being entered, causing multiple user accounts per individual, and accounts that are not connected to the SSO.
Note: FluidReview recommends a single point of entry, whether through the SSO or native FluidReview login, per user group type (i.e. recommenders, applicants, reviewers). As such, we never recommend co-applicant functionality in a site using SSO. However, “Request for recommendation” functionality is acceptable as long as the recommenders are only using the FluidReview native login.
To report a bug/issue or to ask a Support question, please log into your site as an administrator https://yoursite.fluidreview.com/helpdesk/contact/ or https://example.yoursite.com/helpdesk/contact if you have a vanity URL.