Share via


使用 PowerShell 管理 Azure Stack Hub 中的金鑰保存庫

本文說明如何使用 PowerShell 在 Azure Stack Hub 中建立和管理金鑰保存庫。 您將了解如何使用金鑰保存庫 PowerShell Cmdlet:

  • 建立金鑰保存庫。
  • 儲存及管理密碼編譯金鑰和密碼。
  • 授權使用者或應用程式叫用保存庫中的作業。

注意

本文中所述的金鑰保存庫 PowerShell Cmdlet 會隨附於 Azure PowerShell SDK 中。

Prerequisites

針對金鑰保存庫作業啟用您的租用戶訂用帳戶

在您可以對金鑰保存庫進行任何作業之前,必須先確保已針對保存庫作業啟用您的租用戶訂用帳戶。 若要確認金鑰保存庫作業已啟用,執行以下命令:

Get-AzResourceProvider -ProviderNamespace Microsoft.KeyVault | ft -Autosize

若已針對保存庫作業啟用訂用帳戶,在針對金鑰保存庫之所有資源類型的輸出中,[RegistrationState] 都會顯示為 [Registered] 。

Powershell 中的金鑰保存庫註冊狀態

如果尚未啟用作業,使用下列命令來註冊訂用帳戶中的金鑰保存庫服務:

Register-AzResourceProvider -ProviderNamespace Microsoft.KeyVault

如果註冊成功,會傳回下列輸出:

Powershell 中的金鑰保存庫註冊成功

當您叫用金鑰保存庫命令時,可能會遇到錯誤,例如「未註冊訂用帳戶,無法使用命名空間 'Microsoft.KeyVault'」。如果您遇到錯誤,請確認您已依照先前所述的指示啟用 Key Vault 資源提供者。

建立金鑰保存庫

建立金鑰保存庫之前,先建立資源群組,使所有與金鑰保存庫相關的資源都存在於資源群組中。 請使用下列命令以建立新的資源群組:

New-AzResourceGroup -Name "VaultRG" -Location local -verbose -Force

在 Powershell 中產生的新資源群組

現在,使用下列 Cmdlet 以在稍早所建立的資源群組中建立金鑰保存庫。 這個命令會讀取三個必要參數:資源群組名稱、金鑰保存庫名稱、地理位置。

請執行下列命令以建立金鑰保存庫:

New-AzKeyVault -VaultName "Vault01" -ResourceGroupName "VaultRG" -Location local -verbose

在 Powershell 中產生的新金鑰保存庫

此命令的輸出會顯示您所建立的金鑰保存庫屬性。 應用程式存取此保存庫時,它必須使用 [保存庫 URI] 屬性,在此範例中為 https://vault01.vault.local.azurestack.external

Active Directory 同盟服務 (AD FS) 部署

在 AD FS 部署中,您可能會收到這個警告:「未設定存取原則。 使用者或應用程式沒有使用此保存庫的存取權限。」若要解決此問題,請使用 Set-AzKeyVaultAccessPolicy 命令來設定保存庫的存取原則:

# Obtain the security identifier(SID) of the active directory user
$adUser = Get-ADUser -Filter "Name -eq '{Active directory user name}'"
$objectSID = $adUser.SID.Value

# Set the key vault access policy
Set-AzKeyVaultAccessPolicy -VaultName "{key vault name}" -ResourceGroupName "{resource group name}" -ObjectId "{object SID}" -PermissionsToKeys {permissionsToKeys} -PermissionsToSecrets {permissionsToSecrets} -BypassObjectIdValidation

管理金鑰和祕密

在您建立保存庫之後,請使用這些步驟來建立並管理保存庫中的金鑰和祕密。

建立金鑰

使用 Add-AzureKeyVaultKey Cmdlet,在金鑰保存庫中建立或匯入受到軟體保護的金鑰:

Add-AzureKeyVaultKey -VaultName "Vault01" -Name "Key01" -verbose -Destination Software

-Destination 參數是用來指定金鑰已受到軟體保護。 成功建立金鑰時,命令會輸出所建立金鑰的詳細資料。

在 Powershell 中產生的新金鑰保存庫金鑰

您現在可以使用其 URI 參考建立的金鑰。 如果您建立或匯入與現有金鑰名稱相同的金鑰,就會以新金鑰中指定的值來更新原始金鑰。 您可以使用金鑰的版本特定 URI 來存取先前的版本。 例如:

  • 使用 https://vault10.vault.local.azurestack.external:443/keys/key01 以一律可取得最新版本。
  • 使用 https://vault010.vault.local.azurestack.external:443/keys/key01/d0b36ee2e3d14e9f967b8b6b1d38938a 以取得此特定版本。

取得金鑰

使用 Get AzureKeyVaultKey Cmdlet 以讀取金鑰及其詳細資料:

Get-AzureKeyVaultKey -VaultName "Vault01" -Name "Key01"

建立祕密

使用 Set-AzureKeyVaultSecret Cmdlet 以建立或更新保存庫中的祕密。 如果祕密尚不存在,系統便會建立一個。 如果已經存在,則會建立新版本的密碼:

$secretvalue = ConvertTo-SecureString "User@123" -AsPlainText -Force
Set-AzureKeyVaultSecret -VaultName "Vault01" -Name "Secret01" -SecretValue $secretvalue

在 Powershell 中建立秘密

取得祕密

使用 Get-AzureKeyVaultSecret Cmdlet 以讀取金鑰保存庫中的祕密。 此命令可傳回所有或特定版本的祕密:

Get-AzureKeyVaultSecret -VaultName "Vault01" -Name "Secret01"

建立金鑰和祕密之後,可以授權讓外部應用程式使用它們。

授權應用程式使用金鑰或祕密

使用下列 Cmdlet 來授權應用程式存取金鑰保存庫中的金鑰或密碼。

在以下範例中,保存庫名稱是 ContosoKeyVault,且您想要授權的應用程式用戶端識別碼是 8f8c4bbd-485b-45fd-98f7-ec6300b7b4ed。 若要授權應用程式,請執行下列命令。 您也可以指定 PermissionsToKeys 參數來設定使用者、應用程式或安全性群組的權限。

對已設定 ADFS 的 Azure Stack Hub 環境使用 Cmdlet 時,應提供 BypassObjectIdValidation 參數

Set-AzKeyVaultAccessPolicy -VaultName 'ContosoKeyVault' -ServicePrincipalName 8f8c4bbd-485b-45fd-98f7-ec6300b7b4ed -PermissionsToKeys decrypt,sign -BypassObjectIdValidation

如果您想要授權該相同的應用程式讀取您保存庫中的祕密,請執行以下 Cmdlet:

Set-AzKeyVaultAccessPolicy -VaultName 'ContosoKeyVault' -ServicePrincipalName 8f8c4bbd-485b-45fd-98f7-ec6300 -PermissionsToKeys Get -BypassObjectIdValidation

後續步驟