Find-GraphLeastPrivilege
SYNOPSIS
Finds the least privileged permission(s) required for a Microsoft Graph API endpoint.
SYNTAX
Find-GraphLeastPrivilege [-Path] <String> [[-Method] <String>] [[-Scheme] <String>]
[-ProgressAction <ActionPreference>] [<CommonParameters>]
DESCRIPTION
The Find-GraphLeastPrivilege function identifies the minimal permissions needed to access a specific Microsoft Graph API endpoint. It queries the permissions cache (automatically initialized if needed) and returns only those permissions explicitly marked as least privileged in the Microsoft Graph permissions metadata.
This function helps implement the principle of least privilege by identifying the minimum permission scope required for your application to function.
EXAMPLES
EXAMPLE 1
Find-GraphLeastPrivilege -Path "/me/messages" -Method GET -Scheme DelegatedWork
Returns the least privileged permission needed to read the current user's messages
using delegated work/school account permissions.
Output:
Path Method Scheme Permission
---- ------ ------ ----------
/me/messages GET DelegatedWork Mail.ReadBasic
\`\`\`
### EXAMPLE 2
Find-GraphLeastPrivilege -Path "/users/{id}/messages" -Method GET
Returns the least privileged permissions for reading a user's messages across all authentication schemes.
Output: Path Method Scheme Permission
/users/{id}/messages GET Application Mail.ReadBasic.All /users/{id}/messages GET DelegatedWork Mail.ReadBasic /users/{id}/messages GET DelegatedPersonal Mail.ReadBasic ```
EXAMPLE 3
Find-GraphLeastPrivilege -Path "/me/messages"
Returns least privileged permissions for all HTTP methods and schemes available
for the /me/messages endpoint.
\`\`\`
### EXAMPLE 4
"/me/messages", "/me/calendar/events" | Find-GraphLeastPrivilege -Method GET -Scheme DelegatedWork
Demonstrates pipeline usage to query multiple endpoints at once. Returns the least privileged delegated work permission for reading messages and calendar events.
Output: Path Method Scheme Permission
/me/messages GET DelegatedWork Mail.ReadBasic /me/calendar/events GET DelegatedWork Calendars.ReadBasic ```
EXAMPLE 5
$paths = @("/users/{id}", "/groups/{id}", "/applications") $paths | Find-GraphLeastPrivilege -Method GET -Scheme Application | Select-Object Path, Permission
Queries multiple paths and displays only the path and permission, useful for
generating permission requirement documentation.
\`\`\`
## PARAMETERS
### -Path
The Microsoft Graph API path to query.
Path matching is case-insensitive.
Use {id} placeholders for dynamic segments (e.g., "/users/{id}/messages").
This parameter accepts pipeline input, allowing you to query multiple paths at once.
```yaml
Type: String
Parameter Sets: (All)
Aliases:
Required: True
Position: 1
Default value: None
Accept pipeline input: True (ByValue)
Accept wildcard characters: False
-Method
The HTTP method to filter by. Valid values are: GET, POST, PUT, PATCH, DELETE
If not specified, returns least privileged permissions for all available methods on the path.
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: 2
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Scheme
The authentication scheme to filter by. Valid values are:
- DelegatedWork: Delegated permissions for work/school accounts
- DelegatedPersonal: Delegated permissions for personal Microsoft accounts
- Application: Application permissions (app-only access)
If not specified, returns least privileged permissions for all available schemes.
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: 3
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-ProgressAction
{{ Fill ProgressAction Description }}
Type: ActionPreference
Parameter Sets: (All)
Aliases: proga
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
CommonParameters
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.
INPUTS
OUTPUTS
PSCustomObject
Returns objects with the following properties:
- Path: The API path queried
- Method: The HTTP method
- Scheme: The authentication scheme
- Permission: The least privileged permission name
NOTES
- If a path is not found, a warning is displayed and no output is returned for that path
- If no least privileged permissions are defined for the specified method/scheme combination, a warning is displayed
- The permissions cache is automatically initialized on first use by calling Initialize-GraphPermissions
- To refresh the permissions data, run: Initialize-GraphPermissions -Force