Best practices for federating Google Cloud with an external identity provider

Last reviewed 2023-02-27 UTC

This document presents best practices and guidance that help you set up federation consistently and securely. The guidance builds on the best practices for using Cloud Identity or Google Workspace with Google Cloud.

All Google services, including Google Cloud, Google Marketing Platform, and Google Ads, rely on Google Sign-In to authenticate users. Instead of manually creating and maintaining user accounts in Cloud Identity or Google Workspace for each employee, you can federate Cloud Identity or Google Workspace with your external identity provider (IdP) such as Active Directory or Azure Active Directory. Setting up federation typically entails the following:

Mapping identities

The identity of a user account that's managed by Cloud Identity or Google Workspace is defined by its primary email address. The primary email address is listed as Google Account email on the Google Account page. To be considered valid, the primary email address must use one of the domains that you have added to your Cloud Identity or Google Workspace account.

The primary email address also serves these purposes:

  • The primary email address is the username that a user must provide when signing in. Although users can add alternate email addresses or aliases to their Google user account, these addresses are not considered identities and can't be used to sign in.
  • When an admin needs to send out notifications to users (for example, to announce a potential security risk), those notifications are sent to the primary email address only.

To set up single sign-on and automatic user provisioning between Google and your external IdP, you must map identities in your external IdP to corresponding identities in Cloud Identity or Google Workspace. The following sections describe best practices for establishing this mapping.

Use the same identity across all federated systems

All that's required to establish a mapping is to verify that the SAML assertion that the IdP supplies to Google contains a NameID claim with a value that matches the primary email address of an existing Cloud Identity or Google Workspace user. The IdP is free to use whatever mapping or logic is applicable to derive a suitable NameID claim for its existing users.

Many IdPs rely on email addresses (or more generally, RFC 822–compliant names) to identify users. Examples include the following:

  • The userPrincipalName attribute in Active Directory is an RFC 822–compliant name that uniquely identifies a user and that can be used to sign in to Windows or Active Directory Federation Services (AD FS).
  • Azure Active Directory uses the UserPrincipalName attribute to identify users and let them sign in.

If the users that your external IdP manages already rely on an email address as their identity, you can use the same identity as the primary email address in Cloud Identity or Google Workspace. Using the same user identity across federated systems has multiple advantages:

  • When users sign in to a Google tool such as the Google Cloud console, they are first prompted to provide the primary email address of their Cloud Identity or Google Workspace user before they are redirected to your external IdP. Depending on your IdP, the user might then be presented with another sign-on screen that prompts for their username and password.

    If the email addresses differ for these steps, the sequence of sign-on screens can easily confuse end users. In contrast, if users can use a common identity across all steps, they aren't exposed to the technical differences between IdPs, which minimizes potential confusion.

  • If you don't have to map between user identities, it's easier for you to correlate audit logs from Google Cloud with logs from on-premises systems.

  • Similarly, if applications that are deployed on-premises and on Google Cloud need to exchange data containing user identities, you avoid the extra complexity of having to map user identifiers.

For more details on mapping Active Directory users or Azure AD users to Cloud Identity or Google Workspace, see the Active Directory or Azure AD guide.

Ensure that identities use routable email addresses

Google Cloud uses the primary email address of a user to deliver notification emails. Examples of these notifications include the following:

  • Budget alerts: If you've configured a budget alert, Google Cloud sends a notification to Billing Admins and Billing Users when a budget threshold is crossed.

  • Payment notifications: Any payment-related notifications or alerts are sent to the email addresses of payment users that are configured for the affected billing account.

  • Project invitations: If you assign the Project Admin role to a user that is part of a different Cloud Identity or Google Workspace account than the one the project's organization is associated with, an invitation is sent to the user. Before the newly granted role can take effect, the user has to accept the invite by clicking a link in the email message.

  • Replies to support cases and other notifications from Support.

If you use Google Workspace and have properly configured the necessary DNS MX records, all notification emails that are sent to the primary email address are delivered to the corresponding user's Gmail inbox.

For Cloud Identity users, Google Cloud also attempts to deliver notification emails, but the email must be handled by your existing email infrastructure. To make sure that your Cloud Identity users don't miss notifications, make sure that your existing email system accepts messages that are sent to the primary email addresses of Cloud Identity users, and that it routes this email to the correct mailboxes. Do the following:

  • Ensure that all domains added to Cloud Identity have DNS MX records that point to your existing email system.

  • Ensure that the primary email address of a Cloud Identity user matches an existing mailbox in your email system. If there is a mismatch between the primary email address used by Cloud Identity and the user's email address, configure an alias in your existing email system so that email sent to each primary email address is routed to the right mailbox.

If these solutions aren't practical, consider adding Google Workspace to your existing Cloud Identity account and assigning Google Workspace licenses to the key users that are in charge of billing or interacting with support, and who are therefore most likely to receive notifications.

Assess migration options for existing consumer accounts

If your employees were using Google services such as Google Ad Manager, Google AdSense, or Google Analytics before your organization signed up for Cloud Identity or Google Workspace, it's possible that your employees have been using consumer accounts to access these services.

Letting employees use consumer accounts for business purposes can be risky. For more details on what these risks are and how you can surface existing consumer accounts, see Assessing your existing Google accounts.

You can handle existing consumer accounts in the following ways:

  • Keep the consumer accounts as they are, accepting potential risks.
  • Migrate the accounts to Cloud Identity or Google Workspace by initiating a transfer.
  • Force the owners of the unmanaged user accounts to change their email address to use a different domain.

For more details on how to consolidate existing consumer accounts, see Assessing identity consolidation options.

How you decide to deal with consumer accounts influences how and in what sequence you set up federation. Assess any existing consumer accounts that your users use before you begin creating user accounts or setting up single sign-on in Cloud Identity or Google Workspace.

Mapping identity sets

When you've defined how individual identities are mapped between your external IdP and Cloud Identity or Google Workspace, you have to determine the set of identities for which to enable access to Google services.

The effective set of identities that can authenticate to Google services is the intersection of two sets:

  1. External identities that map to an identity in Cloud Identity or Google Workspace.
  2. External identities that your external IdP allows for single sign-on to Cloud Identity or Google Workspace.

    The process for controlling who is permitted to use single sign-on differs depending on which IdP you use. For example, Azure AD relies on assignments, while AD FS uses access control policies.

Limit the set of identities that can authenticate to Google services

Depending on how you plan to use Google Cloud, Google Workspace, and other Google tools, either all of your organization's employees or only a subset of them must be able to authenticate to Google services.

If you plan to grant only a subset of your organization's employees access to Google services, then it's best to restrict authentication to this set of users. By restricting the number of users that can authenticate, you establish an extra layer of defense that helps in case you accidentally configured any access control rule to be too lax.

You can limit the set of users that can authenticate to Google in the following ways:

  • Minimize the number of user accounts in Cloud Identity or Google Workspace. If there is no mapped user account, any attempt by a user to authenticate will fail, even if the IdP permits the user to sign in to Cloud Identity or Google Workspace by using single sign-on.
  • Configure single-sign on in your IdP to minimize the number of users that are allowed to sign in to Cloud Identity or Google Workspace.

The best approach for your situation depends on whether you have existing consumer accounts that you need to migrate.

Limit the set of identities that you provision if you still need to migrate consumer accounts

You can migrate a consumer account to Cloud Identity or Google Workspace only if you haven't created a user account with the same identity in Cloud Identity or Google Workspace.

If you have existing consumer accounts that you still plan to migrate, you need to be careful not to accidentally create conflicting user accounts. Follow these guidelines:

  • Limit authentication by creating new Cloud Identity or Google Workspace user accounts only for users that need them and are known to not have an existing consumer account.
  • Avoid inadvertently locking out migrated accounts by allowing single sign-on not only for the users for whom you create user accounts in Cloud Identity or Google Workspace, but also for all consumer accounts that are yet to be migrated.

The following diagram shows how different types of identities overlap and interrelate.

How different types of identities overlap and interrelate.

In the diagram, identities with a user account in Cloud Identity or Google Workspace are in the smallest (yellow) ellipse. That ellipse is contained in the second (blue) ellipse, which contains identities that are able to authenticate. The third and largest ellipse (pink) contains the others and consists of the identities that have a user account in your IdP. For details on how to configure Active Directory, Azure AD, or Okta, see our separate best practices guide.

Prevent new consumer account sign-ups

Adding a domain such as example.com to your Cloud Identity or Google Workspace account doesn't prevent employees from signing up for new consumer accounts using the same domain. These new consumer accounts are surfaced as unmanaged users in your Cloud Identity or Google Workspace account, but they aren't allowed to use single sign-on or any other configuration you applied in your Cloud Identity or Google Workspace account.

One way to block the creation of a new consumer account is to create a user account in Cloud Identity or Google Workspace with the same email address. For example, if you created a user alice@example.com in your Cloud Identity or Google Workspace account, then any attempts by an employee to sign up for a new consumer account with the same identity will fail. However, if no corresponding user exists in Cloud Identity or Google Workspace yet, then signing up for a new consumer account will succeed.

When there are no more consumer accounts to migrate to Cloud Identity, prevent new consumer account sign-ups by applying the following configuration:

  • Limit authentication by permitting only relevant users to use single sign-on to Cloud Identity or Google Workspace.

  • Provision Cloud Identity or Google Workspace users for all employees. Ensure that the user accounts use the employee's corporate email address as the primary email address or alias so that no new consumer accounts can be created using the same email address. If possible, keep user accounts that are not enabled for single sign-on in a suspended state.

The following diagram shows this configuration.

Preventing new consumer account sign-ups.

If you are still in the process of migrating consumer accounts, you can temporarily monitor new consumer account sign-ups by capturing the verification emails sent during the sign-up process. Verification emails use an envelope sender address that matches *@idverification.bounces.google.com. Set up a filter in your email system that identifies emails with this envelope sender address and holds them for internal review.

Make Cloud Identity or Google Workspace identities a subset of the identities in your external IdP

Your Cloud Identity or Google Workspace account might contain user accounts with identities that don't map to any users in your external IdP. There are two typical scenarios that can result in these user accounts:

  • You create a new user account in Cloud Identity or Google Workspace and use a primary email address that doesn't map to any user in your external IdP.
  • You have a user account in Cloud Identity or Google Workspace that maps to an identity in your external IdP, but then you delete the identity in the external IdP. For example, you might delete the identity if the employee leaves the company.

When you enable single sign-on in Cloud Identity or Google Workspace, all users (with the exception of super admins) are forced to use single sign-on. For a Cloud Identity or Google Workspace user account that doesn't map to an identity in your external IdP, any attempt to use single sign-on will fail. A user account without such a counterpart is effectively defunct, but might still pose a risk, as in the following situations:

  • If at some point single sign-on is temporarily or permanently disabled, the user account can be used again. This might enable a former employee to sign in and access corporate resources.

  • The name of the deleted user account might be reused. For example, an employee joining the company might share the same name with a different employee who left the company months or years earlier. If the previous employee's user account has meanwhile been deleted, it's possible that you might assign the new employee the username that the former employee used to use.

    The new employee's user account might have an internal ID that's different from that of the former employee. However, from a federation perspective, the two user accounts are considered the same if they both map to the same primary email address in Cloud Identity or Google Workspace. As a result, when the new employee signs in to Google, they might "inherit" existing data, settings, and permissions from the former employee.

Cloud Identity and Google Workspace super-admin users are exempt from the requirement to use single sign-on, but they are still allowed to use single sign-on when sign-on is initiated by the IdP. The ability to use IdP-initiated single sign-on makes super-admin users sensitive to name squatting if they lack a counterpart in your external IdP.

Consider the following example: Alice has a super-admin user alice-admin@example.com in Cloud Identity or Google Workspace and does not use two-step verification. Mallory, who does not know Alice's password, finds a way to create a new user in the external IdP that maps to alice-admin@example.com. Although this newly created user account might not have any special privileges and has no relation to Alice's user account, the fact that it shares a common identity with Alice's super-admin account now enables Mallory to use IdP-initiated single sign-on and authenticate as alice-admin@example.com.

To mitigate this name-squatting risk, make sure that your Cloud Identity or Google Workspace identities are a subset of the identities in your external IdP. The best way to accomplish this is to map the entire user account lifecycle as implemented by your external IdP to the user account lifecycle in Cloud Identity or Google Workspace.

Use dedicated super-admin users

Google Workspace and Cloud Identity super-admin accounts have a powerful set of permissions that apply not only to the Cloud Identity or Google Workspace account, but also to an associated Google Cloud organization. Because only a small number of activities require super-admin privileges, whenever possible it's best to limit the number of administrators with super-admin access and to use less-privileged user accounts for the daily administration of your account or Google Cloud organization.

When you've identified the administrators who require super-admin access, create dedicated super-admin user accounts—for example:

  • Create a user account with the identity alice@example.com and assign regular permissions. This account should be used on an everyday basis for routine activities.
  • Create a second user account with identity alice-admin@example.com and assign it super-user privileges. It's a best practice for Alice to use this account only for occasions where super-admin privileges are required.

    To ensure that notification emails sent to this email address are received in the user's mailbox, configure Google Workspace or your existing email system so that the email address alice-admin@example.com is an alias or is forwarded to alice@example.com.

Ensure that both identities are recognized by your external IdP so that the set of identities in Cloud Identity or Google Workspace continues to be a subset of the identities in your external IdP.

We recommend following a naming scheme for these dedicated super-admin accounts so that in audit logs you can track where and how they're being used. For example, add -admin to the username, as in the previous example.

Limit the number of service users in Google Workspace and Cloud Identity

Your external IdP might contain not only user accounts for employees, but also user accounts intended for machine users such as applications, tools, or background jobs.

In contrast, the preferred way on Google Cloud to enable an application to authenticate and access Google APIs is to implement one of the following approaches:

  • A web application or tool that needs to access Google APIs or services on an end user's behalf should use either OAuth 2.0 or OpenID Connect. By using one of these protocols, the application first solicits the end user's consent to access the user's data and, on receiving consent, is then able to perform the access on behalf of the end user.

  • If access to APIs or services should not be on behalf of an end user but rather on behalf of the application itself, it's best to use Google Cloud service accounts for authentication and then grant the service account access to the resources by using IAM.

If Google Cloud service accounts are granted the appropriate roles in IAM, they can be used to authenticate and use any Cloud API. If you need to grant a service account access to APIs that are outside Google Cloud, for example, to the Directory API or Drive API, you can use Google Workspace domain-wide delegation.

With Google Workspace domain-wide delegation, you enable a service account to act on behalf of a Cloud Identity or Google Workspace user. Because delegation is a powerful privilege, we recommend that you use Google Workspace domain-wide delegation only in cases where the OAuth approach is not practical.

Use a dedicated Cloud Identity or Google Workspace user for every Google Cloud service account that is enabled