Create Permission

The Create Permission operation creates a permission (a security descriptor) at the share level. You can use the created security descriptor for the files and directories in the share. This API is available as of version 2019-02-02.

Protocol availability

Enabled file share protocol	Available
SMB
NFS

Request

You can construct the Create Permission request as shown here. We recommend that you use HTTPS.

Method	Request URI	HTTP version
PUT	https://myaccount.file.core.windows.net/myshare?restype=share&comp=filepermission	HTTP/1.1

Replace the path components shown in the request URI with your own components, as shown here:

Path component	Description
myaccount	The name of your storage account.
myshare	The name of your file share. The name can contain only lowercase characters.

For information about path-naming restrictions, see Name and reference shares, directories, files, and metadata.

URI parameters

You can specify additional parameters on the request URI as shown here:

Parameter	Description
timeout	Optional. The timeout parameter is expressed in seconds. For more information, see Set time-outs for Queue service operations.

Request headers

The required and optional request headers are described in the following table:

Request header	Description
Authorization	Required. Specifies the authorization scheme, storage account name, and signature. For more information, see Authorize requests to Azure Storage.
Date or x-ms-date	Required. Specifies the Coordinated Universal Time (UTC) for the request. For more information, see Authorize requests to Azure Storage.
x-ms-version	Optional. Specifies the version of the operation to use for this request. For more information, see Versioning for Azure Storage services.
x-ms-client-request-id	Optional. Provides a client-generated, opaque value with a 1-kibibyte (KiB) character limit that's recorded in the logs when logging is configured. We highly recommend that you use this header to correlate client-side activities with requests that the server receives. For more information, see Monitor Azure Files.
x-ms-file-request-intent	Required if Authorization header specifies an OAuth token. Acceptable value is backup. This header specifies that the Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action or Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action should be granted if they are included in the RBAC policy assigned to the identity that is authorized using the Authorization header. Available for version 2022-11-02 and later.

Request body

You create a security descriptor by placing a JSON object in the request body. The JSON object can have the following fields:

JSON key	Description
permission	Required. Permission in the Security Descriptor Definition Language (SDDL) or (version 2024-11-04 or later) in base64-encoded binary security descriptor format. The security descriptor must have an owner, group, and discretionary access control list (DACL).
format	Optional. Version 2024-11-04 or later. Describes the format of the permission provided in permission. If defined, this field must be set to "sddl" or "binary". If omitted, the default of "sddl" is used.

If using SDDL, the SDDL string format of the security descriptor shouldn't have a domain relative identifier (for example, DU, DA, or DD) in it.

{
    "permission": "<SDDL>"
}

In version 2024-11-04 or later, you can optionally explicitly specify that the permission is in SDDL format:

{
    "format": "sddl",
    "permission": "<SDDL>"
}

In version 2024-11-04 or later, you can also create a permission in base-64 encoded binary format. In that case, you must explicitly specify that the format is "binary".

{
    "format": "binary",
    "permission": "<base64>"
}

Sample request

PUT https://myaccount.file.core.windows.net/myshare?restype=share&comp=filepermission HTTP/1.1  

Request Headers:
x-ms-date: Mon, 27 Jan 2014 22:15:50 GMT
x-ms-version: 2014-02-14
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=

Request Body:
{"permission": "O:S-1-5-21-2127521184-1604012920-1887927527-21560751G:S-1-5-21-2127521184-1604012920-1887927527-513D:AI(A;;FA;;;SY)(A;;FA;;;BA)(A;;0x1200a9;;;S-1-5-21-397955417-626881126-188441444-3053964)"}

Response

The response includes an HTTP status code and a set of response headers.

Status code

A successful operation returns status code 201 (Created).

For information about status codes, see Status and error codes.

Response headers

The response for this operation includes the following headers. The response might also include additional standard HTTP headers. All standard headers conform to the HTTP/1.1 protocol specification.

Response header	Description
x-ms-request-id	Uniquely identifies the request that was made, and you can use it to troubleshoot the request.
x-ms-version	Indicates the Azure Files version that was used to execute the request.
Date or x-ms-date	A UTC date/time value that's generated by the service and that indicates the time when the response was initiated.
x-ms-file-permission-key	The key of the permission created.
x-ms-client-request-id	Can be used to troubleshoot requests and their corresponding responses. The value of this header is equal to the value of the x-ms-client-request-id header if it's present in the request and the value contains no more than 1,024 visible ASCII characters. If the x-ms-client-request-id header isn't present in the request, it isn't present in the response.

Response body

None.

Authorization

Only the account owner or a caller that has a share-level shared access signature with write and delete authorization may call this operation.

Remarks

To make the SDDL format portable across domain and non-domain joined machines, the caller can use the ConvertSecurityDescriptorToStringSecurityDescriptor Windows function to get the base SDDL string for the security descriptor. The caller can then replace the SDDL notation that's listed in the following table with the correct SID value.

Name	SDDL notation	SID value	Description
Local Administrator	LA	S-1-5-21-domain-500	A user account for the system administrator. By default, it's the only user account that's given full control over the system.
Local Guests	LG	S-1-5-21-domain-501	A user account for people who don't have individual accounts. This user account doesn't require a password. By default, the Guest account is disabled.
Certificate Publishers	CA	S-1-5-21-domain-517	A global group that includes all computers that are running an enterprise certification authority. Certificate Publishers are authorized to publish certificates for User objects in Active Directory.
Domain Admins	DA	S-1-5-21-domain-512	A global group whose members are authorized to administer the domain. By default, the Domain Admins group is a member of the Administrators group on all computers that have joined a domain, including the Domain Controllers. Domain Admins is the default owner of any object that's created by any member of the group.
Domain Controllers	DD	S-1-5-21-domain-516	A global group that includes all Domain Controllers in the domain. New Domain Controllers are added to this group by default.
Domain Users	DU	S-1-5-21-domain-513	A global group that, by default, includes all user accounts in a domain. When you create a user account in a domain, the account is added to this group by default.
Domain Guests	DG	S-1-5-21-domain-514	A global group that, by default, has only one member, the domain's built-in Guest account.
Domain Computers	DC	S-1-5-21-domain-515	A global group that includes all clients and servers that have joined the domain.
Schema Admins	SA	S-1-5-21root domain-518	A universal group in a native-mode domain; a global group in a mixed-mode domain. The group is authorized to make schema changes in Active Directory. By default, the only member of the group is the Administrator account for the forest root domain.
Enterprise Admins	EA	S-1-5-21root domain-519	A universal group in a native-mode domain; a global group in a mixed-mode domain. The group is authorized to make forest-wide changes in Active Directory, such as adding child domains. By default, the only member of the group is the Administrator account for the forest root domain.
Group Policy Creator Owners	PA	S-1-5-21-domain-520	A global group that's authorized to create new Group Policy objects in Active Directory.
RAS and IAS Servers	RS	S-1-5-21-domain-553	A domain local group. By default, this group has no members. Remote Access Server (RAS) and Internet Authentication Service (IAS) servers in this group have Read Account Restrictions and Read Logon Information access to User objects in the Active Directory domain local group.
Enterprise Read-only Domain Controllers	ED	S-1-5-21-domain-498	A universal group. Members of this group are Read-only Domain Controllers in the enterprise.
Read-only Domain Controllers	RO	S-1-5-21-domain-521	A global group. Members of this group are Read-only Domain Controllers in the domain.