New-CertKitAppProxyIdentity.ps1
|
<#PSScriptInfo .VERSION 1.3 .GUID a9e0f308-5a4c-4ee6-a6f9-452dc867ee72 .AUTHOR Richard Hicks .COMPANYNAME Richard M. Hicks Consulting, Inc. .COPYRIGHT Copyright (C) 2026 Richard M. Hicks Consulting, Inc. All Rights Reserved. .LICENSE Licensed under the MIT License. See LICENSE file in the project root for full license information. .LICENSEURI https://github.com/richardhicks/certkit/blob/main/LICENSE .PROJECTURI https://github.com/richardhicks/certkit .TAGS CertKit, Entra, EntraID, AppProxy, ApplicationProxy, Certificate, TLS, SSL, MicrosoftGraph, Graph, ServicePrincipal, PIM, LeastPrivilege #> <# .SYNOPSIS Creates a least-privilege Microsoft Entra identity for CertKit to deploy TLS certificates to Entra Application Proxy applications. .DESCRIPTION This script creates everything CertKit needs to deploy certificates to Microsoft Entra Application Proxy applications using client secret authentication, following least privilege. - A dedicated app registration and service principal for CertKit. - A custom Entra role that can only read Application Proxy settings and update the Application Proxy SSL certificate. - The read-only Microsoft Graph application permission Application.Read.All, used by CertKit to find App Proxy applications. - A tenant-wide assignment of the custom role to the CertKit service principal, made directly or through Privileged Identity Management (PIM). - A client secret, which is copied to the clipboard and never displayed on screen. The script is safe to run more than once. Existing objects with the same names are reused, and existing role and permission assignments are not duplicated. A new client secret is created on every run. Use -RemoveExistingSecrets to remove older client secrets after the new one is created. .PARAMETER TenantId The tenant ID (GUID) or a verified domain name of the Microsoft Entra tenant to configure. Optional. If omitted, the script uses the tenant of the account you sign in with. Specify this parameter when your account has access to more than one tenant, such as a guest account in a customer tenant, or when the PowerShell session is already connected to Microsoft Graph in another tenant. .PARAMETER DisplayName The display name of the CertKit app registration. The default is 'CertKit App Proxy Deployment'. .PARAMETER RoleName The display name of the custom Entra role. The default is 'App Proxy Certificate Manager'. .PARAMETER SecretExpirationMonths The lifetime of the client secret in months, from 1 to 24. The default is 12. .PARAMETER UsePim Assigns the custom role through Privileged Identity Management (PIM) as a permanent active assignment. Requires Microsoft Entra ID P2 or Microsoft Entra ID Governance. Without this switch, the role is assigned directly. When the custom role is newly created, PIM can take several minutes to recognize it, and the script waits up to 10 minutes. .PARAMETER RemoveExistingSecrets Removes all other client secrets from the app registration after the new client secret is created. Use this when rotating the secret or replacing a secret that was lost. CertKit can't authenticate with a removed secret, so update CertKit with the new secret right away. Without this switch, existing secrets are kept and the script reports how many remain. .EXAMPLE .\New-CertKitAppProxyIdentity.ps1 Creates the CertKit identity with the default names and a 12-month client secret, and assigns the custom role directly. .EXAMPLE .\New-CertKitAppProxyIdentity.ps1 -UsePim -SecretExpirationMonths 6 Creates the CertKit identity with a 6-month client secret, and assigns the custom role through PIM. .EXAMPLE .\New-CertKitAppProxyIdentity.ps1 -TenantId contoso.onmicrosoft.com Signs in to the contoso.onmicrosoft.com tenant and creates the CertKit identity there, regardless of the account's home tenant. .EXAMPLE .\New-CertKitAppProxyIdentity.ps1 -RemoveExistingSecrets Creates a new client secret for the existing CertKit identity and removes all older client secrets. .INPUTS None. .OUTPUTS System.Management.Automation.PSCustomObject .LINK https://directaccess.richardhicks.com/ .NOTES Version: 1.3 Creation Date: November 14, 2026 Last Updated: November 14, 2026 Author: Richard Hicks Organization: Richard M. Hicks Consulting, Inc. Contact: rich@richardhicks.com Website: https://www.richardhicks.com/ Requirements: - Microsoft Entra ID P1 or higher (required for Application Proxy and custom roles). - The Microsoft.Graph.Authentication PowerShell module. - An account with at least the Privileged Role Administrator role. #> #Requires -Version 5.1 #Requires -Modules @{ ModuleName = 'Microsoft.Graph.Authentication'; ModuleVersion = '2.0.0' } [CmdletBinding(SupportsShouldProcess)] Param ( [string]$TenantId, [string]$DisplayName = 'CertKit App Proxy Deployment', [string]$RoleName = 'App Proxy Certificate Manager', [ValidateRange(1, 24)] [int]$SecretExpirationMonths = 12, [switch]$UsePim, [switch]$RemoveExistingSecrets ) #Region Logging # Start transcript, including -WhatIf runs $LogPath = Join-Path -Path $env:ProgramData -ChildPath 'RMHCI\PowerShell' $LogFile = Join-Path -Path $LogPath -ChildPath "New-CertKitAppProxyIdentity_$(Get-Date -Format 'yyyyMMdd-HHmmss').log" If (-not (Test-Path -Path $LogPath)) { New-Item -Path $LogPath -ItemType Directory -Force -WhatIf:$false -Confirm:$false | Out-Null } Start-Transcript -Path $LogFile -WhatIf:$false -Confirm:$false | Out-Null $ExitCode = 0 #EndRegion # Retry Graph requests that can fail while new objects replicate across Entra ID Function Invoke-GraphRequestWithRetry { [CmdletBinding()] Param ( [Parameter(Mandatory)] [hashtable]$Request, [int]$MaxAttempts = 6, [int]$DelaySeconds = 10 ) For ($Attempt = 1; $Attempt -le $MaxAttempts; $Attempt++) { Try { Return Invoke-MgGraphRequest @Request -ErrorAction Stop } Catch { # Retry only errors caused by replication delay, throttling, or service faults. Fail fast on anything else $StatusCode = $null If ($_.Exception.Response) { $StatusCode = [int]$_.Exception.Response.StatusCode } $ErrorText = "$($_.ErrorDetails.Message) $($_.Exception.Message)" $IsTransient = ($null -eq $StatusCode) -or ($StatusCode -in 404, 408, 429) -or ($StatusCode -ge 500) -or ($StatusCode -eq 400 -and $ErrorText -match 'not ?found|does ?not ?exist|does not reference a valid') If (-not $IsTransient -or $Attempt -eq $MaxAttempts) { Throw } Write-Verbose "Request failed with status $StatusCode (attempt $Attempt of $MaxAttempts). Retrying in $DelaySeconds seconds..." Start-Sleep -Seconds $DelaySeconds } } } Try { $GraphUri = 'https://graph.microsoft.com/v1.0' # Application Proxy permissions granted by the custom role $RolePermissions = @( 'microsoft.directory/applications/applicationProxy/read' 'microsoft.directory/applications/applicationProxySslCertificate/update' 'microsoft.directory/connectorGroups/allProperties/read' ) # Connect to Microsoft Graph Write-Verbose 'Connecting to Microsoft Graph...' $ConnectParams = @{ Scopes = 'Application.ReadWrite.All', 'AppRoleAssignment.ReadWrite.All', 'RoleManagement.ReadWrite.Directory' NoWelcome = $true ErrorAction = 'Stop' } # Sign in to a specific tenant when one is specified If ($TenantId) { $ConnectParams['TenantId'] = $TenantId } Connect-MgGraph @ConnectParams $TenantId = (Get-MgContext).TenantId # Display the connected tenant so it's clear where objects will be created Try { $TenantName = (Invoke-MgGraphRequest -Method GET -Uri "$GraphUri/organization?`$select=displayName" -ErrorAction Stop).value[0].displayName } Catch { $TenantName = 'Unknown' } Write-Information "Connected to tenant '$TenantName' ($TenantId)." -InformationAction Continue # Build OData filters with apostrophes doubled and the expression URL-encoded, so any display name is safe $RoleFilter = [uri]::EscapeDataString("displayName eq '$($RoleName -replace "'", "''")'") $AppFilter = [uri]::EscapeDataString("displayName eq '$($DisplayName -replace "'", "''")'") # Create or reuse the custom role. Never reuse a built-in role with the same name $RoleCreated = $false $MatchingRoles = @((Invoke-MgGraphRequest -Method GET -Uri "$GraphUri/roleManagement/directory/roleDefinitions?`$filter=$RoleFilter" -ErrorAction Stop).value) If ($MatchingRoles | Where-Object { $_.isBuiltIn }) { Throw "'$RoleName' is the name of a built-in Entra role. Specify a different name with -RoleName." } $Role = $MatchingRoles | Select-Object -First 1 If ($Role) { Write-Verbose "Using existing custom role '$RoleName' ($($Role.id))." } ElseIf ($PSCmdlet.ShouldProcess($RoleName, 'Create custom Entra role')) { $RoleBody = @{ displayName = $RoleName description = 'Can read Application Proxy settings and update the Application Proxy SSL certificate. Used by CertKit.' isEnabled = $true rolePermissions = @(@{ allowedResourceActions = $RolePermissions }) } $Role = Invoke-MgGraphRequest -Method POST -Uri "$GraphUri/roleManagement/directory/roleDefinitions" -Body $RoleBody -ErrorAction Stop $RoleCreated = $true Write-Verbose "Created custom role '$RoleName' ($($Role.id))." } # Create or reuse the app registration $App = (Invoke-MgGraphRequest -Method GET -Uri "$GraphUri/applications?`$filter=$AppFilter" -ErrorAction Stop).value | Select-Object -First 1 If ($App) { Write-Verbose "Using existing app registration '$DisplayName' ($($App.appId))." } ElseIf ($PSCmdlet.ShouldProcess($DisplayName, 'Create app registration')) { $AppBody = @{ displayName = $DisplayName signInAudience = 'AzureADMyOrg' } $App = Invoke-MgGraphRequest -Method POST -Uri "$GraphUri/applications" -Body $AppBody -ErrorAction Stop Write-Verbose "Created app registration '$DisplayName' ($($App.appId))." } # Create or reuse the service principal $Sp = (Invoke-MgGraphRequest -Method GET -Uri "$GraphUri/servicePrincipals?`$filter=appId eq '$($App.appId)'" -ErrorAction Stop).value | Select-Object -First 1 If ($Sp) { Write-Verbose "Using existing service principal ($($Sp.id))." } ElseIf ($PSCmdlet.ShouldProcess($DisplayName, 'Create service principal')) { $SpRequest = @{ Method = 'POST' Uri = "$GraphUri/servicePrincipals" Body = @{ appId = $App.appId } } $Sp = Invoke-GraphRequestWithRetry -Request $SpRequest Write-Verbose "Created service principal ($($Sp.id))." } # Grant the read-only Microsoft Graph application permission Application.Read.All $GraphSp = (Invoke-MgGraphRequest -Method GET -Uri "$GraphUri/servicePrincipals?`$filter=appId eq '00000003-0000-0000-c000-000000000000'&`$select=id,appRoles" -ErrorAction Stop).value[0] $AppRoleId = ($GraphSp.appRoles | Where-Object { $_.value -eq 'Application.Read.All' -and $_.allowedMemberTypes -contains 'Application' }).id # With -WhatIf, a service principal that doesn't exist yet has no grants to look up $ExistingGrant = $null If ($Sp) { $ExistingGrant = (Invoke-MgGraphRequest -Method GET -Uri "$GraphUri/servicePrincipals/$($Sp.id)/appRoleAssignments" -ErrorAction Stop).value | Where-Object { $_.appRoleId -eq $AppRoleId } } If ($ExistingGrant) { Write-Verbose 'Application.Read.All is already granted.' } ElseIf ($PSCmdlet.ShouldProcess($DisplayName, 'Grant Microsoft Graph application permission Application.Read.All')) { $GrantRequest = @{ Method = 'POST' Uri = "$GraphUri/servicePrincipals/$($Sp.id)/appRoleAssignments" Body = @{ principalId = $Sp.id; resourceId = $GraphSp.id; appRoleId = $AppRoleId } } Invoke-GraphRequestWithRetry -Request $GrantRequest | Out-Null Write-Verbose 'Granted Application.Read.All.' } # Assign the custom role tenant-wide, directly or through PIM # With -WhatIf, a service principal or role that doesn't exist yet has no assignments to look up $ExistingAssignment = $null $RoleAssigned = 'Not assigned' If ($Sp -and $Role) { $ExistingAssignment = (Invoke-MgGraphRequest -Method GET -Uri "$GraphUri/roleManagement/directory/roleAssignments?`$filter=principalId eq '$($Sp.id)' and roleDefinitionId eq '$($Role.id)'" -ErrorAction Stop).value } If ($ExistingAssignment) { $RoleAssigned = 'Already assigned' Write-Verbose "The '$RoleName' role is already assigned." } ElseIf ($UsePim) { If ($PSCmdlet.ShouldProcess($DisplayName, "Assign '$RoleName' role through PIM")) { $PimRequest = @{ Method = 'POST' Uri = "$GraphUri/roleManagement/directory/roleAssignmentScheduleRequests" Body = @{ action = 'adminAssign' justification = 'CertKit certificate deployment to Entra Application Proxy' roleDefinitionId = $Role.id directoryScopeId = '/' principalId = $Sp.id scheduleInfo = @{ startDateTime = (Get-Date).ToUniversalTime().ToString('o') expiration = @{ type = 'noExpiration' } } } } # PIM can take several minutes to recognize a newly created custom role, so allow up to 10 minutes If ($RoleCreated) { Write-Information 'Waiting for PIM to recognize the new custom role. This can take several minutes...' -InformationAction Continue } Invoke-GraphRequestWithRetry -Request $PimRequest -MaxAttempts 60 | Out-Null $RoleAssigned = 'Through PIM' Write-Verbose "Assigned the '$RoleName' role through PIM." } } ElseIf ($PSCmdlet.ShouldProcess($DisplayName, "Assign '$RoleName' role")) { $AssignmentRequest = @{ Method = 'POST' Uri = "$GraphUri/roleManagement/directory/roleAssignments" Body = @{ '@odata.type' = '#microsoft.graph.unifiedRoleAssignment' roleDefinitionId = $Role.id principalId = $Sp.id directoryScopeId = '/' } } Invoke-GraphRequestWithRetry -Request $AssignmentRequest | Out-Null $RoleAssigned = 'Directly' Write-Verbose "Assigned the '$RoleName' role." } # Create a client secret and copy it to the clipboard $NewSecretKeyId = $null $SecretExpires = (Get-Date).AddMonths($SecretExpirationMonths) If ($PSCmdlet.ShouldProcess($DisplayName, "Create client secret expiring $($SecretExpires.ToString('d'))")) { $SecretBody = @{ passwordCredential = @{ displayName = 'CertKit' endDateTime = $SecretExpires.ToUniversalTime().ToString('o') } } $Secret = Invoke-MgGraphRequest -Method POST -Uri "$GraphUri/applications/$($App.id)/addPassword" -Body $SecretBody -ErrorAction Stop $NewSecretKeyId = $Secret.keyId $Secret.secretText | Set-Clipboard Remove-Variable -Name Secret Write-Warning 'The client secret was copied to the clipboard. Paste it into CertKit now, then clear the clipboard with Set-Clipboard -Value $null.' } # Remove older client secrets, or report how many remain $SecretsRemoved = 0 If ($App.id) { $OldSecrets = @((Invoke-MgGraphRequest -Method GET -Uri "$GraphUri/applications/$($App.id)?`$select=passwordCredentials" -ErrorAction Stop).passwordCredentials | Where-Object { $_.keyId -ne $NewSecretKeyId }) # Remove older secrets only after a new secret was successfully created If ($OldSecrets.Count -gt 0 -and $RemoveExistingSecrets -and $NewSecretKeyId) { ForEach ($OldSecret in $OldSecrets) { If ($PSCmdlet.ShouldProcess($DisplayName, "Remove client secret '$($OldSecret.displayName)' ($($OldSecret.hint)***), expiring $(([datetime]$OldSecret.endDateTime).ToString('d'))")) { Invoke-MgGraphRequest -Method POST -Uri "$GraphUri/applications/$($App.id)/removePassword" -Body @{ keyId = $OldSecret.keyId } -ErrorAction Stop $SecretsRemoved++ Write-Verbose "Removed client secret $($OldSecret.keyId)." } } } ElseIf ($OldSecrets.Count -gt 0) { Write-Warning "The app registration has $($OldSecrets.Count) older client secret(s). Once CertKit is using the new secret, delete them on the app registration's Certificates & secrets page in the Entra admin center. Running this script again with -RemoveExistingSecrets would also remove the secret CertKit is now using." } } # Output the values CertKit needs [PSCustomObject]@{ TenantName = $TenantName TenantId = $TenantId ClientId = $App.appId SecretExpires = $SecretExpires CustomRole = $RoleName RoleAssigned = $RoleAssigned OldSecretsRemoved = $SecretsRemoved } } Catch { # Record the error in the transcript before logging stops $ErrorActionPreference = 'Continue' Write-Error -ErrorRecord $_ $ExitCode = 1 } Finally { Stop-Transcript | Out-Null } If ($ExitCode -ne 0) { Exit $ExitCode } |