0
# Access Control and Security
1

2
Comprehensive access control management including POSIX-style ACLs, SAS token generation, and lease-based concurrency control. Azure Data Lake Storage Gen2 provides fine-grained security controls for hierarchical data management.
3

4
## Capabilities
5

6
### Shared Access Signature (SAS) Generation
7

8
Functions for generating SAS tokens that provide delegated access to Data Lake Storage resources with fine-grained permissions and time constraints.
9

10
```python { .api }
11
def generate_account_sas(
12
    account_name: str,
13
    account_key: str,
14
    resource_types: ResourceTypes,
15
    permission: AccountSasPermissions,
16
    expiry: datetime,
17
    start: datetime = None,
18
    **kwargs
19
) -> str:
20
    """
21
    Generate an account-level SAS token for accessing storage resources.
22
    
23
    Args:
24
        account_name (str): Storage account name
25
        account_key (str): Account access key for signing
26
        resource_types (ResourceTypes): Types of resources accessible with this SAS
27
        permission (AccountSasPermissions): Permissions granted by the SAS
28
        expiry (datetime): Expiration time for the SAS token
29
        start (datetime, optional): Start time for SAS validity
30
        **kwargs: Additional options including IP range, protocol
31
        
32
    Returns:
33
        str: SAS token query string
34
    """
35

36
def generate_file_system_sas(
37
    account_name: str,
38
    file_system_name: str,
39
    account_key: str,
40
    permission: FileSystemSasPermissions = None,
41
    expiry: datetime = None,
42
    start: datetime = None,
43
    **kwargs
44
) -> str:
45
    """
46
    Generate a file system-level SAS token.
47
    
48
    Args:
49
        account_name (str): Storage account name
50
        file_system_name (str): Name of the file system
51
        account_key (str): Account access key for signing
52
        permission (FileSystemSasPermissions, optional): Permissions for the file system
53
        expiry (datetime, optional): Expiration time for the SAS token
54
        start (datetime, optional): Start time for SAS validity
55
        **kwargs: Additional options including IP range, protocol, cache control
56
        
57
    Returns:
58
        str: SAS token query string
59
    """
60

61
def generate_directory_sas(
62
    account_name: str,
63
    file_system_name: str,
64
    directory_name: str,
65
    account_key: str,
66
    permission: DirectorySasPermissions = None,
67
    expiry: datetime = None,
68
    start: datetime = None,
69
    **kwargs
70
) -> str:
71
    """
72
    Generate a directory-level SAS token.
73
    
74
    Args:
75
        account_name (str): Storage account name
76
        file_system_name (str): Name of the file system
77
        directory_name (str): Name/path of the directory
78
        account_key (str): Account access key for signing
79
        permission (DirectorySasPermissions, optional): Permissions for the directory
80
        expiry (datetime, optional): Expiration time for the SAS token
81
        start (datetime, optional): Start time for SAS validity
82
        **kwargs: Additional options including IP range, protocol
83
        
84
    Returns:
85
        str: SAS token query string
86
    """
87

88
def generate_file_sas(
89
    account_name: str,
90
    file_system_name: str,
91
    file_path: str,
92
    account_key: str,
93
    permission: FileSasPermissions = None,
94
    expiry: datetime = None,
95
    start: datetime = None,
96
    **kwargs
97
) -> str:
98
    """
99
    Generate a file-level SAS token.
100
    
101
    Args:
102
        account_name (str): Storage account name
103
        file_system_name (str): Name of the file system
104
        file_path (str): Path to the file
105
        account_key (str): Account access key for signing
106
        permission (FileSasPermissions, optional): Permissions for the file
107
        expiry (datetime, optional): Expiration time for the SAS token
108
        start (datetime, optional): Start time for SAS validity
109
        **kwargs: Additional options including IP range, protocol
110
        
111
    Returns:
112
        str: SAS token query string
113
    """
114
```
115

116
**Usage Examples:**
117

118
```python
119
from datetime import datetime, timedelta
120
from azure.storage.filedatalake import (
121
    generate_file_system_sas,
122
    generate_file_sas,
123
    FileSystemSasPermissions,
124
    FileSasPermissions
125
)
126

127
# Generate file system SAS with read and list permissions
128
fs_sas = generate_file_system_sas(
129
    account_name="mystorageaccount",
130
    file_system_name="myfilesystem",
131
    account_key="<account_key>",
132
    permission=FileSystemSasPermissions(read=True, list=True),
133
    expiry=datetime.utcnow() + timedelta(hours=1)
134
)
135

136
# Generate file SAS with read and write permissions
137
file_sas = generate_file_sas(
138
    account_name="mystorageaccount",
139
    file_system_name="myfilesystem", 
140
    file_path="data/results.json",
141
    account_key="<account_key>",
142
    permission=FileSasPermissions(read=True, write=True),
143
    expiry=datetime.utcnow() + timedelta(hours=2),
144
    start=datetime.utcnow()
145
)
146

147
print(f"File System SAS: {fs_sas}")
148
print(f"File SAS: {file_sas}")
149
```
150

151
### DataLakeLeaseClient
152

153
Lease-based concurrency control for ensuring exclusive access to Data Lake Storage resources during critical operations.
154

155
```python { .api }
156
class DataLakeLeaseClient:
157
    """
158
    A client for managing leases on Data Lake Storage resources.
159
    
160
    Attributes:
161
        id (str): The lease ID
162
        etag (str): The ETag of the leased resource
163
        last_modified (datetime): Last modified time of the leased resource
164
    """
165
    
166
    def __init__(self, client, lease_id: str = None):
167
        """
168
        Initialize the DataLakeLeaseClient.
169
        
170
        Args:
171
            client: The DataLake client (Service, FileSystem, Directory, or File)
172
            lease_id (str, optional): Existing lease ID to use
173
        """
174
    
175
    def acquire(
176
        self,
177
        lease_duration: int = -1,
178
        **kwargs
179
    ) -> None:
180
        """
181
        Acquire a lease on the resource.
182
        
183
        Args:
184
            lease_duration (int): Duration in seconds (-1 for infinite lease)
185
            **kwargs: Additional options including conditions
186
        """
187
    
188
    def renew(self, **kwargs) -> None:
189
        """
190
        Renew the lease.
191
        
192
        Args:
193
            **kwargs: Additional options including conditions
194
        """
195
    
196
    def release(self, **kwargs) -> None:
197
        """
198
        Release the lease.
199
        
200
        Args:
201
            **kwargs: Additional options including conditions
202
        """
203
    
204
    def change(self, proposed_lease_id: str, **kwargs) -> None:
205
        """
206
        Change the lease ID.
207
        
208
        Args:
209
            proposed_lease_id (str): New lease ID to use
210
            **kwargs: Additional options including conditions
211
        """
212
    
213
    def break_lease(self, lease_break_period: int = None, **kwargs) -> int:
214
        """
215
        Break the lease.
216
        
217
        Args:
218
            lease_break_period (int, optional): Break period in seconds
219
            **kwargs: Additional options including conditions
220
            
221
        Returns:
222
            int: Remaining lease time in seconds
223
        """
224
    
225
    def __enter__(self) -> 'DataLakeLeaseClient':
226
        """Context manager entry - acquires lease."""
227
    
228
    def __exit__(self, *args) -> None:
229
        """Context manager exit - releases lease."""
230
```
231

232
**Usage Examples:**
233

234
```python
235
from azure.storage.filedatalake import DataLakeFileClient, DataLakeLeaseClient
236

237
# Create a file client
238
file_client = DataLakeFileClient(
239
    account_url="https://mystorageaccount.dfs.core.windows.net",
240
    file_system_name="myfilesystem",
241
    file_path="critical/data.json",
242
    credential="<account_key>"
243
)
244

245
# Acquire a lease for exclusive access
246
lease_client = DataLakeLeaseClient(file_client)
247

248
# Using context manager (automatically acquires and releases)
249
with lease_client:
250
    # Perform critical operations with exclusive access
251
    file_client.upload_data("critical data", overwrite=True)
252
    print(f"Operations completed with lease: {lease_client.id}")
253

254
# Manual lease management
255
lease_client.acquire(lease_duration=60)  # 60 second lease
256
try:
257
    # Perform operations
258
    file_client.append_data("additional data", offset=0)
259
    file_client.flush_data(offset=15)
260
    
261
    # Renew lease if more time needed
262
    lease_client.renew()
263
    
264
finally:
265
    # Always release the lease
266
    lease_client.release()
267
```
268

269
### Permission Classes
270

271
Comprehensive permission classes for controlling access to different resource types with fine-grained capabilities.
272

273
```python { .api }
274
class AccountSasPermissions:
275
    """
276
    Account-level SAS permissions.
277
    
278
    Attributes:
279
        read (bool): Read access to account resources
280
        write (bool): Write access to account resources
281
        delete (bool): Delete access to account resources
282
        list (bool): List access to account resources
283
        add (bool): Add access to account resources
284
        create (bool): Create access to account resources
285
        update (bool): Update access to account resources
286
        process (bool): Process access to account resources
287
    """
288
    
289
    def __init__(self, **kwargs):
290
        """Initialize with permission flags."""
291
    
292
    @classmethod
293
    def from_string(cls, permission: str) -> 'AccountSasPermissions':
294
        """Create permissions from string representation."""
295

296
class FileSystemSasPermissions:
297
    """
298
    File system-level SAS permissions.
299
    
300
    Attributes:
301
        read (bool): Read files and file properties
302
        add (bool): Add files to the file system
303
        create (bool): Create new files
304
        write (bool): Write to files
305
        delete (bool): Delete files
306
        list (bool): List files and directories
307
        move (bool): Move/rename files and directories
308
        execute (bool): Execute files (get file system info)
309
        ownership (bool): Change ownership of files and directories
310
        permissions (bool): Change permissions of files and directories
311
    """
312
    
313
    def __init__(self, **kwargs):
314
        """Initialize with permission flags."""
315
    
316
    @classmethod
317
    def from_string(cls, permission: str) -> 'FileSystemSasPermissions':
318
        """Create permissions from string representation."""
319

320
class DirectorySasPermissions:
321
    """
322
    Directory-level SAS permissions.
323
    
324
    Attributes:
325
        read (bool): Read directory contents and properties
326
        add (bool): Add files to the directory
327
        create (bool): Create new files and subdirectories
328
        write (bool): Write to files in the directory
329
        delete (bool): Delete files and subdirectories
330
        list (bool): List directory contents
331
        move (bool): Move/rename within the directory
332
        execute (bool): Execute (traverse) the directory
333
        ownership (bool): Change ownership
334
        permissions (bool): Change permissions
335
    """
336
    
337
    def __init__(self, **kwargs):
338
        """Initialize with permission flags."""
339
    
340
    @classmethod
341
    def from_string(cls, permission: str) -> 'DirectorySasPermissions':
342
        """Create permissions from string representation."""
343

344
class FileSasPermissions:
345
    """
346
    File-level SAS permissions.
347
    
348
    Attributes:
349
        read (bool): Read file content and properties
350
        add (bool): Add content to the file (append)
351
        create (bool): Create the file
352
        write (bool): Write to the file
353
        delete (bool): Delete the file
354
        move (bool): Move/rename the file
355
        execute (bool): Execute the file
356
        ownership (bool): Change file ownership
357
        permissions (bool): Change file permissions
358
    """
359
    
360
    def __init__(self, **kwargs):
361
        """Initialize with permission flags."""
362
    
363
    @classmethod
364
    def from_string(cls, permission: str) -> 'FileSasPermissions':
365
        """Create permissions from string representation."""
366
```
367

368
### Access Control Models
369

370
Data models for representing and managing POSIX-style access control lists and recursive ACL operations.
371

372
```python { .api }
373
class AccessControlChangeCounters:
374
    """
375
    Counters for tracking ACL change operations.
376
    
377
    Attributes:
378
        directories_successful (int): Number of directories successfully changed
379
        files_successful (int): Number of files successfully changed
380
        failure_count (int): Number of failures encountered
381
    """
382

383
class AccessControlChangeFailure:
384
    """
385
    Information about a failed ACL change operation.
386
    
387
    Attributes:
388
        name (str): Path name where the failure occurred
389
        is_directory (bool): Whether the failed path is a directory
390
        error_message (str): Error message describing the failure
391
    """
392

393
class AccessControlChangeResult:
394
    """
395
    Result of a recursive ACL change operation.
396
    
397
    Attributes:
398
        counters (AccessControlChangeCounters): Success/failure counters
399
        continuation_token (str): Token for continuing the operation
400
        batch_failures (List[AccessControlChangeFailure]): List of individual failures
401
    """
402

403
class AccessControlChanges:
404
    """
405
    Batch of ACL changes to apply.
406
    
407
    Attributes:
408
        acl (str): Access control list in POSIX format
409
        continue_on_failure (bool): Whether to continue on individual failures
410
    """
411
```
412

413
**Usage Examples:**
414

415
```python
416
from azure.storage.filedatalake import (
417
    DataLakeDirectoryClient,
418
    FileSystemSasPermissions,
419
    generate_file_system_sas
420
)
421

422
# Create directory client
423
directory_client = DataLakeDirectoryClient(
424
    account_url="https://mystorageaccount.dfs.core.windows.net",
425
    file_system_name="myfilesystem",
426
    directory_name="secure-data",
427
    credential="<account_key>"
428
)
429

430
# Set fine-grained ACLs
431
directory_client.set_access_control(
432
    owner="user1",
433
    group="secure-group",
434
    permissions="0750",  # rwxr-x---
435
    acl="user::rwx,group::r-x,other::---,user:analyst1:r-x,group:auditors:r--"
436
)
437

438
# Apply ACLs recursively with error handling
439
acl_result = directory_client.set_access_control_recursive(
440
    acl="user::rwx,group::r-x,other::---,user:analyst1:r-x",
441
    continue_on_failure=True
442
)
443

444
print(f"ACL Results:")
445
print(f"  Directories: {acl_result.counters.directories_successful}")
446
print(f"  Files: {acl_result.counters.files_successful}")
447
print(f"  Failures: {acl_result.counters.failure_count}")
448

449
if acl_result.batch_failures:
450
    print("Failures:")
451
    for failure in acl_result.batch_failures:
452
        print(f"  {failure.name}: {failure.error_message}")
453

454
# Generate SAS with specific permissions
455
permissions = FileSystemSasPermissions(read=True, list=True, execute=True)
456
sas_token = generate_file_system_sas(
457
    account_name="mystorageaccount",
458
    file_system_name="myfilesystem",
459
    account_key="<account_key>",
460
    permission=permissions,
461
    expiry=datetime.utcnow() + timedelta(hours=2),
462
    ip="192.168.1.0/24"  # Restrict to specific IP range
463
)
464
```