Troubleshooting

Contingency Plan for Disabling SSO

In the case where SSO needs to be disabled between Okta and Google Workspace immediately, complete these steps:

  1. Sign in to Google Workspace using the backdoor URL ([http://www.google.com/a/mydomain.com])
  2. Select Advanced ToolsSet up single sign-on (SSO).
  3. Uncheck Enable Single Sign-on.
  4. Un-specify (blank out) the 3 URL fields.
  5. Click Save Changes.
  6. The username/password sign-in page re-appears for all end users when they try to access Google Workspace. There may be a lag of 30 seconds before this appears.

SSO errors

If you are using a Google environment that has Google Context Aware Access (CAA) enabled, you may experience issues clicking on the tiles in Okta. If an access denied screen appears, refreshing the page should fix the issue.

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 user interface and Contacts app user interface are inconsistent with this Google User Schema. For example, an attribute value might not appear in the user interface, even though it's correctly populated via the API. Additionally, an attribute value entered in the Google Admin User Interface (UI) might not show up in the Google User Schema properly. Google is aware of this inconsistency between user interfaces 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. Learn about the impact of this inconsistency in specific use cases, and how to work around them:

Validate User Data in the Google User Schema

User creation in Google Workspace from Okta

User import from Google Workspace

User import from Google and subsequent update from Okta

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: https://developers.google.com/apis-explorer/#s/admin/directory_v1/directory.users.get.
  2. Authenticate Oauth with default scopes.
  3. Enter the primary email of desired user in the userKey field.
  4. UserKey value in the Google API Explorer tool

User creation in Google Workspace from Okta

The following Google Workspace User base attribute values created in Okta and pushed to Google Workspace 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 Workspace

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 attribute values such that Okta can import them. Note that this issue only affects imports from G Suite. Provisioning of attributes from Okta to Google Workspace works successfully.

Google Admin UI Attribute Name Sample Data entered into Google Sample Data shown in Google User Schema via API Use GAM to reconfigure Sample Data in Google User Schema Attribute will show up in G Suite Base Attribute or Custom Attribute
Secondary Email mailto:myemail@test.com emails: address=myemail@test.com, type=custom, customType="" emails: type=work address=myemail@test.com
  • Work email
Phone (Work) 111-111-1111 phones: type=work value=111-111-1111 no GAM update needed
  • Primary phone
Phone (Home) 111-111-1111 phones: type=home value=111-111-1111 no GAM update needed Add as Custom Attribute:
  • Phones Home Value
Phone (Mobile) 111-111-1111 phones: type=mobile value=111-111-1111 no GAM update needed
  • Phones WorkMobile Value
Address (Work) 301 Brannan St San Francisco, CA 94105 addresses: 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 94105 addresses: 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 ID 123 externalIds: type=organization value=123 no GAM update needed Add as Custom Attribute:
  • ExternalIds Organization Value
Manager admin@oktaskylab.net relations: type=Manager value=admin@oktaskylab.net no GAM update needed
  • Manager
Title Sales organizations: title=Sales customType="" organizations: title=Sales type="work"
  • Organizations title
Employee type Engineer organizations: description=Engineer customType="" organizations: description=Engineer customType="work" Add as Custom Attribute:
  • Organizations Work Description
Department Engineering organizations: department=Engineering customType="" organizations: department=Engineering customType="work"
  • Organizations department
Cost Center EN101 organizations: costCenter=EN101 customType="" organizations: costCenter=EN101 customType="work"
  • Organizations costCenter

User import from Google and subsequent update from Okta

For a Google Workspace User who was originally created in Google Admin user interface, updating their profile in Okta will not overwrite attribute values that were originally populated in Google Workspace UI and to which Okta does not explicitly map to. For example, if the Cost Center attribute is first filled out in Google Admin user interface, then updating Organizations costCenter in Okta will not result in a Google Admin UI update. By contrast, if the 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.

Known issues and common errors

  • Multi-word attributes

    The Search bar in PeopleProfile EditorGoogle Workspace UserAdd Attribute sequence cannot search for multi-word attribute names that contain spaces.

  • Separate Primary Email attribute

    The Google Workspace User profile shows a separate Primary Email attribute. This is because the Google Workspace instance was created prior to the January 2015 GA update and is a deprecated implementation. A best practice is to set up a brand new Google Workspace instance in your Okta org, and deactivate the old one. If this is not feasible, continue using the existing Google Workspace instance, but don't map any Okta user attribute to the Google Workspace User Primary Email attribute.

  • Contacts App does not appear

    After provisioning a user to Google Workspace, the Contacts app doesn't show the updated user profile. This is expected behavior as it takes up to 24 hours for updated values to appear in the Google Workspace Directory section of the Contacts app.

  • How are Google groups affected by Okta?

    Okta imports a user's groups when they are imported from Google Workspace or when their Google Workspace account is assigned to their Okta account. After a user is imported or assigned, updates to groups in Google Workspace are not reflected in Okta.

    Select Push Okta user profiles to Google Workspace to have group changes made within Okta pushed to Google Workspace.

  • Import errors

    If new org units are added in Google, you may need to refresh your application data before running an import or else you may receive the following error:

    Field error in object GoogleAppBaseProfile on field orgUnitPath: rejected value

  • Custom Schema Attributes are not showing up

    If you're using Enhanced Schema Discovery for Google Workspace application, but don't see any new attributes coming to Okta in the Profile Editor, you need to re-authenticate on the Provisioning tab, to allow Okta to import custom schemas from Google Workspace.

    To do this, go to the Provisioning tab, then select API Integration and re-authenticate.

  • Errors during profile updates

    If you're using Enhanced Schema Discovery for Google Workspace application, and you have imported and assigned some properties from a custom user schema in Google Workspace, and after that you removed that custom user schema from Google Workspace, you may see the following error (New_UserSchema in the image is the deleted schema from Google Workspace):

    To resolve this error, manually remove custom properties from Okta's Google Workspace user in Profile Editor.

  • Error message example

Google resources