共用方式為

使用 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

後續步驟