การใช้ Microsoft Graph SDK สำหรับ PowerShell กับ Azure Automation

จาก Runbooks ไปจนถึงอีเมล

ในบทความก่อนหน้านี้เกี่ยวกับการใช้บัญชี Azure Automation และ Runbooks กับโมดูล PowerShell การจัดการ Exchange Online ในบทความนั้น ฉันยังได้อธิบายวิธีใช้การสืบค้น Graph API ในสคริปต์ PowerShell ที่ดำเนินการใน Runbook คำถามที่ตามมาโดยทั่วไปคือการถามว่า Microsoft Graph PowerShell SDK รองรับ runbook หรือไม่ ฉันสามารถรายงานว่า SDK สามารถใช้กับ Azure Automation ได้โดยใช้การรับรองความถูกต้องตามใบรับรองหรือข้อมูลประจำตัวที่ได้รับการจัดการ แน่นอนว่าข้อความง่ายๆ สามารถซ่อนความซับซ้อนได้มากมาย ดังนั้นเรามาสำรวจรายละเอียดกันดีกว่า

เพื่อเป็นตัวอย่างในทางปฏิบัติของสิ่งที่เป็นไปได้ ในบทความนี้ ฉันจะแปลงสคริปต์เพื่อส่งอีเมลไปยังกล่องจดหมายใหม่ที่อธิบายไว้ที่นี่เพื่อดำเนินการใน Runbook

การตั้งค่าการทำงานอัตโนมัติของ Azure

ตามที่กล่าวไว้ในบทความก่อนหน้านี้ เราจะใช้บัญชี Azure Automation (เชื่อมโยงกับการสมัครใช้งาน Azure) เพื่อเรียกใช้สคริปต์บนเซิร์ฟเวอร์ Sandbox Azure Automation รองรับข้อมูลประจำตัวที่ได้รับการจัดการ และฉันจะเจาะลึกหัวข้อนั้นในบทความต่อๆ ไป สำหรับตอนนี้ เทคนิคที่ได้รับการทดลองและทดสอบแล้วได้ผล

อัปเดต: Azure Automation ไม่รองรับบัญชี Runbook อีกต่อไป ใช้ข้อมูลระบุตัวตนที่ได้รับการจัดการแทน ดูบทความนี้สำหรับข้อมูลเพิ่มเติม หลักการที่อธิบายไว้ที่นี่เกี่ยวกับการโหลดโมดูลลงในบัญชีอัตโนมัติและการกำหนดสิทธิ์กราฟให้กับบัญชีอัตโนมัติยังคงใช้ได้

การนำเข้าโมดูลกราฟ

บัญชี RunAs มีหลักการบริการและใบรับรองที่จัดการโดย Azure สิ่งเหล่านี้เป็นองค์ประกอบสำคัญที่ใช้ในการตรวจสอบสิทธิ์ อย่างไรก็ตาม การรับรองความถูกต้องเป็นเพียงจุดเริ่มต้นเท่านั้น ในการทำให้ Microsoft Graph PowerShell SDK พร้อมใช้งานสำหรับ Runbook เราต้องนำเข้าโมดูลไปยังบัญชีอัตโนมัติเป็นทรัพยากรที่ใช้ร่วมกัน

คุณอาจสังเกตเห็นว่าฉันใช้โมดูลไม่ใช่โมดูล เมื่อคุณดาวน์โหลด Microsoft Graph PowerShell SDK จากแกลเลอรี PowerShell และติดตั้งบนเวิร์กสเตชัน คุณจะไม่ได้รับโมดูลเดียว แต่ SDK จะแยกออกเป็นโมดูลต่างๆ มากมาย โดยแต่ละโมดูลจะดูแลส่วนเล็กๆ ของภาพรวมกราฟโดยรวม เมื่อคุณนำเข้า SDK ไปยังบัญชีอัตโนมัติ คุณต้องนำเข้าโมดูลที่สคริปต์ต้องการ งานแรกคือการตรวจสอบเอกสารประกอบสำหรับ cmdlet ที่คุณวางแผนจะใช้เพื่อค้นหาว่าแต่ละ cmdlet อยู่ในโมดูลใด

ตัวอย่างเช่น สมมติว่าสคริปต์ของคุณใช้ Get-MgOrganization cmdlet เพื่อส่งคืนรายละเอียดของผู้เช่าของคุณ เอกสารของ Microsoft แจ้งให้เราทราบว่า cmdlet เป็นของโมดูล Microsoft.Graph.Identity.DirectoryManagement (รูปที่ 1)

ให้ฉันบอกว่าเอกสารประกอบสำหรับ SDK cmdlets เป็นตัวอย่างที่น่าสยดสยองว่าทำไมบางครั้งปัญญาประดิษฐ์จึงทำงานได้ไม่ดีนักเมื่อใช้ในการสร้างเอกสารตามซอร์สโค้ด การปรับปรุงเอกสารประกอบจะช่วยให้ผู้คนเข้าใจ SDK cmdlets ได้ดีขึ้น และสนับสนุนการใช้งานของพวกเขา สำหรับตอนนี้ จำเป็นต้องมีการตีความที่ชัดเจนและต้องใช้ความอดทนอย่างมาก

กำลังโหลดโมดูล SDK ลงในบัญชี Azure Automation

หลังจากตรวจสอบสคริปต์เพื่อค้นหา SDK cmdlets ทั้งหมดแล้ว ฉันจึงนำเข้าโมดูลสี่โมดูลได้ (รูปที่ 2):

• Microsoft.Graph.Authentication: เพื่อตรวจสอบสิทธิ์กับกราฟ
• Microsoft.Graph.Users.Action: เพื่อส่งข้อความ
• Microsoft.Graph.Mail: เพื่อเข้าถึงข้อความเมล
• Microsoft.Graph.Identity.Management: เพื่อรับรายละเอียดองค์กร

การกำหนดสิทธิ์อนุญาตกราฟ

การโหลดโมดูล SDK เพื่อโต้ตอบกับกราฟเป็นการเริ่มต้นของเรา: การได้รับอนุญาตให้ทำเช่นนั้นจะทำให้วงกลมสมบูรณ์ เมื่อคุณเชื่อมต่อโดยใช้ Connect-MgGraph cmdlet เซสชันที่คุณสร้างจะสามารถใช้สิทธิ์อนุญาตกราฟบางอย่างได้ นี่คือขอบเขตเซสชัน ในกรณีนี้ สคริปต์จำเป็นต้องเข้าถึงกล่องจดหมายของผู้ใช้เพื่อสร้างข้อความก่อนที่จะส่งไปยังผู้รับข้อความ ดังนั้นเอนทิตีที่ใช้สำหรับการตรวจสอบสิทธิ์จะต้องมีสิทธิ์การใช้งานแอปพลิเคชันกราฟที่จำเป็นในการดำเนินการเหล่านี้ เอนทิตีเป็นบริการหลักสำหรับบัญชี RunAs ก่อนที่สคริปต์จะสามารถส่งอีเมลได้ ผู้ดูแลระบบจะต้องให้ความยินยอมเพื่ออนุญาตให้ผู้ให้บริการหลักมีสิทธิ์ Mail.Send และ Mail.ReadWrite

การกำหนดสิทธิ์ให้กับบริการหลักสำหรับบัญชี RunAs นั้นเหมือนกับการกำหนดสิทธิ์ให้กับแอปที่ลงทะเบียนไว้ ไปที่ศูนย์การจัดการ Azure AD ค้นหาบริการหลักในชุดแอปที่ลงทะเบียน เพิ่มสิทธิ์ที่จำเป็น และให้ความยินยอมในนามขององค์กร คุณควรจะได้บางอย่างเช่น รูปที่ 3 มีสิทธิ์อนุญาตกราฟเพิ่มเติมสองรายการเนื่องจากฉันใช้บริการหลักนี้ในบทความที่แล้ว

ระวังอย่าสร้างบริการหลักที่มีสิทธิ์เข้าถึงกราฟมากเกินไป เช่นเดียวกับบริการหลักที่ใช้สำหรับเซสชันแบบโต้ตอบกับ Microsoft Graph PowerShell SDK เป็นเรื่องง่ายสำหรับบริการหลักที่จะสะสมสิทธิ์เมื่อเวลาผ่านไปหากใช้สำหรับงานหลายอย่าง ในการผลิต ให้พิจารณาใช้บัญชีอัตโนมัติแยกต่างหากสำหรับงานที่แตกต่างกัน

การแก้ไขรหัส PowerShell

ตอนนี้เรามีบัญชี RunAs ที่มีสิทธิ์ที่ถูกต้องและเข้าถึงโมดูลที่จำเป็นได้ ถึงเวลาเขียนโค้ดแล้ว สคริปต์การทำงานสามารถใช้เป็นจุดเริ่มต้นได้ แต่ต้องมีการปรับเปลี่ยนจึงจะทำงานใน Runbook ได้ นี่คือสิ่งที่ฉันทำ:

ก่อนอื่น ฉันเพิ่มส่วนการรับรองความถูกต้องใหม่เพื่อรับรหัสประจำตัวใบรับรองจากบัญชีอัตโนมัติ ใบรับรองจะตรวจสอบการเชื่อมต่อกับ Microsoft Graph

$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

ต่อไป ฉันดึงข้อมูลโดเมนบริการผู้เช่าและใช้ร่วมกับรหัสประจำตัวใบรับรองเดียวกันเพื่อเชื่อมต่อกับ Exchange Online (เพื่อดึงชุดกล่องจดหมายที่เพิ่มล่าสุด)

$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

โปรดจำไว้ว่าบัญชีอัตโนมัติจำเป็นต้องมีสิทธิ์บางอย่างเพื่อเชื่อมต่อกับ Exchange Online การอนุญาตเหล่านั้นอธิบายไว้ในบทความก่อนหน้าของฉัน

ฉันกำหนดแล้วว่าข้อความนั้นมาจากใคร (กล่องจดหมายที่ฉันต้องการใช้) เมื่อฉันเรียกใช้สคริปต์แบบโต้ตอบ ฉันจะดึงข้อมูลนี้จากบัญชีที่เชื่อมต่อกับ PowerShell ในปัจจุบัน แต่สิ่งนี้ใช้ไม่ได้กับบัญชี RunAs ดังนั้นเราจึงจำเป็นต้องกำหนดที่อยู่ SMTP ของบัญชีเพื่อใช้ในตัวแปร

$MsgFrom = "WelcomeNewUsers@Office365itpros.com"

สคริปต์ของฉันแนบจดหมายต้อนรับที่จัดเก็บไว้ในไดรฟ์ในเครื่อง แน่นอนว่าสคริปต์ที่ทำงานบนแซนด์บ็อกซ์ไม่สามารถเข้าถึงไดรฟ์ในเครื่องของฉันได้ ดังนั้นฉันจึงดาวน์โหลดจดหมายต้อนรับจากเว็บไซต์และจัดเก็บไว้ในโฟลเดอร์ในเครื่องแทน จากนั้นสคริปต์จะเข้ารหัสเนื้อหาเพื่อให้สามารถแนบไฟล์ไปกับข้อความได้

$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))

ในที่สุด. ฉันลบข้อความที่ส่งไปที่หน้าจอโดยใช้ Write-Host ไม่มีประโยชน์ที่จะส่งข้อความเหล่านี้เนื่องจากไม่มีหน้าจอให้แสดงเมื่อมีการเรียกใช้โค้ดใน runbook

ข้อความมาถึง

และนั่นก็คือ กระบวนการนี้ไม่ยากเมื่องานเตรียมการเสร็จสิ้น รหัสทำงานเนื่องจากโมดูลที่จำเป็นทั้งหมดมีอยู่ในบัญชี และบัญชีมีสิทธิ์การใช้งานกราฟที่ถูกต้อง ดังนั้น เมลจึงไหลเข้าสู่กล่องจดหมายของผู้ใช้ใหม่ (รูปที่ 4)

คุณสามารถดาวน์โหลดสำเนาของสคริปต์ทั้งหมดที่ฉันใช้ได้จาก GitHub

ระบบอัตโนมัติเป็นสิ่งที่ดี

ข้อดีของการใช้ Azure Automation คือคุณสามารถเผยแพร่สคริปต์แล้วกำหนดเวลาให้รันทุกสัปดาห์เพื่อส่งข้อความต้อนรับไปยังผู้ใช้ที่เข้าร่วมในช่วงสัปดาห์ก่อนหน้า เพียงคลิกไม่กี่ครั้ง ผู้เข้าร่วมใหม่ก็จะได้รับคลื่นแห่งความสุข และเทคนิคเดียวกันในการสร้างและส่งอีเมลสามารถใช้เพื่อเผยแพร่ข้อมูลที่สร้างจากงานอื่นๆ อีกมากมาย นั่นไม่ใช่เรื่องดีเหรอ?