For many admins, the use of ‘Scopes’ is a new addition to Office 365 PowerShell’ing.
The Scopes parameter was introduced with the Microsoft Graph PowerShell API, but the concept of Scopes is actually part of the OAuth2 specification.
The use of Scopes limits the user permissions available to an application.
By configuring Scopes when connecting to the Microsoft Graph PowerShell API, you effectively limit what permissions are available for the execution of commands.
We’ll see this in a live example further down. But first, let’s consider the following:
Why Use Scopes?
Let’s say you want to run a script that exports some user information from the Microsoft 365 Graph.
Since you’ll only be reading user information, it makes good sense to limit your permissions to read-only (principle of least privilege).
This will ensure that you don’t accidentally make updates to user accounts.
Also, it protects you from a rogue application trying to make changes when it should only be reading information.
Connecting to MS Graph With Scopes
To establish a connection with the Microsoft Graph PowerShell API to read user information, you can use the following command:
Connect-MgGraph -Scopes "User.Read.All" -TenantId c1493961-2ba6-41ae-b462-e3e7e4dae630(Replace TenantId with your own tenant id)
This will cause OAuth2 authentication to kick in (unless you have already consented to the permissions requested in the Scopes parameter):
Notice that you can clearly see what permissions you’re allowing the Microsoft Graph PowerShell application to use.
Additionally, you can ‘consent on behalf of your organization‘:
Granting consent will spare your coworkers from seeing the above permission request and allow Microsoft Graph PowerShell to immediately run commands on behalf of your coworkers.
Keep in mind: Consent does not grant any new permissions to users in your organization. Consent only allows the application (in this case, Microsoft Graph PowerShell) to use permissions already assigned to users. Read more about consent here.
After you accept the permissions request, the Microsoft Graph PowerShell application is configured with the new consent.
Go to Enterprise Applications, click on Microsoft Graph PowerShell, select Permissions, and select User consent to see it:
Unfortunately, the Enterprise Application settings seen in the above screenshot only show settings with no ability to reconfigure or delete permissions.
If you would like to learn how to manage Admin and User consent using PowerShell scripting, read this article.
Testing Scope Settings on MS Graph PowerShell
To illustrate the protection received by using scopes configuration, let’s try to update an Azure AD user account by setting the UsageLocation attribute.
We connect with Scopes set to “User.Read.All” and as expected, this fails:
PS C:\> Connect-MgGraph -Scopes "User.Read.All" -TenantId c1493961-2ba6-41ae-b462-e3e7e4dae630
Welcome To Microsoft Graph!
PS C:\> PS C:\> Get-MgUser -UserId lene.hau@azure.skrubbeltrang.com -Property DisplayName,UsageLocation | ft DisplayName,UsageLocation
DisplayName UsageLocation
----------- -------------
Lene Hau DK
PS C:\> PS C:\> Update-MgUser -UserId lene.hau@azure.skrubbeltrang.com -UsageLocation "US"
Update-MgUser : Insufficient privileges to complete the operation. To fix this we have to reconnect using a more extensive scope:
Connect-MgGraph -Scopes "User.ReadWrite.All" -TenantId c1493961-2ba6-41ae-b462-e3e7e4dae630Assuming we haven’t previously consented to this, we receive a new OAuth2 authentication dialog stating the new level of consent:
After accepting this, the User consent of the Microsoft Graph PowerShell Enterprise Application is updated with the new consent which we can verify in the Azure Portal:
With the new scope in place we are now able to write new information to user objects in Azure AD:
PS C:\> Connect-MgGraph -Scopes "User.ReadWrite.All" -TenantId c1493961-2ba6-41ae-b462-e3e7e4dae630 Welcome To Microsoft Graph! PS C:\> Update-MgUser -UserId lene.hau@azure.skrubbeltrang.com -UsageLocation "US" PS C:\> Get-MgUser -UserId lene.hau@azure.skrubbeltrang.com -Property DisplayName,UsageLocation | ft DisplayName,UsageLocation DisplayName UsageLocation ----------- ------------- Lene Hau US
Manage Office 365 Directly From Active Directory
Hybrid Office 365 management can be very time-consuming and cumbersome.
Some attributes are managed in on-premises Active Directory while others are managed in various web portals like Microsoft 365 Admin Center and Exchange Online Admin Center.
Again, some settings like calendar delegation can only be managed via PowerShell.
With Easy365Manager, you can perform all daily Office 365 management from Active Directory Users & Computers.
Easy365Manager is a snap-in that extends user properties with an Office 365 tab and a Mailbox tab.
This allows for super fast and super convenient Office 365 administration:
With Easy365Manager, you no longer need to worry about a plethora of Office 365 web consoles and PowerShell APIs that are expiring.
You can install Easy365Manager in just a few minutes, and there are no changes to your infrastructure.
Download your 30-day trial here.