I want to share a step-by-step breakdown of a practical script I’ve put together using Microsoft Graph PowerShell. The goal? To automatically create Terms of Use (ToU) agreements for guest users, making compliance management more streamlined for IT admins. This kind of automation not only saves time but also provides a consistent user experience. Let’s dive into the key parts of this script.
The Scenario
Imagine you’re managing a rapidly expanding environment where guest users are frequently onboarded. It’s crucial that they accept Terms of Use for compliance reasons. Doing this manually for each new guest can be cumbersome, not to mention error-prone. The solution? Automate it with a PowerShell script that integrates with Microsoft Graph, so every guest user has to accept a predefined agreement before gaining access.
Preparing the Microsoft Graph Module
First things first, we need to ensure we have the Microsoft Graph PowerShell module installed. The script starts by checking if it’s installed, and if not, it installs it automatically.
Ensure the Microsoft.Graph module is installed
if (-not (Get-Module -Name Microsoft.Graph -ListAvailable)) { Install-Module -Name Microsoft.Graph -Scope CurrentUser -Force }
This helps in avoiding compatibility issues later on, especially in environments where permissions to install modules might be restricted. Note that we’re installing the module for the current user, so there’s no need for admin privileges.
Importing and Authenticating with Microsoft Graph
Once the module is installed, we import the specific components needed for identity governance and sign-ins, which are crucial for managing the ToU agreements.
Import the necessary Graph modules
Import-Module Microsoft.Graph.Identity.SignIns
Import-Module Microsoft.Graph.Identity.Governance
Authenticate to Microsoft Graph
Connect-MgGraph -Scopes "Agreement.ReadWrite.All"
The Connect-MgGraph cmdlet authenticates us to Microsoft Graph with the necessary scope (Agreement.ReadWrite.All). It’s important to have sufficient permissions to create and manage agreements, so make sure the logged-in account has the proper role assigned in Azure AD.
Defining the Agreement Content
The next step is to define the actual agreement. The script looks for a local PDF file called “touGuests.pdf” that contains the Terms of Use. If the file isn’t found, an error is thrown and the process halts—a nice, user-friendly way to prevent execution if a required resource is missing.
Define the agreement file data
$filePath = Join-Path (Get-Location) "touGuests.pdf" if (-Not (Test-Path -Path $filePath)) { Write-Error "File not found: $filePath" return }
The script reads the PDF as a byte array, which is a requirement for adding files to Microsoft Graph as binary data.
Read the file bytes
$fileBytes = [System.IO.File]::ReadAllBytes($filePath)
Define the agreement file data correctly
$fileData = @{ Data = $fileBytes }
Then, we create a structure that defines how the agreement should appear, including properties like DisplayName, Language, and IsDefault, which ensures this version of the document is set as the default ToU agreement.
Configuring Agreement Properties
Now we move on to defining key parameters for the agreement, such as the expiration and reacceptance requirements. These parameters ensure that users are kept compliant, revisiting agreements when necessary.
Define the terms expiration
$termsExpiration = @{ Frequency = "P1Y"; StartDateTime = "2024-06-01T00:00:00Z" }
Define the agreement body parameter
$bodyParameter = @{ DisplayName = "ToU Agreement Guests" Files = @($agreementFile) IsPerDeviceAcceptanceRequired = $false IsViewingBeforeAcceptanceRequired = $true TermsExpiration = $termsExpiration UserReacceptRequiredFrequency = "P6M" }
The expiration is set to one year, and users must re-accept the agreement every six months, ensuring regular updates to their understanding of the terms. This is useful for scenarios where compliance requirements evolve over time.
Creating the Agreement
After defining everything, the script attempts to create the agreement using the New-MgAgreement cmdlet. The try-catch block provides error handling to notify us if the creation process fails.
try { New-MgAgreement -BodyParameter $bodyParameter } catch { Write-Error "Failed to create agreement: $_" }
This approach ensures that any unexpected issues are captured, providing a clear error message, which is a good practice for troubleshooting.
Disconnect from Microsoft Graph
Disconnect-MgGraph
Wrapping Up
This script is a great example of how Microsoft Graph and PowerShell can be used to automate critical IT tasks. By creating a Terms of Use agreement for guest users, we can maintain control and ensure compliance without manually managing each new guest.
Feel free to modify the script to suit your own needs—every IT environment is different, and what works for one may need slight tweaks for another. As always, your feedback is highly appreciated, and I would love to hear how you’re using these techniques in your environment.
Disclaimer: All scripts are provided as-is, and while they’ve worked well in my environment, your mileage may vary. Be sure to test thoroughly!