Microsoft Entra ID (formerly Azure AD) user provisioning and single sign-on


This document shows you how to set up user provisioning and single sign-on between a Microsoft Entra ID (formerly Azure AD) tenant and your Cloud Identity or Google Workspace account.

The document assumes that you already use Microsoft Office 365 or Microsoft Entra ID in your organization and want to use Microsoft Entra ID for allowing users to authenticate with Google Cloud. Microsoft Entra ID itself might be connected to an on-premises Active Directory and might use AD FS federation, pass-through authentication, or password hash synchronization.

Objectives

  • Set up Microsoft Entra ID 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 a Microsoft Entra ID user account or a user that has been provisioned from Active Directory to Microsoft Entra ID.

Costs

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

Check the Microsoft Entra ID pricing page for any fees that might apply to using Microsoft Entra ID.

Before you begin

  • Make sure you understand the differences between connecting Google Cloud to Microsoft Entra ID versus directly connecting Google Cloud to Active Directory.
  • Decide how you want to map identities, groups, and domains between Microsoft Entra ID and Cloud Identity or Google Workspace. Specifically, answer the following questions:
    • Do you plan to use email addresses or User Principal Names (UPNs) as common identifiers for users?
    • Do you plan to provision groups? If so, do you plan to map groups by email address or by name?
    • Do you plan to provision all users to Google Cloud or only a select subset of users?
  • Before connecting your production Microsoft Entra ID tenant to Google Cloud, consider using a Microsoft Entra ID test tenant for setting up and testing user provisioning.
  • 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 Microsoft Entra ID

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

The Microsoft Entra ID 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 Microsoft Entra ID 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 an name and description for the OU:
    • Name: Automation
    • Description: Automation users
  4. Click Create.

Create a user account for Microsoft Entra ID 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: Microsoft Entra ID
    • Last Name: Provisioning
    • Primary email: azuread-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 Microsoft Entra ID

To let Microsoft Entra ID create, list, and suspend users and groups in your Cloud Identity or Google Workspace account, you must grant the azuread-provisioning user additional privileges as follows:

  • To allow Microsoft Entra ID to manage all users, including delegated administrators and super-admin users, you must make the azuread-provisioning user a super-admin.

  • To allow Microsoft Entra ID to manage non-admin users only, it's sufficient to make the azuread-provisioning user a delegated administrator. As a delegated administrator, Microsoft Entra ID can't manage other delegated administrators or super-admin users.

Super-admin

To make the azuread-provisioning user a super-admin, do the following:

  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.

Delegated administrator

To make the azuread-provisioning user a delegated administrator, create a new admin role and assign it to the user:

  1. In the menu, go to Account > Admin roles.
  2. Click Create new role.
  3. Provide a name and description for the role such as the following:
    • Name: Microsoft Entra ID
    • Description: Role for automated user and group provisioning
  4. Click Continue.
  5. On the next screen, scroll down to the section named Admin API privileges and set the following privileges to enabled:
    • Organization Units > Read
    • Users
    • Groups
  6. Click Continue.
  7. Click Create role.
  8. Click Assign users.
  9. Select the azuread-provisioning user and click Assign role.

Register domains

In Cloud Identity and Google Workspace, users and groups are identified by email address. The domains used by these email addresses must be registered and verified first.

Prepare a list of DNS domains that you need to register:

  • If you plan to map users by UPN, include all domains used by UPNs. If in doubt, include all custom domains of your Microsoft Entra ID tenant.
  • If you plan to map users by email address, include all domains used in email addresses. The list of domains might be different from the list of custom domains of your Microsoft Entra ID tenant.

If you plan to provision groups, amend the list of DNS domains:

  • If you plan to map groups by email address, include all domains used in group email addresses. If in doubt, include all custom domains of your Microsoft Entra ID tenant.
  • If you plan to map groups by name, include a dedicated subdomain like groups.PRIMARY_DOMAIN, where PRIMARY_DOMAIN is the primary domain name of your Cloud Identity or Google Workspace account.

Now that you've identified the list of DNS domains, you can register any missing domains. For each domain on the list not yet registered, perform the following steps:

  1. In the Admin Console, go to Account > Domains > Manage domains.
  2. Click Add/remove domains.
  3. Click Add a domain.
  4. Enter the domain name and select Secondary domain.
  5. Click Add domain and start verification and follow the instructions to verify ownership of the domain.

Configuring Microsoft Entra ID provisioning

Create an enterprise application

You are now ready to connect Microsoft Entra ID to your Cloud Identity or Google Workspace account by setting up the Google Cloud/G Suite Connector by Microsoft gallery app from the Microsoft Azure marketplace.

The gallery app can be configured to handle both user provisioning and single sign-on. In this document, you use two instances of the gallery app—one for user provisioning and one for single sign-on.

First, create an instance of the gallery app to handle user provisioning:

  1. Open the Azure portal and sign in as a user with global administrator privileges.
  2. Select Microsoft Entra ID > Enterprise applications.
  3. Click New application.
  4. Search for Google Cloud, and then click the Google Cloud/G Suite Connector by Microsoft item in the result list.
  5. Set the name of the application to Google Cloud (Provisioning).
  6. Click Create.
  7. Adding the application may take a few seconds, you should then be redirected to a page titled Google Cloud (Provisioning) - Overview.
  8. In the menu on the left, click Manage > Properties:
    1. Set Enabled for users to sign-in to No.
    2. Set User assignment required to No.
    3. Set Visible to users to No.
    4. Click Save.
  9. In the menu on the left, click Manage > Provisioning:
    1. Click Get started.
    2. Change Provisioning Mode to Automatic.
    3. Click Admin Credentials > Authorize.
    4. Sign in using the azuread-provisioning@DOMAIN user you created earlier, where DOMAIN is the primary domain of your Cloud Identity or Google Workspace account.
    5. Because this is the first time you've signed on using this user, you are asked to accept the Google Terms of Service and privacy policy.
    6. If you agree to the terms, click I understand.
    7. Confirm access to the Cloud Identity API by clicking Allow.
    8. Click Test Connection to verify that Microsoft Entra ID can successfully authenticate with Cloud Identity or Google Workspace.
    9. Click Save.

Configure user provisioning

The right way to configure user provisioning depends on whether you intend to map users by email address or by UPN.

UPN

  1. Under Mappings, click Provision Azure Active Directory Users.
  2. Under Attribute Mappings, select the row surname and set Default value if null to _.
  3. Select the row givenName and set Default value if null to _.
  4. Click OK.
  5. Click Save.
  6. Confirm that saving changes will result in users and groups being resynchronized by clicking Yes.
  7. Click X to close the Attribute Mapping dialog.

UPN: domain substitution

  1. Under Mappings, click Provision Azure Active Directory Users.
  2. Under Attribute Mapping, select the row userPrincipalName and configure the following mapping:

    • Mapping type: Expression
    • Expression:

      Replace([userPrincipalName], "@DOMAIN", , , "@SUBSTITUTE_DOMAIN", , )
      

    Replace the following:

    • DOMAIN: domain name you want to replace
    • SUBSTITUTE_DOMAIN domain name to use instead
  3. Click OK.

  4. Select the row surname and set Default value if null to _.

  5. Select the row givenName and set Default value if null to _.

  6. Click OK.

  7. Click Save.

  8. Confirm that saving changes will result in users and groups being resynchronized by clicking Yes.

  9. Click X to close the Attribute Mapping dialog.

Email address

  1. Under Mappings, click Provision Azure Active Directory Users.
  2. Under Attribute Mapping, select the row userPrincipalName and set Source Attribute to mail.
  3. Select the row surname and set Default value if null to _.
  4. Select the row givenName and set Default value if null to _.
  5. Click OK.
  6. Click Save.
  7. Confirm that saving changes will result in users and groups being resynchronized by clicking Yes.
  8. Click X to close the Attribute Mapping dialog.

You must configure mappings for primaryEmail, name.familyName, name.givenName, and suspended. All other attribute mappings are optional.

When you configure additional attribute mappings, note the following:

  • The Google Cloud/G Suite Connector by Microsoft gallery currently doesn't let you assign email aliases.
  • The Google Cloud/G Suite Connector by Microsoft gallery currently doesn't let you assign licenses to users. As a workaround, consider setting up automatic licensing for organizational units.
  • To assign a user to an organization unit, add a mapping for OrgUnitPath. The path must begin with a / character and must refer to an organizational unit that already exists, for example /employees/engineering.

Configure group provisioning

The right way to configure group provisioning depends on whether your groups are mail-enabled. If groups aren't mail-enabled, or if groups use an email address ending with "onmicrosoft.com", you can derive an email address from the group's name.

No group mapping

  1. Under Mappings, click Provision Azure Active Directory Groups.
  2. Set Enabled to No.
  3. Click Save.
  4. Confirm that saving changes will result in users and groups being resynchronized by clicking Yes.
  5. Click X to close the Attribute Mapping dialog.

Name

  1. Under Mappings section, click Provision Azure Active Directory Groups.
  2. In the Attribute Mappings section, click mail, which opens the Edit Attribute dialog.
  3. Configure the following settings:
    1. Mapping type: Expression.
    2. Expression: Join("@", NormalizeDiacritics(StripSpaces([displayName])), "GROUPS_DOMAIN"). Replace GROUPS_DOMAIN with the domain that all group email addresses are supposed to use—for example, groups.example.com.
    3. Target attribute: email.
  4. Click OK.
  5. Click Save.
  6. Confirm that saving changes will result in users and groups being resynchronized by clicking Yes.
  7. Click X to close the Attribute Mapping dialog.

Email address

  • If you map groups by email address, keep the default settings.

Configure user assignment

If you know that only a certain subset of users need access to Google Cloud, you can optionally restrict the set of users to be provisioned by assigning the enterprise app to specific users or groups of users.

If you want all users to be provisioned, you can skip the following steps.

  1. In the menu on the left, click Manage > Users and groups.
  2. Click Add user.
  3. Select Users.
  4. Select the users or groups you want to provision. If you select a group, all members of this group are automatically provisioned.
  5. Click Select.
  6. Click Assign.

Enable automatic provisioning

The next step is to configure Microsoft Entra ID to automatically provision users to Cloud Identity or Google Workspace:

  1. In the menu on the left, click Manage > Provisioning.
  2. Select Edit provisioning.
  3. Set Provisioning Status to On.
  4. Under Settings, set Scope to one of the following:

    1. Sync only assigned users and groups if you have configured user assignment.
    2. Sync all users and groups otherwise.

    If this box to set the scope isn't displayed, click Save and refresh the page.

  5. Click Save.

Microsoft Entra ID starts an initial synchronization. Depending on the number of users and groups in the directory, this process can take several minutes or hours. You can refresh the browser page to see the status of the synchronization at the bottom of the page or select Audit Logs in the menu to see more details.

After the initial synchronization has completed, Microsoft Entra ID will periodically propagate updates from Microsoft Entra ID to your Cloud Identity or Google Workspace account. For further details on how Microsoft Entra ID handles user and group modifications, see Mapping the user lifecycle and Mapping the group lifecycle.

Troubleshooting

If the synchronization doesn't start within five minutes, you can force it to start by doing the following:

  1. Set Provisioning Status to Off.
  2. Click Save.
  3. Set Provisioning Status to On.
  4. Click Save.
  5. Check Restart provisioning.
  6. Click Save.
  7. Confirm restarting the synchronization by clicking Yes.

If synchronization still doesn't start, click Test Connection to verify that your credentials have been saved successfully.

Configuring Microsoft Entra ID for single sign-on

Although all relevant Microsoft Entra ID users are now automatically being provisioned to Cloud Identity or Google Workspace, you cannot use these users to sign in yet. To allow users to sign in, you still need to configure single sign-on.

Create an enterprise application

Create a second enterprise application to handle single sign-on:

  1. In the Azure portal, go to Microsoft Entra ID > Enterprise applications.
  2. Click New application.
  3. Search for Google Cloud, and then click Google Cloud/G Suite Connector by Microsoft in the result list.
  4. Set the name of the application to Google Cloud.
  5. Click Add.

    Adding the application may take a few seconds. You are then redirected to a page titled Google Cloud - Overview.

  6. In the menu on the left, click Manage > Properties.

  7. Set Enabled for users to sign-in to Yes.

  8. Set User assignment required to Yes unless you want to allow all users to use single sign-on.

  9. Click Save.

Configure user assignment

If you already know that only a certain subset of users need access to Google Cloud, you can optionally restrict the set of users to be allowed to sign in by assigning the enterprise app to specific users or groups of users.

If you set User assignment required to No before, then you can skip the following steps.

  1. I