Google Apps Deployment Guide Skip to main content
How satisfied are you with the Okta Help Center?
Thank you for your feedback!
How satisfied are you with the Okta Help Center?
Very Dissatisfied
Very satisfied
Enter content less than 200 characters.
Google Apps Deployment Guide
Published: Feb 17, 2015   -   Updated: Jun 22, 2018

User-added image


New Features

The following Google Apps Early Access features have now been made Generally Available to all new Okta orgs:

To enable these features for existing orgs, contact your Okta Support representative then re-authenticate your Google Apps instance, (see Migrating an Existing Google Apps Instance, below, for details).

These changes do not affect other generally available Google Apps features.

Migrating an Existing Google Apps Instance

To migrate an existing Google Apps instance, re-authenticate your Google Apps instance as follows:

  1. From the Okta Admin Dashboard, select the Applications tab.
  2. From the list of active apps, locate the Google Apps instance.
  3. Select Google Apps, then navigate to the Provisioning tab.
  4. Select Edit.
  5. Select Re-authenticate with Google Apps

    User-added image
  6. Select Save.

Single Sign-On

Google Apps supports SAML 2.0. The setup is relatively straight forward through the admin console when you log in as a Google Apps admin.


Google Apps SAML configuration supports both Service-provider (SP) initiated and Identity-provider (IDP) initiated SAML negotiation.

  1. For IDP-initiated SAML, an assertion is sent out from Okta when a user tries to access Google Apps by clicking on the app icon on his Okta home page.
  2. For SP-initiated SAML, a user hits a deep link that is tied to their Google Apps domain (for eg. [] or [https://]). Based on the "Sign-in page URL" setting, Google Apps redirects back to Okta. A user will be required to log in to Okta. In the case where Desktop SSO is configured with your Active Directory domain, Okta will automatically log in the user and SAML into Google Apps if a Google Apps deep link is being accessed.
  3. Network masks can be used to control the users affected by SAML. According to Google - "Network masks determine which addresses will be affected by single sign-on. If no masks are specified, SSO functionality will be applied to the entire network".
  4. Use a semicolon to separate the masks, for example: (; Use this feature to control your rollout or for initial testing of a small population of users.

A few important points about Google Apps SAML configuration:

  1. With the recent Google Apps migration, the cookie sharing between apps within Google Apps and also with your personal account has been integrated.
  2. Previously, users had no problem logging into Google Apps and Google Personal simultaneously in a single browser. This is still supported today - but it requires end users to go into Account Settings and enable the Multiple Sign-In feature. This needs to be done in both the Google Apps account and the personal account.
  3. SAML support between the core Google Apps (mail, docs, calendar) are well supported. We have observed some issues with some of the applications in the Google Apps Marketplace. While they share the same Google Apps user name, the SAML support is not extended to those apps and as a result, the user is still prompted for credentials.
  4. User Password in Google Apps may still be relevant even with SAML enabled. While SAML authentication itself does not require a password, the password may still be needed for client configuration with IMAP email client on your desktop (eg. Outlook, Mac Mail) or mobile devices. See Managing Users for more information on password synchronization with Google Apps.
  5. The Sign-In URL property is active even if the Enable Single Sign-On check box is unchecked. So while SAML is not active, users will still be re-directed back to Okta for login. When disabling SAML, make sure you blank out the 3 URL fields also.
  6. Backdoor URL. There is a backdoor URL that allows an administrator to login using their username and password regardless of whether SAML is enabled or not. The Google Apps Admin app in Okta provides this backdoor login. It is strongly recommended that Google Apps admin to be provisioned with this app. The actual URL is in the form of: []. A login form (a green login prompt) will show up. Only admins can login through this page.

Managing Users

Okta's provisioning features enable you to integrate with the Google Apps Provisioning Web Services API. The integration requires a username and password of an admin user. The following features are supported:

Password Synchronization

This allows Okta to synchronize the password used by the Okta user to log in to Okta, then into Google Apps. If the user is not associated with his AD account, or Okta-delegated authentication to AD is not enabled, then the user logs into Okta with his Okta password. That is the value that will be pushed out to Google Apps.

If the 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 Apps when the user logs into their Okta org (ie.

Even with SAML enabled, there are use cases where a password is needed in Google Apps. Other mail, calendar clients (desktop or mobile) utilize a separate authentication mechanism and will require Google Apps user name and password for setup. Synchronizing the password with Okta means one less password to 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 in order for provisioning to work. 

Account Creation

Account creation allows Okta to create new accounts in Google Apps. It is important to note that Google Apps does not allow the reuse of a recently deleted username (1 week restriction) for a new account. The Google Apps user will go through a welcome-routine from Google when they first login

Account Deactivation/Re-activation

Okta deactivates a user's Google Apps account when the user is deactivated in Okta. While Google Apps allows an account to be completely deleted in Google Apps, the deletion is a rather destructive operation that removes all emails, documents, pages, etc 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.

Profile Update

Any profile changes detected in Okta will be pushed to Google Apps. This includes first name, last name, etc.

Account Import

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. CSV can also be used for file-based account mapping - similar to what API import can do.

Google Organizational Units (OUs)

Google Organizational Units (OUs) are typically used to grant access to various resources within Google Apps, such as access to Drive, GmailCalender, and Google Apps Marketplace. A user can only be assigned to one OU at one time. OUs are different from Google Groups, which are email aliases used as listservs.

Okta automatically imports valid OU values from Google Apps. An OU value is simply represented as a user attribute in Okta. Okta can provision a user with an OU value and subsequently push changes to Google Apps. 

Note: If an existing OU is renamed, moved, or deleted in Google Apps, Okta updates the valid OU values on the next import. However, existing Okta users that were previously assigned to the changed OU are not updated, since it is not clear what OU the user should be moved to. Instead, Okta shows that the user is assigned the default “/” root OU, and does not push this attribute. The Admin needs to manually select a new OU for the Okta user, which then triggers an update to Google Apps. 

Profile Editor with Universal Directory

With Universal Directory enabled, the integration can provision and import an expanded set of user attributes. These attributes and mappings can be viewed, edited, and expanded in the Profile Editor.

User-added image

Note: The Google Apps User Username attribute shown in the Profile Editor is equivalent to the Primary Email attribute in Google Apps. There is no separate Google Apps User Primary Email attribute. This is because Google Apps uses Primary Email as the unique identifier/username to login to Google Apps. The Primary Email also doubles as the Google App User’s Gmail email address.

Provisioning Credentials

Admin user credentials are needed to enable provisioning in Okta. With password synchronization enabled, if Okta detects that the username whose password is being updated matches that of the API username, Okta will not synchronize the password into Google Apps to ensure the API to continue functioning.

After you've configured your provisioning options and want to test it out, make sure you have signed out of Google with the user account that you are testing provisioning with.

Recommended Setup

User-added image

The recommended setup consists of the following:

  1. SAML configured between Okta and Google.
  2. Enable provisioning and have all the options enabled.
  3. In particular, enabling password push synchronizes a user's Okta login password with their Google Apps password - since a password is still needed for clients such as POP3/IMAP clients for email.
Where Active Directory integration is needed, the recommendation above still holds.  The topology will look like the following:
User-added image

With AD integration, end users benefit from the following:

  1. Seamless Desktop SSO when logging in behind the firewall
  2. SAML into Google Apps via Okta using AD credentials when outside the firewall.
  3. Email clients requiring username/password now leverage the users' AD password - one less password for the end user to remember.  This is accomplished through AD password synchronization.

Rollout Recommendation

  1. For SSO, SAML should be the goal. This enables centralized access management since all web-based sessions have to go through Okta as the identity provider.
  2. SAML should be tested 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 (eg. several of the IT folks) to test out the configuration and the end user experience.
  3. It is important to let your end users know about the need to modify account settings in order to use Google Personal and Google Apps together in the same browser session. This setting is independent of whether or not Okta has been deployed. It is needed by Google to allow sharing of session cookies.
  4. Be aware that some apps from Google Market place may not be as tightly integrated as they should be with Google Apps in terms of SSO. Let Okta know about any issues and Okta support will help you solve any problems that may arise.
  5. Passwords in Google Apps are still recommended. Okta recommends enabling the password synchronization feature with Google Apps. The Change Password URL should be configured to point users back to Okta if they try to change their passwords from within Google Apps when password synchronization is turned on. The URL will take the user back to Okta.
  6. Make sure the availability and use of the backdoor URL is well understood among administrators. A Google Apps Admin App is also available in the application catalogue.
  7. When enabling provisioning, choose the admin credentials used for the integration carefully. Ideally, use a system account. If an end user account is used, make sure password reset is handled correctly and that the Okta API settings are updated accordingly.
  8. If Google Apps users are going to be created primarily in Google Apps with an existing process outside of Okta, then account creation need not be enabled in Okta. User import (through API or CSV) can easily map existing Google Apps accounts with Okta users. This should be done in an ongoing fashion to bootstrap new users.
  9. Okta recommends enabling user deactivation/reactivation to ensure automated deactivation happens when a user is deactivated in Okta or in AD which is integrated with Okta.

Contingency Plan for Disabling SSO

In the case where SSO needs to be disabled between Okta and Google Apps immediately, do the following:

  1. Admin logs into Google Apps using the backdoor URL ([]) 
  2. Select Advanced Tools > Set up single sign-on (SSO).
  3. Uncheck Enable Single Sign-on.
  4. Un-specify (blank out) the 3 URL fields.
  5. Select Save Changes.
  6. The username/password login page re-appears for all end users when they try to access Google Apps. There might be a lag of 30 seconds before this kicks in.

Known Issues

  • The Search bar in People > Profile Editor > Google Apps User > Add Attribute sequence cannot search for multi-word attribute names that contain spaces.
  • The Google Apps User profile shows a separate Primary Email attribute. This is because the Google Apps instance was created prior to the January 2015 GA update and is a deprecated implementation. A best practice is to setup a brand new Google Apps instance in your Okta org, and de-activate the old one. If this is not feasible, it is fine to continue using the existing Google Apps instance, but do not map any Okta user attribute to the Google Apps User Primary Email attribute.
  • After provisioning a user to Google Apps, the Contacts app does not show the updated user profile. This is expected behavior as it takes up to 24 hours for updated values to appear in the Google Apps Directory section of the Contacts app.


Google API / UI Attribute Inconsistency

Okta attributes are mapped to the Google User Schema in the Google Directory API. In some cases, the Google Admin UI and Contacts app UI are inconsistent with this Google User Schema. For example, an attribute value might not show up in the UI, even though it's correctly populated via the API. Additionally, an attribute value entered in the Google Admin UI might not show up in the Google User Schema properly. Google has communicated that they are aware of this inconsistency between UIs and API, and are working to resolve it. In general, query the Directory API directly to determine whether Okta has correctly pushed user profiles to Google. The following provides additional details on the impact of this inconsistency in specific use cases, and how to work around them.

Validate User Data in the Google User Schema

Use Google API Explorer tool to validate user data in the Google User Schema: 

  1. Go to:
  2. Authenticate Oauth with default scopes.
  3. Enter the primary email of desired user in the userKey field.

    User-added image

User creation in Google Apps from Okta

The following Google Apps User base attribute values created in Okta and pushed to Google Apps will not show up in the Contacts app and Google Admin UI, but they will show up in the API:

  • Second email
  • Street address
  • City
  • State
  • Zip code
  • Country code

User import from Google Apps

By default, Okta does not import some user attributes entered via the Google Admin UI. This is because these attribute values are incorrectly exposed in the Google User Schema via API. This issue may get resolved at some point by Google, but the suggested workaround is to use a tool like GAM to reconfigure the attributes values such that Okta can import them. Note that this issue only affects imports from Google Apps. Provisioning of attributes from Okta to Google Apps works successfully.

 User-added image

Google Admin UI Attribute NameSample Data entered into GoogleSample Data shown in Google User Schema via APIUse GAM to reconfigure Sample Data in Google User SchemaAttribute will show up in Google App Base Attribute or Custom Attribute
Secondary Emailmailto:myemail@test.comemails:, type=custom, customType=""emails: type=work
  • Work email
Phone (Work)111-111-1111phones: type=work value=111-111-1111no GAM update needed
  • Primary phone
Phone (Home)111-111-1111phones: type=home value=111-111-1111no GAM update neededAdd as Custom Attribute:
  • Phones Home Value
Phone (Mobile)111-111-1111phones: type=mobile value=111-111-1111no GAM update needed
  • Phones WorkMobile Value
Address (Work)301 Brannan St San Francisco, CA 94105addresses: type=work formatted="301 Brannan St San Francisco, CA 94105"addresses: type=work streetAddress="301 Brannan St" locality="San Francisco" Region="CA" PostalCode="94105"
  • Street address
  • City
  • State
  • Zip code
Address (Home)301 Brannan St San Francisco, CA 94105addresses: type=home formatted="301 Brannan St San Francisco, CA 94105"addresses: type=home streetAddress="301 Brannan St" locality="San Francisco" Region="CA" PostalCode="94105"Add as Custom Attributes:
  • addressesHomeStreetAdress
  • addressesHomeLocality
  • addressesHomeRegion
  • addressesHomePostalCode
Employee ID123externalIds: type=organization value=123no GAM update neededAdd as Custom Attribute:
  • ExternalIds Organization Value
Manageradmin@oktaskylab.netrelations: type=Manager value=admin@oktaskylab.netno GAM update needed
  • Manager
TitleSalesorganizations: title=Sales customType=""organizations: title=Sales type="work"
  • Organizations title
Employee typeEngineerorganizations: description=Engineer customType=""organizations: description=Engineer customType="work"Add as Custom Attribute:
  • Organizations Work Description
DepartmentEngineeringorganizations: department=Engineering customType=""organizations: department=Engineering customType="work"
  • Organizations department
Cost CenterEN101organizations: costCenter=EN101 customType=""organizations: costCenter=EN101 customType="work"
  • Organizations costCenter


User import from Google, and then subsequent update from Okta

For a Google Apps User who was originally created in Google Admin UI, updating their profile in Okta will not overwrite attribute values that were originally populated in Google Apps UI and to which Okta does not explicitly map to.  For example, if "Cost Center" attribute is first filled out in Google Admin UI, then updating "Organizations costCenter" in Okta will not result in a Google Admin UI update. By contrast, if "Phone (Work)" attribute is first filled out in Google Admin UI, then updating "Primary phone" in Okta will result in an update in the Google Admin UI.

Additional Information