Get-AzKeyVaultSecret在PowerShell函数中执行时脚本挂起问题

问题描述 #

我有一个.psm1模块文件，包含run.ps1脚本的若干辅助函数。其中一个函数调用Azure Key Vault获取连接密钥时，run.ps1脚本出现挂起现象：已配置托管标识且其拥有密钥库访问权限，执行时会收到访问密钥的[警告]信息，但脚本在此处完全停止，无错误输出。

将该段代码直接复制到run.ps1顶部可正常运行，可运行的代码片段如下：

$applicationId = 'abc123'
$securePassword = Get-AzKeyVaultSecret -VaultName "KV-SANDBOX" -Name "ConnectionSecret"
$credential = New-Object -TypeName System.Management.Automation.PSCredential -ArgumentList $applicationId, $securePassword.SecretValue

Connect-PowerBIServiceAccount  -ServicePrincipal -Credential $credential -TenantId 'a1b2c3'

已尝试的操作：

• 本地运行脚本正常；
• 点源.ps1文件中的函数时出现问题；
• 将函数放入\Modules\文件夹下的.psm1文件时出现问题；
• 将函数代码直接复制到run.ps1中可正常运行。

怀疑是作用域问题，但未找到相关资料。

可能的原因与解决方法 #

1. 模块作用域未完整加载Az.KeyVault依赖 #

模块默认运行在独立作用域，可能未加载Az.KeyVault的全部组件，导致Get-AzKeyVaultSecret在无人值守环境中等待隐式交互输入（比如权限确认），表现为脚本挂起。

解决方法：在.psm1文件顶部显式导入Az.KeyVault模块，强制加载完整组件：

# 放在.psm1文件最开头
Import-Module Az.KeyVault -Force -AllowClobber

2. 托管标识身份上下文未在模块作用域继承 #

脚本顶层作用域中已初始化托管标识的身份上下文，但模块作用域无法继承该上下文，导致Get-AzKeyVaultSecret在尝试获取身份验证令牌时挂起。

解决方法：在模块函数中显式通过元数据服务获取托管标识令牌，直接调用密钥库API获取密钥：

function Get-ConnectionSecret {
    param(
        [string]$VaultName = "KV-SANDBOX",
        [string]$SecretName = "ConnectionSecret"
    )
    # 获取托管标识访问令牌
    $tokenEndpoint = "http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01&resource=https%3A%2F%2Fvault.azure.net"
    $token = Invoke-RestMethod -Uri $tokenEndpoint -Headers @{Metadata = "true"}
    # 调用密钥库API获取密钥
    $secretUri = "https://$VaultName.vault.azure.net/secrets/$SecretName/?api-version=7.4"
    $secretResponse = Invoke-RestMethod -Uri $secretUri -Headers @{Authorization = "Bearer $($token.access_token)"}
    # 转换为SecureString
    return ConvertTo-SecureString $secretResponse.value -AsPlainText -Force
}

3. 函数依赖全局作用域变量导致挂起 #

如果模块函数依赖全局作用域的变量（如$applicationId、$TenantId），而这些变量在模块作用域中未定义，可能导致后续Connect-PowerBIServiceAccount隐式等待输入，表现为整体挂起。

解决方法：将所有依赖项通过参数传递给函数，避免依赖全局变量：

function Connect-PowerBIWithManagedIdentity {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory=$true)]
        [string]$ApplicationId,
        [Parameter(Mandatory=$true)]
        [string]$VaultName,
        [Parameter(Mandatory=$true)]
        [string]$SecretName,
        [Parameter(Mandatory=$true)]
        [string]$TenantId
    )
    # 确保模块加载
    Import-Module Az.KeyVault -Force -AllowClobber
    # 获取密钥并创建凭据
    $securePassword = Get-AzKeyVaultSecret -VaultName $VaultName -Name $SecretName
    $credential = New-Object System.Management.Automation.PSCredential -ArgumentList $ApplicationId, $securePassword.SecretValue
    # 连接PowerBI服务
    Connect-PowerBIServiceAccount -ServicePrincipal -Credential $credential -TenantId $TenantId
}

4. 启用调试定位挂起点 #

通过添加调试输出和启用PowerShell调试模式，明确挂起发生的具体位置：

操作步骤：

• 在模块函数中添加调试输出：

function Your-ModuleFunction {
    Write-Host "Entering function: Your-ModuleFunction"
    Write-Host "Attempting to retrieve secret from KV-SANDBOX..."
    $securePassword = Get-AzKeyVaultSecret -VaultName "KV-SANDBOX" -Name "ConnectionSecret"
    Write-Host "Secret retrieved successfully"
    # 后续代码
}

• 在run.ps1中启用跟踪调试：

Set-PSDebug -Trace 2
.\run.ps1

内容的提问来源于stack exchange，提问作者James