Reconciling orphaned managed user accounts

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

If you use an external identity provider (IdP), then the authoritative source for identities is external to Cloud Identity or Google Workspace. Each identity in Cloud Identity or Google Workspace should therefore have a counterpart in the external authoritative source. It's possible that some of the identities in your Cloud Identity or Google Workspace account lack a counterpart in your external authoritative source—if so, these user accounts are considered orphaned. Orphaned accounts can occur under the following circumstances:

  • A Cloud Identity or Google Workspace administrator has manually created a user account that has a non-matching identity.
  • You have migrated a consumer account to Cloud Identity or Google Workspace, but the account uses an 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 following prerequisites:

Process

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

Identifying orphaned user accounts

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

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

  1. In the Admin Console, go to the Users page.
  2. Select Download users.
  3. Select All user info columns and currently selected columns.
  4. Click Download.

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

  5. Click Download CSV and save the file to your local disk.

If you use Active Directory or Azure Active Directory (Azure AD) 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"

    Replace GOOGLE_PATH with the file path to the CSV file that you downloaded before.

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

    $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 accounts in Cloud Identity or Google Workspace against the userPrincipalName attribute in Active Directory. If you are using a different mapping between Active Directory users and Cloud Identity or Google Workspace user accounts, you might need to adjust the command.

    The output is similar to this:

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

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

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

  5. Delete the CSV file from your local disk.

Azure AD

  1. In the Azure Portal, go to Azure Active Directory Users.
  2. Click Download users.
  3. Enter a filename and click Start.

    Wait until a Click here to download link appears.

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

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

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

  6. Set two environment variables:

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

    Replace GOOGLE_PATH and AZURE_PATH with the file paths to the CSV files that you previously downloaded.

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

    $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 accounts in Cloud Identity or Google Workspace against the userPrincipalName attribute in Azure AD. If you are using a different mapping between Azure AD users and the Cloud Identity or Google Workspace user accounts, you might need to adjust the command.

    The output is similar to the following:

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

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

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

  8. Delete both CSV files from your local disk.

Reconciling orphaned user accounts

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

If you think a user account is obsolete, check whether any configuration settings 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 and change its primary email address to an address that is unlikely to ever cause a collision. For example, rename olly.obsolete@example.com to obsolete-2019-11-10-olly.obsolete@example.com.

For each user account that is still valid, try to fix the primary email address so that it matches an identity in your authoritative source. This might require the 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).

Best practices

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

  • If you migrate consumer accounts to Cloud Identity or Google Workspace, repeat the reconciliation process at least once for every batch of user accounts that you migrate.