Creación de una firma de acceso compartido de OneLake

2025-05-20

Puede crear una firma de acceso compartido (SAS) de OneLake para proporcionar acceso delegado a corto plazo a una carpeta o archivo en OneLake respaldado por sus credenciales de Microsoft Entra. Una SAS de OneLake puede proporcionar acceso temporal a las aplicaciones que no admiten Microsoft Entra. Estas aplicaciones pueden cargar datos o servir como servidores proxy entre otras aplicaciones cliente o empresas de desarrollo de software.

Para crear una SAS de OneLake, solicite una clave de delegación de usuario llamando a la operación Obtener clave de delegación de usuarios . A continuación, use la clave para firmar la SAS.

Una SAS de OneLake solo puede conceder acceso a archivos y carpetas dentro de elementos de datos. No se puede usar para operaciones de administración como crear o eliminar áreas de trabajo o elementos.

La creación de una SAS de OneLake es similar a la creación de una SAS delegada por el usuario de Azure Storage. Use los mismos parámetros para la compatibilidad con herramientas y aplicaciones que funcionan con Azure Storage.

Permisos necesarios

Solicitar una clave de delegación de usuarios es una operación de nivel de inquilino en Microsoft Fabric. El usuario o la entidad de seguridad que solicita una clave de delegación de usuario debe tener al menos permisos de lectura en un área de trabajo del arrendatario de Fabric. La identidad del usuario solicitante se usa para autenticar la SAS, por lo que el usuario debe tener permiso para los datos a los que concede acceso SAS.

Adquisición de un token de OAuth 2.0

Para obtener la clave de delegación de usuario, primero solicite un token de OAuth 2.0 de Microsoft Entra ID. Autorice la llamada a la Get User Delegation Key operación proporcionando el token de portador. Para obtener más información sobre cómo solicitar un token de OAuth desde microsoft Entra ID, consulte el artículo sobre los flujos de autenticación y los escenarios de aplicación.

Solicitud de la clave de delegación de usuario

La llamada a la Get User Delegation Key operación devuelve la clave como un conjunto de valores que se usan como parámetros en el token SAS de delegación del usuario. Estos parámetros se describen en la referencia Obtener clave de delegación de usuario y en la siguiente sección.

Nota:

Llamar a la operación Get User Delegation Key con una carga de trabajo de Fabric, como un cuaderno de Python, requiere el punto de conexión regional para OneLake. La región de capacidad determina este punto de conexión. De lo contrario, la respuesta recibida es 200 Healthy en lugar de la clave de delegación.

Cuando un cliente solicita una clave de delegación de usuarios mediante un token de OAuth 2.0, OneLake devuelve la clave en nombre del cliente. A una SAS creada con esta clave de delegación de usuario se le conceden, como máximo, los mismos permisos otorgados al cliente. Pero se limitan a los permisos concedidos explícitamente en la SAS.

Puede crear cualquier número de tokens SAS de OneLake durante la vigencia de la clave de delegación de usuarios. Sin embargo, una SAS de OneLake y las claves de delegación de usuarios pueden ser válidas durante no más de una hora. No pueden superar el tiempo de vida del token que los solicitó. Estas restricciones de duración son más cortas que la duración máxima de una SAS de delegación de usuarios de Azure Storage.

Construcción de una SAS de delegación de usuario

En la siguiente tabla se resumen los campos que se admiten para un token de SAS de OneLake. En las secciones posteriores se proporcionan más detalles sobre estos parámetros y cómo difieren de los tokens de SAS de Azure Storage. OneLake no admite todos los parámetros opcionales que admite Azure Storage. Se rechazará una SAS de OneLake construida con un parámetro no admitido.

Nombre del campo de SAS	Parámetro del token de SAS	Estado	Descripción
`signedVersion`	`sv`	Obligatorio	Este campo indica la versión del servicio de almacenamiento que se usa para construir el campo de firma. OneLake admite la versión `2020-02-10` y versiones anteriores, o versiones `2020-12-06` y posteriores.
`signedResource`	`sr`	Obligatorio	Este campo especifica qué recursos son accesibles a través de la firma de acceso compartido. Solo el blob (`b`) y el directorio (`d`) son aplicables a OneLake.
`signedStart`	`st`	Opcionales	Este campo especifica la hora en que la firma de acceso compartido es válida. Está en formato ISO 8601 UTC.
`signedExpiry`	`se`	Obligatorio	Este campo especifica la hora en que expira la firma de acceso compartido.
`signedPermissions`	`sp`	Obligatorio	Este campo indica qué operaciones puede realizar la SAS en el recurso. Para obtener más información, consulte la sección Especificar permisos .
`signedObjectId`	`skoid`	Obligatorio	Este campo identifica un principio de seguridad de Microsoft Entra.
`signedtenantId`	`sktid`	Obligatorio	Este campo especifica el arrendatario de Microsoft Entra en el que se define un principal de seguridad.
`signedKeyStartTime`	`skt`	Opcionales	Este campo especifica la hora en UTC cuando se inicia la clave de firma. La `Get User Delegation Key` operación la devuelve.
`signedKeyExpiryTime`	`ske`	Obligatorio	Este campo especifica la hora en UTC cuando finaliza la clave de firma. La operación `Get User Delegation Key` devuelve eso.
`signedKeyVersion`	`skv`	Obligatorio	Este campo especifica la versión del servicio de almacenamiento que se usa para obtener la clave de delegación de usuarios. La operación `Get User Delegation Key` devuelve el resultado. OneLake admite la versión `2020-02-10` y versiones anteriores, o versiones `2020-12-06` y posteriores.
`signedKeyService`	`sks`	Obligatorio	Este campo indica el servicio válido para la clave de delegación de usuarios. OneLake solo admite Azure Blob Storage (`sks=b`).
`signature`	`sig`	Obligatorio	La firma es un código de autenticación de mensajes basado en hash (HMAC) calculado sobre la cadena a signo y la clave mediante el algoritmo SHA256 y, a continuación, codificado mediante la codificación Base64.
`signedDirectoryDepth`	`sdd`	Opcionales	Este campo indica el número de directorios dentro de la carpeta raíz del directorio especificado en el campo `canonicalizedResource` de la cadena para firmar. Solo se admite cuando `sr=d`.
`signedProtocol`	`spr`	Opcionales	OneLake solo admite solicitudes HTTPS.
`signedAuthorizedObjectId`	`saoid`	No compatible	Una SAS de OneLake no admite esta característica.
`signedUnauthorizedObjectId`	`suoid`	No compatible	Una SAS de OneLake no admite esta característica.
`signedCorrelationId`	`suoid`	No compatible	Una SAS de OneLake no admite este parámetro.
`signedEncryptionScope`	`ses`	No compatible	Actualmente, una SAS de OneLake no admite ámbitos de cifrado personalizados.
`signedIP`	`sip`	No compatible	Actualmente, una SAS de OneLake no admite el filtrado ip.
Encabezado de respuesta`Cache-Control`	`rscc`	No compatible	Una SAS de OneLake no admite este parámetro.
Encabezado de respuesta`Content-Disposition`	`rscd`	No compatible	Una SAS de OneLake no admite este parámetro.
Encabezado de respuesta`Content-Encoding`	`rsce`	No compatible	Una SAS de OneLake no admite este parámetro.
Encabezado de respuesta`Content-Language`	`rscl`	No compatible	Una SAS de OneLake no admite este parámetro.
Encabezado de respuesta`Content Type`	`rsct`	No compatible	Una SAS de OneLake no admite este parámetro.

Especificar permisos

Los permisos especificados en el signedPermissions campo (sp) del token de SAS indican qué operaciones puede realizar un cliente que posee la SAS en el recurso.

Los permisos se pueden combinar para permitir que un cliente realice varias operaciones con la misma SAS. Al construir la SAS, debe incluir permisos en el orden siguiente: racwdxyltmeopi.

Entre los ejemplos de opciones de permisos válidos se incluyen rw, rd, rl, wd, wl y rl. No se puede especificar un permiso más de una vez.

Para garantizar la paridad con las herramientas de Azure Storage existentes, OneLake usa el mismo formato de permiso que Azure Storage. OneLake evalúa los permisos concedidos a una SAS en signedPermissions, los permisos de la identidad de firma en Fabric y los roles de acceso a datos de OneLake, si procede.

Recuerde que algunas operaciones, como establecer permisos o eliminar áreas de trabajo, por lo general no se permiten en OneLake a través de las API de Azure Storage. Conceder ese permiso (sp=op) no permite que una SAS de OneLake realice esas operaciones.

Permiso	Símbolo de URI	Recurso	Operaciones permitidas
Lectura	`r`	Directorio, objeto binario	Lea el contenido, la lista de bloques, las propiedades y los metadatos de cualquier blob del contenedor o directorio. Use un blob como origen de una operación de copia.
Agregar	`a`	Directorio, objeto binario	Agregue un bloque a un blob en anexos.
Crear	`c`	Directorio, blob	Escriba un nuevo blob, una instantánea de un blob o copie un blob en un nuevo blob.
Escribir	`w`	Directorio, blob	Cree o escriba contenido, propiedades, metadatos o una lista de bloqueados. Tome una instantánea o conceda el blob. Use el blob como destino de una operación de copia.
Eliminar	`d`	Directorio, objeto binario	Eliminar un blob.
Eliminar versión	`x`	Masa amorfa	Eliminar una versión de un blob.
Eliminación permanentemente	`y`	Masa amorfa	Elimine permanentemente una instantánea de blob o una versión.
Lista	`l`	Directorio	Enumere los blobs de forma no recursiva.
Etiquetas	`t`	Masa amorfa	Lea o escriba las etiquetas en un blob.
Mueve	`m`	Directorio, blob	Mueva un blob o un directorio y su contenido a una nueva ubicación.
Ejecutar	`e`	Directorio, blob	Obtiene las propiedades del sistema. Si el espacio de nombres jerárquico está habilitado para la cuenta de almacenamiento, se puede obtener la lista de control de acceso POSIX de un objeto conocido como 'blob'.
Propiedad	`o`	Directorio, blob	Establezca el propietario o el grupo propietario. Esta operación no está admitida en OneLake.
Permisos	`p`	Directorio, blob	Configure los permisos. Esta operación no es compatible con OneLake.
Establecer política de inmutabilidad	`i`	Masa amorfa	Establezca o elimine la directiva de inmutabilidad o suspensión legal en un blob.

Especificación de la firma

El signature campo (sig) se usa para autorizar una solicitud realizada por un cliente con la firma de acceso compartido. La cadena para firmar es una cadena única que se construye a partir de los campos que se deben comprobar para autorizar la solicitud. La firma es un HMAC que se calcula a través de la cadena a signo y la clave mediante el algoritmo SHA256 y, a continuación, se codifica mediante la codificación Base64.

Para construir la cadena de la firma de una delegación de usuario SAS:

Cree la cadena a firmar a partir de los campos incluidos en la solicitud.
Codifique la cadena como UTF-8.
Calcule la firma mediante el algoritmo HMAC SHA256.

Los campos que se incluyen en la cadena para firmar deben ser descodificados desde URL. Los campos obligatorios dependen de la versión del servicio que se usa para el campo de autorización (sv). En las secciones siguientes se describen las configuraciones de cadena a signo para versiones que admiten SAS de OneLake.

Versión 2020-12-06 y posteriores

StringToSign =  signedPermissions + "\n" +
                signedStart + "\n" +
                signedExpiry + "\n" +
                canonicalizedResource + "\n" +
                signedKeyObjectId + "\n" +
                signedKeyTenantId + "\n" +
                signedKeyStart + "\n" +
                signedKeyExpiry  + "\n" +
                signedKeyService + "\n" +
                signedKeyVersion + "\n" +
                signedAuthorizedUserObjectId + "\n" +
                signedUnauthorizedUserObjectId + "\n" +
                signedCorrelationId + "\n" +
                signedIP + "\n" +
                signedProtocol + "\n" +
                signedVersion + "\n" +
                signedResource + "\n" +
                signedSnapshotTime + "\n" +
                signedEncryptionScope + "\n" +
                rscc + "\n" +
                rscd + "\n" +
                rsce + "\n" +
                rscl + "\n" +
                rsct

Versión 2020-02-10 y versiones anteriores

Esta configuración se aplica a la versión 2020-02-10 y anteriores, excepto a la versión 2020-01-10 (que se describe en la sección siguiente).

StringToSign =  signedPermissions + "\n" +  
                signedStart + "\n" +  
                signedExpiry + "\n" +  
                canonicalizedResource + "\n" +  
                signedKeyObjectId + "\n" +
                signedKeyTenantId + "\n" +
                signedKeyStart + "\n" +
                signedKeyExpiry  + "\n" +
                signedKeyService + "\n" +
                signedKeyVersion + "\n" +
                signedAuthorizedUserObjectId + "\n" +
                signedUnauthorizedUserObjectId + "\n" +
                signedCorrelationId + "\n" +
                signedIP + "\n" +  
                signedProtocol + "\n" +  
                signedVersion + "\n" +  
                signedResource + "\n" +
                rscc + "\n" +
                rscd + "\n" +  
                rsce + "\n" +  
                rscl + "\n" +  
                rsct

Versión 2020-01-10

StringToSign =  signedPermissions + "\n" +
                signedStart + "\n" +
                signedExpiry + "\n" +
                canonicalizedResource + "\n" +
                signedKeyObjectId + "\n" +
                signedKeyTenantId + "\n" +
                signedKeyStart + "\n" +
                signedKeyExpiry  + "\n" +
                signedKeyService + "\n" +
                signedKeyVersion + "\n" +
                signedAuthorizedUserObjectId + "\n" +
                signedUnauthorizedUserObjectId + "\n" +
                signedCorrelationId + "\n" +
                signedIP + "\n" +
                signedProtocol + "\n" +
                signedVersion + "\n" +
                signedResource + "\n" +
                signedSnapshotTime + "\n" +
                rscc + "\n" +
                rscd + "\n" +
                rsce + "\n" +
                rscl + "\n" +
                rsct

Recurso canonizado

La parte canonicalizedResource de la cadena es una ruta de acceso canónica al recurso. Debe incluir el punto de conexión de OneLake y el nombre del recurso, y debe descodificar la dirección URL. La ruta de acceso de OneLake debe incluir su área de trabajo. Una ruta de acceso de directorio debe incluir el número de subdirectorios que corresponden al parámetro sdd.

En los ejemplos siguientes se muestra cómo convertir la dirección URL de OneLake en el recurso canónico correspondiente. Recuerde que OneLake admite tanto sistemas de archivos distribuidos (DFS) como operaciones de blobs y puntos de conexión. El nombre de cuenta de OneLake es siempre onelake.

Archivo de blob

URL = https://onelake.blob.fabric.microsoft.com/myWorkspace/myLakehouse.Lakehouse/Files/sales.csv
canonicalizedResource = "/blob/onelake/myWorkspace/myLakehouse.Lakehouse/Files/sales.csv"

Directorio DFS

URL = https://onelake.dfs.fabric.microsoft.com/myWorkspace/myLakehouse.Lakehouse/Files/
canonicalizedResource = "/blob/onelake/myWorkspace/myLakehouse.Lakehouse/Files/"

Ejemplo de SAS de OneLake

En el ejemplo siguiente se muestra un URI de SAS de OneLake con un token de SAS de OneLake anexado a él. El token de SAS proporciona permisos de lectura y escritura en la Files carpeta de lakehouse.

https://onelake.blob.fabric.microsoft.com/myWorkspace/myLakehouse.Lakehouse/Files/?sp=rw&st=2023-05-24T01:13:55Z&se=2023-05-24T09:13:55Z&skoid=<object-id>&sktid=<tenant-id>&skt=2023-05-24T01:13:55Z&ske=2023-05-24T09:13:55Z&sks=b&skv=2022-11-02&sv=2022-11-02&sr=d&sig=<signature>