Como corrigir UPN “.local” e contas duplicadas no Microsoft Entra ID (Azure AD): passo a passo com PowerShell

Guia prático para corrigir UPN “.local”, eliminar duplicados e manter sincronização estável entre o Active Directory e o Microsoft Entra ID (antigo Azure AD). Inclui passo‑a‑passo, scripts PowerShell e checklist de validação.

Índice

Visão geral do problema

Equipas de TI herdam, com frequência, ambientes onde os utilizadores on‑premises têm UPN com sufixo .local (não roteável) e, ao mesmo tempo, já existem contas “em nuvem” criadas com o domínio <tenant>.onmicrosoft.com. Quando a sincronização é ativada, surgem conflitos:

Criação de contas duplicadas no Microsoft Entra ID.
Falhas de exportação por atributos duplicados (ex.: proxyAddresses e UPN repetidos).
Objetos deixam de sincronizar ou ficam sem join entre local e nuvem.

Este artigo mostra como planear e executar a migração de UPN para um domínio público (ex.: contoso.com), eliminar duplicidades e ativar a sincronização de forma suportada — com foco em Microsoft Entra Connect Sync (antigo Azure AD Connect) e Microsoft Entra Cloud Sync.

A mudança de UPN “.local” causa problemas?

Na maioria dos ambientes, não. O início de sessão interno continua a funcionar com DOMÍNIO\utilizador (sAMAccountName) e o Kerberos não depende do UPN. O que tipicamente exige atenção são aplicações legadas que usam o UPN para SSO ou bind LDAP e cenários de MFA/Authenticator.

O que não muda normalmente	O que precisa de validação
Login em Windows com `DOMÍNIO\utilizador`.	Aplicações que usam UPN diretamente para autenticação.
Permissões NTFS, ACLs, SID, group membership.	SSO antigo (ADFS, LDAP‑bind) e integrações com UPN “gravado”.
Perfis locais Windows.	Tokens de sessão em apps móveis (Outlook/Teams/Authenticator).

Boa prática: alinhar o UPN a um domínio público e verificado no tenant (ex.: contoso.com). O UPN é o identificador de início de sessão por defeito em Microsoft 365 e o principal sign‑in name do Entra ID. Com planeamento e testes, a mudança é segura.

Arquitetura de sincronização recomendada

Existem duas abordagens suportadas. A escolha depende de requisitos de funcionalidades, gestão e topologia:

Opção	Quando usar	Âncora (sourceAnchor) recomendada	Notas
Microsoft Entra Connect Sync (antigo AAD Connect)	Ambientes que requerem recursos como writeback (grupos, dispositivos), filtragem complexa ou regras avançadas.	mS‑DS‑ConsistencyGuid para utilizadores (recomendado); `objectGUID` para grupos/dispositivos.	Instalação no servidor; suporta modo staging e swing de servidores.
Microsoft Entra Cloud Sync	Cenários leves e distribuídos (várias florestas, vários agentes), gestão no portal.	Geralmente mS‑DS‑ConsistencyGuid para utilizadores (o serviço pode gerir o valor); `objectGUID` para outros objetos.	Agente leve; configuração central no portal; sem MIIS client.

Atenção: a âncora (sourceAnchor) identifica um objeto para sempre. Não a altere após iniciar a sincronização. Para novos projetos, use mS‑DS‑ConsistencyGuid em utilizadores.

Passo‑a‑passo para eliminar duplicados e ativar a sincronização

Verificar e adicionar um domínio público ao tenant

Garanta um domínio público (ex.: contoso.com) e verifique-o no Microsoft Entra ID.
Não utilize .local como UPN em serviços cloud. O sufixo deve ser roteável e verificado.

Criar sufixo UPN alternativo no Active Directory

GUI: Active Directory Domains and Trusts → botão direito no nó raiz → Properties → Alternative UPN suffixes → adicionar contoso.com.

PowerShell (método rápido e idempotente):

Import-Module ActiveDirectory

Adiciona contoso.com como UPN suffix no forest (idempotente)

$forest = Get-ADForest
if ($forest.UPNSuffixes -notcontains "contoso.com") {
Set-ADForest -Identity $forest.Name -UPNSuffixes @{Add="contoso.com"}
}

Atualizar os UPN dos utilizadores

Defina critérios (OU/Grupo) e execute um lote seguro. O sAMAccountName não muda.

Import-Module ActiveDirectory

$searchBase = "OU=Colaboradores,OU=Corp,DC=contoso,DC=local"
$newSuffix  = "contoso.com"

Pré-validação: verifique colisões de UPN antes de mudar

Get-ADUser -SearchBase $searchBase -Filter * -Properties SamAccountName,UserPrincipalName |
ForEach-Object {
$newUpn = "$($*.SamAccountName)@$newSuffix"
if (Get-ADUser -Filter "UserPrincipalName -eq '$newUpn'") {
Write-Warning "Colisão de UPN prevista para $($.*.SamAccountName) -> $newUpn"
}
}

Mudança controlada

Get-ADUser -SearchBase $searchBase -Filter * -Properties SamAccountName,UserPrincipalName |
ForEach-Object {
$newUpn = "$($*.SamAccountName)@$newSuffix"
Set-ADUser -Identity $* -UserPrincipalName $newUpn
}

Dica: se o endereço de e‑mail principal for igual ao novo UPN, a curva de adoção é mais suave (autodiscover, SSO e experiência do utilizador).

Limpar conflitos com a ferramenta IDFix

Antes de ligar a sincronização, execute o IDFix no AD para detetar e corrigir:

Duplicados em proxyAddresses (especialmente o SMTP: principal) e userPrincipalName.
Formatação incorreta (caracteres inválidos, espaços, maiúsculas/minúsculas em SMTP: vs smtp:).
Domínios não verificados em UPN, mail, targetAddress.

Corrija no AD sempre que possível (não no cloud), exporte um relatório de “antes/depois” e arquive para auditoria.

Preparar a correspondência (matching) com objetos já existentes na nuvem

Quando já há contas “em nuvem”, escolha a estratégia conforme o cenário. O objetivo é que o objeto local “faça join” ao objeto cloud ideal, evitando duplicados.

Estratégia	Quando usar	Como fazer	Prós / Contras
Soft‑Match (por UPN/SMTP)	UPN ou `proxyAddresses` (SMTP principal) são iguais entre AD e nuvem.	Garanta que o `userPrincipalName` e/ou o `proxyAddresses` (`SMTP:`) no AD coincidem com a conta cloud. Execute uma sincronização delta.	Simples e rápido; depende de alinhamento perfeito de atributos.
Hard‑Match (por ImmutableId)	UPN/SMTP não coincidem ou necessita controlar objeto a objeto.	Defina no utilizador cloud o `onPremisesImmutableId` para o `mS‑DS‑ConsistencyGuid` (ou `objectGUID`) do AD em Base64 antes de sincronizar.	Determinístico; requer cuidado com a âncora e permissões em Graph.
Excluir e recriar	Conta cloud sem dados críticos (sem OneDrive/Teams/Exchange com conteúdo relevante).	Remova licenças, elimine a conta cloud, aguarde reciclagem e sincronize a partir do AD.	Limpo; perda de artefactos cloud se não for bem planeado.

Exemplo de Hard‑Match com Microsoft Graph PowerShell

Pré‑requisitos: a conta cloud deve estar “Cloud‑Only” (a propriedade onPremisesSyncEnabled ainda não deve estar ativa). Execute com uma conta com permissões adequadas.

# 1) Obter a âncora a partir do AD (mS-DS-ConsistencyGuid preferencialmente; senão, objectGUID)
Import-Module ActiveDirectory

Exemplo com mS-DS-ConsistencyGuid; se estiver vazio, use ObjectGUID

$user = Get-ADUser jdoe -Properties "mS-DS-ConsistencyGuid","ObjectGUID"
$bytes = if ($user."mS-DS-ConsistencyGuid") { $user."mS-DS-ConsistencyGuid" } else { $user.ObjectGUID.ToByteArray() }
$immutableId = [Convert]::ToBase64String($bytes)

2) Ligar ao Microsoft Graph

Connect-MgGraph -Scopes "User.ReadWrite.All","Directory.AccessAsUser.All"
Select-MgProfile -Name "v1.0"

3) Definir o onPremisesImmutableId no utilizador cloud (antes de ligar a sincronização)

Substitua pelo UPN atual cloud da pessoa

$cloudUpn = "[jdoe@tenant.onmicrosoft.com](mailto:jdoe@tenant.onmicrosoft.com)"
Update-MgUser -UserId $cloudUpn -OnPremisesImmutableId $immutableId

Depois de definido o onPremisesImmutableId no cloud user, ative a sincronização. O serviço fará o join ao objeto local com a mesma âncora.

Configurar o mecanismo de sincronização

Microsoft Entra Connect Sync

Instale em modo Staging num servidor (evita exportações até validar).
Selecione mS‑DS‑ConsistencyGuid como sourceAnchor para utilizadores (recomendado).
Mapeie o UPN para um domínio verificado (contoso.com).
Defina filtragem por OU ou por grupos para começar pequeno.
Valide no Synchronization Rules Editor e no Synchronization Service Manager (miisclient).

Microsoft Entra Cloud Sync

Instale o agente em servidores membros (alta disponibilidade com múltiplos agentes).
Configure a(s) floresta(s), domínios e escopo (OU/grupos) no portal.
Use mS‑DS‑ConsistencyGuid como âncora (o serviço pode povoar o valor se estiver vazio).
Habilite Hybrid Azure AD Join se aplicável.

Executar a sincronização inicial

Connect Sync: após validar, desative o Staging e execute: # Sincronização completa Start-ADSyncSyncCycle -PolicyType Initial Em execuções subsequentes: Start-ADSyncSyncCycle -PolicyType Delta
Cloud Sync: acompanhe o estado dos agentes e da configuração no portal e inicie um Full Sync pelo próprio serviço.

Monitore exports e errors até que todos os utilizadores fiquem com estado Synced no Entra ID.

Pós‑sincronização

Licenças: prefira atribuição baseada em grupos. Só licencie após confirmar o estado “Synced”.
MFA & Authenticator: alguns utilizadores podem ter de entrar novamente; valide cenários de Number Matching e sessões móveis.
Comunicação: informe o novo nome de início de sessão (UPN) e oriente sobre a atualização do Outlook/Teams/Authenticator.
Governança: considere Password Hash Sync (PHS) ou Pass‑through Authentication (PTA). PHS simplifica e dá resiliência; PTA reduz exposição de hash e pode atender requisitos regulatórios.

Resolução de problemas (erros comuns e correções)

“Another object with the same value for attribute proxyAddresses exists”

O proxyAddresses deve ser único em toda a organização. Procure entradas duplicadas (especialmente o SMTP: principal). Corrija no AD e execute nova sincronização.

“UPN conflict” ao exportar

O UPN já existe na nuvem. Verifique se há uma conta cloud antiga (sem sincronização) com o mesmo UPN; opte por Soft‑Match (alinhe SMTP/UPN), Hard‑Match (defina onPremisesImmutableId) ou exclusão controlada da conta cloud legada.

“ImmutableId already in use”

O valor de âncora já foi associado a outro objeto cloud (talvez um teste anterior). Remova/limpe o valor na conta cloud incorreta ou recicle o objeto antes de reutilizar a âncora.

Contas duplicadas surgiram após ativar a sincronização

Coloque o servidor de sincronização em staging (ou pare o agente Cloud Sync).
Identifique qual objeto cloud deve ser o “vivo” (com caixa de correio, OneDrive, Teams, etc.).
Use Hard‑Match para “grudar” o objeto local ao cloud correto, ou exclua a conta cloud desnecessária após retirada de licenças.
Execute delta sync e confirme se não criou novos duplicados.

UPN mudou mas os utilizadores continuam a iniciar sessão com o nome antigo

É esperado durante o período de transição. Em serviços Microsoft 365, o início de sessão passa a aceitar o novo UPN; o UPN antigo deixa de funcionar conforme as políticas e a propagação. Garanta comunicação e, se necessário, configure alias de e‑mail coerentes para reduzir atrito.

Perfis, dispositivos e Hybrid Join

A alteração do UPN não muda o perfil local Windows. Em cenários de Hybrid Azure AD Join (dispositivos ligados ao AD local e registados no Entra ID), verifique se o dispositivo mantém o registo; se necessário, reenvie políticas, reavalie o join ou re‑registre a máquina.

Guia de execução (checklist prático)

Descoberta: inventarie domínios, UPNs, proxyAddresses, licenças cloud e aplicações que dependem de UPN.
Domínio público: adicione e verifique o domínio no tenant.
UPN suffix: crie o sufixo UPN alternativo no AD (contoso.com).
Renomeie UPNs: lote controlado, começando por um grupo piloto.
IDFix: elimine duplicados e erros de formato.
Matching: defina se será Soft‑Match, Hard‑Match ou exclusão/recriação.
Configuração: escolha Connect Sync (staging) ou Cloud Sync e valide regras.
Primeira sincronização: faça Initial/Full, monitore exportações e resolva erros.
Pós‑sync: atribua licenças (de preferência por grupos), valide MFA e comunique a mudança.
Operação contínua: ative alertas (Connect Health/Agentes), planeie janelas de manutenção e auditorias periódicas de identidade.

Exemplos adicionais de scripts úteis

Verificar consistência entre UPN e e‑mail principal

Import-Module ActiveDirectory
$searchBase = "OU=Colaboradores,DC=contoso,DC=com"

Get-ADUser -SearchBase $searchBase -Filter * -Properties mail,UserPrincipalName |
Select-Object SamAccountName,UserPrincipalName,mail,
@{n="UpnVsMail";e={ if ($.UserPrincipalName -ieq $.mail) { "OK" } else { "DIFERENTE" } }} |
Sort-Object UpnVsMail,SamAccountName

Detetar e normalizar `proxyAddresses` (maiúsculas do SMTP principal)

Import-Module ActiveDirectory
$users = Get-ADUser -Filter * -Properties proxyAddresses
foreach ($u in $users) {
    $proxies = @($u.proxyAddresses)
    if ($proxies.Count -eq 0) { continue }
    $primary = $proxies | Where-Object { $_ -cmatch "^SMTP:" }
    if (-not $primary) {
        # Promover o e-mail principal atual (mail) para SMTP: se aplicável
        if ($u.mail) {
            $new = "SMTP:$($u.mail)"
            $others = $proxies | Where-Object { $_ -notmatch "^SMTP:" }
            Set-ADUser $u -Add @{ proxyAddresses = $new }
            # Remova duplicados se necessário…
        }
    }
}

Exportar `objectGUID`/`mS‑DS‑ConsistencyGuid` em Base64 (para Hard‑Match)

Import-Module ActiveDirectory

Get-ADUser -Filter * -Properties "mS-DS-ConsistencyGuid","ObjectGUID","UserPrincipalName" |
Select-Object UserPrincipalName,
@{n="ImmutableId_Base64";e={
$b = if ($.{"mS-DS-ConsistencyGuid"}) { $.{"mS-DS-ConsistencyGuid"} } else { $_.ObjectGUID.ToByteArray() }
[Convert]::ToBase64String($b)
}} | Export-Csv .\ImmutableIds.csv -NoTypeInformation -Encoding UTF8

Boas práticas complementares

Connect Health/Agentes Cloud Sync: ative alertas e revise relatórios de erros semanalmente.
Governança de identidades: políticas de acesso condicional, MFA por padrão, SSPR, auditoria de contas privilegiadas.
Grupos e partilhas (Power BI/Teams): prefira grupos sincronizados do AD para delegar acessos; isso evita “fantasmas” quando um utilizador é desativado.
Recuperação: mantenha um runbook de rollback (ex.: reverter UPN para .local ou pausar exportações) e backups de scripts/relatórios.

FAQ (perguntas frequentes)

Preciso manter “.local” como UPN?
Não. Use um domínio público e verificado. O UPN “.local” não é roteável e não deve ser usado para logon cloud.

Mudar o UPN quebra o e‑mail?
Não necessariamente. O que manda para e‑mail é o proxyAddresses (SMTP principal). Alinhar UPN ao e‑mail principal ajuda na experiência do utilizador.

Qual a melhor âncora?
mS‑DS‑ConsistencyGuid para utilizadores. Não a altere após iniciar a sincronização.

Como evito duplicados?
Corrija proxyAddresses e UPN no AD, use IDFix, e escolha Soft‑Match (se houver igualdade de atributos) ou Hard‑Match (definindo onPremisesImmutableId no cloud antes da sync). Em último caso, elimine e recrie a conta cloud.

Connect Sync ou Cloud Sync?
Connect para cenários com writeback e regras avançadas; Cloud Sync para simplicidade, múltiplas florestas e gestão no portal.

Resumo rápido

Dúvida	Resposta curta
Preciso manter “.local”?	Não. Registe um domínio público, adicione-o como sufixo UPN no AD e mude os UPNs. Riscos são mínimos se planear e testar.
Como evitar duplicados?	Use Soft‑Match (UPN/SMTP iguais) ou Hard‑Match (onPremisesImmutableId); em último caso, elimine contas cloud antes de sincronizar.
Passos fundamentais?	(1) Verificar domínio, (2) adicionar sufixo UPN, (3) mudar UPNs, (4) limpar conflitos com IDFix, (5) configurar Connect/Cloud Sync, (6) executar sincronização.

Conclusão

Ao substituir o UPN “.local” por um domínio público, limpar atributos com o IDFix e escolher a estratégia correta de matching (Soft ou Hard), a organização obtém identidades únicas e alinhadas no local e na nuvem. Com a sincronização estável, licenciamento baseado em grupos e MFA por padrão, os serviços Microsoft 365 — incluindo Power BI, Exchange Online, Teams e OneDrive — operam de forma previsível, segura e escalável.