Forem: SRINIVAS VARUKALA

Manage Azure AD Enterprise Applications permissions using Microsoft Graph PowerShell

SRINIVAS VARUKALA — Mon, 03 Oct 2022 22:16:08 +0000

Recently I was asked this question:

Is it supported to revoke permissions (selectively) for an enterprise application?

This blogpost shows how to manage enterprise applications permissions. Note that Azure Portal UI doesn't allow these actions, so you have to rely on some scripting. Hence this blog post.

What is an enterprise application?

I will take a snippet from one of my old posts to save some time.

To list permissions of an Enterprise Application

To get the list of permissions granted for a given service application you can use script posted to my GitHub Gist. Here is example output:

To revoke existing permissions of an Enterprise Application

Let's take Waldo App as an example. Here is the enterprise application of Waldo app. Note the object id of this service principal.

Next, view the permissions granted for this app. You can see the permissions in two tabs:

Admin consent and
User consent. To get the permissions grant for the Waldo app, run below cmdlet with its Object Id. ```powershell

Get-MgServicePrincipalOauth2PermissionGrant -ServicePrincipalId 090beef1-f5b6-4f35-9326-6d8596e42942

**ConsentType** column in the output signifies if its the Admin consent (AllPrincipals) or User consent (Principal) permissions.
![Sample output of PS script](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/em5a8cvu1dtf5e9m6kzt.png)

#### Revoke all the permissions
You can remove all the permissions completely using below cmdlet and passing the ID value from the output as the GrantId:
```powershell


Remove-MgOauth2PermissionGrant -OAuth2PermissionGrantId 8e4LCbb1NU-TJm2FluQpQjqF4W-UGkRLtzPexGZThns

Revoke the permissions selectively

In order to remove the permissions (aka scopes) selectively. Here is an example. Let's say I want to remove "User.Read" and "Directory.Read.All" scopes but retain other scopes. Create an array for the scopes to be removed:



$permissionsToRemove = @("User.Read", "Directory.Read.All")

Get the grants using the object id:



$grant = Get-MgServicePrincipalOauth2PermissionGrant -ServicePrincipalId 090beef1-f5b6-4f35-9326-6d8596e42942
$grant.Scope

Here is the sample output of the scopes that are already granted:

Place.Read.All offline_access User.Read User.ReadBasic.All User.Read.All Directory.Read.All Calendars.ReadWrite openid ChatMessage.Send Chat.ReadBasic Chat.Create

Create a new array of scopes by removing the unwanted scopes.



$permissionsToRemove = $permissionsToRemove | % { $_.ToLower() }
$newPermissions = $grant.Scope.Split(" ") | ? { -not $permissionsToRemove.Contains($_.ToLower()) }
$newScope = $newPermissions -join " "

Finally update the grant with the new scopes using the grant id.



Update-MgOauth2PermissionGrant -OAuth2PermissionGrantId $grant.Id -Scope $newScope

Here is a sample run of the above cmdlets:

After removing the 2 scopes here is the current permissions:

To grant permissions to an enterprise application

Below is a sample script that shows how to add Microsoft Graph permissions to an enterprise application.



# The object id of the enterprise application 
$ObjectId = "b29d7573-2f76-49b6-b660-cc85b34fe516"
# Add the correct Graph scope to grant (e.g. User.Read)
$graphScope = "Sites.Selected"

Connect-MgGraph -Scope AppRoleAssignment.ReadWrite.All

# Get the Microsoft Graph service principal
$graph = Get-MgServicePrincipal -Filter "AppId eq '00000003-0000-0000-c000-000000000000'"

# Get the graph app role for the scope that we want to grant
$graphAppRole = $graph.AppRoles | ? Value -eq $graphScope

# Prepare the app role assignment
$appRoleAssignment = @{
    "principalId" = $ObjectId
    "resourceId"  = $graph.Id
    "appRoleId"   = $graphAppRole.Id
}

# Grant the app role
New-MgServicePrincipalAppRoleAssignment -ServicePrincipalId $ObjectID -BodyParameter $appRoleAssignment | Format-List

The above script uses the AppRoleAssignment.ReadWrite.All which is a privileged permission. You can grant application permissions using app grant consent policy which doesn't require the privileged permissions. Here is a blog post from Sahil Malik that goes into details of how its done.

Use Microsoft Graph to Set Granular Permissions to SharePoint Online Sites for Azure AD Application

SRINIVAS VARUKALA — Tue, 09 Feb 2021 06:57:53 +0000

I recently put out a Twitter post about the upcoming capability
that allows you to apply granular permissions to SharePoint Online Sites for Azure AD Applications.

// Detect dark theme var iframe = document.getElementById('tweet-1349747161504882688-873'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1349747161504882688&theme=dark" }

This capability is now live and available in the Microsoft Graph API (both v1.0 and Beta). Find the API reference on Microsoft Graph documentation. I have seen a lot of our customers rely on the legacy 'Access Control Services' (ACS) based apps (apps registered using /_layouts/15/appregnew.aspx page) to meet the site level/granular permissions requirements. With this update you can now stop doing that and embrace the modern way using Microsoft Graph.

In this blog I will show how this is accomplished using PowerShell and Microsoft Graph REST API calls.

The current implementation feels like a MVP('minimal viable product') of a long term solid plan from Microsoft. Therefore, at the moment there is no UI/UX for admins to manage (add/remove permissions at) the individual site level permissions. It's only possible through Microsoft Graph API. You will need two apps to accomplish this.

First is the Azure AD application (let's call it 'client-app') registered that needs to be given app-only permissions to select few sites (as against to all sites in the tenant). First step is to navigate to the "API Permissions" for that app. Select "Application permissions" box. Then select "Sites.Selected" permission scope listed under "Sites" category.

You need another Azure AD application (let's call it 'admin-app') that has 'Sites.FullControl.All' app-only permissions. Assume this is created and managed by your IT Admins. IT admin will use this application (as a helper utility) to call Microsoft Graph and assign 'client-app' the permissions (read or write) for each site that it needs access. In this way the 'client-app' will be able to make queries only to those set of sites. Microsoft graph is updated to support this capability. To add/remove permissions at site collection level, you need to use the /sites/{site-id}/permissions REST API.
Here is an example:

https://graph.microsoft.com/v1.0/sites/contoso.sharepoint.com,ab37ac98-a777-4444-b90f-20e2a8728caf,faaf89c8-4444-4639-978f-39e07847b61a/permissions

Here is a sample PowerShell script to enumerate existing site level permissions using Microsoft Graph

NOTE: When we enumerate the granular permissions, its not showing the role (read/write) details. It's showing the unique perm id, display name and client app id. This might be a temporary gap in the functionality.

Here is a script sample to add granular permissions to a site using Microsoft Graph:

Here is a script to remove all granular permissions or selected granular permissions based on the app id:

I created a sample script to finally test this out. This sample script enumerates all the lists in a given SPO site. Below image shows the script failing before giving the granular permissions:

Now I ran the Add-SPOSiteGranularPermission script giving my client-app 'read' permissions to the site. Here is the output from the script:

Below image shows the same script now successful after giving the granular permissions on the site:

Here is the sample script that I used for my sample run:

Some of the limitations I see in the current state:

Thie granular permissions is limited to application permissions (app-only) for an Azure AD app.
There is no UI/UX to manage the granular permissions
There is currently no endpoint to list out sites that has granular permissions enabled for a given AAD app
Site collection level seems to be the most granular it can go.

Jeremy Kelley (Microsoft PM) presented on this topic in February's Microsoft Graph community call. He answered a bunch of questions and also hinted that this capability is just beginning and it has a long way to go. You can access the recording here.

Finally I am working on a full blown script to manage the site level permissions in bulk. You can retrieve, add, remove permissions by supplying a CSV file as input. I will update the link here once that is ready.

Please leave any comments, questions or feedback.

Learn How Authentication Works in the latest PnP.PowerShell Module

SRINIVAS VARUKALA — Mon, 11 Jan 2021 02:12:00 +0000

The transition to the new PnP.PowerShell for Microsoft 365 module should be smooth but if you see errors like 404 unauthorized or consent error, this blog might help you understand the underlying authentication mechanism behind PnP.PowerShell.

Introduction

Microsoft 365 Patterns and Practices (PnP) team published a new PowerShell module for M365 that runs on .NET Core 3.1/.NET Framework 4.6.1 and PowerShell Core v7.1. This means this module is platform agnostic. This also means the legacy SharePointPnPPowerShellOnline module will eventually be discontinued. The reason for this shift is well explained by PnP PowerShell team.

If you are wondering what is the best way to switch from SharePointPnPPowerShellOnline to Pnp.PowerShell, you got covered by awesome folks like Todd Klindt - also explains reason for the switch and Jeff Jones - bonus quick short video.

PnP PowerShell Authentication with Service Principal

The transition to the new PowerShell module should be smooth but I am seeing some folks (example) getting stuck with errors like this one:

Connect-PnPOnline : AADSTS65001: The user or administrator has not consented to use the application with ID
'31359c7f-bd7e-475c-86db-fdb8c937548e' named 'PnP Management Shell'. Send an interactive authorization request for this user and resource

There are two pieces of information in this error that is relevant to this blog.

31359c7f-bd7e-475c-86db-fdb8c937548e <-- The application ID
PnP Management Shell <-- The name of the application

One of the important changes is the way authentication works in the new module. The final step after installing the PnP.PowerShell module is to run this command:

Register-PnPManagementShellAccess

This PS command will create an Azure AD Enterprise Application (a service principal) with an ID (31359c7f-bd7e-475c-86db-fdb8c937548e) and the name of this application is "PnP Management Shell". You can navigate to your Azure Portal > Azure Active Directory > Enterprise Applications. You can see the app there.

Note: The same enterprise application with ID 31359c7f-bd7e-475c-86db-fdb8c937548e is also used by CLI for Microsoft 365 too.

This is a service principal with a fixed ID and name.

How does it have a fixed name/id and how is it different from Azure AD App registration?

Consider contoso.onmicrosoft.com tenant is where a AAD App is registered with the ID (31359c7f-bd7e-475c-86db-fdb8c937548e) and name "PnP Management Shell". And this app is configured as a multi-tenant app. Sine this is multi-tenant app, whenever a user uses it the first time from a different tenant (say fabrikam.onmicrosoft.com), a corresponding service principal is created in the 'enterprise applications' section in their tenant with the same ID/Name. It's basically a projection of the app with the same permissions but requested and consented in the users (in this example its fabrikam.onmicrosoft) tenant. The Register-PnPManagementShellAccess command is doing exactly this.

How to consent to minimal permissions for the PnP PowerShell Enterprise App

When you run the Register-PnPManagementShellAccess command, it will prompt you to consent to a large number of permissions. See picture below.

There is a way to take control on the permissions, minimize the permissions for the PnP PowerShell app for reasons like a shared environment or may be to use PnP PowerShell in Azure DevOps CICD pipeline. To do that instead of running the Register-PnPManagementShellAccess command, you need to create the Service Principal on your own and request the minimal permissions needed for your scenario. Here is an Azure CLI script sample:

Caveat with previously consented SharePointPnPPowerShellOnline app

If you've previously installed SharePointPnPPowerShellOnline and used it to log into your M365 tenant at some point, then that would have already created the Azure AD Enterprise app with the same ID but a different name ("PnP Office 365 Management Shell"). You can navigate to your Azure Portal > Azure Active Directory > Enterprise Applications to see the service principal.

In this case running Register-PnPManagementShellAccess can be optional. The cmdlets work just fine. But not all commands work. Here is an error for Get-PnPSiteTemplate for example:

To fix the above issue I ran the Register-PnPManagementShellAccess command but that didn't help. I had to delete the existing legacy enterprise app. To delete, you need to open the enterprise application, go to properties and select delete. Then run the Register-PnPManagementShellAccess command.

Use your own Azure AD App with PnP PowerShell

The steps to create your Azure AD App to use with PnP PowerShell is documented here. However, based on my research and understanding, you can use it for App-Only access alone. To use with user login (i.e. delegated access) you have to use the service principal corresponding to PnP Management Shell.

Issue with uninstalling module in PowerShell Core 7.1

When I tried to uninstall a module using Uninstall-Module command, although it runs without any errors, the module actually is not deleted. When I navigate to the module locations, I can see the folder corresponding to the module. To check the PS Module Path you can run the command $env:PSModulePath.
I had to manually delete the module folder to get rid of the module. This might be an isolated issue but calling it out here if anyone hits that issue.

Happy scripting!

Hope that helps!