Documentation

GSuite

Pre-requisites

  1. GSuite Business or Enterprise is required. Does not work on GSuite Basic.
  2. If you already have active users in ThoughtFarmer and you're looking to switch them over to GSuite, please contact ThoughtFarmer first. 

Setup GSuite User Sync

  1. Click on this link and follow the steps under "Create the service account and credentials" and "Delegate domain-wide authority to your service account" to create a service account and setup "Domain-wide Delegation of Authority".

    service%20account.PNG      
     

Thoughtfarmer sync configuration

  1. To set up the sync on the ThoughtFarmer side, you'll need to gather and note down the below values:
    • Domain: Your organization's domain that is managed through Gsuite
    •  PrivateKey: 
      • Go to https://console.developers.google.com/iam-admin/serviceaccounts
      • Select your ThoughtFarmer project
      • If you haven't yet created a private key, use the ellipsis menu next to the service account name, select "Create key", then select JSON.
      • Open the file, copy the "private_key" value.  The file is in JSON format. It is best viewed in an editor like or NotePad++.

        create%20key.PNG
         
    • ClientEmail: The email of the service account you created. 
    • Customer: Go to  https://play.google.com/work/adminsettings?pli=1 , copy "Organisation ID". 
    • AdminUser: The username of an active admin user. The sync will impersonate this user.
    • Group: The name of the group containing users who you want to give ThoughtFarmer access to. It's best to create this in advance.
  2. Go to https://console.developers.google.com/apis/library. At the top, make sure you have your ThoughtFarmer project selected.

    1. At the top search bar, search for and select "Admin SDK"
    2. Click the Enable button
  3. In ThoughtFarmer, go to Admin panel -> Employee Directory Connector -> Add new external user store -> Select type "Google" and give it a name.
  4. Click the Configuration tab. Copy the below values, including the curly brackets. Paste it into the Configuration tab. Replace the dummy values with the ones you gathered in the previous steps, keep the double quotes.

    {
    "domain": "yourDomain",
    "privateKey": "-----BEGIN PRIVATE KEY-----yourKeyHere-----END PRIVATE KEY-----\n",
    "clientEmail": "email@yourOrganization.iam.gserviceaccount.com",
    "customer": "yourCustomerValue",
    "adminUser": "adminUserEmail@domain.com", "group": "yourGroupName"
    }
     
  5. Field Mappings: By default the first name, last name and email of users in the group that you are syncing with, will be populated in users' profiles. You can pull in additional fields by specifying this under the "Field mappings" tab. List of GSuite field mappings is below.

    field%20mappings.PNG
    givenName (mapped with ThoughtFarmer's FirstName field) EmailHome PhoneWork EmailAlias BuildingID 
    familyName (mapped with ThoughtFarmer's LastName field) EmailWork  PhoneMobile  EmployeeID  FloorName 
    primaryEmail (mapped with ThoughtFarmer's Email field if ThoughtFarmer's Email is not mapped with EmailAlias) EmailCustom  AddressHome JobTitle  FloorSection 
    manager (mapped with ThoughtFarmer's Manager field), EmailOther  AddressWork  Department    
    thumbnailPhotoUrl (mapped with ThoughtFarmer's Image field) PhoneHome  AddressOther  CostCenter   
  6. For the ThoughtFarmer user you're currently logged in as, if you want that user to be a GSuite user, you'll need to convert the account type to "External". Go to Admin Panel > User Management. Search for the user. On the right, click the gear icon > Edit Account. Change the type to "External", add the GSuite username, choose your GSuite in the drop down and save. Do the same for any other existing users in ThoughtFarmer that will come from GSuite. If the GSuite user doesn't have a ThoughtFarmer account yet, you can let the sync create the user. If you need help bulk changing many users at a time, contact ThoughtFarmer. 

  7. After you change the account type, you'll need to make sure you finish the authentication sections below, else, you won't be able to log back into the site after you're logged out. You could create a temporary regular user if you need to log out of ThoughtFarmer and log back in before finishing up the authentication steps. Then delete the regular user when you don't need it anymore.
  8. Click the Synchronization Settings tab. Click "Validate credentials". If your configuration settings are correct, the credential validation should be successful. You may have to refresh to see the status of the credential validation. In the daily synchronization section, you can set up a schedule where the sync will run at a certain time of the day and at a certain frequency. Then check off the sync tasks and click "Synchronization now" to run a sync.

    synchronization%20settings.PNG
     
  9. In case it fails you should be able to find out more about the reason for failure under Admin panel -> System Logs if you are a self-hosted client. Else if you're a cloud client, please contact ThoughtFarmer.
  10. Click the Basic Information tab. If a user doesn't have a ThoughtFarmer account, but they're a member of the Gsuite group that ThoughtFarmer is syncing with, you can have their account be automatically created after they log in without having to run a sync first. If you want this enabled, check off "User auto-creation".  

Setup Gsuite as an External SAML login provider

The steps for setting up the Gsuite login also has 2 main parts. The first part is done on the Gsuite end, the other is on the ThoughtFarmer end:
  1. Setting up a custom SAML application in Gsuite
  2. External SAML login provider in ThoughtFarmer

Gsuite Custom SAML app setup

  1. For cloud clients, the site url you'll use is the ustom url on your domain (ex: https://intranet.yourCompany.com) and not the default url that we set you up with initially (ex: https://intranet.thoughtfarmer.com). If you're a cloud client and you don't yet have your custom url, please wait for that to be set up before proceeding further.
  2. In this link, follow steps 1-17 under "Set up your own custom SAML app". Note down the Entity Id, SSO Url and download the X509 Certificate from step number 2. We'll need these values when we're configuring the login provider on the ThoughtFarmer side later on. 
    1. In the "Service Provider Details" window add the below information
      • ACS URL: Append "/auth/saml/assertionconsumerservice" to the end of your site url. (ex: https://intranet.yourCompany.com/auth/saml/assertionconsumerservice)
      • Entity ID: thoughtfarmer
      • Start url: BLANK
    2. In the "Attribute Mapping" step, map the "Username" attribute in the application to the primary email. This can vary based on your requirements.


       
  3. Turn on SSO for the users whom you want to provide access to ThoughtFarmer. In your Google admin console click the new SAML app you just setup and click "Edit Service" at the top right. Provide access to everyone or some users based on the requirement and save.

Add External SAML login provider on Thoughtfarmer Site

  1. In ThoughtFarmer, go to Admin Panel -> Login Provider. Add a new login provider under "External Providers". Select "Custom SAML".


     
  2. Fill in these ThoughtFarmer fields using the Gsuite values you copied earlier:
    • Hostname: Enter your site url. Remove "https://"; because it's already specified in the drop down menu next to it.
    • Login Provider complete hostname: Gsuite's SSO Url. Remove "https://"; because it's already specified in the drop down menu next to it.
    • External user store configuration: Choose your Gsuite external user store.
    • Certificate: Open the X.509 certificate in Notepad and copy the value into the certificate field.
      • *Certificate expiry - In Gsuite, click on your ThoughtFarmer SAML app > Service Provider Details. Keep track of the expiry date for the certificate. You'll need to make sure the certificate is renewed before the expiry date. If the certificate in Gsuite changes, it should be updated in the Certificate field in the ThoughtFarmer login provider page.
    • Configuration options: check off "Want Assertion Signed"
    • Issuer URL / Name: Gsuite's Entity Id


       
  3. Log out of ThoughtFarmer and access your site again using a member of the Gsuite group that ThoughtFarmer syncs with. A successful login should bring you back to Thoughtfarmer. If you are unable to login, please look at Admin Panel -> System Logs (if self-hosted) and Gsuite logs (https://support.google.com/a/answer/7007375?hl=en ) to determine root cause.