Google Workspace

Learn how to configure provisioning for Google Workspace in your Okta org.

Overview

Recommended setup

This is the recommended setup:

  • Configure SAML between Okta and Google.
  • Enable provisioning and have all the options enabled.
  • Enable password push which synchronizes a user's Okta password with their Google Workspace password. A password is still needed for clients such as POP3/IMAP clients for email.

This recommendation is also valid in scenarios where Active Directory integration is needed.

With AD integration, these are the benefits for end users:

  • Seamless Desktop SSO when logging in behind the firewall
  • Access to Google Workspace via Okta using SAML and AD credentials from outside the firewall
  • Email clients requiring username and password now leverage the users' AD password (one less password for the end user to remember due to AD password synchronization)

Recommended rollout

  1. For SSO, use SAML if possible. It enables centralized access management since all web-based sessions have to go through Okta as the identity provider.
  2. Test SAML with a small group of users first. Using the Network masks feature in Google, you can limit the SAML-enabled users to a small audience (for example, several IT staff) to test the configuration and the end-user experience.
  3. It’s important to inform end users that they have to modify the account settings in order to use Google Personal and Google Workspace together in the same browser session. This setting is independent of whether or not Okta has been deployed. Google requires this setting configuration to allow sharing of session cookies.
  4. Be aware that some apps from Google Marketplace may not be tightly integrated with Google Workspace in terms of SSO. Let Okta know about any issues, and Okta Support might be able to help you solve the problems.
  5. Passwords in Google Workspace are recommended. Okta recommends enabling the password synchronization feature with Google Workspace. Change Password URL should be configured to point users back to Okta if they try to change their passwords from within Google Workspace when password synchronization is turned on. The URL will take the user back to Okta.
  6. Google Workspace users assigned to the Super Administrator role can bypass SSO and log in directly to https://admin.google.com.
  7. When you enable provisioning, and choose the admin credentials for the integration, consider using a system account. If an end-user account is used, ensure that password reset is handled correctly and the Okta API settings are updated accordingly.
  8. If Google Workspace users are created primarily in Google Workspace with an existing process outside of Okta, account creation should not be enabled in Okta. User import (through API or CSV) can map existing Google Workspace accounts with Okta users. This action should be ongoing to bootstrap new users.
  9. Okta recommends enabling user deactivation/reactivation to ensure that users are automatically deactivated if they’re deactivated in Okta or in AD, which is integrated with Okta.

Prerequisites

  • Add a Google Workspace app instance and configure SSO. The assumption is that you have already added a Google Workspace app instance in Okta and have configured SSO. See How to Configure SAML 2.0 for Google Workspace.

    For general information about adding applications, see Add existing app integrations.

  • Google Workspace: Enable the API Access checkbox in Google Workspace:

    1. Sign in to your Google Workspace admin console.
    2. Go to Security > API Controls.
    3. Select Unrestricted.

Provisioning features

Push Groups Groups and their members can be pushed to remote systems. For more information, see About Group Push and Group Push operations.
Import New Users New users created in the third-party application will be downloaded and turned in to new AppUser objects, for matching against existing OKTA users.

Specifically: This is an implicit feature when provisioning is configured - meaning with the username/password set up and verified. Import allows Okta to map active Google accounts to an Okta user. This is usual for the initial app assignment bootstrap. For file-based account mapping you can also use CSV (similar to API import).
Schema Discovery Import additional user attributes from Google Workspace.
Profile Sourcing New users created through Okta will also be created in the third-party application.
Push New Users New users created through Okta will also be created in the third-party application.

Specifically: Account creation allows Okta to create new accounts in Google Workspace. Note that Google Workspace doesn’t reuse a recently deleted username (1 week restriction) for a new account. The Google Workspace user will go through a welcome routine from Google when they sign in.

Push empty values for custom fields

Selecting this option allows pushing empty values to non-required custom fields.
Push Password Updates Changes to the user's password are automatically synchronized to the application.

Specifically: This feature allows Okta to synchronize the password used by the Okta user to log in to Okta, then into Google Workspace. If a user is not associated with an AD account or Okta-delegated authentication to AD is not enabled, the user logs into Okta with their Okta password. That is the value that is pushed out to Google Workspace.

If a user is tied to an AD user and Okta-delegated authentication to AD is enabled, then the AD password will be pushed out to Google Workspace when the user logs into their Okta org (for example, myorg.okta.com)

Even with SAML enabled, there are use cases where a password is needed in Google Workspace. Other mail and calendar clients (desktop or mobile) utilize a separate authentication mechanism and require a Google Workspace user name and password for setup. Synchronizing the password with Okta means one less password to be managed by the end user. This is a standard deployment model for many existing Okta customers.

Note: Okta password policy should match Google's requirements for provisioning to work.
Push Profile Updates Updates made to the user's profile through Okta will be pushed to the third-party application.

Specifically: Any profile changes detected in Okta will be pushed to Google Workspace. This includes first name, last name, etc. Some attributes, such as department and title, are only used for push profile and will not work for import user. Those attributes only work if they were initially updated from Okta.
Push User Deactivation/Reactivate Users Deactivating the user through Okta removes the user from the organization and all teams in the third party application. Reactivating the user through Okta will reactivate the user in the third-party application.

Specifically: Okta deactivates a user's Google Workspace account when the user is deactivated in Okta. While Google Workspace allows an account to be completely deleted in Google Workspace, the deletion is a rather destructive operation that removes all emails, documents, pages, and so on created by this user. For most enterprises, this is not the desired operation. Okta sets the user to the inactive state - allowing administrators to go in and clean things up before deciding on whether a hard deletion is necessary.

Procedures

Configure Google Workspace provisioning

Configure your Provisioning settings for Google Workspace as follows:

  1. In Okta, select the Provisioning tab for the Google Workspace app, then click Configure API Integration.

  2. Check Enable API integration, then click Authenticate with Google Workspace.

  3. Enter your Google Workspace Admin account credentials, then click Log In

    • Enter your admin username.

    • Enter your admin password.

    • Review the list of permissions Google will grant Okta to perform in your Google Workspace tenant. If acceptable click Allow:

  4. Back on the Provisioning page in Okta you'll see messages confirming successful authentication. Click Save.

  5. Select To App, then select the Provisioning features you want to enable, then click Save.

Configure Profile and Lifecycle sourcing

  1. Select To Okta, then select Allow Google Workspace to source Okta users.

  2. When a user is deactivated in Google Workspace, you can choose what action Okta takes against the matching Okta user by using the Profile and Lifecycle Sourcing options.

    The options for when a user is deactivated in the app are:

    • Do nothing: Google Workspace is unassigned from the Okta user.
    • Deactivate: The Okta user is deactivated and is no longer be able to sign in or access Okta. If re-activated in Google Workspace in the future, the Okta user will go through the re-activation process in Okta. The user will go through the initial Okta user setup procedure again.
    • Suspend: The Okta user is suspended and is no longer be able to sign in or access Okta. If re-activated in Google Workspace in the future, the user will become re-activated in Okta and no further steps are needed. The Okta user can sign in to Okta.

Assign users to the Google Workspace app

  1. Open the app, go to the Assignments tab, and click Assign to People.

  2. In the Assign Google Workspace app to People dialog, select a user, then click Assign.

  3. You can select which Organizational unit will be pushed. Set Deactivation options and Manage licenses options for users. See Managing Google Workspace Users).

Google Workspace schema discovery

By default, the following base attributes are imported from Google Workspace:

FIRST_NAME

LAST_NAME

EMAIL

SECOND_EMAIL

MOBILE_PHONE

Google Workspace also supports User's Schema Discovery, so you can add extra attributes to User's Profile.

Enhanced schema discovery

With enhanced schema discovery you can use custom user schemas defined in Google Workspace. Okta will import all custom user schemas to provide you the ability to manage these attributes. On import, Okta brings in these custom attributes from your users just like normal attributes, and also pushes them to Google Workspace on create and update operations.

Okta also supports importing multi-valued custom attributes from Google Workspace. They are represented as dynamic arrays in Okta. There is a limitation for Boolean multi-value properties, as these are not currently supported within Universal Directory and are ignored during schema import. Multi-valued boolean properties won't be visible in the Profile Editor.

If you are unable to use schema discovery, re-authenticate using OAuth.

Add schema attributes

  1. In the Okta Admin Console, go to Directory > Profile Editor.

  2. Select the APPS section in the left navigation bar, then find your app in the list.

  3. Check the list of attributes, and if you decide you need more, click Add Attribute. A list of extended attributes appears.

  4. Select the attributes you want to add, then click Save.

  5. You can now import and push these user attribute values to or from Google Workspace.