Single sign-on with Google

Pre-requisites:

1. You must be an Appraisd administrator.
2. You must be an admin of your Organisation's Google account with permission to create new SAML apps.

Configuring the single sign-on app

Please follow the steps below to configure SAML SSO using Google for your Appraisd account:

1. Turn on the Single sign-on with SAML setting in the Advanced section of the Configuration area.
   
2. You'll now see a SAML single sign-on section appear in the left-hand column of the Configuration. Click into it.
3. Take note of the following values as we'll need them later:
   1. ACS (Consumer) URL
   2. Issuer ID
   3. Default Relay State
      
4. In a new tab, log into your Google admin centre. Then select Home>Apps>Web and mobile apps. Press on 'Add app' and select 'Add a custom SAML app'
   
5. Provide an app Name and Description which will be shown to your employees. We suggest:
   Name: Appraisd
   Description: Appraisd is the online platform used for our performance management at [Company Name] including reviews, objective tracking and peer feedback.
6. Add an app icon, then press 'Continue'. You can download the Appraisd app icon here
7. You will be shown IdP metadata on the next page which we need to copy and paste into the Appraisd single sign-on configuration page we have open in the other tab.
   
   SSO URL -> Identity Provider Single Sign-On URL
   Entity ID -> Identity Provider Issuer URL
   Certificate - > X.509 Certificate
   
   Make sure you save each field once you've pasted in the correct information. 
8. Back in the Google admin centre, press 'Continue'.
9. Copy data from the Appraisd single sign-on section into the Service provider details in the Google admin centre. 
   
   ACS (Consumer) URL -> ACS URL
   Issuer ID -> Entity ID
   Default Relay State -> Start URL (and tick 'Signed response')
   
10. In the 'Name ID' section choose 'EMAIL' from the 'Name ID format' dropdown
    
11. Select 'Continue'.
12. Most organisations do not need to add attributes or Group membership values. Just press 'Finish'
    
13. We now need to configure which of your users can access Appraisd using the Google SSO app. To do this click on the 'User access' panel.
    
14. For most organisations you will want to turn on the service for all users, but you can do it by turning on the SAML app for only specific user groups if needed. In our example case we will turn on the service for all users and press 'Save'.
    
15. Sign out of Appraisd in the other tab and navigate back to the SAML app overview page and press on 'TEST SAML LOGIN'. You should see a new browser tab open up where you may be asked to input your Google credentials and then you'll be logged into Appraisd and re-directed to the dashboard.
    
16. Go to the SAML section of configuration and copy the 'Service-initiated login URL'.
    Log out of Appraisd. Then confirm that you can use the 'Service-initiated login URL' to log into Appraisd.
17. Once you've confirm that your new Google SAML app is working, you can use the configuration area in Appraisd to allow access exclusively via SSO and switch off password access - this will make the system more secure.
    
    When your employees enter their email address, the SSO button will automatically load.
    

Troubleshooting

Here are things to check if SSO is not working:

• If you find some users cannot log in using SSO but some can, then it's unlikely to be a problem with Appraisd or the way you've configured your connection with Appraisd. Instead, ask them to try a different browser, and check that they have been configured in your identity provider with the same privileges to access the application profile as you.
• Make sure the NameID being passed to Appraisd is set to be the user's email address
• Ensure the email address in the identity provider matches the email in Appraisd exactly
• Are some people signed in to Chrome with two identities (eg one for work, one for personal)? If so, it could be trying to log in to Appraisd with their personal email address, not their work email. You can test this by signing out of the personal account and trying to log in again. If that's the problem, contact support@appraisd.com.

If you have any other issues, contact support@appraisd.com including details of any error messages you're receiving.