Troubleshooting
Contingency plan to disable SSO
Complete the following steps to immediately disable SSO between Okta and Google Workspace:
- Sign in to Google Workspace using the backdoor URL (http://www.google.com/a/mydomain.com)
- Select .
- Clear the Enable Single Sign-on checkbox.
- Clear the 3 URL fields.
- Click Save Changes.
After SSO is disabled, the username/password sign-in page is presented to all end users when they try to access Google Workspace. There may be a lag of 30 seconds before this appears.
SSO errors
When using a Google environment that has Google Context Aware Access (CAA) enabled, you may experience issues clicking the tiles in Okta. If you encounter an Access Denied error message, refresh the page.
Inconsistencies between Google API and UI attributes
Okta attributes are mapped to the Google User Schema in the Google Directory API. Sometimes, 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 if the API correctly populates the attribute. Also, an attribute value entered in the Google Admin User Interface (UI) might not properly appear in the Google User Schema. In general, query the Directory API directly to determine whether Okta has correctly pushed user profiles to Google. The following use cases demonstrate the impact of these inconsistencies 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 the Google APIs Explorer to validate user data in the Google User Schema.
- Go to the users.get documentation.
- Open the APIs Explorer by clicking the API icon.
- Authenticate OAuth with default scopes.
- Enter the primary email of the desired user in the userKey field.
User creation in Google Workspace from Okta
The following Google Workspace User base attribute values are created in Okta and pushed to Google Workspace. These attributes don't appear in the Contacts app and Google Admin UI, but they do appear in the API.
- Second email
- Street address
- City
- State
- Zip code
- Country code
User import from Google Workspace
By default, Okta doesn't import some user attributes entered using the Google Admin UI. This is because the API incorrectly exposes these attribute values in the Google User Schema. The suggested workaround is to use a tool like GAM to reconfigure the attribute values such that Okta can import them. This issue only affects imports from Google Workspace. Provisioning 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 through the API |
Use GAM to reconfigure Sample Data in Google User Schema |
Attribute appears in Google Workspace 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 |
|
| Phone (Work) | 111-111-1111 | phones: type=work value=111-111-1111 | no GAM update needed |
|
| Phone (Home) | 111-111-1111 | phones: type=home value=111-111-1111 | no GAM update needed | Add as Custom Attribute:
|
| Phone (Mobile) | 111-111-1111 | phones: type=mobile value=111-111-1111 | no GAM update needed |
|
| 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" |
|
| 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:
|
| Employee ID | 123 | externalIds: type=organization value=123 | no GAM update needed | Add as Custom Attribute:
|
| Manager | admin@oktaskylab.net | relations: type=Manager value=admin@oktaskylab.net | no GAM update needed |
|
| Title | Sales | organizations: title=Sales customType="" | organizations: title=Sales type="work" |
|
| Employee type | Engineer | organizations: description=Engineer customType="" | organizations: description=Engineer customType="work" | Add as Custom Attribute:
|
| Department | Engineering | organizations: department=Engineering customType="" | organizations: department=Engineering customType="work" |
|
| Cost Center | EN101 | organizations: costCenter=EN101 customType="" | organizations: costCenter=EN101 customType="work" |
|
User import from Google and subsequent update from Okta
Suppose that a Google Workspace User was originally created in the Google Admin user interface. Updating their profile in Okta doesn't overwrite the attribute values that were originally populated in the Google Workspace UI (Okta doesn't explicitly map to this). For example, if the Cost Center attribute is first entered in the Google Admin user interface, then updating Organizations costCenter in Okta doesn't result in a Google Admin UI update. By contrast, suppose the Phone (Work) attribute is first filled out in the Google Admin UI. In this case, updating the user's Primary phone in Okta does result in an update in the Google Admin UI.
Known issues and common errors
-
Multi-word attributes
The Search bar in sequence can't 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 before the January 2015 GA update and is a deprecated implementation. Set up a new Google Workspace instance in your Okta org, and deactivate the old one. If this isn't feasible, continue using the existing instance, but don't map any Okta user attribute to the Google Workspace User Primary Email attribute.
-
Contacts app doesn't appear
After provisioning a user to Google Workspace, the Contacts app doesn't show the updated user profile. This is expected behavior. It can take 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're 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 aren't reflected in Okta. You can run an import to get any subsequent changes to Google Workspace groups.
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 app data before running an import. Otherwise, you may receive the following error:
Field error in object GoogleAppBaseProfile on field orgUnitPath: rejected value
-
Custom Schema Attributes don't appear
If you're using Enhanced Schema Discovery for Google Workspace, 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
Consider the case where you're using Enhanced Schema Discovery for Google Workspace. Suppose that you imported and assigned some properties from a custom user schema in Google Workspace (for example, New_UserSchema. If you remove that schema from Google Workspace, you may encounter the following error:
To resolve this error, manually remove custom properties from the Google Workspace User in the Profile Editor. See Map Okta attributes to app attributes in the Profile Editor.
