Google Workspace (G suite)
Pre-requisites
- Requires a Google Workplace subscription. Works with all pricing tiers.
- If you already have active users in ThoughtFarmer and you're looking to switch them over to Google Workspace, please open a support request on the ThoughtFarmer Helpdesk.
Setup Google Workspace User Sync
- Go to these instructions for Performing Google Workspace Domain-Wide Delegation of Authority and follow the steps under the headings 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 values below for the step that requires you to enter the API scopes:
- https://www.googleapis.com/auth/admin.directory.group
- https://www.googleapis.com/auth/admin.directory.user
- Enter the values below for the step that requires you to enter the API scopes:
Thoughtfarmer sync configuration
- To set up the sync on the ThoughtFarmer side, find and make a note of the values below:
- Domain: Your organization's domain that is managed through Gsuite.
- PrivateKey:
- 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 to whom you want to give ThoughtFarmer access. It's best to create this group in advance.
- Go to the Google API Library. At the top, make sure your ThoughtFarmer project is selected.
- In the top search bar, search for and select Admin SDK.
- Click the Enable button.
- In ThoughtFarmer, go to the Admin panel: Users & security section > Employee Directory Connector page.
- Click +Add new external user store. On the New external user store page, give the user store a name and select Google from the Type dropdown menu. Click Save.
- Click the Configuration tab. Copy the values below, including the curly brackets. Paste it into the Configuration tab. Replace the dummy values with the ones you gathered in the previous steps, keeping 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"
}
- Click the Field Mappings tab. 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 adding them here. List of G Suite field mappings is below.
- To add a field mapping, click +Add. Select the ThoughtFarmer field from the dropdown menu, Enter the corresponding G Suite field mapping in the External store field box, select Gsuite as the Data owner, and click the Save icon. Repeat to add more field mappings.
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
- To add a field mapping, click +Add. Select the ThoughtFarmer field from the dropdown menu, Enter the corresponding G Suite field mapping in the External store field box, select Gsuite as the Data owner, and click the Save icon. Repeat to add more field mappings.
- If you want the ThoughtFarmer user you are currently logged in as to be a G Suite user, convert the account type to External using the steps below. Repeat for any other existing users in ThoughtFarmer that will come from Google Workspace. If the Google Workspace 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.
- Go to the ThoughtFarmer Admin Panel: Users & Security section > User Management page.
- Search for the user.
- On the right of the user in the results, click the gear icon. Select Edit Account from the dropdown menu.
- Change the Account type to External, choose your Google Workspace in the Employee Directory Connector configuration dropdown menu, and enter the Google Workspace username.
- Click Save.
After you change the account type, make sure you finish the authentication sections below, otherwise 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.
- Back on the ThoughtFarmer admin panel external user store page (Admin panel: Users & security section > Employee directory connector page. Click on the Google user store that you created.), 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 to run the selected synchronization tasks at a certain time of the day and at a certain frequency. To run a sync on demand, select the checkboxes for the synchronization tasks you want to run and click Synchronize now to run a sync.
- In case it fails:
- If you are an on-premise/self-hosted customer, you can find out more about the reason for the failure under the ThoughtFarmer Admin panel: Logs & statistics section > System Logs page.
- If you are a cloud client, please open a Support request on the Helpdesk.
- On the external user store page, click the Basic Information tab. If a user doesn't have a ThoughtFarmer account, but they are a member of the Google Workspace 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, select the User auto-creation checkbox. Click Save.
Setup Google Workspace as an External SAML login provider
There are two parts to setting up the Google Workspace login:- Setting up a custom SAML application in Google Workspace
- Add an external SAML login provider on ThoughtFarmer Site
Google Workplace Custom SAML app setup
For cloud clients, the site url you will use is the custom url on your domain (eg. https://intranet.yourCompany.com) and not the default url that we set you up with initially (eg. https://intranet.thoughtfarmer.com). If you are a cloud client and you don't yet have a custom url, please wait for that to be set up before proceeding further.
- Go to these instructions for Setting up your own custom SAML application and follow the steps under the subheading 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 information below:
- 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 to whom you want to provide ThoughtFarmer access. In your Google admin console click the new SAML app you just set up and click Edit Service at the top right. Provide access to everyone or to some users based on the requirements and Save.
Add External SAML login provider on Thoughtfarmer Site
- In ThoughtFarmer, go to the Admin Panel: Users & security section > Login Provider page. Under External Providers, add a new login provider. Select Custom SAML.
- Fill in the ThoughtFarmer fields using the Google Workspace values you copied earlier:
- Hostname: Enter your site url. Remove "https://"; because it's already specified in the dropdown menu next to it.
- Login Provider complete hostname: Google Workspace's SSO Url. Remove "https://"; because it's already specified in the dropdown menu next to it.
- External user store configuration: Choose your Google Workspace external user store.
- Certificate: Click the Advanced SAML Options to expand it. Open the X.509 certificate in Notepad and copy the value into the Certificate field.
- Configuration options: Select the checkbox Want Assertion Signed.
- Issuer URL / Name: Google Workspace Entity Id
*Certificate expiry- In Google Workspace, 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 Google Workspace changes, it should be updated in the Certificate field in the ThoughtFarmer login provider page.
- Log out of ThoughtFarmer and access your site again using a member of the Google Workspace group that ThoughtFarmer syncs with. A successful login should bring you back to Thoughtfarmer. If you are unable to login, look at the ThoughtFarmer Admin Panel: Logs & statistics section > System Logs page (if on-premise/self-hosted) and the Google Workspace logs to determine the root cause.
Comments
0 comments
Please sign in to leave a comment.