Azure Otomasyonu ile PowerShell için Microsoft Graph SDK'sını kullanma
Runbook'lardan E-postaya
Azure Otomasyon hesaplarını ve runbook'ları Exchange Online yönetimi PowerShell modülü ile kullanma hakkında daha önceki bir yazımda, o yazımda ayrıca bir runbook'ta çalıştırılan bir PowerShell betiğinde Graph API sorgularının nasıl kullanılacağını da anlatmıştım. Doğal olarak devam eden soru, Microsoft Graph PowerShell SDK'sının runbook'ları destekleyip desteklemediğini sormaktır. SDK'nın Azure Otomasyonu ile sertifika tabanlı kimlik doğrulama veya yönetilen kimlikler kullanılarak kullanılabileceğini bildirebilirim. Elbette basit bir ifade birçok karmaşıklığı gizleyebilir; o yüzden gelin ayrıntıları inceleyelim.
Neyin mümkün olduğuna dair pratik bir örnek olarak, bu makalede, burada açıklanan yeni posta kutularına e-posta göndermek için komut dosyasını bir runbook'ta yürütmek üzere dönüştürüyorum.
Azure Otomasyonu Kurulumu
Önceki makalede tartışıldığı gibi, betiği bir korumalı alan sunucusunda çalıştırmak için bir Azure Otomasyon hesabı (Azure aboneliğine bağlı) kullanacağız. Azure Otomasyonu yönetilen kimlikleri destekler ve bu konuyu gelecekteki bir makalede ele alacağım. Şimdilik denenmiş ve test edilmiş teknik işi yapıyor.
Güncelleme: Azure Otomasyonu artık Runbook hesaplarını desteklememektedir. Bunun yerine yönetilen bir kimlik kullanın. Daha fazla bilgi için bu makaleye bakın. Modüllerin bir otomasyon hesabına yüklenmesi ve Otomasyon hesaplarına Grafik izinlerinin atanması konusunda burada açıklanan prensipler hala geçerlidir.
Grafik Modüllerini İçe Aktarma
RunAs hesabının bir hizmet sorumlusu ve Azure tarafından yönetilen bir sertifikası vardır. Bunlar kimlik doğrulama için kullanılan temel bileşenlerdir. Ancak kimlik doğrulama yalnızca başlangıçtır. Microsoft Graph PowerShell SDK'sını bir runbook'ta kullanılabilir hale getirmek için modüllerini otomasyon hesabına paylaşılan kaynaklar olarak aktarmamız gerekir.
Modül değil modül kullandığımı fark edebilirsiniz. Microsoft Graph PowerShell SDK'yı PowerShell galerisinden indirip bir iş istasyonuna yüklediğinizde tek bir modül alamazsınız. Bunun yerine SDK, her biri genel Graph manzarasının küçük bir kısmıyla ilgilenen birçok farklı modüle bölünür. SDK'yı bir otomasyon hesabına aktardığınızda, bir komut dosyasının ihtiyaç duyduğu modülleri de içe aktarmanız gerekir. İlk görev, her cmdlet'in hangi modülde olduğunu keşfetmek için kullanmayı planladığınız cmdlet'lerin belgelerini kontrol etmektir.
Örneğin, komut dosyanızın kiracınızın ayrıntılarını döndürmek için Get-MgOrganization cmdlet'ini kullandığını varsayalım. Microsoft'un belgeleri bize cmdlet'in Microsoft.Graph.Identity.DirectoryManagement modülüne ait olduğunu söylüyor (Şekil 1).
Bu arada, SDK cmdlet'lerinin dokümantasyonunun, yapay zekanın kaynak koduna dayalı dokümantasyon oluşturmak için kullanıldığında neden bazen bu kadar iyi çalışmadığının korkunç bir örneği olduğunu söyleyeyim. Belgelerin iyileştirilmesi, insanların SDK cmdlet'lerini daha iyi anlamalarına yardımcı olacak ve bunların kullanımını teşvik edecektir. Şimdilik ciddi bir yoruma ve çok fazla sabra ihtiyaç var.
SDK Modüllerini Azure Otomasyon Hesabına Yükleme
Tüm SDK cmdlet'lerini bulmak için betiği kontrol ettikten sonra dört modülü içe aktardım (Şekil 2):
- Microsoft.Graph.Authentication: Grafiğe karşı kimlik doğrulamak için.
- Microsoft.Graph.Users.Action: mesaj göndermek için.
- Microsoft.Graph.Mail: posta mesajlarına erişmek için.
- Microsoft.Graph.Identity.Management: organizasyon ayrıntılarını almak için.
Grafik İzinlerini Atama
Grafikle etkileşime geçmek için SDK modüllerinin yüklenmesi bizi başlatır: bunu yapmak için gerekli izinlere sahip olmak döngüyü tamamlar. Connect-MgGraph cmdlet'ini kullanarak bağlandığınızda, oluşturduğunuz oturum belirli Grafik izinlerini kullanabilir. Bu oturum kapsamıdır. Bu durumda, komut dosyasının, mesajı alıcılara göndermeden önce bir mesaj oluşturmak için kullanıcının posta kutusuna erişmesi gerekir; dolayısıyla kimlik doğrulama için kullanılan varlığın, bu eylemleri gerçekleştirmek için gerekli Grafik uygulaması iznine sahip olması gerekir. Varlık, RunAs hesabının hizmet sorumlusudur. Komut dosyasının e-posta gönderebilmesi için önce bir yöneticinin, hizmet sorumlusunun Mail.Send ve Mail.ReadWrite izinlerine sahip olmasına izin vermesi gerekir.
RunAs hesabı için hizmet sorumlusuna izin atamak, kayıtlı bir uygulamaya izin atamakla aynıdır. Azure AD yönetim merkezine gidin, kayıtlı uygulamalar kümesinde hizmet sorumlusunu bulun, gerekli izinleri ekleyin ve kuruluş adına onay verin. Şekil 3'teki gibi bir sonuç elde etmelisiniz. Önceki makalede bu hizmet ilkesini kullandığım için ekstra iki Grafik izni mevcut.
Çok fazla Grafik iznine sahip hizmet sorumluları oluşturmamaya dikkat edin. Microsoft Graph PowerShell SDK ile etkileşimli oturumlar için kullanılan hizmet sorumlusu gibi, birden fazla görev için kullanıldığında hizmet sorumlusunun zaman içinde izinleri toplaması kolaydır. Üretimde farklı işler için ayrı otomasyon hesapları kullanmayı düşünün.
PowerShell Kodunu Değiştirme
Artık doğru izinlere ve gerekli modüllere erişime sahip bir RunAs hesabımız var, bu yüzden biraz kod yazmanın zamanı geldi. Başlangıç noktası olarak çalışan bir betik mevcuttur ancak runbook'ta çalışması için ayarlanması gerekir. İşte yaptığım şey:
Öncelikle otomasyon hesabından sertifika parmak izini almak için yeni bir kimlik doğrulama bölümü ekledim. Sertifika daha sonra Microsoft Graph'a olan bağlantının kimliğini doğrular.
$Connection = Get-AutomationConnection -Name AzureRunAsConnection
# Get certificate from the automation account
$Certificate = Get-AutomationCertificate -Name AzureRunAsCertificate
# Connect to the Graph SDK endpoint using the automation account
Connect-MgGraph -ClientID $Connection.ApplicationId -TenantId $Connection.TenantId -CertificateThumbprint $Connection.CertificateThumbprint
Daha sonra, kiracı hizmeti etki alanını aldım ve bunu Exchange Online'a bağlanmak için (yakın zamanda eklenen posta kutusu kümesini getirmek için) aynı sertifika parmak iziyle birlikte kullandım.
$Organization = Get-MgOrganization
$TenantName = $Organization.DisplayName
$TenantDomain = $Organization.Verifieddomains | ? {$_.IsInitial -eq $True} | Select -ExpandProperty Name
# Connect to Exchange Online
Connect-ExchangeOnline –CertificateThumbprint $Connection.CertificateThumbprint –AppId $Connection.ApplicationID –ShowBanner:$false –Organization $TenantDomain
Otomasyon hesabının Exchange Online'a bağlanmak için bazı izinlere ihtiyacı olduğunu unutmayın. Bu izinler önceki yazımda anlatılmıştı.
Daha sonra mesajın kimden geldiğini tanımladım (kullanmak istediğim posta kutusu). Betiği etkileşimli olarak çalıştırdığımda bu bilgiyi PowerShell'e bağlı olan hesaptan alıyorum ancak RunAs hesabında bu işe yaramıyor bu yüzden bir değişkende kullanmak üzere hesabın SMTP adresini tanımlamamız gerekiyor.
$MsgFrom = "WelcomeNewUsers@Office365itpros.com"Komut dosyam, yerel bir sürücüde saklanan bir hoş geldiniz mektubunu ekliyor. Açıkçası, sanal alanda çalışan bir komut dosyasının yerel sürücüme erişimi yok, bu yüzden bunun yerine hoş geldiniz mektubunu bir web sitesinden indiriyorum ve yerel bir klasörde saklıyorum. Komut dosyası daha sonra dosyanın bir mesaja eklenmesine izin verecek şekilde içeriği kodlar.
$WebAttachmentFile = "https://office365itpros.com/wp-content/uploads/2022/02/WelcomeToOffice365ITPros.docx"
New-Item -Path c:\TempForScriptxxx -ItemType directory -ErrorAction SilentlyContinue
$AttachmentFile = "c:\TempForScriptxxx\WelcomeNewEmployeeToOffice365itpros.docx"
Invoke-WebRequest -uri $WebAttachmentFile -OutFile $AttachmentFile
$Attachment = (Get-Item -Path $AttachmentFile).Name
$EncodedAttachmentFile = [Convert]::ToBase64String([IO.File]::ReadAllBytes($AttachmentFile))
Nihayet. Write-Host kullanarak ekrana gönderilen tüm mesajları kaldırdım. Bir runbook'ta kod yürütüldüğünde bunların görüntüleneceği bir ekran olmadığından bu mesajları vermenin bir anlamı yoktur.
Mesajlar Geliyor
Ve bu kadar. Hazırlık çalışmaları yapıldıktan sonra süreç zor değildir. Kod, gerekli tüm modüllerin hesapta mevcut olması ve hesabın doğru Grafik izinlerine sahip olması nedeniyle çalışır; böylece posta, yeni kullanıcıların posta kutularına akar (Şekil 4).
Kullandığım betiğin tamamının bir kopyasını GitHub'dan indirebilirsiniz.
Otomasyon Güzeldir
Azure Otomasyonunu kullanmanın güzel yanı, betiği yayınlayıp, önceki hafta katılan kullanıcılara hoş geldiniz mesajları göndermek üzere haftalık olarak çalışacak şekilde zamanlayabilmenizdir. Birkaç tıklamayla yeni katılanlar mutluluk dalgalarına kavuşur. Ve aynı e-posta oluşturma ve gönderme tekniği, diğer birçok işin ürettiği bilgileri dağıtmak için kullanılabilir. Bu hoş bir şey değil mi?