Uso de PowerShell para administrar listas de control de acceso en Azure Data Lake Storage

Este artículo te muestra cómo usar PowerShell para obtener, configurar y actualizar las listas de control de acceso (ACLs) de directorios y archivos.

Los nuevos elementos secundarios que se creen en un directorio principal heredan automáticamente las ACL. Sin embargo, también puedes añadir, actualizar y eliminar ACL de forma recursiva en los elementos secundarios existentes dentro de un directorio principal sin tener que realizar estos cambios de forma individual para cada elemento secundario.

Referencia | Envío de comentarios

Requisitos previos

• Suscripción a Azure. Para obtener más información, vea Obtención de una evaluación gratuita de Azure.

• Una cuenta de almacenamiento que tenga habilitado el espacio de nombres jerárquico (HNS). Siga estas instrucciones para crear uno.

• Uno de los siguientes permisos de seguridad:

  • Un entidad de seguridad de Microsoft Entra ID aprovisionada a la que se le haya asignado el rol de Propietario de datos de blobs de almacenamiento, con un ámbito que abarque el contenedor de destino, la cuenta de almacenamiento, el grupo de recursos principal o la suscripción.

  • El usuario propietario del contenedor o directorio de destino al que va a aplicar la configuración de ACL. Para establecer ACLs de forma recursiva, este usuario incluye todos los elementos hijos del contenedor o directorio destino.

Instalación del módulo de PowerShell

1. Verifica que la versión de PowerShell que instalaste sea 5.1 superior o superior usando el siguiente comando.

   echo $PSVersionTable.PSVersion.ToString()
   

   Para actualizar tu versión de PowerShell, consulta Actualizar PowerShell de Windows existente.

2. Instale el módulo Az.Storage.

   Install-Module Az.Storage -Repository PSGallery -Force  
   

   Para más información sobre cómo instalar módulos PowerShell, consulte Instalar el módulo Azure PowerShell.

Conexión con la cuenta

1. Abra una ventana de comandos de Windows PowerShell e inicie sesión en la suscripción de Azure con el comando Connect-AzAccount y siga las instrucciones en pantalla.

   Connect-AzAccount
   

2. Si tu identidad está asociada a más de una suscripción y no te piden que selecciones la suscripción, configura tu suscripción activa a la suscripción de la cuenta de almacenamiento que quieres usar. En este ejemplo, reemplace el valor de marcador de posición <subscription-id> por el identificador de la suscripción.

   Select-AzSubscription -SubscriptionId <subscription-id>
   

3. Obtenga el contexto de la cuenta de almacenamiento.

   $ctx = New-AzStorageContext -StorageAccountName '<storage-account-name>' -UseConnectedAccount
   

Obtención de listas de control de acceso

Obtenga la ACL de un directorio o archivo mediante el cmdlet Get-AzDataLakeGen2Item.

En Azure Data Lake Storage, un contenedor también se denomina sistema de archivos. El -FileSystem parámetro utilizado en los siguientes ejemplos toma el nombre de tu contenedor.

El siguiente ejemplo obtiene la ACL del directorio raíz de un contenedor y luego imprime la ACL en la consola.

$filesystemName = "my-file-system"
$filesystem = Get-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName
$filesystem.ACL

El siguiente ejemplo obtiene la ACL de un directorio y luego imprime la ACL en la consola.

$filesystemName = "my-file-system"
$dirname = "my-directory/"
$dir = Get-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $dirname
$dir.ACL

El siguiente ejemplo obtiene la ACL de un archivo y luego imprime la ACL en la consola.

$filePath = "my-directory/upload.txt"
$file = Get-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $filePath
$file.ACL

En la siguiente imagen se muestra la salida después de obtener la ACL de un directorio.

En este ejemplo, el usuario propietario tiene permisos de lectura, escritura y ejecución. El grupo propietario tiene permisos de solo lectura y ejecución. Para más información sobre las listas de control de acceso, vea Control de acceso en Azure Data Lake Storage.

Establecimiento de listas de control de acceso

Cuando configuras una ACL, reemplazas toda la ACL, incluyendo todas sus entradas. Si quieres cambiar el nivel de permiso de un principal de seguridad o añadir un nuevo principal de seguridad a la ACL sin afectar a otras entradas existentes, actualiza la ACL en su lugar. Para actualizar una ACL en lugar de reemplazarla, consulte la sección Actualización de ACL de este artículo.

Si elige establecer la lista de control de acceso, debe agregar una entrada para el usuario propietario, otra para el grupo propietario y una tercera para los demás usuarios. Para más información sobre el usuario propietario, el grupo propietario y el resto de usuarios, consulte Usuarios e identidades.

Esta sección le muestra cómo:

• Establecimiento de una ACL
• Establecimiento de listas de control de acceso de forma recursiva

Establecimiento de una ACL

Use el cmdlet Set-AzDataLakeGen2ItemAclObject para crear una ACL para el usuario propietario, el grupo propietario u otros usuarios. A continuación, use el cmdlet Update-AzDataLakeGen2Item para confirmar la ACL.

En este ejemplo se establece la ACL en el directorio raíz de un contenedor del usuario propietario, el grupo propietario o de otros usuarios, y luego se imprime la ACL en la consola.

$filesystemName = "my-file-system"
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType user -Permission rw-
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType group -Permission rw- -InputObject $acl
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType other -Permission -wx -InputObject $acl
Update-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Acl $acl
$filesystem = Get-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName
$filesystem.ACL

En este ejemplo se establece la ACL en un directorio del usuario propietario, el grupo propietario o de otros usuarios, y luego se imprime la ACL en la consola.

$filesystemName = "my-file-system"
$dirname = "my-directory/"
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType user -Permission rw-
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType group -Permission rw- -InputObject $acl
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType other -Permission -wx -InputObject $acl
Update-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $dirname -Acl $acl
$dir = Get-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $dirname
$dir.ACL

En este ejemplo se establece la ACL en un archivo del usuario propietario, el grupo propietario o de otros usuarios, y luego se imprime la ACL en la consola.

$filesystemName = "my-file-system"
$filePath = "my-directory/upload.txt"
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType user -Permission rw-
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType group -Permission rw- -InputObject $acl
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType other -Permission "-wx" -InputObject $acl
Update-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $filePath -Acl $acl
$file = Get-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $filePath
$file.ACL

En la siguiente imagen se muestra la salida después de establecer la ACL de un archivo.

En este ejemplo, el usuario propietario y el grupo propietario tienen permisos de solo lectura y escritura. Los demás usuarios tienen permisos de escritura y ejecución. Para más información sobre las listas de control de acceso, vea Control de acceso en Azure Data Lake Storage.

Establecimiento de listas de control de acceso de forma recursiva

Establezca listas de control de acceso de forma recursiva mediante el cmdlet Set-AzDataLakeGen2AclRecursive.

En este ejemplo se establece la ACL de un directorio denominado my-parent-directory. Estas entradas otorgan permisos de lectura, escritura y ejecución al usuario propietario, otorgan al grupo propietario solo permisos de lectura y ejecución, y no permiten acceso a todos los demás. La última entrada de ACL de este ejemplo proporciona a un usuario específico con el identificador de objeto "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" permisos de lectura y ejecución.

$filesystemName = "my-container"
$dirname = "my-parent-directory/"
$userID = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";

$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType user -Permission rwx
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType group -Permission r-x -InputObject $acl
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType other -Permission "---" -InputObject $acl
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType user -EntityId $userID -Permission r-x -InputObject $acl

Set-AzDataLakeGen2AclRecursive -Context $ctx -FileSystem $filesystemName -Path $dirname -Acl $acl

Para ver un ejemplo que establezca ACL de forma recursiva en lotes especificando un tamaño de lote, consulte el artículo de referencia Set-AzDataLakeGen2AclRecursive.

Actualización de ACL

Cuando actualiza una ACL, modifica la ACL en lugar de reemplazarla. Por ejemplo, puede agregar una nueva entidad de seguridad a la ACL sin que esto afecte a otras entidades de seguridad que se enumeran en la ACL. Para reemplazar la ACL en lugar de actualizarla, consulte la sección Establecimiento de listas de control de acceso de este artículo.

Esta sección le muestra cómo:

• Actualización de una ACL
• Actualización de listas de control de acceso de forma recursiva

Actualización de una ACL

En primer lugar, obtenga la lista de control de acceso. A continuación, use el cmdlet Set-AzDataLakeGen2ItemAclObject para agregar o actualizar una entrada de ACL. Use el cmdlet Update-AzDataLakeGen2Item para confirmar la ACL.

En este ejemplo se crea o actualiza la lista de control de acceso en un directorio para un usuario.

$filesystemName = "my-file-system"
$dirname = "my-directory/"
$acl = (Get-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $dirname).ACL
$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType user -EntityID aaaaaaaa-bbbb-cccc-1111-222222222222 -Permission r-x -InputObject $acl
Update-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $dirname -Acl $acl

Actualización de listas de control de acceso de forma recursiva

Actualice las listas de control de acceso de forma recursiva mediante el cmdlet Update-AzDataLakeGen2AclRecursive.

En este ejemplo se actualiza una entrada de ACL con permiso de escritura.

$filesystemName = "my-container"
$dirname = "my-parent-directory/"
$userID = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";

$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType user -EntityId $userID -Permission rwx

Update-AzDataLakeGen2AclRecursive -Context $ctx -FileSystem $filesystemName -Path $dirname -Acl $acl

Para ver un ejemplo que actualice ACL de forma recursiva en lotes especificando un tamaño de lote, consulte el artículo de referencia Update-AzDataLakeGen2AclRecursive.

Eliminar entradas de ACL

Esta sección le muestra cómo:

• Eliminación de una entrada de ACL
• Eliminación de las entradas de ACL de forma recursiva

Eliminación de una entrada de ACL

En este ejemplo se elimina una entrada de una lista de control de acceso existente. Reutiliza el contexto de la cuenta de almacenamiento de $ctx y las variables $acl, $filesystemName y $dirname definidas en secciones anteriores de este artículo.

$id = "xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

# Create the new ACL object.
[Collections.Generic.List[System.Object]]$aclnew =$acl

foreach ($a in $aclnew)
{
    if ($a.AccessControlType -eq "User" -and $a.DefaultScope -eq $false -and $a.EntityId -eq $id)
    {
        $aclnew.Remove($a);
        break;
    }
}
Update-AzDataLakeGen2Item -Context $ctx -FileSystem $filesystemName -Path $dirname -Acl $aclnew

Eliminación de las entradas de ACL de forma recursiva

Puede quitar una o varias entradas de ACL de forma recursiva. Para eliminar una entrada de ACL, crea un nuevo objeto ACL para la entrada de ACL que quieres eliminar, y luego usa ese objeto en la operación de eliminar ACL. No obtenga la ACL existente; simplemente proporcione las entradas de la ACL que se deben eliminar.

Quite las entradas de ACL mediante el cmdlet Remove-AzDataLakeGen2AclRecursive.

En este ejemplo se quita una entrada de ACL del directorio raíz del contenedor.

$filesystemName = "my-container"
$userID = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

$acl = Set-AzDataLakeGen2ItemAclObject -AccessControlType user -EntityId $userID -Permission "---"

Remove-AzDataLakeGen2AclRecursive -Context $ctx -FileSystem $filesystemName  -Acl $acl

Para ver un ejemplo que quite ACL de forma recursiva en lotes especificando un tamaño de lote, consulte el artículo de referencia Remove-AzDataLakeGen2AclRecursive.

Recuperación de errores

Al modificar listas de control de acceso de forma recursiva, es posible que se produzcan errores del entorno de ejecución o de los permisos. Los ejemplos de esta sección reutilizan el contexto de la cuenta de almacenamiento $ctx y las variables $filesystemName, $dirname y $acl definidas en secciones anteriores de este artículo.

En el caso de los errores de tiempo de ejecución, reinicie el proceso desde el principio. Pueden ocurrir errores de permisos si el responsable de seguridad no tiene permiso suficiente para modificar la ACL de un directorio o archivo que está en la jerarquía de directorios que estás modificando. Soluciona el problema de permisos y luego elige reanudar el proceso desde el punto de fallo usando un token de continuación, o reiniciar el proceso desde el principio. No tiene que usar el token de continuación si prefiere reiniciar desde el principio. Puede volver a aplicar las entradas de ACL sin ningún efecto negativo.

Este ejemplo devuelve los resultados a la variable y luego encadena las entradas fallidas a una tabla formateada.

$result = Set-AzDataLakeGen2AclRecursive -Context $ctx -FileSystem $filesystemName -Path $dirname -Acl $acl
$result
$result.FailedEntries | ft

Según la salida de la tabla, puede corregir todos los errores de permisos y, a continuación, reanudar la ejecución mediante el token de continuación.

$result = Set-AzDataLakeGen2AclRecursive -Context $ctx -FileSystem $filesystemName -Path $dirname -Acl $acl -ContinuationToken $result.ContinuationToken
$result

Para ver un ejemplo que establezca ACL de forma recursiva en lotes especificando un tamaño de lote, consulte el artículo de referencia Set-AzDataLakeGen2AclRecursive.

Si quieres que el proceso se complete sin interrupciones por errores de permisos, puedes configurarlo para que lo haga.

En este ejemplo se usa el parámetro ContinueOnFailure para que la ejecución continúe incluso si la operación encuentra un error de permiso.

$result = Set-AzDataLakeGen2AclRecursive -Context $ctx -FileSystem $filesystemName -Path $dirname -Acl $acl -ContinueOnFailure

echo "[Result Summary]"
echo "TotalDirectoriesSuccessfulCount: `t$($result.TotalDirectoriesSuccessfulCount)"
echo "TotalFilesSuccessfulCount: `t`t`t$($result.TotalFilesSuccessfulCount)"
echo "TotalFailureCount: `t`t`t`t`t$($result.TotalFailureCount)"
echo "FailedEntries:"$($result.FailedEntries | ft)

Para ver un ejemplo que establezca ACL de forma recursiva en lotes especificando un tamaño de lote, consulte el artículo de referencia Set-AzDataLakeGen2AclRecursive.

Procedimientos recomendados

En esta sección se proporcionan algunas directrices de procedimientos recomendados para configurar las ACL de forma recursiva.

Manejo de errores de tiempo de ejecución

Se puede producir un error de tiempo de ejecución por muchos motivos (por ejemplo: una interrupción o un problema de conectividad de cliente). Si se produce un error de tiempo de ejecución, reinicie el proceso de ACL recursivo. Las ACL se pueden volver a aplicar a los elementos sin provocar ningún efecto negativo.

Manejo de errores de permisos (403)

Si experimenta una excepción de control de acceso al ejecutar un proceso de ACL recursivo, es posible que la entidad de seguridad de AD no tenga permisos suficientes para aplicar una ACL a uno o varios de los elementos secundarios de la jerarquía de directorios. Cuando se produce un error de permiso, el proceso se detiene y se proporciona un token de continuación. Repare el problema de permisos y, después, use el token de continuación para procesar el conjunto de datos restante. Los directorios y archivos que ya se han procesado correctamente no tendrán que procesarse de nuevo. También puede optar por reiniciar el proceso de ACL recursivo. Las ACL se pueden volver a aplicar a los elementos sin provocar ningún efecto negativo.

Credenciales

Es aconsejable que aprovisione una entidad de seguridad de Microsoft Entra a la que se haya asignado el rol de Propietario de datos de blobs de almacenamiento en el ámbito de la cuenta de almacenamiento o el contenedor de destino.

Rendimiento

Para reducir la latencia, se recomienda ejecutar el proceso de ACL recursivo en una máquina virtual de Azure que se encuentre en la misma región que la cuenta de almacenamiento.

Límites de ACL

El número máximo de ACL que puede aplicar a un directorio o archivo es de 32 ACL de acceso y 32 ACL predeterminadas. Para más información, consulte Control de acceso en Azure Data Lake Storage Gen2.

Consulte también

• Problemas conocidos
• Cmdlets de PowerShell de almacenamiento
• Modelo de control de acceso de Azure Data Lake Storage
• Listas de control de acceso (ACL) en Azure Data Lake Storage