|
| 1 | +function Grant-CippAppGraphConsent { |
| 2 | + <# |
| 3 | + .SYNOPSIS |
| 4 | + Ensures a tenant-wide (AllPrincipals) oauth2PermissionGrant exists from an app's service |
| 5 | + principal to Microsoft Graph, covering the given delegated scopes. |
| 6 | + .DESCRIPTION |
| 7 | + Admin-consents delegated Microsoft Graph scopes for an app registration in the partner |
| 8 | + tenant, so users signing in through it are not prompted to consent. Used to pre-consent |
| 9 | + the OIDC + offline_access scopes an MCP client (Copilot Studio, Claude, ChatGPT, VS Code) |
| 10 | + requests: without offline_access consent, Entra will not issue a refresh token and the |
| 11 | + client re-authenticates every time the access token expires (~hourly). |
| 12 | +
|
| 13 | + This matters most in tenants that disable user consent to applications (which CIPP's own |
| 14 | + OauthConsentLowSec standard recommends): there, an un-consented offline_access request |
| 15 | + silently yields no refresh token. Admin consent is the only reliable path. |
| 16 | +
|
| 17 | + Additive — existing consented scopes are preserved and only the missing ones are added. |
| 18 | + The service principal of a freshly created app is not always queryable immediately, so |
| 19 | + the client SP lookup retries briefly before giving up. |
| 20 | + .PARAMETER AppId |
| 21 | + Application (client) ID of the app whose service principal should receive the grant. |
| 22 | + .PARAMETER Scopes |
| 23 | + Delegated Microsoft Graph scope names to ensure are consented (e.g. openid, profile, |
| 24 | + offline_access). |
| 25 | + .FUNCTIONALITY |
| 26 | + Internal |
| 27 | + #> |
| 28 | + [CmdletBinding()] |
| 29 | + param( |
| 30 | + [Parameter(Mandatory)] |
| 31 | + [string]$AppId, |
| 32 | + |
| 33 | + [Parameter(Mandatory)] |
| 34 | + [string[]]$Scopes |
| 35 | + ) |
| 36 | + |
| 37 | + $GraphAppId = '00000003-0000-0000-c000-000000000000' |
| 38 | + |
| 39 | + # The app's own service principal may still be replicating right after creation. |
| 40 | + $ClientSp = $null |
| 41 | + for ($Attempt = 1; $Attempt -le 3 -and -not $ClientSp.id; $Attempt++) { |
| 42 | + try { |
| 43 | + $ClientSp = New-GraphGetRequest -uri "https://graph.microsoft.com/v1.0/servicePrincipals(appId='$AppId')?`$select=id" -NoAuthCheck $true -asapp $true |
| 44 | + } catch { |
| 45 | + Write-Information "[App-Consent] Service principal for $AppId not queryable yet (attempt $Attempt): $($_.Exception.Message)" |
| 46 | + } |
| 47 | + if (-not $ClientSp.id -and $Attempt -lt 3) { Start-Sleep -Seconds 2 } |
| 48 | + } |
| 49 | + if (-not $ClientSp.id) { |
| 50 | + throw "Service principal for app '$AppId' was not found; cannot write consent grant yet." |
| 51 | + } |
| 52 | + |
| 53 | + $GraphSp = New-GraphGetRequest -uri "https://graph.microsoft.com/v1.0/servicePrincipals(appId='$GraphAppId')?`$select=id" -NoAuthCheck $true -asapp $true |
| 54 | + if (-not $GraphSp.id) { |
| 55 | + throw 'Microsoft Graph service principal was not found in this tenant.' |
| 56 | + } |
| 57 | + |
| 58 | + $Grants = @(New-GraphGetRequest -uri "https://graph.microsoft.com/v1.0/servicePrincipals/$($ClientSp.id)/oauth2PermissionGrants" -NoAuthCheck $true -asapp $true) |
| 59 | + $TenantGrant = $Grants | Where-Object { $_.resourceId -eq $GraphSp.id -and $_.consentType -eq 'AllPrincipals' } | Select-Object -First 1 |
| 60 | + |
| 61 | + if ($TenantGrant) { |
| 62 | + $CurrentScopes = @($TenantGrant.scope -split ' ' | Where-Object { $_ }) |
| 63 | + $MissingScopes = @($Scopes | Where-Object { $_ -notin $CurrentScopes }) |
| 64 | + if ($MissingScopes.Count -eq 0) { |
| 65 | + return [PSCustomObject]@{ AppId = $AppId; Action = 'nochange'; Scopes = $CurrentScopes } |
| 66 | + } |
| 67 | + $MergedScopes = (@($CurrentScopes + $MissingScopes) | Sort-Object -Unique) -join ' ' |
| 68 | + $PatchBody = @{ scope = $MergedScopes } | ConvertTo-Json -Compress |
| 69 | + $null = New-GraphPOSTRequest -uri "https://graph.microsoft.com/v1.0/oauth2PermissionGrants/$($TenantGrant.id)" -body $PatchBody -type PATCH -NoAuthCheck $true -asapp $true |
| 70 | + return [PSCustomObject]@{ AppId = $AppId; Action = 'updated'; Scopes = @($MergedScopes -split ' ') } |
| 71 | + } |
| 72 | + |
| 73 | + $CreateBody = @{ |
| 74 | + clientId = $ClientSp.id |
| 75 | + consentType = 'AllPrincipals' |
| 76 | + resourceId = $GraphSp.id |
| 77 | + scope = ($Scopes -join ' ') |
| 78 | + } | ConvertTo-Json -Compress |
| 79 | + $null = New-GraphPOSTRequest -uri 'https://graph.microsoft.com/v1.0/oauth2PermissionGrants' -body $CreateBody -type POST -NoAuthCheck $true -asapp $true |
| 80 | + return [PSCustomObject]@{ AppId = $AppId; Action = 'created'; Scopes = @($Scopes) } |
| 81 | +} |
0 commit comments