Reconcile orphaned managed user accounts

Last reviewed 2024-07-11 UTC

This document describes how to identify and reconcile orphaned user accounts.

If you use anexternal identity provider (IdP),then the authoritative source for identities is external toCloud Identity orGoogle Workspace.Each identity in Cloud Identity or Google Workspace shouldtherefore have a counterpart in theexternal authoritative source.It's possible that some of the identities in your Cloud Identity orGoogle Workspace account lack a counterpart in your external authoritativesource—if so, these user accounts are consideredorphaned. Orphaned accountscan occur under the following circumstances:

  • A Cloud Identity or Google Workspace administrator hasmanually created a user account that has a non-matching identity.
  • You havemigrated a consumer account to Cloud Identity or Google Workspace, but the account usesan identity that does not match any existing identity in the external source.

Before you begin

To reconcile orphaned managed user accounts, you must meet the followingprerequisites:

Process

To reconcile orphaned user accounts, you must first identify which useraccounts are orphaned. For each user account, you then have to decide how tobest reconcile that account.

Identify orphaned user accounts

To find orphaned user accounts, you must compare the identities of useraccounts in Cloud Identity or Google Workspace against theidentities that are recognized by your authoritative source.

To perform a comparison, you can use the export functionality of aGoogle Workspace or Cloud Identity account to obtain a list ofyour current user accounts:

  1. In the Admin Console, go to theUsers page.
  2. SelectDownload users.
  3. SelectAll user info columns and currently selected columns.

  4. ClickDownload.

    After a few minutes, depending on the number of user accounts you have, yousee a notification that the user info CSV file is ready to be downloaded.

  5. ClickDownload CSV and save the file to your local disk.

    Note: The CSV export might contain personally identifiable information(PII). Make sure that you select a storage location that is protectedagainst unauthorized access.

If you use Active Directory or Microsoft Entra ID (formerly Azure ActiveDirectory) as your authoritative source, follow these steps to compare identities:

Active Directory

  1. Sign on to a workstation that has access to Active Directory.
  2. Open a PowerShell console.

  3. Set a variable to the location of your downloaded file:

    $GoogleUsersCsv="GOOGLE_PATH"

    ReplaceGOOGLE_PATH with the path to theCSV file that you downloaded before.

  4. Determine the list of user accounts that lack a counterpart in ActiveDirectory:

    $GoogleUsers = (Import-Csv -Path $GoogleUsersCsv -Header FirstName,LastName,Email | Select-Object -Skip 1)$LdapFilter = "(|{0})" -f (($GoogleUsers | Select-Object @{Name="Clause";Expression={"(userPrincipalName=$($_.Email))"}} | Select-Object -ExpandProperty Clause) -join "")$GoogleUsersWithMatch = Get-ADUser -LdapFilter $LdapFilter `    | Select-Object -ExpandProperty UserPrincipalName$GoogleUsers | Where-Object {$_.Email -NotIn $GoogleUsersWithMatch}

    The command compares the primary email address of user accountsin Cloud Identity or Google Workspace against theuserPrincipalName attribute in Active Directory. If you areusing a different mapping between Active Directory users andCloud Identity or Google Workspace user accounts, youmight need to adjust the command.

    Note: If the CSV file contains a large number of users, theGet-ADUser command might take several minutes to executeand might cause significant load on the associated domain controller.

    The output is similar to this:

    FirstName LastName     Email--------- --------     -----Alice     Admin        admin@example.orgOlly      Orphaned     olly@example.orgMatty     Mismatch     matty@wrongsubdomain.example.org

    Each item listed in the output represents a user account inCloud Identity or Google Workspace that lacks acounterpart in Active Directory.

    An empty result indicates that you don't have any orphaned useraccounts in Google Workspace or Cloud Identity.

  5. Delete the CSV file from your local disk.

Entra ID

  1. In theAzure Portal,go toAzure Active Directory Users.
  2. ClickDownload users.

  3. Enter a filename and clickStart.

    Wait until aClick here to download link appears.

    Depending on the number of user accounts you have, it might take a fewminutes for the operation to complete.

  4. ClickClick here to download and save the file to your local disk.

    Note: The CSV export might contain personally identifiable information(PII). Make sure that you select a storage location that is protectedagainst unauthorized access.

  5. On a workstation that has PowerShell installed, open a PowerShellconsole.

  6. Set two environment variables:

    $GoogleUsersCsv="GOOGLE_PATH"$AzureUsersCsv="AZURE_PATH"

    ReplaceGOOGLE_PATH andAZURE_PATH with the file paths to the CSV filesthat you previously downloaded.

  7. Determine the list of user accounts that lack a counterpart in ActiveDirectory:

    $GoogleUsers = (Import-Csv -Path $GoogleUsersCsv    -Header FirstName,LastName,Email | Select-Object -Skip 1)$AzureUsers = (Import-Csv -Path $AzureUsersCsv)$GoogleUsers | Where-Object {$_.Email -NotIn ($AzureUsers | Select-Object -ExpandProperty userPrincipalName)}

    The command compares the primary email address of user accountsin Cloud Identity or Google Workspace against theuserPrincipalName attribute in Entra ID. If you are using adifferent mapping between Entra ID users and the Cloud Identityor Google Workspace user accounts, you might need to adjust thecommand.

    The output is similar to the following:

    FirstName  LastName    Email---------  --------    -----Alice      Admin       admin@example.orgOlly       Orphaned    olly@example.orgMatty      Mismatch    matty@wrongsubdomain.example.org

    Each item listed in the output represents a user account inCloud Identity or Google Workspace that lacks acounterpart in Active Directory.

    An empty result indicates that you don't have any orphaned useraccount in Google Workspace or Cloud Identity.

  8. Delete both CSV files from your local disk.

Reconcile orphaned user accounts

To reconcile orphaned user accounts, you have to analyze each user accountto determine why its identity lacks a counterpart in yourauthoritative source system.

If you think a user account is obsolete, check whether any configurationsettings or data associated with the account are worth preserving:

  • To keep existing Google Drive data,transfer the data to a different user.
  • If you don't want to keep any existing configuration settings or data,delete the user account.
  • To temporarily retain the user account, suspend the user account andchange its primary email address to an address that is unlikely to evercause a collision.For example, renameolly.obsolete@example.com toobsolete-2019-11-10-olly.obsolete@example.com.

For each user account that is still valid, try to fix the primary email addressso that it matches an identity in your authoritative source. This might requirethe following:

  • Changing the domain of the primary email address.
  • Swapping the primary email address and an alias address.
  • Fixing casing or spelling of the primary email address (for example,adding or removing dots).
Note: Changing the primary email address impacts the owner of the associateduser account. Make sure that you notify the owner of the change so that theyknow which email address to use for subsequent sign-ins.

Best practices

We recommend the following best practices when you are reconciling managed useraccounts:

  • If you migrate consumer accounts to Cloud Identity orGoogle Workspace, repeat the reconciliation process at least once forevery batch of user accounts that you migrate.

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2024-07-11 UTC.