Entra ID (Azure AD) Kullanıcı Yönetimi – Microsoft Graph PowerShell ile Listeleme, ImmutableId, Silme ve Geri Yükleme

Bu doküman; kullanıcıları listeleme, silinen kullanıcıları görüntüleme, ImmutableId değerlerini görme/değiştirme, kullanıcı silme (soft delete), silineni kalıcı silme (hard delete) ve silineni geri yükleme adımlarını, Microsoft Graph PowerShell ve doğrudan Graph API (Invoke-MgGraphRequest) yöntemleriyle adım adım anlatır.

1) Ön Gereksinimler

• Windows PowerShell 5.1 veya PowerShell 7.x
• Microsoft Graph PowerShell SDK (tek paket):

Install-Module Microsoft.Graph -Force -AllowClobber
Import-Module Microsoft.Graph

Install-Module Microsoft.Graph -Force -AllowClobber
Import-Module Microsoft.Graph

• Yeterli yetkiler (delegated):
  • Genel kullanım için: User.ReadWrite.All
  • Silme/purge/restore işlemleri için çoğu senaryoda ek olarak: Directory.AccessAsUser.All
• Oturum açma:

Connect-MgGraph -Scopes "Directory.AccessAsUser.All","User.ReadWrite.All"

Connect-MgGraph -Scopes "Directory.AccessAsUser.All","User.ReadWrite.All"

Not: Tenant’ta admin consent gerekebilir. İlk bağlantıda çıkan pencereyi yönetici olarak onaylayın.

Kullanıcıları Listelemek

2.1 Tüm kullanıcıları temel liste

Get-MgUser | Select-Object Id, DisplayName, UserPrincipalName, AccountEnabled

Get-MgUser | Select-Object Id, DisplayName, UserPrincipalName, AccountEnabled

2.2 Filtre, sayfalama ve sayaç (büyük tenant’lar)

# OData sayacı için consistency seviyesi
$users = Get-MgUser -ConsistencyLevel eventual -Count userCount -Top 999 -All
$users.Count  # PowerShell tarafında sayım
$userCount    # Graph’ın döndürdüğü toplam kayıt sayısı

# OData sayacı için consistency seviyesi
$users = Get-MgUser -ConsistencyLevel eventual -Count userCount -Top 999 -All
$users.Count  # PowerShell tarafında sayım
$userCount    # Graph’ın döndürdüğü toplam kayıt sayısı

2.3 Belirli kullanıcıyı bulma

# UPN ile
Get-MgUser -UserId "user@domain.com"

# DisplayName içinde arama (client-side filtre)
Get-MgUser -All | Where-Object { $_.DisplayName -like "*Omer Gundogan*" } | Select Id, DisplayName, UserPrincipalName

# UPN ile
Get-MgUser -UserId "user@domain.com"

# DisplayName içinde arama (client-side filtre)
Get-MgUser -All | Where-Object { $_.DisplayName -like "*Omer Gundogan*" } | Select Id, DisplayName, UserPrincipalName

3) Silinen Kullanıcıları Listelemek (Recycle Bin)

Silinen kullanıcılar 30 gün boyunca Deleted Users içinde tutulur.

3.1 Tüm silinen kullanıcılar

Get-MgDirectoryDeletedUser | Select-Object Id, DisplayName, UserPrincipalName, DeletedDateTime

Get-MgDirectoryDeletedUser | Select-Object Id, DisplayName, UserPrincipalName, DeletedDateTime

3.2 Filtreleme örnekleri

# UPN parçasına göre (client-side)
Get-MgDirectoryDeletedUser | Where-Object { $_.UserPrincipalName -like "*birol.benli*" } |
  Select Id, DisplayName, UserPrincipalName, DeletedDateTime

# UPN parçasına göre (client-side)
Get-MgDirectoryDeletedUser | Where-Object { $_.UserPrincipalName -like "*birol.benli*" } |
  Select Id, DisplayName, UserPrincipalName, DeletedDateTime

İpucu: Büyük listelerde -All parametresini kullanın ve gerekirse client-side Where-Object ile daraltın.

4) ImmutableId Nedir?

• onPremisesImmutableId (eski adıyla ImmutableId), kullanıcıyı on-premises AD objesiyle eşleştirmek için kullanılan değerdir.
• Tipik olarak on-premises ObjectGUID değerinin Base64 kodlanmış halidir.
• DirSync/Entra Connect ile eşitlenen kullanıcılar için bu alan read-only’dir; değişiklik on-premises tarafta yapılır ve senkronizasyonla buluta yansır.

4.1 Kullanıcının ImmutableId değerini görmek

# Tek kullanıcı
Get-MgUser -UserId username@domain.com -Property OnPremisesImmutableId | select OnPremisesImmutableId

# Birçok kullanıcı için
Get-MgUser -All | Select-Object Id, UserPrincipalName, OnPremisesImmutableId | Format-Table -AutoSize

# Tek kullanıcı
Get-MgUser -UserId username@domain.com -Property OnPremisesImmutableId | select OnPremisesImmutableId

# Birçok kullanıcı için
Get-MgUser -All | Select-Object Id, UserPrincipalName, OnPremisesImmutableId | Format-Table -AutoSize

4.2 GUID ↔ Base64 dönüşümleri (yardımcı fonksiyonlar)

# GUID -> Base64 (ImmutableId tipik formatı)
function Convert-GuidToImmutableId {
    param([Parameter(Mandatory)][Guid]$Guid)
    return [Convert]::ToBase64String($Guid.ToByteArray())
}

# Base64 -> GUID (kontrol için)
function Convert-ImmutableIdToGuid {
    param([Parameter(Mandatory)][string]$ImmutableId)
    $bytes = [Convert]::FromBase64String($ImmutableId)
    return [Guid]::new($bytes)
}

# Örnek kullanım
$g = [Guid]::NewGuid()
$imm = Convert-GuidToImmutableId -Guid $g
$back = Convert-ImmutableIdToGuid -ImmutableId $imm
$g
$imm
$back

# GUID -> Base64 (ImmutableId tipik formatı)
function Convert-GuidToImmutableId {
    param([Parameter(Mandatory)][Guid]$Guid)
    return [Convert]::ToBase64String($Guid.ToByteArray())
}

# Base64 -> GUID (kontrol için)
function Convert-ImmutableIdToGuid {
    param([Parameter(Mandatory)][string]$ImmutableId)
    $bytes = [Convert]::FromBase64String($ImmutableId)
    return [Guid]::new($bytes)
}

# Örnek kullanım
$g = [Guid]::NewGuid()
$imm = Convert-GuidToImmutableId -Guid $g
$back = Convert-ImmutableIdToGuid -ImmutableId $imm
$g
$imm
$back

4.3 ImmutableId’yi değiştirmek (yalnızca uygun senaryolar)

Dikkat: Kullanıcı dirsync ile eşitlenen bir kullanıcıysa OnPremisesImmutableId bulutta değiştirilemez. Değişiklik on-prem AD’de yapılmalı ve senkronizasyon beklenmelidir.

Cloud-Only kullanıcı için değiştirme örnekleri:

# 1) Mevcut değeri temizlemek (hard/soft match hazırlığı)
Update-MgUser -UserId "user@domain.com" -OnPremisesImmutableId $null

# 2) Yeni bir ImmutableId atamak (ör. hedef on-prem GUID’nin Base64 hali)
$newGuid = [Guid]"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
$newImmutableId = [Convert]::ToBase64String($newGuid.ToByteArray())
Update-MgUser -UserId "user@domain.com" -OnPremisesImmutableId $newImmutableId

# 3) Yeni immutable ataman başka yöntem
Update-MgUser -UserId username@domain.com -OnPremisesImmutableId "yeni-immutable-id"

# 1) Mevcut değeri temizlemek (hard/soft match hazırlığı)
Update-MgUser -UserId "user@domain.com" -OnPremisesImmutableId $null

# 2) Yeni bir ImmutableId atamak (ör. hedef on-prem GUID’nin Base64 hali)
$newGuid = [Guid]"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
$newImmutableId = [Convert]::ToBase64String($newGuid.ToByteArray())
Update-MgUser -UserId "user@domain.com" -OnPremisesImmutableId $newImmutableId

# 3) Yeni immutable ataman başka yöntem
Update-MgUser -UserId username@domain.com -OnPremisesImmutableId "yeni-immutable-id"

Senaryolar:

• Hard Match (eski cloud hesabını on-prem ile eşlemek):
  1. Cloud kullanıcıda OnPremisesImmutableId boş yapılır (gerekirse).
  2. On-prem AD obje GUID’sinin Base64 karşılığı atanır.
  3. Entra Connect senkronu çalıştığında eşleşme gerçekleşir.

5) Kullanıcıyı Silmek (Soft Delete)

Kullanıcı silindiğinde Deleted Users alanına taşınır; 30 gün içinde geri yüklenebilir.

5.1 Soft delete komutu

Remove-MgUser -UserId "user@domain.com"
# veya GUID ile
Remove-MgUser -UserId "<GUID>"

Remove-MgUser -UserId "user@domain.com"
# veya GUID ile
Remove-MgUser -UserId "<GUID>"

5.2 Doğrulama

Get-MgDirectoryDeletedUser | Where-Object { $_.UserPrincipalName -eq "user@domain.com" }

Get-MgDirectoryDeletedUser | Where-Object { $_.UserPrincipalName -eq "user@domain.com" }

6) Silinen Kullanıcıyı Kalıcı Silmek (Hard Delete / Purge)

Bazı ortamlarda Remove-MgDirectoryDeletedUser cmdlet’i bulunmayabilir. Bu durumda Graph API çağrısı ile kesin sonuç alınır.

6.1 Tek bir kullanıcıyı purge etmek

# <ID> yerine Deleted Users içindeki kullanıcı Id’sini (GUID) yazın
Invoke-MgGraphRequest -Method DELETE -Uri "https://graph.microsoft.com/v1.0/directory/deletedItems/<ID>"

# <ID> yerine Deleted Users içindeki kullanıcı Id’sini (GUID) yazın
Invoke-MgGraphRequest -Method DELETE -Uri "https://graph.microsoft.com/v1.0/directory/deletedItems/<ID>"

Örnek:

Invoke-MgGraphRequest -Method DELETE -Uri "https://graph.microsoft.com/v1.0/directory/deletedItems/588cd69a-3f38-4y56-b051-ade334ec0d2e"

Invoke-MgGraphRequest -Method DELETE -Uri "https://graph.microsoft.com/v1.0/directory/deletedItems/588cd69a-3f38-4y56-b051-ade334ec0d2e"

6.2 Toplu purge

$deleted = Get-MgDirectoryDeletedUser
foreach ($u in $deleted) {
    Write-Host "Purge: $($u.DisplayName) [$($u.Id)]"
    Invoke-MgGraphRequest -Method DELETE -Uri "https://graph.microsoft.com/v1.0/directory/deletedItems/$($u.Id)"
}

$deleted = Get-MgDirectoryDeletedUser
foreach ($u in $deleted) {
    Write-Host "Purge: $($u.DisplayName) [$($u.Id)]"
    Invoke-MgGraphRequest -Method DELETE -Uri "https://graph.microsoft.com/v1.0/directory/deletedItems/$($u.Id)"
}

Geri dönüşü yoktur. Kalıcı silme sonrası kullanıcı, lisanslar ve bağlı objeler geri alınamaz (ilgili hizmetlerin kendi saklama politikaları hariç).

6) Silinen Kullanıcıyı Geri Yüklemek (Restore)

7.1 Tek kullanıcı restore (cmdlet mevcutsa)

# Bazı sürümlerde vardır:
Restore-MgDirectoryDeletedItem -DirectoryObjectId <ID>

# Bazı sürümlerde vardır:
Restore-MgDirectoryDeletedItem -DirectoryObjectId <ID>

7.2 Graph API ile restore

$body = @{ } | ConvertTo-Json
Invoke-MgGraphRequest -Method POST -Uri "https://graph.microsoft.com/v1.0/directory/deletedItems/<ID>/restore" -Body $body -ContentType "application/json"

$body = @{ } | ConvertTo-Json
Invoke-MgGraphRequest -Method POST -Uri "https://graph.microsoft.com/v1.0/directory/deletedItems/<ID>/restore" -Body $body -ContentType "application/json"

Örnek:

Invoke-MgGraphRequest -Method POST -Uri "https://graph.microsoft.com/v1.0/directory/deletedItems/9776bf02-fhc7-42c0-8537-67ec272a869a/restore" -Body '{}' -ContentType "application/json"

Invoke-MgGraphRequest -Method POST -Uri "https://graph.microsoft.com/v1.0/directory/deletedItems/9776bf02-fhc7-42c0-8537-67ec272a869a/restore" -Body '{}' -ContentType "application/json"

Başarılı olursa, Graph restore edilen nesnenin (user) detaylarını döndürür.

8) Sık Görülen Hatalar ve Çözümler

• CommandNotFoundException: İlgili Graph modülü yüklü/değil veya sürüm karmaşası.
  Çözüm: Install-Module Microsoft.Graph -Force -AllowClobber ve sonra Import-Module Microsoft.Graph. Cmdlet gelmezse Invoke-MgGraphRequest ile REST çağrısı kullanın.
• 403 Forbidden / Insufficient privileges: Bağlanırken gerekli scope’lar verilmedi (Directory.AccessAsUser.All, User.ReadWrite.All). Connect-MgGraph komutunu doğru scope’larla tekrarlayın, admin consent verin.
• 400 Bad Request (OnPremisesImmutableId değişmiyor): Kullanıcı DirSync ile eşitleniyor. Değişiklik on-prem AD’de yapılmalı.
• 404 Not Found: Yanlış Id/UPN veya nesne zaten purge edilmiş.