Skip to content

Find-MgGraphPermission #809

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 16 commits into from
Aug 13, 2021
Merged

Find-MgGraphPermission #809

merged 16 commits into from
Aug 13, 2021

Conversation

FehintolaObafemi
Copy link
Contributor

@FehintolaObafemi FehintolaObafemi commented Aug 6, 2021

This change adds the Find-MgGraphPermission command to the Microsoft.Graph.Authentication module as part of #704. See that issue for details on the functionality and use cases. Here are the implementation highlights:

  • The Find-MgGraphPermission command is implemented as a custom script command using PowerShell itself, not C#
  • A custom type Microsoft.Graph.Custom.Permission is defined as the output type of Find-MgGraphPermission so that other commands like Select-Object can implement auto-complete for the output of Find-MgGraphPermission
  • The change also includes new output formatting in the ps1xml definition for Microsoft.Graph.Custom.Permission
  • Existing sample scripts for Application and Connect have been updated to include relevant use cases involving Find-MgGraphPermission
  • Documentation is included with the command as part of comment-based documentation
  • Unit test coverage is accomplished through a set of Pester test cases

To understand the expected behavior, you can review:

As noted in the original proposal, the permissions data is sourced from Microsoft Graph itself. However, many users will not have the privileges required to read it (you must be able to read the Microsoft Graph service principal object in your Azure Active Directory organization; company admins will have no problem with this, but many lower-privileged users won't be able to. Due to this, there is a fallback to snapshot of that service principal included in the code. For 99% of cases, the fallback will be fine as the newest permissions are unlikely to be those that someone is looking for. We do need to periodically update the file though.

Note that the command also includes additional documented capabilities that were not part of the original proposal -- these were added to simplify automation cases where you where partial matches and non-determinism are unacceptable. The additional filtering allows the set of results to be narrowed down to just one result (or none!) which is required for scenarios such as translating a known friendly permission name to the unique id for use with Microsoft Graph REST APIs or commands for those APIs.

@FehintolaObafemi FehintolaObafemi changed the title Fehintola obafemi/permission Find-MgGraphPermission Aug 6, 2021
@adamedx
Copy link

adamedx commented Aug 6, 2021

@peombwa , I can't find a log of the Pester test runs in the repository -- do you have a pointer to this?

@peombwa
Copy link
Member

peombwa commented Aug 6, 2021

I can't find a log of the Pester test runs in the repository -- do you have a pointer to this?

@adamedx, the Pester test run results can be found here. @georgend, would you know why Invoke-MgGraphRequest tests a failing here?

@FehintolaObafemi, you can ignore the failing Invoke-MgGraphRequest tests since they are not related to your changes.

@adamedx
Copy link

adamedx commented Aug 6, 2021

I can't find a log of the Pester test runs in the repository -- do you have a pointer to this?

@adamedx, the Pester test run results can be found here. @georgend, would you know why Invoke-MgGraphRequest tests a failing here?

@FehintolaObafemi, you can ignore the failing Invoke-MgGraphRequest tests since they are not related to your changes.

Thanks @peombwa -- it seems I don't have permission to see the test results, even though I'm signed in to Azure DevOps. Any way to fix that? If not, can you validate that the tests we added are indeed running? The unit test file is linked in the PR description.

@@ -26,6 +26,7 @@ $app3 = New-MgApplication -displayName "ImplicitWebApp" `
}

# Create an registration for an ASP.NET Web App
$scopeId_UserRead = Find-MgGraphPermission User.Read -ExactMatch -PermissionType Delegated | Select-Object -ExpandProperty Id
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@peombwa you'll want to sign off on having the sample changed to use the new command.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This looks good! This is a good example of how Find-MgGraphPermission can be used to aid in scope discovery.

$GroupReadAll = @{ Id = "5b567255-7703-4780-807c-7be8301ae99b"; Type = "Role" }
$MailboxSettingsRead = @{ Id = "40f97065-369a-49f4-947c-6a255697ae91"; Type = "Role" }
$MailSend = @{ Id = "b633e1c5-b582-4048-a93e-9f11b44c7e96"; Type = "Role" }
# Show friendly Graph permission names given their unique identifiers
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Another big change to the sample @peombwa

@@ -6,6 +6,9 @@ Connect-Graph
# Try to Get-User
Get-MgUser

# Search for delegated permissions related to sites
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@peombwa goal here is to show you can use the new command to find permissions, and also to get to the permissions reference help.

@@ -17,3 +20,7 @@ Connect-Graph -Scopes "User.Read","User.ReadWrite.All","Mail.ReadWrite",`

# Forget all access tokens
Disconnect-Graph

# Launch detailed permissions documentation
Get-Help Find-MgGraphPermission -Online
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@msewaweru , this works because the .LINKS field in the comment help has exactly one entry, and it's the URI to the permissions docs. That means we can't provide references to other commands in .LINKS though -- hope that's ok.

Copy link
Contributor

@georgend georgend Aug 10, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@maisarissi given the pointer by @adamedx it means we cannot use related links as we had intended to store Survey Links.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You may want to sync with someone from the https://github.com/powershell/powershell or other experts on dcs + PowerShell project to confirm the behavior I observed.

Copy link

@maisarissi maisarissi Aug 11, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If there is such a limitation they should call Related Link instead of Related Links (plural) LOL
I will try to sync with someone to confirm this behavior.

}

<#
.SYNOPSIS
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@msewaweru this is the documentation section -- I believe this will be used to generate the online docs...

in the default table view.

.LINK
https://docs.microsoft.com/en-us/graph/permissions-reference
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This allows Get-Help -Online Find-MgGraphPermission to actually point at the permissions reference rather than help for Find-MgGraphPermission. If that's not ok, we can change this.

The SearchString parameter allows you to specify a string such as 'user' or 'mail' that represents the subject or domain
of the permission you're searching for. Since permissions usually have names such as 'User.Read' or 'Mail.ReadWrite', the
command uses the SearchString parameter to return all permissions that contain the value specified for SearchString in the
name of the permission.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@FehintolaObafemi Clarification: I thought you said this searches the description field as well. I don't think that is the case, but just want to make sure.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@TannerTrombley Adam and I opted to excluding the description field search.

@peombwa
Copy link
Member

peombwa commented Aug 9, 2021

Thanks @peombwa -- it seems I don't have permission to see the test results, even though I'm signed in to Azure DevOps. Any way to fix that? If not, can you validate that the tests we added are indeed running? The unit test file is linked in the PR description.

AzDO is picking up the Find-MgGraphPermission Pester tests and running them as expected. However, the following test is failing with:

The Find-MgGraphPermission Command.When executing the command using a constrained set of permissions returned by MS Graph and there is a connection.Should return null and not throw an exception if ExactMatch is specified and there is no match

Expected no exception to be thrown, but an exception "No results were found that exactly matched the specified permission 'IDontExist'" was thrown from C:\a\1\s\src\Authentication\Authentication\test\Find-MgGraphPermission.Tests.ps1:119 char:15
+ …           { Find-MgGraphPermission -ExactMatch IDontExist 2>&1 | out-+               ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~.
at { Find-MgGraphPermission -ExactMatch IDontExist 2>&1 | out-null } | Should -Not -Throw, C:\a\1\s\src\Authentication\Authentication\test\Find-MgGraphPermission.Tests.ps1:119

cc\ @FehintolaObafemi

@adamedx adamedx force-pushed the FehintolaObafemi/permission branch from 0a9db56 to 21c50f3 Compare August 9, 2021 20:18
adamedx and others added 9 commits August 9, 2021 16:22
Find-MgGraphPermission: Define new location for common script code
Find-MgGraphPermission: Add formatting

Work around Pester corrupting variable scopes

Add missing files: Work around Pester corrupting variable scopes
Add help documentation for Find-MgGraphPermission
Add pipeline support, ExactMatch and explicitly return all
…tion to make errors ignorable

Update samples to include usage of Find-MgGraphPermission
@adamedx adamedx force-pushed the FehintolaObafemi/permission branch from 21c50f3 to ae89eec Compare August 9, 2021 20:22
@adamedx
Copy link

adamedx commented Aug 9, 2021

Thanks @peombwa -- it seems I don't have permission to see the test results, even though I'm signed in to Azure DevOps. Any way to fix that? If not, can you validate that the tests we added are indeed running? The unit test file is linked in the PR description.

AzDO is picking up the Find-MgGraphPermission Pester tests and running them as expected. However, the following test is failing with:

The Find-MgGraphPermission Command.When executing the command using a constrained set of permissions returned by MS Graph and there is a connection.Should return null and not throw an exception if ExactMatch is specified and there is no match

Expected no exception to be thrown, but an exception "No results were found that exactly matched the specified permission 'IDontExist'" was thrown from C:\a\1\s\src\Authentication\Authentication\test\Find-MgGraphPermission.Tests.ps1:119 char:15
+ …           { Find-MgGraphPermission -ExactMatch IDontExist 2>&1 | out-+               ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~.
at { Find-MgGraphPermission -ExactMatch IDontExist 2>&1 | out-null } | Should -Not -Throw, C:\a\1\s\src\Authentication\Authentication\test\Find-MgGraphPermission.Tests.ps1:119

cc\ @FehintolaObafemi

Interesting -- then my question why are the checks passing? Shouldn't this failure cause the checks to all fail and turn red?

I'm not sure why this would fail unless the $ErrorActionPreference is set to something non-standard. I have an idea how to compensate for that...

@peombwa
Copy link
Member

peombwa commented Aug 11, 2021

Thanks @peombwa -- it seems I don't have permission to see the test results, even though I'm signed in to Azure DevOps. Any way to fix that? If not, can you validate that the tests we added are indeed running? The unit test file is linked in the PR description.

AzDO is picking up the Find-MgGraphPermission Pester tests and running them as expected. However, the following test is failing with:

The Find-MgGraphPermission Command.When executing the command using a constrained set of permissions returned by MS Graph and there is a connection.Should return null and not throw an exception if ExactMatch is specified and there is no match

Expected no exception to be thrown, but an exception "No results were found that exactly matched the specified permission 'IDontExist'" was thrown from C:\a\1\s\src\Authentication\Authentication\test\Find-MgGraphPermission.Tests.ps1:119 char:15
+ …           { Find-MgGraphPermission -ExactMatch IDontExist 2>&1 | out-+               ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~.
at { Find-MgGraphPermission -ExactMatch IDontExist 2>&1 | out-null } | Should -Not -Throw, C:\a\1\s\src\Authentication\Authentication\test\Find-MgGraphPermission.Tests.ps1:119

@adamedx, I've figured out why the failing tests were not causing the checks to fail. You can find the PR to fix this here.

# both functions and cmdlets at export; if only one of
# these classes is specified, nothing of the other
# class will be exported.
Export-ModuleMember -Function * -Cmdlet *
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just an FYI Exporting module members like this will suppress currently exported cmdlet aliases such as Connect-Graph. The Pester tests to confirm this can be found here. I've fixed this in my PR by adding Get-ModuleCmdlet and Get-ScriptCmdlet helper cmdlets to aid in exporting functions, cmdlets, and aliases.

This will be fixed #816 when we merge the 2 PRs.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Other than the issue highlighted here (which has been fixed by PR #816), everything else looks good to me!

Awesome, thank you @peombwa! What are the next steps? It sounds like this is in your queue to merge and you'll be the person to handle merging this (along with the related PR's)?

Copy link
Member

@peombwa peombwa Aug 12, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@adamedx, That's right. I'll merge the PR later today (to give others time to review it) then schedule everything for a 1.7.0 release.

@FehintolaObafemi, thank you for the excellent contribution!! I'm quite sure our customers will find this command valuable for their scripts.

peombwa
peombwa previously approved these changes Aug 11, 2021
Copy link
Member

@peombwa peombwa left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Other than the issue highlighted here (which has been fixed by PR #816), everything else looks good to me!

@peombwa peombwa merged commit 0d1a30c into dev Aug 13, 2021
@peombwa peombwa mentioned this pull request Sep 7, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

6 participants