(GHA) Update the auth action to accept an allowlist (#12181)

Prior to this change, the verification/`authorization` GitHub Action
only supported checking the assigned permissions for a user. This
worked for normal accounts. However, the managed bot account for the
Learn platform doesn't have permissions for this repository.

This change adds a new (backwards-compatible) `authorized_accounts`
parameter to the GHA. Repository maintainers can now define an
allowlist to use for authorization in addition to the permissions
to check. If a user is explicitly in the allowlist, the action skips
checking their permissions. If a user isn't in the allowlist, they
can still pass authorization if they have matching permissions.

Author: michaeltlombardi

.github/actions/.pwsh/scripts/Test-Authorization.ps1

@@ -69,7 +69,8 @@ param(
   [Parameter(Mandatory, ParameterSetName='Path')]
   [string[]]$TargetPath,
   [ValidateSet('Admin', 'Maintain', 'Pull', 'Push', 'Triage')]
-  [string[]]$ValidPermissions = @('Admin', 'Maintain')
+  [string[]]$ValidPermissions = @('Admin', 'Maintain'),
+  [string[]]$AuthorizedAccounts
 )
 
 begin {
@@ -101,6 +102,10 @@ begin {
       Console = Format-ConsoleStyle -Text $User -DefinedStyle UserName
       Markdown = "``$User``"
     }
+    AuthorizedAccounts = @{
+      Console = Format-ConsoleStyle -Text 'AuthorizedAccounts' -DefinedStyle Success
+      Markdown = '`AuthorizedAccounts`'
+    }
   }
   if (![string]::IsNullOrEmpty($TargetBranch)) {
     $ConsoleBranch = Format-ConsoleStyle -Text $TargetBranch -StyleComponent $TargetStyle
@@ -123,6 +128,19 @@ begin {
 }
 
 process {
+  if ($AuthorizedAccounts.Count -gt 0 -and $User -in $AuthorizedAccounts) {
+    $template = "Account {0} is explicitly permitted per the {1} parameter."
+    $message  = @{
+      summary = ($template -f $Texts.Author.Markdown, $Texts.AuthorizedAccounts.Markdown)
+      console = ($template -f $Texts.Author.Console,  $Texts.AuthorizedAccounts.Console)
+    }
+    $null = $Summary.AppendLine('## Authorization').AppendLine()
+    $null = $Summary.AppendLine($message.summary).AppendLine()
+    # Console Logging
+    $message.console
+
+    return
+  }
   try {
     $Permissions = Get-AuthorPermission -Owner $Owner -Repo $Repo -Author $User
   } catch {
@@ -149,7 +167,7 @@ process {
     "$Prefix`t$Setting"
   }
   #endregion Permission Retrieval Messaging
-  
+
   $null = $Summary.AppendLine('## Result').AppendLine()
 
   # Check for authorization; if the user has any of the valid permissions, they

.github/actions/verification/authorization/v1/Parameters.psd1

@@ -29,6 +29,25 @@
         return $Parameters
       }
     }
+    @{
+      Name = 'AuthorizedAccounts'
+      Type = 'String[]'
+      IfNullOrEmpty = {
+          param($ErrorTarget)
+
+          # This parameter is optional, so don't error.
+      }
+      Process = {
+        param($Parameters, $Value, $ErrorTarget)
+
+        [string[]]$SpecifiedAccounts = $Value -split ','
+        if ($SpecifiedAccounts.Count -gt 0) {
+          $Parameters.AuthorizedAccounts = $SpecifiedAccounts
+          Write-HostParameter -Name AuthorizedAccounts -Value $Parameters.AuthorizedAccounts
+        }
+        return $Parameters
+      }
+    }
 
     @{
       Name = 'Permissions'

.github/actions/verification/authorization/v1/action.yml

@@ -4,6 +4,16 @@ description: |
   branch of a repository or to submit a PR editing repo configuration.
 author: PowerShell Docs Team
 inputs:
+  authorized_accounts:
+    description: |
+      Defines one or more authorized accounts to skip permission-checking for. This is best used
+      for bot accounts, which may not have specific permissions to a repository but are used by
+      the organization's automation. Must be a comma-separated string of account names.
+
+      If a user is in the authorized accounts list, the action skips checking permissions and
+      passes for that user.
+    required: false
+    default: ''
   permissions:
     description: |
       The permissions a user requires to perform a given task. Must be a comma-separated string of
@@ -84,6 +94,7 @@ runs:
         INPUT_PERMISSIONS: ${{ inputs.permissions }}
         INPUT_TARGET: ${{ inputs.target }}
         INPUT_USER: ${{ inputs.user }}
+        INPUT_AUTHORIZED_ACCOUNTS: ${{ inputs.authorized_accounts }}
         GITHUB_TOKEN: ${{ inputs.token }}
       run: |
         Write-Output "::group::Generic Setup"

.github/actions/verification/authorization/v1/readme.md

@@ -54,14 +54,18 @@ jobs:
         uses: MicrosoftDocs/PowerShell-Docs/.github/actions/verification/authorization/v1@main
         with:
           token: ${{ github.token }}
+          authorized_accounts: 'learn-build-service-prod[bot]'
 ```
 
 This workflow uses the `pull_request_target` trigger to check whether a Pull Request author is
 permitted to submit their Pull Request to the `live` branch. It only runs on Pull Requests which
 target the `live` branch, so other Pull Requests don't get a skipped message for this check.
 
 It passes the GitHub token to the action but does not specify a target, relying on the default for
-that input, which is the `live` branch.
+that input, which is the `live` branch. It does specify that the `learn-build-service-prod[bot]`
+managed account is authorized with the `authorized_accounts` parameter. If the account creating a
+PR to the `live` branch is the managed account or has either the `Maintain` or `Admin` permission,
+the workflow will pass.
 
 ### Verifying authorization to change sensitive files
 
@@ -104,6 +108,21 @@ authorization to change files in those paths.
 
 ## Inputs
 
+### `authorized_accounts`
+
+Defines one or more authorized accounts to skip permission-checking for. This is best used for bot
+accounts, which may not have specific permissions to a repository but are used by the
+organization's automation. Must be a comma-separated string of account names.
+
+If a user is in the authorized accounts list, the action skips checking permissions and passes for
+that user.
+
+```yaml
+required : false
+type     : string
+default  : ''
+```
+
 ### `permissions`
 
 The permissions a user requires to perform a given task. Must be a comma-separated string of valid

.github/workflows/targeting-valid-branch.yml

@@ -23,3 +23,4 @@ jobs:
         uses: ./.github/actions/verification/authorization/v1
         with:
           token: ${{ github.token }}
+          authorized_accounts: learn-build-service-prod[bot]