Okta user provisioning and single sign-on

Last reviewed 2024-01-03 UTC

---

This document shows you how to set up user provisioning and single sign-on between an Okta organization and your Cloud Identity or Google Workspace account.

The document assumes that you already use Okta in your organization and want to use Okta for allowing users to authenticate with Google Cloud.

Note: This article uses classic organizational SSO profiles instead of SAML profiles to set up single sign-on. Organizational SSO profiles let you choose whether to apply additional authentication challenges to users, which is not supported for SAML profiles.

Objectives

• Configure Okta to automatically provision users and, optionally, groups to Cloud Identity or Google Workspace.
• Configure single sign-on to allow users to sign in to Google Cloud by using an Okta user account.

Costs

If you are using the free edition of Cloud Identity, setting up federation with Okta won't use any billable components of Google Cloud.

Check the Okta pricing page for any fees that might apply to using Okta.

Before you begin

• Sign up for Cloud Identity if you don't have an account already.
• If you're using the free edition of Cloud Identity and intend to provision more than 50 users, request an increase of the total number of free Cloud Identity users through your support contact.
• If you suspect that any of the domains you plan to use for Cloud Identity could have been used by employees to register consumer accounts, consider migrating these user accounts first. For more details, see Assessing existing user accounts.

Preparing your Cloud Identity or Google Workspace account

Create a user for Okta

To let Okta access your Cloud Identity or Google Workspace account, you must create a user for Okta in your Cloud Identity or Google Workspace account.

The Okta user is only intended for automated provisioning. Therefore, it's best to keep it separate from other user accounts by placing it in a separate organizational unit (OU). Using a separate OU also ensures that you can later disable single sign-on for the Okta user.

To create a new OU, do the following:

1. Open the Admin Console and log in using the super-admin user created when you signed up for Cloud Identity or Google Workspace.
2. In the menu, go to Directory > Organizational units.
3. Click Create organizational unit and provide a name and description for the OU:
   • Name: Automation
   • Description: Automation users
4. Click Create.

Create a user account for Okta and place it in the Automation OU:

1. In the menu, go to Directory > Users and click Add new user to create a user.

2. Provide an appropriate name and email address such as the following:

   • First Name: Okta
   • Last Name: Provisioning

   • Primary email: okta-provisioning

     Keep the primary domain for the email address.

3. Click Manage user's password, organizational unit, and profile photo and configure the following settings:

   • Organizational unit: Select the Automation OU that you created previously.
   • Password: Select Create password and enter a password.
   • Ask for a password change at the next sign-in: Disabled.

4. Click Add new user.

5. Click Done.

Assign privileges to Okta

To let Okta create, list, and suspend users and groups in your Cloud Identity or Google Workspace account, you must make the okta-provisioning user a super-admin:

1. Locate the newly created user in the list and click the user's name to open their account page.
2. Under Admin roles and privileges, click Assign roles.
3. Enable the super-admin role.
4. Click Save.

Note: The super-admin role grants the user full access to Cloud Identity, Google Workspace, and Google Cloud resources.

Warning: To protect the user against credential theft and malicious use, we recommend that you enable 2-step verification for the user. For more details on how to protect super-admin users, see Security best practices for administrator accounts.

Configuring Okta provisioning

You are now ready to connect Okta to your Cloud Identity or Google Workspace account by setting up the Google Workspace application from the Okta catalog.

Note: This application is an Okta product and is not maintained or supported by Google.

The Google Workspace application can handle both user provisioning and single sign-on. Use this application even if you're using Cloud Identity and you're only planning to set up single sign-on for Google Cloud.

Create an application

To set up the Google Workspace application, do the following:

1. Open the Okta admin dashboard and sign in as a user with Super Administrator privileges.
2. In the menu, go to Applications > Applications.
3. Click Browse app catalog.
4. Search for Google Workspace and select the Google Workspace application.
5. Click Add integration.

6. On the General settings page, configure the following:

   • Application label: Google Cloud
   • Your Google Apps company domain: the primary domain name used by your Cloud Identity or Google Workspace account.

   • Display the following links:

     • Set Account to enabled.
     • Set other links to enabled if you're using Google Workspace, set other links to disabled otherwise.

   • Application Visibility: set to enabled if you're using Google Workspace, disabled otherwise

   • Browser plugin auto-submit: set to disabled

7. Click Next.

8. On the Sign-on options page, configure the following:

   • Sign on methods: select SAML 2.0
   • Default Relay State: leave empty
   • Advanced Sign-on Settings > RPID: leave empty

9. Decide how you want to populate the primary email address for users in Cloud Identity or Google Workspace. A user's primary email address must use either the primary domain of your Cloud Identity or Google Workspace account or one of its secondary domains.

   Okta username

   To use user's Okta username as primary email address, use the following settings:

   • Application username format: Okta username
   • Update application username on: Create and update.

   Email

   To use user's Okta username as primary email address, use the following settings:

   • Application username format: Email
   • Update application username on: Create and update.

10. Click Done.

Configure user provisioning

In this section, you configure Okta to automatically provision users and groups to Google Cloud.

1. On the settings page for the Google Cloud application, open the Provisioning tab.

2. Click Configure API Integration and configure the following:

   • Enable API integration: set to to enabled
   • Import Groups: set to disabled unless you have existing groups in Cloud Identity or Google Workspace that you want to import to Okta

3. Click Authenticate with Google Workspace.

4. Sign in using the okta-provisioning@DOMAIN user you created earlier, where DOMAIN is the primary domain of your Cloud Identity or Google Workspace account.

5. Review the Google Terms of Service and privacy policy. If you agree to the terms, click I understand.

6. Confirm access to the Cloud Identity API by clicking Allow.

7. Click Save.

Okta is connected to your Cloud Identity or Google Workspace account, but provisioning is still disabled. To enable provisioning, do the following:

1. On the settings page for the Google Cloud application, open the Provisioning tab.

2. Click Edit and configure the following:

   • Create users: set to enabled
   • Update user attributes: set to enabled
   • Deactivate users: set to enabled
   • Sync password: set to disabled
   Note: You might need to adjust these settings if you're planning to consolidate existing consumer accounts. For more details, see Making Okta federation safe for account consolidation

3. Optionally, click Go to profile editor to customize attribute mappings.

   If you use custom mappings, you must map userName, nameGivenName, and nameFamilyName. All other attribute mappings are optional.

4. Click Save.

Configure user assignment

In this section, you configure which Okta users to provision to Cloud Identity or Google Workspace:

1. On the settings page for the Google Cloud application, open the Assignments tab.
2. Click Assign > Assign to people or Assign > Assign to groups.
3. Select a user or group and click Assign.
4. On the assignment dialog that appears, keep the default settings and click Save and go back.
5. Click Done.

Repeat the steps in this section for each user or group that you want to provision. To provision all users to Cloud Identity or Google Workspace, assign the Everyone group.

Configure group assignment

Optionally, you can let Okta provision groups to Cloud Identity or Google Workspace. Instead of selecting groups individually, it's best to configure Okta to provision groups based on a naming convention.

For example, to let Okta provision all groups that begin with google-cloud, do the following:

1. On the settings page for the Google Cloud application, open the Push groups tab.
2. Click Push groups > Find groups by role.

3. On the Push groups by rule page, configure the following rule:

   • Rule name: name for the role, for example Google Cloud.
   • Group name: starts with google-cloud

4. Click Create rule.

Troubleshooting

To troubleshoot user or group provisioning, click View logs on the settings page for the Google Cloud application.

To let Okta retry a failed attempt to provision users, do the following:

1. Go to Dashboard > Tasks.
2. Find the failed task and open the details.
3. On the details page, click Retry selected.

Configuring Okta for single sign-on

If you've followed the steps to configure Okta provisioning, all relevant Okta users are now automatically being provisioned to Cloud Identity or Google Workspace. To allow these users to sign in, configure single sign-on:

1. On the settings page for the Google Cloud application, open the Sign on tab.
2. Click SAML 2.0 > More details.
3. Click Download to download the signing certificate.
4. Note the Sign-on URL and Sign-out URL, you need these URLs in one of the following steps.

After you've prepared Okta for single sign-on, you can enable single sign-on in your Cloud Identity or Google Workspace account:

1. Open the Admin Console and log in using a super-admin user.
2. In the menu, click Show more and go to Security > Authentication > SSO with third-party IdP.

3. Click Add SSO profile.

   Important: Don't use the Add SAML profile button.

4. Set Setup SSO with third party identity provider to enabled.

5. Enter the following settings:

   1. Sign-in page URL: enter the Sign-on URL that you copied from the Okta settings page.
   2. Sign-out page URL: enter the Sign-out URL that you copied from the Okta settings page.
   3. Change password URL: https://ORGANIZATION.okta.com/enduser/settings where ORGANIZATION is the name of your Okta organization.

6. Under Verification certificate, click Upload certificate, and then pick the token signing certificate that you downloaded previously.

7. Click Save.

Update the SSO settings for the Automation OU to disable single sign-on:

1. Under Manage SSO profile assignments, click Get started.
2. Expand Organizational units and select the Automation OU.
3. Change the SSO profile assignment from Organization's third-party SSO profile to None.
4. Click Override.

Add the Google Cloud console and other Google services to the app dashboard

To add the Google Cloud console and, optionally, other Google services to your users' Okta app dashboard, do the following:

1. In the Okta admin dashboard, select Applications > Applications.
2. Click Browse app catalog.
3. Search for Bookmark app and select the Bookmark app application.
4. Click Add integration.

5. On the General settings page, configure the following:

   • Application label: Google Cloud console
   • URL: https://www.google.com/a/PRIMARY_DOMAIN/ServiceLogin?continue=https://console.cloud.google.com/, replacing PRIMARY_DOMAIN with the primary domain name used by your Cloud Identity or Google Workspace account.

6. Click Done.

7. Change the application logo to the Google Cloud logo.

8. Open the Sign on tab.

9. Click User authentication > Edit and configure the following:

   • Authentication policy: set to Okta dashboard

10. Click Save.

11. Open the Assignment tab and assign one or more users. Assigned users see the Google Cloud console link in their user dashboard.

    Important: The assignment settings of the Bookmark app only control visibility. To grant a user permission to use single sign-on and access Google Cloud, you must also assign them to the Google Workspace app.

Optionally, repeat the steps above for any additional Google services you want to include in user dashboards. The table below contains the URLs and logos for commonly used Google services:

Google service	URL	Logo
Google Docs	https://docs.google.com/a/DOMAIN
Google Sheets	https://www.google.com/a/DOMAIN/ServiceLogin?continue=https://sheets.google.com
Google Sites	https://www.google.com/a/DOMAIN/ServiceLogin?continue=https://slides.google.com
Google Drive	https://drive.google.com/a/DOMAIN
Gmail	https://mail.google.com/a/DOMAIN
Google Groups	https://www.google.com/a/DOMAIN/ServiceLogin?continue=https://groups.google.com
Google Keep	https://www.google.com/a/DOMAIN/ServiceLogin?continue=https://keep.google.com
Looker Studio	https://www.google.com/a/DOMAIN/ServiceLogin?continue=https://lookerstudio.google.com

Test single sign-on

After you've completed the single sign-on configuration in both Okta and Cloud Identity or Google Workspace, you can access Google Cloud in two ways:

• Through the list in your Okta user dashboard.
• Directly by opening https://console.cloud.google.com/.

To check that the second option works as intended, run the following test:

1. Pick an Okta user that has been provisioned to Cloud Identity or Google Workspace and that doesn't have super-admin privileges assigned. Users with super-admin privileges always have to sign in using Google credentials and are therefore not suitable for testing single sign-on.
2. Open a new browser window and go to https://console.cloud.google.com/.
3. In the Google Sign-In page that appears, enter the email address of the user and click Next.

4. You are redirected to Okta and will see another sign-in prompt. Enter your email address of the user and follow the steps to authenticate.

   After successful authentication, Okta should redirect you back to Google Sign-In. Because this is the first time you've signed in using this user, you're asked to accept the Google Terms of Service and privacy policy.

5. If you agree to the terms, click I understand.

   You are redirected to the Google Cloud console, which asks you to confirm preferences and accept the Google Cloud Terms of Service.

6. If you agree to the terms, choose Yes and click Agree and continue.

7. Click the avatar icon on the top left of the page, and then click Sign out.

   You are redirected to a Okta page confirming that you have been successfully signed out.

Keep in mind that users with super-admin privileges are exempted from single sign-on, so you can still use the Admin Console to verify or change settings.

Clean up

To avoid incurring charges to your Google Cloud account for the resources used in this tutorial, either delete the project that contains the resources, or keep the project and delete the individual resources.

What's next

• Learn more about best practices for planning accounts and organizations and best practices for federating Google Cloud with an external identity provider.
• Acquaint yourself with our best practices for managing super-admin accounts.