Create a JSON file to store permission scopes required for ScubaGear

[MichaelHicks-MSFT]

🗣 Description

Permissions file containing current SCuBAGear permissions mapping.

💭 Motivation and context

Added permissions file to allow centralized management of all SCuBAGear Microsoft Graph permissions.

#1391 is a follow up to this issue, which aims to modify the Connection module to read from the new ScubaPermissions.json file instead of hard coded values.

Closes #1356

🧪 Testing

Testing was conducted across commercial and gcchigh tenants. Created PowerShell code that imported the JSON file and made connections to Microsoft Graph utilizing the permission scopes defined under Permission within the ScubaGearGraphScopes section of the file.

✅ Pre-approval checklist

• This PR has an informative and human-readable title.
• PR targets the correct parent branch (e.g., main or release-name) for merge.
• Changes are limited to a single goal - eschew scope creep!
• Changes are sized such that they do not touch excessive number of files.
• All future TODOs are captured in issues, which are referenced in code comments.
• These code changes follow the ScubaGear content style guide.
• Related issues these changes resolve are linked preferably via closing keywords.
• All relevant type-of-change labels added.
• All relevant project fields are set.
• All relevant repo and/or project documentation updated to reflect these changes.
• Unit tests added/updated to cover PowerShell and Rego changes.
• Functional tests added/updated to cover PowerShell and Rego changes.
• All relevant functional tests passed.
• All automated checks (e.g., linting, static analysis, unit/smoke tests) passed.

✅ Pre-merge checklist

• PR passed smoke test check.

• Feature branch has been rebased against changes from parent branch, as needed

  Use Rebase branch button below or use this reference to rebase from the command line.

• Resolved all merge conflicts on branch

• Notified merge coordinator that PR is ready for merge via comment mention

✅ Post-merge checklist

• Feature branch deleted after merge to clean up repository.
• Verified that all checks pass on parent branch (e.g., main or release-name) after merge.

[tkol2022]

• Can you move the file from the /Connection folder to a new /Permissions folder instead?
• I noticed you removed the ScubaGearSPPermissions node. In the future ScubaGear will have a utility script that helps users register a service principal to run the tool. Is the thought that our new utility script can just filter the GraphCmdLetPermissions node for entries that are of runtype = application and just use that list to create the needed permissions for the service principal in Entra Id?
• We need to add the following REST APIs as entries to the GraphCmdLetPermissions node along with their associated required permissions. Entra Id now includes direct calls to REST APIs without Cmdlets and therefore we need to ensure those permissions are represented.
  • /beta/roleManagement/directory/roleEligibilityScheduleInstances
  • /beta/roleManagement/directory/roleAssignmentScheduleInstances
  • /beta/identityGovernance/privilegedAccess/group/eligibilityScheduleInstances
  • /beta/privilegedAccess/aadGroups/resources

[schrolla]

Minor recommendation for the format as we've had code trip over string vs list values before when it isn't consistent.

[schrolla]

Found a few more multi-valued fields that are represented as strings when singletons. Recommend consistently representing as multi-valued structure (array or dictionary) to make the structure easier to traverse in all cases. Specific fields and examples are included in review comments below.

[mitchelbaker-cisa]

Updated leastPermissions and poshModule keys to array type.

[buidav]

This applies to all of the JSON objects in this file. Do we know for sure that this works for dod?
We have this DoD diclaimer as we've never tested on a DoD tenant.

[mitchelbaker-cisa]

I think since we include DoD endpoints as a valid option for the M365Environment parameter across many commandlets, we keep references to dod for consistency purposes until a public-reported issue is received saying otherwise.

[buidav]

Connect-SPOService doesn't support Service Principal auth. This should be empty array.

[mitchelbaker-cisa]

A new property was added to indicate noninteractive permissions, "spRolePermissions": []. @buidav does that resolve your comment? Or are additional changes needed.

[MichaelHicks-MSFT]

Updated permissions file to reflect discussion last week. Unified keys across objects, renamed rolePermissions to spRolePermissions. Created singular objects for connect cmdlets to break out apiResource based on the environment.

[schrolla]

Updates addressed previous comments. Looks merge ready to me.

[buidav]

Items 1 - 4 were observed when attempting to use this JSON as the source of permissions for ScubaGear.

1. "RoleManagementPolicy.Read.Directory" was listed as a least permission. However ScubaGear does not use this permission.
   Does ScubaGear use something else not listed?

"moduleCmdlet": "Get-MgBetaPolicyRoleManagementPolicyAssignment",
 "CareSource": "/beta/policies/roleManagementPolicyAssignments",
        "poshModule": [
            "Microsoft.Graph.Beta.Identity.SignIns"
        ],
        "leastPermissions": [
            "RoleManagementPolicy.Read.Directory"
        ],
        "higherPermissions": [
            "RoleManagement.ReadWrite.Directory",
            "RoleManagement.Read.All",
            "RoleManagementPolicy.ReadWrite.Directory"
        ],

This JSON lists
RoleManagementPolicy.Read.Directory as least permissions for this cmdlet.

ScubaGear does not use any permissions in least Permissions or higher permissions listed here.

AI says Policy.Read,All is needed. ScubaGear does use Policy.Read.All but it's not enough for this cmdlet -1 for AI.
Graph explorer says RoleManagementPolicy.Read.Directory

Double checking with Ted
ScubaGear uses RoleManagment.Read.Directory which is NOT listed anywhere in the JSON. Either we have to modify ScubaGear's permissions or add RoleManagment.Read.Directory under the higherPermissions listed here.

---

2. "RoleManagement.Read.All" was listed as a least permission. However ScubaGear does not use this permission.
   Does ScubaGear use something else not listed?

Get-MgBetaRoleManagementDirectoryRoleAssignmentScheduleInstance

"apiResource": "/beta/roleManagement/directory/roleAssignmentScheduleInstances",
"poshModule": [
     "Microsoft.Graph.Beta.Identity.Governance"
 ],
     "leastPermissions": [
            "RoleAssignmentSchedule.Read.Directory"
      ],
        "higherPermissions": [
            "RoleAssignmentSchedule.ReadWrite.Directory",
            "RoleManagement.ReadWrite.Directory",
            "RoleManagement.Read.All",
            "RoleManagement.Read.Directory"
        ],

The JSON uses
"RoleAssignmentSchedule.Read.Directory"

With help from Ted. ScubaGear uses
"RoleManagement.Read.Directory"
We use the higher level permission which serves as the leastPermission in a different cmdlet.

---

3. "RoleEligibilitySchedule.Read.Directory" was listed as a least permission. However ScubaGear does not use this permission.
   Does ScubaGear use something else not listed?

Get-MgBetaRoleManagementDirectoryRoleEligibilityScheduleInstance

"moduleCmdlet": "Get-MgBetaRoleManagementDirectoryRoleEligibilityScheduleInstance",
"apiResource": "/beta/roleManagement/directory/roleEligibilityScheduleInstances",
"poshModule": [
            "Microsoft.Graph.Beta.Identity.Governance"
   ],
  "leastPermissions": [
            "RoleEligibilitySchedule.Read.Directory"
 ],
  "higherPermissions": [
      "RoleEligibilitySchedule.ReadWrite.Directory",
      "RoleManagement.Read.All",
      "RoleManagement.Read.Directory",
      "RoleManagement.ReadWrite.Directory"
],

With help from Ted.
ScubaGear uses RoleManagement.Read.Directory
We're using a higher level permission as it serves as a leastPermission in a another cmdlet.

---

4. "RoleManagementPolicy.Read.AzureADGroup" is NO where to be found in the JSON. Despite ScubaGear using the permission.

Not at all in the JSON and it's used as a permission within ScubaGear. Not sure which cmdlet throws the error but looks like something in our custom AAD provider functions. (I wish I took a screenshot someone will have to recreate the error)

This permission needs to be added to the JSON somewhere.

How does the helper function(s) account for these differences in permission sets between ScubaGear and the JSON?
Do we need to change ScubaGear's permissions or modify the JSON itself?
Those questions need can be answer later.
However, points 1 and 4 need to be addressed in this PR somehow.