- G Suite Business or Enterprise is required. Does not work on G Suite Basic.
- If you already have active users in ThoughtFarmer and you're looking to switch them over to G Suite, please open a Support request on the ThoughtFarmer Helpdesk.
- 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".
- Enter the below values for the step that requires you to enter the API scopes:
Thoughtfarmer sync configuration
- 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
- Go to Google's Service Accounts page
- 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++.
- 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.
- Go to the Google API Library. At the top, make sure you have your ThoughtFarmer project selected.
- At the top search bar, search for and select "Admin SDK"
- Click the Enable button
- In ThoughtFarmer, go to Admin panel -> Employee Directory Connector -> Add new external user store -> Select type "Google" and give it a name.
- 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.
"privateKey": "-----BEGIN PRIVATE KEY-----yourKeyHere-----END PRIVATE KEY-----\n",
"adminUser": "adminUserEmail@domain.com", "group": "yourGroupName"
- 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 G Suite field mappings is below.
|givenName (mapped with ThoughtFarmer's FirstName field)
|familyName (mapped with ThoughtFarmer's LastName field)
|primaryEmail (mapped with ThoughtFarmer's Email field if ThoughtFarmer's Email is not mapped with EmailAlias)
|manager (mapped with ThoughtFarmer's Manager field),
|thumbnailPhotoUrl (mapped with ThoughtFarmer's Image field)
- For the ThoughtFarmer user you're currently logged in as, if you want that user to be a G Suite 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 G Suite username, choose your G Suite in the drop down and save. Do the same for any other existing users in ThoughtFarmer that will come from G Suite. If the G Suite 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, open a request on our Helpdesk.
- 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.
- 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.
- 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 open a Support request on the Helpdesk.
- Click the Basic Information tab. If a user doesn't have a ThoughtFarmer account, but they're a member of the G Suite 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".
The steps for setting up the G Suite login also has 2 main parts. The first part is done on the G Suite end, the other is on the ThoughtFarmer end:
- Setting up a custom SAML application in G Suite
- External SAML login provider in ThoughtFarmer
G Suite Custom SAML app setup
- For cloud clients, the site url you'll use is the custom url on your domain (e.g: https://intranet.yourCompany.com) and not the default url that we set you up with initially (e.g.: 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.
- In this link, follow the steps 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.
- 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
- In the "Attribute Mapping" step, map the "Username" attribute in the application to the primary email. This can vary based on your requirements.
- 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
- In ThoughtFarmer, go to Admin Panel -> Login Provider. Add a new login provider under "External Providers". Select "Custom SAML".
- Fill in these ThoughtFarmer fields using the G Suite 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: G Suite's SSO Url. Remove "https://"; because it's already specified in the drop down menu next to it.
- External user store configuration: Choose your G Suite external user store.
- Certificate: Open the X.509 certificate in Notepad and copy the value into the certificate field.
- *Certificate expiry - In G Suite, 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 G Suite 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: G Suite's Entity Id
- Log out of ThoughtFarmer and access your site again using a member of the G Suite 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 G Suite logs (https://support.google.com/a/answer/7007375?hl=en ) to determine root cause.