DEFINITIVE GUIDE TO OKTA
G SUITE (&GCP) INTEGRATION

I used to work with Okta, and I must say, amazing people, great product, and very 💪💪 fit management:)
I also got an opportunity to implement Okta and Google Workspace for some enterprises in my IT consulting career, some went pretty smooth, and some had a few learning lessons.
I thought to share my experience via this detailed blog post to help community seamlessly integrate Okta with Google (Google Workspace and/or Google Cloud Platform)

Table of Contents

1. SSO & Provisioning Overview

Cetranlized user lifecycle and SSO - Overview & Benefits

Jump to section

2. SSO Terminology

SSO and provisioning terminology in plain enlsigh.

Jump to section

3. User Provisioning via Okta

Instructions to setup Google user provisioning via Okta

Jump to section

4. SSO to Google via Okta

Step by step instructions to setup Okta SSO for Google

Jump to section

5. Advance Use Cases

Attribute transformation, existing Google Users

Jump to section

6. GCDS vs Okta Provisioning

Which one should you use? Rationale & Recommendation

Jump to section

7. FAQs

Get answer to FAQs, or ask if you have any question.

Jump to section

1. SSO & Provisioning Overview

This section includes SSO overview, how does SSO help in providing rich user experience along with increasing our security posture.

SSO & User Lifecycle Management with Okta

Before I show you how to set up Google SSO and user lifecycle management with Okta, let us first understand why we need Okta Google Workspace integration in the first place. I mean what are we missing in life if we do not even have Okta or its integration with Google.

For that, let me take a scenario, lets say your company uses 10 different software applications to perform day to day tasks, for e.g Salesforce for CRM, Google Workspace for messaging and collaboration, Asana for task management etc.

Now, when a new employee joins you, your IT Administrator would go and create this new employee’s account in these 10 different applications (one by one), and then finally send the user id and password of each of these apps to the user.

Manually creating user accounts in 10 different applications, yuck…. That is painful…..very time consuming, but let me add some flavor to it.

What if you are a big business, and 100 new employees join you today?

Oh.. and what if 100 leave you every month, would you not need to then go to those 10 applications and delete these accounts????

and what if by any chance your IT Administrator (being human) missed to delete a user’s account from any of these applications? security compromised……..

It is not just your IT administrator who gets all the frustration here, it is also shared by your regular employees, because they now need to manage 10 different user ids and passwords (one for each application).

Now, if you are in this situation, what would you do? May be keep the same user id and password for all these applications, which works well as you only need to remember one set of credentials, but if your password gets compromised, that means all your 10 apps are potentially compromised because you have same password for them too.

So, to summarize, here are the problems-:

Administration Problems

Time consuming and de-centralized user management
Lack of security (what if an Admin forgets to remove a user account from an application after the user leaves your company)

User Problems

Multiple user ids and passwords to manage
Lack of productivity, less than ideal experience
Lack of security (if user changes password of each app and make it same)

Now, let us see how using a centralized Identity and Access management solution can help us with these problems, though this post is about Okta / Google integration, however conceptually it does not matter which Identity and Access management solution you use (e.g ADFS, Ping Identity, Google Cloud Identity, AzureAD etc).

Administration Benefits with Okta-:

Okta sync very well with your Active Directory or LDAP to bring all your existing identities (e.g users, groups) into Okta.
Now, you do not need to create users accounts manually in to target applications (like Google Workspace, Salesforce etc), as Okta connects with them very well leveraging their APIs.
Once you integrate Okta with these target applications, you only need to provision your users once, either in your Active Directory or in Okta, and then Okta will provision (and de-provision) this user automatically in those 10 applications in our case.
Okta Administrator can apply policies such as enforce Multi Factor Authentication when a user is trying to login to a critical application, or may if a user is trying to login from outside the office.

User benefits with Okta-:

Rich User experience -: Users do not need to remember multiple user ids and passwords for different apps, they only need to login to Okta, and they will be presented with application icons, just click on those icons to login to those applications…… yeah……..
Secure Access based on the access policies setup by Okta Admi

2. SSO & Provisioning Terminology

In this section, let us understand frequently used terminology in Provisioning and SSO including ones which are specific to Okta and Google.

Simplified SSO & User Lifecycle terminology

I hate talking about technical jargon, but it is important to understand some of the terms which will be used frequently, though I am not an expert by any means but i’ll try my best to help you understand these jargons in simple terms.

Identity Provider (IdP) -:

- Identity Provider or IdP for short is an authority system which provides the identity of the user to the relying parties.
- Take an example of DMV which verifies your 6 points id and then issues you a driving license, now you can present this licenses as your identity to other places like at Airport security.
- In this example, Airport security is a service provider which is relying on DMV as the identity provider.

Service Provider (SP)-:

- Service Provider (SP) is also called Relying Party (RP) in Single Sign On world. It is usually an application or service which relies on the Identity provider to authenticate the user and provide its service to him/her.
- In our example above, Airport Service is a service provider (or relying party) and DMV is an Identity provider (IdP).

Let us understand them better with one more example – This weekend I went to a bar near me to have couple of IPAs:), they asked me for a proof which shows me as 21 years or older, I presented my driving license, here DMV is my identity provider and this bar is the relying party (or Service provider) as it is relying on DMV to provide me the service (beer as a service…. yeah….).

Security Assertion Markup Language (SAML)-:

- When two entities talk to each other, they need to agree to talk in a predetermined language, right? Let say if the president of the United States of America is talking to the Prime Minister of India about negotiating a deal, how would they understand each other as they speak different languages?
- Ideally, they would have a translator who understands both languages and then help these leaders with the translation in their own language, so they can make informed decisions.
- Similarly, when Okta and Google need to talk to each other where Okta will say to Google ‘Hey Google, I confirm, Goldy is our employee, let him login to Google Workspace’, this interaction takes place in the language or standard they both understand, this language is called “Security Assertion Markup Language” or SAML for short.
- As per Wikipedia -: Security Assertion Markup Language (SAML, pronounced SAM-el) is an open standard for exchanging authentication and authorization data between parties, in particular, between an identity provider and a service provider.

User Attributes-:

- Attributes are like properties of a user, which helps us gain more information about a user, for example, if a user’s job title is CEO, that tells that this user is an executive, or if the user’s department = sales, that tells us that this user works in the sales department.
- There can be multiple attributes assigned to a user (like first name, last name, email, phone, department, employee ID etc).
- You might also create custom attributes which are so specific to your business, for example if your company provides uniform to employees, you might want to know the shirt size of your employees, and would create an attribute like shirt_Size which will then be filled up based on respective user’s shirt size like S, M, L, XL etc.
- These attributes help us make dynamic rules as we will see later in the post, for e.g create a rule in Okta which says if the user.status = ‘full time employee’, then assign Google Workspace application to these users.

Attribute Transformation-:

- Sometime you would see scenarios where you would need to change the attribute’s value on the fly, let me give you an example, our domain name is @olddomain.com in Okta, but in Google Workspace our domain name is @newdomain.com.
- Now, Google expects that Okta will refer to user@newdomain.com in all the interactions as Google does not have any information about user@olddomain.com.
- In this specific case, we can create an attribute transformation rule in Okta saying, if the user is trying to access Google Workspace, change their email address on the fly from user@olddomain.com TO user@newdomain.com, this is called ‘Attribute Transformation’, geeky way of saying this would be ‘Send transformed attribute in the SAML response’.
- This way, Okta can send the user attribute value which is expected by the target application without changing this user’s attribute in Okta or for other applications assigned to this user in Okta.

Single Sign On (SSO)-:

- An authentication method where a user can login to multiple applications with just one set of credentials is called Single Sign On (SSO).
- This one set of credentials belong to user’s identity provider (for e.g Okta in our use case here), and then behind the scenes this identity provider integrates with other applications or service providers (e.g Google Workspace, Salesforce etc).
  These applications rely on Identity provider for user authentication instead of asking users to provide user id and password.

RelayState

- You can think of the relayState as the first destination where you will land after your IdP authenticates you to the service provider.
- For example, after Okta authenticates you to Google, whether you would land at Gmail, or Google Drive or Google Sites, it really depends on what you have set up in the relayState parameter of the SAML response.
- This might be helpful to know, especially for cases where you want your users to land at a specific Google service after authenticating themselves via Okta.

Network Masking-:

- This is specific to Google Cloud Identity (or Google Workspace) where you can restrict the scope of Single Sign On (SSO) to an IP range.
- For example, if you put an IP range in Google’s network mask while setting up SSO, Google will only redirect users to your IdP if they login from an IP address that belongs to this IP range, other users will be required to login via their Google email address and password as usual.

Classless inter-domain routing (CIDR)-:

- When you configure Networking Mask in Google while setting up SSO, it does not take the IP addresses, rather a CIDR.
- CIDR is a flexible way to define how many bits of an IP address belong to the network (network ID) vs host (e.g host ID), so if you take C class IP4 (192.168.12.12) as an example here and put /32 to it (e.g 192.168.12.12/32), then it means 32 bits (note /32) are the network id which will result in just one IP address.
- We will use this when setting up Okta SSO with Google Workspace, so we can restrict SSO scope to only one IP address for testing before enabling it to all users in our company.

Session Timeout-:

- When you start interacting with an application, it would ask you to authenticate for the first time, however to provide you rich experience, it will create a session which will uniquely identify you, this helps avoid a situation where it needs to ask you to authenticate every time you do interaction with that application.
- You would find different applications with their own default session timeout, for e.g Google Workspace (Gmail, Drive etc) has a default session timeout length of 14 days, which means once you authenticate yourself, then you would not need to authenticate for 14 days (except some scenarios like IP, location, reset cookies etc changes or Google finds something suspicious).
- Some applications provide a way to change default session timeout and have your own custom setting there (like Google Workspace), which means if you change the default session timeout to 2 hours, then users will need to re-authenticate themselves every 2 hours.

SLO

- Single Logout (SLO) -: When your Identity provider (e.g Okta) authenticates you to the service provider (e.g Google Workspace), a session is created. Now if you logout from Okta, your session is still active with Google Workspace, and if you logout from Google Workspace, your session is still active with Okta.
- Single Logout (SLO) is a way to kill all the active sessions for both (Identity provider and Service provider).

User Provisioning to Google via OKta

In this section, let us understand how we can leverage Okta to manage our Google users lifecycle including creating, updating and suspending users.

Watch this video for step by step instructions

Perquisites

To get started, let us first understand what would we need to setup provisioning-:

Google Workspace or Google Cloud Identity Super Administrator Email and Password.
Okta Super Administrator User Id and Password
Atleast one test user account in Okta (either created directly in Okta or brought over by Active Directory)
You should have already taken care of Google Conflicting Accounts.

I would also recommend to have clarity on which users (and groups) you want to provision from Okta to Google before you start.

Though it really depends on your use case, but I have seen some use cases while doing Okta and Google Workspace implementations where enterprises provision based on following-:

AD Group based provisioning -: Some organizations create a group in their Active Directory called google_users and then use this as provisioning basis (e.g whoever is member of this group, provision them to Google).
AD OrgUnit based provisioning -: Though not usual but some organizations go with OrgUnit based approach where any user of a given AD orgUnit gets provisioned to Google (via Okta).
Attribute based approach -: Some organization in some complex or custom use cases also go with user attribute based provisioning (e.g if the user.department = “IT”, then provision them to Google.

Ideally unless you are very clear on your use case and provisioning approach, you should go with Group based provisioning as it provides more flexibility and do less strain on your AD.

I will show you group based provisioning as it is very commonly leveraged, however i’ll put details below on how to do orgUnit and user attribute based provisioning just in case if you need that.

Also, provisioning process is same regardless of whether you are using Google Workspace or Google Cloud Platform or Google Drive Enterprise.

Provisioning Steps

Login to your Okta tenant

Go to your Okta tenant (e.g yourcompany.okta.com)
Enter your User Id and Password (and second factor if it is setup)

Click on the Admin button on the to right to go to Okta Admin console (as shown in the screenshot below).

Go to Applications (as we will be adding Google Workspace application).

Click on Add Application

Search for “Google Workspace” and click on it from the integrations as shown in the screenshot below.

Add Google Workspace Application for provisioning

Along with Google Workspace, products like Google Cloud Platform and Google Drive Enterprise also leverages Google Directory.
So even if you use Google Cloud Platform (without Google Workspace), you would still need to add Google Workspace app in Okta for provisioning to Google Directory.
Think of it like this, though the app here says Google Workspace, but you would be provisioning to Google Directory via it, which can then be used by products like Google Workspace, Google Cloud Platform or Google Drive for Enterprise.

As you see in the screenshot below, this application supports user lifecycle management to Google Directory.
Click on Add button to add the Google Workspace application.

Add your Application label (e.g Google Workspace), this can be changed later.
Add your Google Workspace (or Google Cloud Identity) domain, this can NOT be changed later, please make sure to put it right.
Okta provides users a single dashboard where users see the icons of the applications which are assigned to us, if you would provide Okta SSO access to access to Google Workspace, then check the apps you want to show on users dashboard.

If you would only be using Google Cloud Platform (and not Google Workspace), then you would not want to show these icons (e.g Gmail, Drive etc) on your users Okta dashboard, hence these can be unchecked here.

If you use Google Workspace, Okta provides you functionality to add licenses to your Google Workspace users. You may enter your Google Workspace license count here to leverage Okta seats related reporting.
You can decide whether to show Google Workspace application icons to users on their Okta dashbaord and in Okta’s mobile app.
You would rather be using SAML, do not worry about “Browser plugin auto-submit” and leave it unchecked.

Click on SAML
Click on Save

Note -: We are not turning on SAML or SSO yet, Okta only shows the user provisioning features once you enable SAML, hence we will just click on SAML and Save to move forward.

Now you would see additional options in your Google Workspace app (make sure you are in the Google Workspace app that you started configuring)
Click on “Provisioning” tab
Click on “Configure API Integration”

FYI –: As Okta leverages Google’s Directory API to manage Google user lifecycle (e.g creating, deleting, updating Google users).

Click on Enable API Integration
Then click on “Authentication with Google Workspace”

FYI –: We are now starting the process to authorize Okta (via OAuth) to programmatically (via Google’s Directory API) interact with our Google tenant for users, groups and members management.

Login to your Google Workspace Admin account (which should have either Super Admin OR delegated administration based on your requirements (e.g if you need Okta to manage only users, then delegated admin account here should have user management permissions)
If you are already logged in, please click on the account that you want to use to authorize Okta.

Google is now providing you information about what Okta would be authorize to manage once you click allow.
You can also click on exclamation icons to learn more about each OAuth scope here.
Once/if satisfy, click Allow as shown in the screenshot below.

You should now see the successful message that your API integration has been enabled successfully.

Click on Save.

Please make sure that you are in the same Google Workspace application that you are configuring
Click on Provisioning
Important –: Please make sure the flow of provisioning is from Okta to Google Workspace, and then click on “Edit” as shown in the screenshot below.

Enable “Create Users” if you want Okta to create users in Google Directory.
Enable “Update User Attributes” if you want your users attributes to be synchronized from Okta to Google.
Enable “Deactivate Users” if you want your suspended or deleted Okta users can be suspended or deleted in Google.
Enable “Sync Password” if you want Okta to push your Okta user password (or AD password if you have AD delegated authentication setup).
Once done, click on Save to save your changes.

If you scroll below, you would see user attribute mapping, where Okta should have already mapped primary attributes (e.g Name, email etc).
However, Okta provides you flexibility to map any attributes as per your requirement including the custom attributes that you have created in your Okta (e.g a custom attribute called “T-Shirt Size” to sync with Google Directory.

Testing our configuration

We are now done with setting up user provisioning from Okta to Google Directory, its time to test our configuration.
You would create a test user in your Okta tenant (or use existing if you already have one) and assign him/her Google Workspace application.

Note -: For now we first need to test our configuration with a test user, however later in this post we will set up group based provisioning for dynamic and scalable provisioning.

If you have configured integration with multiple Google Workspace tenants, please make sure to assign our test user the correct Google Workspace tenant.

Choose the Google Organization Unit where you want to create this test user.

By default Okta suspends the users who is deactivated in Okta, you can check the box “do not suspend user”, ideally leave it unchecked.
Okta can provide your Google Workspace license reporting, you may consider putting “true” to manage licenses on create and update.
Select the license you want Okta to apply to this user (Note – If you do not use Google Workspace, and configuring provisioning for GCP, you can select “Cloud Identity” license at the bottom from this list.
Click on Save and go back.

You should see the application as “Assigned” now, click on Done.

You should give it a few minutes and then go to your Google Admin Console –> Reports –> Admin.
You should see that Okta created our test user account in Google and also assigned the license we requested for this user.

If it has been a few minutes and you still do not your test user created, please look at the logs in Okta and in Google. Also, please make sure your Google service account has required permissions.

Scaling our user provisioning

After testing our provisioning setup successfully, I will now leverage Okta’s “Group based provisioning” to add all required users to Google directory.
Okta supports (i) AD Mastered Groups (ii) Application Mastered Groups and (iii) Okta Mastered Groups for provisioning.
Though I personally prefer to go with Okta mastered groups because it allows to define dynamics membership rules (even if/else conditional rules), but let me show you both AD mastered and Okta mastered group assignment below.
Click on the toggle below to see configuration for AD mastered group and Okta mastered group.

Option 1 - Use Active Directory Mastered Group

If you already have a group in your Active Directory that includes the users you want to provision to Google (via Okta), then you can simply choose this group.

However, you would need to keep managing this group in Active Directory as Okta would be making changes to Google directory based on this group membership (e.g if someone is removed from this group, Okta would suspend that user from Google)

I personally prefer “Okta Managed” groups which allows more granularity as you see in the toggled section (Option 2) below.

Option 2 - Use Okta Mastered Group (Recommended)

Leveraging Okta mastered groups for provisioning in target app

I personally prefer to go with Okta groups because it allows to define dynamics memberships based rules (even conditional rules).

Let me show you how to create an Okta group, populate it with members based on our condition, and finally use it as a basis for provisioning.

Step 1-: Login to Okta Admin Console and go to Groups as shown below

Step 2 – Click on “Add Group” to create a new Okta mastered group

Step 3 – Name your Group and give it a description to it becomes easy to find later

Step 4 – Create a new Rule

Let us now create a new rule in our Okta group to

Step 4 – Create a new Rule

You can add users to your Okta group either by selecting “Groups Memberships” as we are doing in the screenshot below.
You can also use user attributes like user.department = “IT”
If you need more flexibility to go granular, you can leverage Okta expressions where you can really combine attributes and groups memberships, and can also use conditionals.

In this example, I am simply asking Okta to add members of my Active Directory Google Workspace users to my Google Workspace Okta group (this will be dynamic so if i change the group membership in AD, it’ll be in sync at next Okta directory sync run).

In this example below, I am using Okta’s expression language to only add members to my Okta Google Workspace group when they are members of Google Workspace group in my Active directory AND if their department is equal to IT.

Assign Group for Google Workspace provisioning Scope

As our group is now available in Okta (either the AD mastered or Okta mastered group).
Its time to assign it to Google Workspace for our provisioning scope as shown in the screenshot below.

SSO to Google via Okta

In this section, we will setup Okta as our Identity provider to Google, so our users can login to Google Workspace (or Google Cloud Platform) from Okta.

Watch this video if you use Google Workspace OR Google Workspace + Google Cloud Platform

Watch this video if you use Google Cloud Platform, but not Google Workspace

Perquisites for SSO to Google via Okta

To get started, let us first understand what would we need to setup SSO-:

Google Workspace or Google Cloud Identity Super Administrator Email and Password.
Okta Super Administrator User Id and Password
Atleast one test user account in Okta (either created directly in Okta or brought over by Active Directory) who has also been provisioned in Google.
Optional, but highly recommended – An IP address to test SSO before rolling it out in production.

Login to your Okta Administration Console.

Go to Applications as shown in the screenshot below.

Click on the Sign On tab and then Click “SAML” radio button as shown in the screenshot below.
Now instructions would appear, click on “View Setup Instructions”.

Scroll down a bit and copy the following as we will need them later when we configure SSO settings in Google Workspace.

Sign in page URL
Sign out page URL
Change Password URL
Click on verification certificate to download it

Your certificate from Okta should be downloaded now, we’ll need this certificate later to upload in Google Workspace (or Google Cloud Identity) SSO settings.

Login to your Google Workspace (or Google Cloud Identity) Administration Console
Go to Security

Scroll down to find “Setup Single Sign-On (SSO) with a third party IdP.
Click on it to open its settings.

Paste the SSO URL that you copied from Okta.
Paste the Sign out Url that you copied from Okta (your may put any url here where you want users to go when they sign out).

Click on upload the certificate.
Select the certificate that you downloaded from Okta.
Upload it.

Please ensure your certificate has been uploaded as you see in the screenshot below.
Check on “Use a domain specific issuer”.
Put your testing IP address here in the CIDR format (You should put /32 to make the SSO only apply on this specific IP address.
You can read more about Network mask feature in Google Workspace above.
Paste the change password URL that you copied from Okta.
Save your changes.

Though you would have your own specific settings from Okta, but they would something like shown in the screenshot.

Now activate SSO by checking the box “Setup SSO with third party identity providers”
Save your changes.

As soon as we save our changes, SSO should be applied but ONLY from the test IP address we have put, all other authentication requests from other IP addresses should route through Google as usual.

Now let us try to sign in via Okta (Idp Initiated sign on) to see how is our SSO working.
Please make sure of following-:
- You are testing SSO via a test user (not the admin user, as Google admin users bypass SSO).
- You are testing it from the IP address that you have put in Network mask above in Google SSO settings.

We should be able to successfully login to Google Workspace now.

If you see any error, please ensure you have followed the above documentation well, or look at the FAQs section at the bottom of this post to understand common SSO errors and their solution.

Now let us try to sign in via Google (Service Provider Initiated sign on) to see how is our SSO working.
Please make sure of following-:
- You are testing SSO via a test user (not the admin user, as Google admin users bypass SSO).
- You are testing it from the IP address that you have put in Network mask above in Google SSO settings.

You should ideally be now redirected to your Okta Sign in page (unless you are not already signed into Okta).
Enter your Okta credentials to sign in.

We should be able to successfully login to Google Workspace now.
If you see any error, please ensure you have followed the above documentation well, or look at the FAQs section at the bottom of this post to understand common SSO errors and their solution.

Handing Advance Scenarios

In this section, let us talk about handling some advance SSO scenarios like transforming attributes on the fly using Okta’s expression language etc.

Table of Contents for Advance Cases:

Use Cases & Solutions

We have different domain name in our AD/Okta vs Google, how do we SSO?
We already have some users in Google, would they get deleted once we start Okta?
What are Okta Expressions, and how do we use it for attribute transformation?

Different Domains in AD/Okta vs Google

Watch the video below if you have different domain in AD/Okta vs Google, but still want to do Okta SSO to Google.

I have done couple of Okta and Google Workspace implementation where due to rebranding those enterprises wanted to go with a new/rebranded company domain for Google Workspace.

Though it is not limited just to rebranding cases, think of acquisition cases where you acquire a company who is already using Google Workspace, but not Okta, you may merge them with you AD, but they would have different Google Workspace domain than of your Active Directory.

I have also seen some cases where enterprises intentionally go for a test domain when doing Google Workspace or Google Cloud Platform proof of concept.

Concerns-:

Google Workspace only accepts user’s primary email address as identifier to authenticate users via Identity providers like Okta.
However, in rebranding, POC or other similar cases, your users LDAP / Okta email would be different than Google Workspace, which means Okta will send user@oldDomain.com in the SAML but Google would need user@newDomain.com.
Hence the SAML SSO will not work.

Solution-:

We can leverage Okta’s attribute transformation feature which provide flexibility to transform attribute before sending it to the target application (e.g Google Workspace).
We can create a rule in Okta saying “when our users try to access Google Workspace, take the user name part (e.g before @ in their email), and then append the domain that we have in Google to it.
I would recommend you to watch my video above to see its done, but let me also add some screenshots below if you prefer them.

Go to Okta Admin Consoe and then to your Google Workspace application.
Click on “Sign On” tab
Click on “Edit” and scroll down to “Application Username Format”

You would a few options here, you should first see if any of the provided options fit your needs.
If they do not, then select “Custom” which allows us to use Okta’s expression to create custom username.

Ensure you have clicked on “Custom” from the application username format dropdown.
Here you should put the expression (based on Okta’s expression language) which would result the required email address for your Google user.
Example -: in below scenario, my users email in Okta is username@id.goldyarora.com, however my Google Workspace domain is @newDomain.com, so i want Okta to send the transformed email address in SAML (nameID)
So, I will use the following Okta expression
(String.substringBefore(user.email, “@”) +”@newDomain.com”)
where Okta does the following-:
(i) It first parses the username string which is before @
(ii) Then it appends @newDomain.com to it.
Now before you save your change, it is critical to ensure that your expression is correct and giving you the expected email address.
For that, you can put any of your Okta user email in preview box (look at #3 in below screenshot)
You should then check the result that preview gives you (look at #4 in screenshot below), this result should match this user’s Google username/email.
You can then save the changes, now onwards, Okta would send the transformed email address (e.g user@newdomain.com in our example) to Google.

We already have some users in Google, how would be manage user lifecycle via Okta?

Watch the video below if your users already exist in Google, and now you want to manage Google user lifecycle via Okta.

We already have some users in Google, would they be deleted?

I have seen some cases where organizations start using Google Workspace (or Google Cloud Platform) before rolling out Okta.

Concerns-:

In this case, concern usually is lack of clarity about whether these Google users would be deleted or not once we start using Okta for provisioning (and SSO).

Solution-:

First of all, though we would need to do some work in this case, but rest assured, we can handle this situation without impacting users.

Okta provides an “Import Users” feature, which means we can import users from Google to Okta, and once these users are in Okta, we can assign them Okta user profile.

There would be two scenarios in such case, and let us handle them one by one.

Scenario One -: Google users also exist in Okta

We can use Okta’s “Import Users” feature to bring these Google users to Okta, and once they are in Okta, we can create their Okta profile.
Result = These users would now have new Okta profile, so they can login to Okta, and Google Workspace would appear on their dashboard to access at one click (via SAML).

Scenario Two -: Google users do not exist in Okta

We can use Okta’s “Import Users” feature to bring these Google users to Okta, and because these users already have their Okta profile, we can map these users to their respective Okta account.
Result = These users would now see Google Workspace apps in their Okta dashboard to access with one click.

Go to your Google Workspace application in Okta
Click on “Import” tab
Click on the “Import Now” button as shown in the screenshot below.

Okta should now start process of importing your Google users to Okta, it may take sometime depending on number of users in Google.

Note -: Please ensure you have already completed API integration setup as shown in provisioning section above, otherwise Okta would fail to import users because Okta would be calling Google’s Directory API to get these users.

Okta should now show you the summary of how many users/groups scanned and imported to Okta

Now on this screen, Okta would show you whether the imported Google user has an Okta profile or not (based on user’s email address).
If the Okta user does not exist, Otka would ask you to confirm new Okta account creation for this user.
You should review and select the checkbox (look at #3 in screenshot below) to select all (or required users).
Click on “Confirm Assignments” to confirm new Okta user account creation.

Note -: In case Okta user already exists with the same email address as of Google user, then instead of creating a new Okta account, it would ask you to confirm the mapping for existing account.

Here you would do the final confirmation and tell Okta whether or not auto-activate users after confirmation.

That is it, now your Google users are in Okta, and can login to Google Workspace via Okta SSO.

Okta would also not try to recreate them in Google, because it now knows that these Okta users are already in Google.

Important

Though everything should be working now for this specific use case, however if you look at assignment tab in Google Workspace app in Okta, you would find these users are individually assigned to Google Workspace application.

Though it is optional, but I would recommend you to convert their assignment from individual user to group based, so you can easily manage them via your AD or Okta groups.

You should follow these steps if you want to do that (or watch my video above)-:
(i) Disable the "Deactivate Users" (go to Okta --> Google Workspace App --> Provisioning Tab --> Edit)
(ii) Delete these users individual assignment (go to Okta --> Google Workspace App --> Assignment tab --> click on X mark)
(iii) Make sure these users are in your Group which you would be using for Google assignment.
(iv) Check the assignment, and these users should have Google app assignment based on your group assignment.
(v) Enable "Deactiave Users"

Recommended

GCDS vs Okta

In this section, let us talk some prominent differences between Okta and Google Cloud Directory Sync (GCDS), which one we should use in which scenario

Google Cloud Directory Sync and Okta both have their pros and cons which should be considered before making your decision to use them for managing your Google users and groups lifecycle.

You should ideally contact your Google or Google partner and Okta for recent developments in their products, however following table would help you as a starting point to understand some differences between these two utilities and recommendations for usage.

Scenario	Rationale & Recommendation
Multiple Data Sources (e.g Multiple AD Forests) or Mergers & Aquisitions use cases	Use Okta If-: 1. You already have all your identities provisioned in Okta (ideally they should be there, thats why you use IdPs). 2. You have multiple data sources (multiple AD Forests & HRMS systems) to bring your identities in Google Use GCDS if-: 1. You have a single AD Forest to bring your identities to Google, though there are workarounds like spinning up multiple GCDS instances and leveraging exclusion rules, but it would not be easily manageable. 2. Your identities (that you want to provision in Google) are not in Okta.
Attribute Level Mastery	If your provisioning requires attribute level mastery For example-: (i) Job title would come from workday. (ii) Email will come from Active Directory. (iii) Phone number will come from Ring Central. Then use should Okta as GCDS does not provide attribute level mastery. If all your attributes would be mastered from Active Directory (or LDAP), then you may use Google Cloud Directory Sync too based on other criteria in this table.
Write back to Active Directory	GCDS does not write back to Active Directory, so you should use Okta for it, however GCDS and Okta can also be used in combination where you leverage GCDS for user lifecycle management, and Okta for write back to AD.
Org Unit Sync	Use GCDS as it synchronizes OrgUnits well to Google, though you may be able to do it with Okta too, however it gets pretty messy as you would need to create lots of groups and assign priorities to it.
Shared Contacts Sync	"Use Google Cloud Directory Sync as Okta does not sync Shared Contacts. (Shared Contacts = your external contacts like vendors, contractors etc) Otherwise, because of other reaons you want to use Okta for provisioning, then you may use Shared Contacts API to separately manage shared contacts."
Resource Calendar Sync	Use Google Cloud Directory Sync as Okta does not sync Resource Calendars. (Resource Calendars = Conference Rooms etc) If because of other reaons you want to use Okta for provisioning, then you may use Calendar API to provision initial resources and then manage them in Google.
Attribute Transformation	Use Okta if you have complex use cases which needs lot of attribute transformation (e.g if you want to send transformed attributes from AD to Google). Though GCDS also let you transform attribute but only the domain name (e.g user@ad.local TO user@googledomain.com)
External members in Google Groups	If you would have external members (e.g @yahoo.com) in your Google Workspace groups, then use GCDS as Okta doesn't manage/sync external members.
HRMS as a Master	If you want to use your HRMS system (e.g Workday) as a master, then use Okta, as Google Cloud Directory Sync does not sync with HR Systems (only LDAP and AD)

Popular Okta Expressions

In this section, I would put some expressions based on Okta Expression language that might help if you have related use case.

Okta Expressions

To Parse the Organizational Unit from distinguishedName (dN)

Example –> Dn = CN=R A,OU=Third OU,DC=ad,DC=goldyarora,DC=com

Need to parse just the OU name, example “Third OU” from above.

Expression -:

String.substringAfter(String.replace(appuser.managerDn, “,DC=ad,DC=goldyarora,DC=com”,””), “OU=”)

Explanation -:

Following internal expression to remove ,DC=ad,DC=goldyarora,DC=com from the string, and then we are left with CN=R A,OU=Third OU

String.replace(appuser.managerDn, “,DC=ad,DC=goldyarora,DC=com”,””

Outside string gets substring after the text after OU= in CN=R A,OU=Third OU

Parsing Manager’s Name from the CN

CN = “CN=R A,OU=Third OU,DC=ad,DC=goldyarora,DC=com”

String.substringBefore(user.manager, “,OU”) – get the part before ,OU

Now we are left with CN=R A

Add another express to to get the part after =

Combine above both expression into one-:

String.substringAfter(String.substringBefore(user.manager, “,OU”), “=”)

Replace any domain while sending to downstream app-:

String.replace(user.email,String.substringAfter(user.email,”@”),”gsuitedomain.com”)

Replace any domain name from input to Google Workspace one

Conditional Expressions-:

Syntax ==> [Condition] ? [Value if TRUE] : [Value if FALSE]

// smtp based on org name – multiple conditions

If you have multiple brands, and want to assign Google Workspace primary email based on brand, you can use conditional expression to check for user attribute and assign email based on it as shown in example below.

(user.organization == “Brand One”) ? (String.substringBefore(user.email, “@”) + “@brandone.com”) : (user.organization == “Brand Two”) ? (String.substringBefore(user.email, “@”) + “@brandtwo.com”) : (String.substringBefore(user.email, “@”) + “@catchall.com”)

In above expression, Okta checks for user.organization attribute value, if it is equal to “Brand One”, it assigns brandone domain to user, otherwise it goes to next condition and assign brandtwo.com if user belongs to Brand Two, if both conditions are false, Okta assigns catchall.com domain.

Okta Google Integration - FAQs

Here am listing some of the frequently asked questions about Okta and Google Integration, if you have any question, please comment in the bottom, and I will add it (along with the answer) to FAQs.

FAQ

Most frequent questions and answers about Google and Okta Provisioning and SSO Integration.

Why can't we delete Google users from Okta?

Okta intentionally does not delete users in Google, rather suspend them as you see here https://support.okta.com/help/s/article/Google-Apps-Deployment-Guide

I think it makes sense as deletion in Google is pretty sensitive, once you delete the account, you get 25 days to recover it, and if you miss it, your data is gone forever.

I have a script which you can leverage to unassign (or delete) users in bulk, you can access these scripts below-:

You should not delete your Google users or unassign their Google Workspace licenses unless you know what you are doing, you should ideally unassign their Google Workspace Business or Enterprise license and assign Google Workspace Archive User License so you pay less than regular Google Workspace license cost but still retain Google Workspace users’ data.

We have configured SSO but Google users can not redirected to Okta

You should check for the following-:

Have you configured “Network Masking”? If yes, make sure you use the IP address that is part of your IP range in Networking masking.

Also, make sure you are not testing through mail.google.com, but rather mail.google.com/a/yourdomain.com
Google Super Admins by pass SSO, so make sure you are testing with a regular Google user, and not a super admin one.
SAML SSO is not supported on POP/IMAP, so ensure you are testing with Google Web application.

This service cannot be accessed because your login request contained no recipient information"?

You should ensure that your Okta SAML response include valid Google ACS URL which can either be-:

https://www.google.com/a/yourdomain.com/acs

or

https://accounts.google.com/a/yourdomain.com/acs

and in case if you are getting the error “It means the Recipient attribute in the SAML Response does not match the Assertion Consumer Service (ACS) URL.” that means though you SAML includes the recipient but not the correct one as provided above.

What does this error message mean: "This account cannot be accessed because the login credentials could not be verified?

This error indicates issues with your certificate (e.g private key used to sign SAML does not match your public key certificate that you uploaded to Google Workspace).

Please upload the right certificate again that you downloaded from Okta to Google Workspace and try again.

If our user logs out from Okta, does he get logout from Google as well?

No, once Okta authenticates your user to Google, then a session is established between the user and Google which Okta do not control.

So you should define your session control in Google, which should ideally be less than your session configured in Okta.

You can read my blog post here about session control in Google Workspace or GCP.

How can we setup multiple Identity providers in Google?

You can not, as Google does not support multiple identity providers.

Though it depends on your scenario, but you might be able to manage this scenario within your Identity provider (e.g Okta).

For e.g -: If you have two set of users (which are different because of their domain name, or any attribute), and you want them to be authenticated via different Identity providers (e.g abc.com users should be authenticated against Okta, and xyz.com users should be via Azure).

You can do following in this specific use case-:

1. Configure required Identity provider in Okta (e.g Azure in above example use case).

2. Configure Google as service provider (with Okta as identity provider).

3. Create an IdP discovery rule in Okta which says (i) if the user is trying to access Google application AND (ii) user domain name is xyz.com, then Azure is the identity provider.

Now, when your xyz.com users try to authenticate to Google, they’ll be redirected to Okta –> Azure –> Okta –> Google, some of this interaction will be invisible to the end user though.

I have a question, what should I do?

Ask it in the comments below, and I would try to answer it (if i can) as soon as I get time.

RECOMMENDED READING

As you just read Definitive Guide to Okta & Google Integration, I would recommend following as complimentary reading.

Google Workspace to Office 365 SSO & Provisioning Guide

Admin Google Workspace Security SSO

Google Workspace to Office 365 SSO and Provisioning Guide

Definitive-Guide-to-Google-Conflicting-Accounts

Google Conflicting Accounts

Definitive Guide to Google Conflicting Accounts

Google Workspace Password Vaulted Apps

Admin Google Workspace Security SSO

Securely login to any app with Google Workspace Password Vaulted Apps

18 thoughts on “Definitive Guide to Okta & Google Integration”

Vivek Vibhuti
May 26, 2022 at 4:24 pm

Hi Goldy,

We are seeing some strange behavior with regards to the process of changing users’ licenses in AD and having it pull/push into Okta and then to Google Workspace. When doing so, the users get stuck marked “Suspended by Admin” and must be manually reinstated. This ties to a specific failover account that isn’t used, but I believe may be tied to the Okta/Google Workspace automation in some way. This did not used to happen, so I want to figure out what is this account’s role in our infrastructure and how to correct the workflow around changing licenses.

any insight as to why this is happening.

Thanks a lot in advance.

Reply
1. Goldy Arora
  July 25, 2022 at 8:12 pm
  
  I think it is more towards Google’s abuse detection (sometime false positives too:), i would recommend you to contact Google support for it.
  
  Reply
Jonathan
November 4, 2021 at 6:03 pm

Hello Goldy,
If we have multiple domains and/or multiple OUs within our Google Workspace, can we enable Okta SSO/Provisioning for only a single domain or OU instead of the entire Workspace?

I ask this because we have service accounts and client accounts within our Workspace that we would not want to block access by configuring Okta to Google since they are not located within Okta.

Reply
Halbert
September 29, 2021 at 3:14 pm

Hi Goldy! Thank you for putting together this detailed guide!
I’ve followed your instructions on integrating Google Workspace in Okta so that user provisioning is managed from Okta. When I create a test user in Okta, the user is created in Google Workspace but it is immediately suspended. This creation process triggers a “Google Identity” alert and it in response, the new user is suspended. The only way to un-suspend the user is to login as that user and reactivate the account via SMS. I reached out to Google’s customer support and he told me this is the expected behavior when a 3rd party invokes a user creation call in Google Workspace.

Is this the same behavior you are experiencing? If so, is there a way to work around this?

Thanks!

Reply
1. Goldy Arora
  October 5, 2021 at 2:39 pm
  
  It has nothing to do with your setup, it is usually around Google’s abuse protection, raise a ticket with Google support, and they should be able to help you.
  
  Reply
Ben
May 20, 2021 at 12:50 pm

Hi Goldy! Thanks for putting this resource together. It’s a real lifesaver!

I’m curious if you’ve ever experienced this issue, or have any thoughts as to what may be the problem:

A team I’m working with is testing Google Workspace Context-Aware Access levels with their core IT – despite meeting all of the CAA conditions, 1 of the 4 core IT users is denied access to Google Apps when navigating from OKTA. If they refresh, they are eventually granted access (though it can take anywhere from 10 seconds to10 minutes of refreshing). They can access Google Apps directly through the app URL with CAA levels applied, and can access Google Apps through OKTA when CAA levels are deleted – but not through OKTA when even a single CAA level is applied.

We’ve tried reconfiguring the CAA levels, attempted to login using different approved devices (mobile, desktop, chromebook), and ensured that the endpoint mgt extension is installed and synced, but this same issue still persists for this one user.

Do you have any insight as to what may be the issue between OKTA and Workspace in this instance, and how to resolve this issue?

Looking forward to hearing your thoughts. Thanks Goldy!

Reply
1. Goldy Arora
  July 27, 2021 at 6:02 pm
  
  let me reach out to you personally to talk about this 1:1.
  
  Reply
2. Koen Korver
  August 13, 2021 at 5:24 am
  
  Hi Ben,
  We experience the same thing and can’t seem to find the right solution. Okta support points to Google and vice versa.
  On Chromebooks there is no problem but all out Mac / Windows users experience the exact same thing as you are describing. It looks like Endpoint Verification is too slow picking up the redirecting url or so.
  We can’t find any documentation anywhere so it would be much appreciated if you or anybody else can help.
  
  Looking forward to hearing from you.
  Koen.
  
  Reply
Michael Ng
November 17, 2020 at 11:06 am

Hi Goldy,

Amazing guide and much appreciate you took to create this.

Questions
1. The “IP” range option, we will only need to provide the IP range or address for testing purposes correct? Let’s say I’m working from home and I use my home IP Address, I should be the only user that will be forced to authenticate through Okta when I setup GSuite/Okta integrations.

2. What happen to users who are using MS Outlook for example? Or they want to setup their Gmail on their phones?

3. We are currently a GSuite customer and we have 2 steps verifications enforced. How does this work?

Thank you very much!

Reply
1. Goldy Arora
  December 11, 2020 at 8:55 pm
  
  Hi Michael, answers below-:
  1. Thats right, if you put your home IP in network mask, then you would be redirected to Okta only if you try to login from this IP address, rest of the requests will take google as identity provider.
  
  2. It depends on the MS Outlook version as it should support modern authentication to make it work with SAML SSO, you can get more information about it on this article by Microsoft https://docs.microsoft.com/en-us/office/dev/add-ins/outlook/authenticate-a-user-with-an-sso-token
  
  Gmail mobile app works well with SSO, so when your users try to configure it, it will redirect them to your identity provider (e.g Okta).
  
  3. Google’s two step verification will be ignored once you setup and enable third party identity provider (e.g Okta), however Google provides a feature called “Post SSO verification”, if you enable it, then Google would challenge the user for Google 2SV if it finds the login attempt as suspicious, more info about this feature is here https://support.google.com/a/answer/6002699?hl=en
  
  hope it helps.
  
  Reply
Damir Reic
August 17, 2020 at 5:46 pm

Hello Goldy,

we have setup Gsuite with Okta long time ago and it’s working fine. Now we tried to setup GCP with Okta and problem we are facing is:

This account cannot be accessed because the login credentials could not be verified.

I was listing certificate from Gsuite and GCP and found out they are not the same. If I create multiple GCP apps on Okta they all use the same certificate from first GCP app. I managed to get the same certs after I deleted all GCP apps and newly one used same cert as GSuite apps.

We have scenario where companies merged and initial domain that was primary before still is primary but all users are using new domain to log to Okta and GApps. For some reason Gapps work fine, but GCP is giving issues with credentials validation.

I tried implementing string replace on the domain so user matches primary domain (which is not his username, only email alias) but still same problem. Any thoughts on the problem?

Reply
1. Goldy Arora
  December 11, 2020 at 10:20 pm
  
  Hi Damir – I am sorry, I could not understand it well enough.
  there is just one connection between Okta and given Google tenant for sso (regardless of whether you use Google Workspace or also use GCP), so no multiple certs.
  have you watched the video above?
  
  if you have multiple Cloud Identity tenants, then you would do one connection per tenant in Okta OR use attribute transformation via okta expressions if it helps with your use case.
  
  Reply
Yessi
July 30, 2020 at 4:38 am

Hi Goldy,

Thank you so much for these guides!! It is a lot of work on your part..so sincerely THANK YOU!
I have a couple questions…
1. What do you recommend setting up first…GSuite SSO or GSuite Provisioning?
2. We have service email accounts, meaning, GSuite email accounts used to integrate applications, say, Zendesk integration with Jira…so we have a service account for that purpose…What will it happens to those accounts when SSO is turned on? How these accounts whould be handle when we turn OKTA SSO?
3. Okta already has user accounts information, when turning on GSuite provisioning… will these accounts duplicate in GSuite? If so, how to prevent these? Ideally would be …If Okta user already exists in GSuite, then do not create…if user doesn’t exist… create account.

Thank you in advance for your guidance..

Reply
1. Goldy Arora
  July 30, 2020 at 7:24 pm
  
  Your welcome, comments below-:
  1. If you are you going to leverage Okta for both provisioning and SSO, then ideally you should setup provisioning first.
  2. If the associated applications (e.g Zendesk et) are leveraging OAuth tokens (taken via associated Google Workspace user consent), then these applications should not be impacted, as they’ll keep directly calling Google’s OAuth server for to refresh access tokens (via refresh tokens).
  3. Neither accounts will be duplicated not they be deleted (assuming you have Google Workspace app assigned to these users in Okta), I have a video in this post which shows how to handle the scenario where you have some users directly created in Google Workspace before Okta.
  
  Hope it helps.
  
  Reply
eddie
May 21, 2020 at 11:36 pm

hey Goldy, thanks for posting this, it was really helpful.

I’m finding it difficult to use String.replace(user.email,String.substringAfter(user.email,”@”),”gsuitedomain.com”) to replace an incoming domain on its way to google. Okta claims a syntax error:

Invalid expression syntax String.replace(“@”,String.substringAfter(user.email,”@”),”gsuitedomain.com”)

Any clues?

Reply
1. Goldy Arora
  June 8, 2020 at 4:31 pm
  
  Hi Eddie – thats because it is expecting a string, but you are providing function, you should try this
  String.replace(user.email, (String.substringAfter(user.email, “@”)), “gsuitedomain.com”)
  
  Reply
Alvaro
April 10, 2020 at 4:43 pm

Hi Goldy, you produce SO GREAT content…we are happy users of your OKGoldy add-on when we deploy GSuite for our customers (we are a small GSuite Parter consultancy firm)

Regarding OKTA.

If ALL the “Saas” apps that our customer uses, have the option to sign on with their gsuite account, would you still recommend using OKTA?
More and more webapps offer SSO with GSuite….

Thanks a lot

Reply
1. Goldy Arora
  April 13, 2020 at 10:48 pm
  
  Your welcome Alvaro, glad I could help.
  regarding your Otka question : “Sign in with Google” is an OpenID way to login to those other applications, which indeed is more secure, and one should certainly use it being an individual.
  
  However if you are a G Customer, then ideally you should be using SAML (documentation here https://support.google.com/cloudidentity/topic/7558768), not because SAML is better than OIDC, but because Google offers controls on SAML.
  
  For e.g, you can decide who should get access to service applications via your Google Workspace / Cloud Identity id.
  
  Till today, Google does not provide option to block OIDC sign in (Sign as Google) for websites, though you can block OAuth scopes so your users can’t share it with 3rd parties other than their identity (openid scope only), but it still increases a bit of shadow it.
  
  So, today, i would recommend Google as your IdP (via SAML), instead of Okta if you are a Google Workspace / Cloud Identity customer.
  
  Reply

Leave a Comment Cancel Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.

© 2022 All rights reserved

Made with love for Google Workspace:)