Google SSO Configuration with Simpplr

■

Follow the steps below to set up your Google SSO with Simpplr. 

Note:

You must be a Google Admin user for your org's Google Workspace, as well as a Simpplr Application manager in order to enable to connection.

Creating a Google SSO SAML Web App

1. Log in to your org's Google Workspace using a Google Admin account (of the workspace that has to be integrated) on this page: https://admin.google.com/.
2. From the Admin Console, on left navigation menu, Navigate to Apps > Web and mobile apps.
   
3. Click on Add app > Add custom SAML app.
   
4. Enter the App name (required) and Description (optional). We recommend using something easy to remember like SimpplrSAML. Then click Continue.
5. Copy the SSO URL and Entity ID, then download the Certificate. Paste these items somewhere you can access later on. You'll need them when connecting the app to Simpplr. Click Continue.
   
6. Enter the ACS URL. This will be the API that is called after Google completes authentication. This will be in the following format:
   • https://api.customerurl.com/v1/identity/accounts/login/saml
   • For example: https://api.goodco.com/v1/identity/accounts/login/saml
7. Enter the Entity ID. Enter a valid identifier and make a note of it (this is to be added in the Account’s Google SSO configuration).
8. Optionally, enter the Start URL - the RelayState that is added to the callback API call
   • Base64 encode the following string: {"callback_url":"https://<account-domain>/home","v":"GO"}
   • For example: {"callback_url":"https://backyard.simpplr.xyz/home","v":"GO"}
9. Check the Signed response checkbox.
   

10. For the Name ID options, choose:

    Name ID format: EMAIL

    Name ID: Basic Information > Primary email

    
    

11. Click Continue.

12. On the next screen, for Attribute mapping - Enter the following mapping:
    
    

13. Note attribute mapping is case sensitive. 

14. Click SAVE.

15. Once the app is ready, click on the User access block, select ON for everyone, then click SAVE.
    

16. The SAML App setup is complete. Now we need to connect the integration within Simpplr.

Enable Google SSO within Simpplr

1. From Simpplr, as the Application manager, go to Manage > Application > Security > External IdP (SSO).
   
2. Check the box next to Google. The options for the Google link, Entity ID and Certificate will appear. Enter all three components with the information you received from Google. 
3. Click Save. Now the integration is complete.

Event Hook Implementation

If the status of the user is changed in Google SSO, it should be reflected in Simpplr. This is done through Event Hook implementation.

If the user status in Google is changed to ‘suspended' or ‘reactivated’, the status of that user should be changed to ‘freeze’ or 'active’ in Simpplr.

If the user is deleted from Google, the status of that particular user in Simpplr should be changed to 'Inactive'.

The Application manager can enable or disable the Event Hook feature from Manage > Application.

Approach:

Google SSO Event Hook setup

1. The Directory API provided by Google, to set up the event hook https://admin.googleapis.com/admin/directory/v1/users
2. Details are referred from https://developers.google.com/admin-sdk/directory/v1/guides/push
3. In order to get the status update, watch events, ‘update user’ and ‘delete user’
4. If application manager disables ‘Event Hook’ feature, call stop channel API to disable the events https://www.googleapis.com/admin/directory_v1/channels/stop
5. In order to call any Google APIs, an authentication token is required. Below are the approaches to get the authentication token:

Approach 1: Authorizing requests with OAuth 2.0

When the Application manager enables an event hook, Google displays consent page for the App manager to provide the credentials. After successful authentication, OAuth token is generated with certain expiry period. This token should be attached to every Google API call.

Once the OAuth token is expired, the Application manager needs to provide consent again.

https://developers.google.com/admin-sdk/directory/v1/guides/authorizing

Approach 2: Google Workspace Domain-Wide Delegation of Authority

Create a service account and delegate the authority of the admin to this service account for accessing certain APIs

https://developers.google.com/admin-sdk/directory/v1/guides/delegation

Below are the steps to set up service account.

1. From the Service Accounts page in the Google Cloud Platform site, click CREATE PROJECT.
2. Assign a name to your project. We recommend Google Event Hooks.
3. From the next screen, click + CREATE SERVICE ACCOUNT.
   
4. Name the service account and create the ID. Optionally, add a description of what the account will do. Then scroll down and click DONE.
   
5. Now we need to generate a Private key against the service account, which then needs to be downloaded and kept for later use. To do so, click into the service account, then choose KEYS.
6. Click ADD KEY > Create new key and generate the new key. Choose JSON, then Create. The key will automatically download to your computer.
   
7. Enable the domain wide delegation for this service account. Back in the Google Workspace Admin menu, navigate to the Admin console, then choose Security > Access and Data Control > API Controls.
   
8. Scroll down and click MANAGE DOMAIN WIDE DELEGATION. Choose Add new and enter the new Client ID and OAuth scopes. These can be found by opening the JSON file (key) you downloaded a moment ago. 
    

Back in Simpplr:

1. Go to Manage > Application > Security > External IdP (SSO).
2. Paste the Google link and Entity ID created above into the appropriate fields. Then upload the certificate file. 
3. Check the boxes for each option you want to enable. We recommend checking all three boxes.
   • Deactivate user if deleted in Google - This ensures that when a user is removed from Google, they're also deactivated in Simpplr.
   • Activate user is activated in Google - Similarly, this will activate a user in Simpplr when activated in Google.
   • Freeze user if suspended in Google - This will suspend a user in Simpplr if they're suspended in Google.
4. Once you check any or all of these boxes, enter your admin email ID in the box that appears. then upload the private key file you received from Google.
5. Click Save.

Note:

Once users are provisioned via Google SSO, they'll receive a welcome email for Simpplr. The user will be "created" in Simpplr once they respond to that email, settings up their password and logging into Simpplr for the first time.
If you suspend a user in Google, it freezes a user in Simpplr. If you delete the user in Google, they become inactive in Simpplr. If you activate a suspended user in Google, then freeze becomes active in Simpplr.
If user is deactivated in Google, the App manager will need to activate the account in Simpplr again.