Administración de Key Vault en Azure Stack Hub mediante PowerShell

  • Artículo

En este artículo se describe cómo crear y administrar un almacén de claves en Azure Stack Hub con PowerShell. Aprenda a usar los cmdlets de PowerShell en Key Vault para:

  • Cree un almacén de claves.
  • Almacenar y administrar claves criptográficas y secretos.
  • Autorizar a los usuarios o a las aplicaciones a invocar operaciones en el almacén.

Nota:

Los cmdlets de PowerShell para Key Vault que se describen en este artículo se ofrecen como parte del SDK de Azure PowerShell.

Prerrequisitos

Habilitación de la suscripción de inquilino para operaciones de Key Vault

Para poder emitir cualquier operación en un almacén de claves, debe asegurarse de que su suscripción de inquilino esté habilitada para operaciones de almacén. Para verificar si están habilitadas las operaciones de almacén de claves, ejecute el siguiente comando:

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

Si la suscripción está habilitada para operaciones de almacén, la salida muestra el valor Registrado para RegistrationState para todos los tipos de recursos de un almacén de claves.

Estado de registro de almacén de claves en Powershell

Si las operaciones de almacén no están habilitadas, emita el comando siguiente para registrar el servicio Key Vault en su suscripción:

Register-AzResourceProvider -ProviderNamespace Microsoft.KeyVault

Si el registro se realiza correctamente, se devuelve la siguiente salida:

Registro del almacén de claves en PowerShell correcto

Al invocar los comandos de Key Vault, podría recibir un error, como "La suscripción no está registrada para usar el espacio de nombres Microsoft.KeyVault". Si se produce un error, confirme que tiene habilitado el proveedor de recursos de Key Vault siguiendo las instrucciones anteriores.

Creación de un Almacén de claves

Antes de crear un almacén de claves, cree un grupo de recursos para que todos los recursos relacionados con dicho almacén de claves se encuentren en un grupo de recursos. Utilice el comando siguiente para crear un nuevo grupo de recursos:

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

Nuevo grupo de recursos generado en Powershell

Ahora, utilice el siguiente cmdlet para crear un almacén de claves en el grupo de recursos que creó anteriormente. Este comando lee tres parámetros obligatorios: el nombre del grupo de recursos, el nombre del almacén de claves y la ubicación geográfica.

Ejecute el siguiente comando para crear un almacén de claves:

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

Nuevo almacén de claves generado en Powershell

La salida de este comando muestra las propiedades del almacén de claves que ha creado. Cuando una aplicación accede a este almacén, debe utilizar la propiedad Vault URI (URI de almacén) que es https://vault01.vault.local.azurestack.external en este ejemplo.

Implementación de Servicios de federación de Active Directory (AD FS)

En una implementación de AD FS, podría obtener esta advertencia: "Access policy is not set. No user or application has access permission to use this vault" (La directiva de acceso no está definida. Ningún usuario ni ninguna aplicación tienen permiso de acceso para utilizar este almacén). Para resolver este problema, establezca una directiva de acceso para el almacén mediante el comando 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

Administración de claves y secretos

Después de crear un almacén, realice estos pasos para crear y administrar claves y secretos en el almacén.

Crear una clave

Use el cmdlet Add-AzureKeyVaultKey para crear o importar una clave protegida mediante software en un almacén de claves:

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

El parámetro -Destination se utiliza para especificar que la clave está protegida mediante software. Cuando la clave se crea correctamente, el comando da como salida los detalles de la clave creada.

Nueva clave del almacén de claves generada en Powershell

Ahora puede hacer referencia a la clave creada utilizando su URI. Si crea o importa una clave con el mismo nombre que una clave existente, la clave original se actualiza con los valores que se especifican en la nueva clave. Puede acceder a la versión anterior utilizando el URI específico de la versión de la clave. Por ejemplo:

  • Use https://vault10.vault.local.azurestack.external:443/keys/key01 para obtener siempre la versión actual.
  • Use https://vault010.vault.local.azurestack.external:443/keys/key01/d0b36ee2e3d14e9f967b8b6b1d38938a para obtener esta versión específica.

Obtener una clave

Use el cmdlet Get-AzureKeyVaultKey para leer una clave y sus detalles:

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

Crear un secreto

Use el cmdlet Set-AzureKeyVaultSecret para crear o actualizar un secreto en un almacén. Si aún no existe, se crea un secreto. Si ya existe, se crea una nueva versión del secreto:

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

Creación de un secreto en Powershell

Obtener un secreto

Use el cmdlet Get-AzureKeyVaultSecret para leer un secreto en un almacén de claves. Este comando puede devolver todas las versiones de un secreto o algunas versiones concretas:

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

Después de crear claves y secretos, puede autorizar a aplicaciones externas para que los usen.

Autorización a una aplicación para que use una clave o un secreto

Para autorizar a una aplicación a acceder a una clave o a un secreto del almacén de claves, use el cmdlet siguiente.

En el siguiente ejemplo, el nombre del almacén es ContosoKeyVault y la aplicación que desea autorizar tiene el identificador de cliente 8f8c4bbd-485b-45fd-98f7-ec6300b7b4ed. Ejecute el comando siguiente para autorizar a la aplicación. También puede especificar el parámetro PermissionsToKeys para establecer permisos para un usuario, una aplicación o un grupo de seguridad.

Cuando use el cmdlet en un entorno de Azure Stack Hub configurado por AD FS, se debe proporcionar el parámetro BypassObjectIdValidation.

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

Si desea autorizar a esa misma aplicación a leer los secretos del almacén, ejecute el siguiente cmdlet:

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

Pasos siguientes