Создание SAS службы

Подпись общего доступа сервиса (SAS) делегирует доступ к ресурсу только в одном из сервисов хранения: Blob Storage (включая Data Lake Storage и dfs конечные точки), Queue Storage, Table Storage или Azure Files. URI для SAS на уровне сервиса состоит из URI ресурса, к которому SAS делегирует доступ, за которым следует токен SAS.

Токен SAS — это строка запроса, включающая всю необходимую информацию для авторизации запроса. Токен указывает ресурс, к которому клиент может получить доступ, предоставленные права и период времени, в течение которого подпись является действительной.

SAS также может указывать поддерживаемый IP-адрес или диапазон адресов, с которого могут исходить запросы, поддерживаемый протокол, с помощью которого может быть сделан запрос, или необязательный идентификатор политики доступа, связанный с запросом.

Наконец, каждый токен SAS содержит подпись.

Авторизация сервиса SAS

Вы защищаете аккаунт SAS, используя ключ аккаунта хранения. Когда вы создаёте аккаунт SAS, ваше клиентское приложение должно содержать ключ аккаунта.

Чтобы использовать учетные данные Microsoft Entra для защиты SAS для контейнера или blob, создайте пользовательскую делегацию SAS.

Поддержка сервиса SAS для доступа в области каталога

Сервис SAS поддерживает область действия каталога (sr=d), если версия авторизации (sv) — 2020-02-10 или позже. Семантика домена каталога (sr=d) схожа с семантикой области контейнера (sr=c), за исключением того, что доступ ограничен каталогом и любыми файлами и подкаталогами внутри него. При указании sr=d также требуется параметр запроса sdd.

Формат входа в строку для авторизации версии 2020-02-10 не изменяется.

Создание сервиса SAS

Следующее изображение представляет части URI сигнатуры общего доступа. Требуемые детали представлены оранжевым цветом. Поля, составляющие токен SAS, описаны в последующих разделах.

В следующих разделах описывается, как задать параметры, из которых состоит токен сервиса SAS.

Укажите поле signedVersion

Поле signedVersion (sv) содержит сервисную версию подписи общего доступа. Это значение указывает версию авторизации общего ключа, используемую этой подписью общего доступа (в поле).signature Значение также указывает версию сервиса для запросов, выполненных с помощью этой общей подписи доступа.

Для получения информации о том, какая версия используется при выполнении запросов через общую подпись доступа, см . раздел «Версионирование для Azure Storage services».

Для получения информации о том, как этот параметр влияет на авторизацию запросов, сделанных с помощью общей подписи доступа, см. раздел «Делегат доступа с общей подписью доступа».

Определите версию устаревшего запроса SAS

В устаревших случаях, где signedVersion не используется, Blob Storage применяет правила для определения версии. Для получения дополнительной информации об этих правилах см. раздел Versioning for Azure Storage services.

Укажите подписанный ресурс (только Blob Storage)

Необходимое поле signedResource (sr) указывает, какие ресурсы доступны с помощью подписанного URL-адреса. В следующей таблице описано, как обращаться к blob или контейнерному ресурсу в токене SAS.

Укажите подписанный ресурс (Azure Files)

SAS поддерживается для Azure Files версии 2015-02-21 и более поздней.

Поле signedResource указывает, какие ресурсы доступны через подпись общего доступа. В следующей таблице описано, как обращаться к файлу или ресурсу для совместного использования в URI.

Задайте параметры запроса для переопределения заголовков ответов (только Blob Storage и Azure Files)

Чтобы определить значения для определенных заголовков ответа, возвращаемых при использовании подписанного URL-адреса в запросе, можно указать заголовки ответа в параметрах запроса. Эта функция поддерживается с версии 2013-08-15 для Blob Storage и версии 2015-02-21 для Azure Files. Подписи общего доступа, использующие эту функцию, должны включать параметры, sv установленные до 2013-08-15 или позже для Blob Storage, или для 2015-02-21 Azure Files.

Заголовки ответов и соответствующие параметры запроса приведены в следующей таблице:

Например, если указать rsct=binary параметр запроса на подписи общего доступа, созданной с версии 2013-08-15 или выше, Content-Type заголовок ответа устанавливается на binary. Это значение переопределяет Content-Type значение заголовка, хранящееся для blob для запроса, использующего только эту подпись общего доступа.

Если вы создаёте сигнатуру общего доступа, которая указывает заголовки ответа как параметры запроса, вы должны включить их в строку от подписи к знаку, используемую для построения строки подписи. Для получения дополнительной информации см. раздел «Построить строку подписи» позже в этой статье. Для дополнительных примеров см. примеры Service SAS.

Укажите имя таблицы (только хранилище таблиц)

Поле tableName указывает название таблицы для совместного использования.

Укажите политику доступа

Раздел политики доступа в URI указывает период времени, в течение которого общая подпись доступа действительна, и какие права будут предоставлены пользователю. Части URI, составляющие политику доступа, описаны в следующей таблице:

¹ Это signedPermissions поле обязательно указано в URI, если оно не указано в политике сохранённого доступа.
²startPkПоля , startRk, endPkи endRk могут быть заданы только на ресурсах хранения таблиц.

Указание разрешений

Права, указанные для signedPermissions поля (sp) на токене SAS, указывают, какие операции клиент может выполнять над ресурсом.

Вы можете комбинировать разрешения, чтобы клиент мог выполнять несколько операций с одним и тем же SAS. При создании SAS необходимо включить разрешения в следующем порядке:

racwdxltmeop

Примеры допустимых параметров разрешений для контейнера включают rw, rd, rl, wd, wlи rl. Примеры недопустимых параметров включают wr, dr, lrи dw. Нельзя указывать обозначение разрешения более одного раза.

Сервис SAS не может предоставить доступ к определённым операциям:

• Контейнеры, очереди и таблицы нельзя создавать, удалять или перечислять.
• Метаданные и свойства контейнера не могут быть прочитаны или записаны.
• Очереди нельзя очистить, и их метаданные нельзя записать.
• Контейнеры не могут быть арендованы.

Чтобы создать SAS, предоставляющий доступ к этим операциям, используйте SAS учетной записи. Дополнительные сведения см. в статье СозданиеSAS учетной записи.

Поддерживаемые права доступа для каждого типа ресурсов описаны в следующих разделах.

Разрешения для каталога, контейнера или blob

Разрешения, поддерживаемые для каждого типа ресурса, описаны в следующей таблице.

Права на файл

Разрешения на использование

Разрешения для очереди

Разрешения для таблицы

Указание IP-адреса или диапазона IP-адресов

По состоянию на версию 2015-04-05 дополнительное signedIp поле (sip) указывает публичный IP-адрес или ряд публичных IP-адресов для приема запросов. Если IP-адрес, из которого создается запрос, не соответствует диапазону IP-адресов или диапазону адресов, указанному в маркере SAS, запрос не авторизован. Поддерживаются только IPv4-адреса.

Когда вы указываете диапазон IP-адресов, обратите внимание, что диапазон является инклюзивным. Например, указание sip=198.51.100.0 или sip=198.51.100.10-198.51.100.20 в SAS ограничивает запрос на эти IP-адреса.

В следующей таблице описывается, стоит ли включать поле signedIp в токен SAS для определённого сценария, исходя из клиентской среды и расположения аккаунта хранения.

Указание протокола HTTP

По состоянию на версию 2015-04-05 поле option signedProtocol (spr) указывает протокол, разрешённый для запроса, сделанного через SAS. Возможные значения : HTTPS и HTTP (https,http) или только HTTPS (https). Значение по умолчанию — https,http. Обратите внимание, что только HTTP не является разрешённым значением.

Укажите диапазоны доступа к таблице

Поля startPk, startRk, endPkи endRk определяют ряд сущностей таблицы, связанных с общей подписью доступа. Запросы к таблице возвращают только результаты, находящиеся в пределах диапазона, и попытки использовать подпись общего доступа для добавления, обновления или удаления сущностей вне этого диапазона будут неудачными.

Если startPk равно endPk, подпись общего доступа авторизирует доступ к сущностям только в одном разделе таблицы.

Если startPk равно endPk и startRk равно endRk, подпись общего доступа может получить доступ только к одной сущности в одном разделе.

Чтобы понять, как эти поля ограничивают доступ к сущностям в таблице, обратитесь к следующей таблице:

Указание глубины каталога

Когда signedResource поле указывает каталог (sr=d), необходимо также указать signedDirectoryDepth поле (sdd) для обозначения количества подкаталогов в корневом каталоге. Значение поля sdd должно быть неотрицательное целое число.

Например, корневой каталог https://{account}.blob.core.windows.net/{container}/ имеет глубину 0. Каждая подкаталога в корневом каталоге добавляется к глубине на 1. Каталог https://{account}.blob.core.windows.net/{container}/d1/d2 имеет глубину 2.

Это поле поддерживается с версией 2020-02-10 или более позднее.

Укажите подписанный идентификатор

Когда вы указываете поле signedIdentifier в URI, вы связываете указанную подпись общего доступа с соответствующей политикой сохранённого доступа. Политика сохранённого доступа обеспечивает дополнительный контроль над одной или несколькими подписями общего доступа, включая возможность отзыва подписи при необходимости. Каждый контейнер, очередь, таблица или общий ресурс может содержать до пяти сохранённых политик доступа.

В следующей таблице описано, как обращаться к подписанному идентификатору на URI:

Политика сохранённого доступа включает подписанный идентификатор — значение до 64 символов, уникальное внутри ресурса. Вы можете указать значение этого подписанного идентификатора для signedidentifier поля в URI для подписи общего доступа. Когда вы указываете подписанный идентификатор на URI, вы связываете подпись с политикой сохранённого доступа. Чтобы установить политику доступа на уровне контейнера с помощью REST API, см. раздел «Делегат доступа с общей подписью доступа».

Указание области шифрования

Используя signedEncryptionScope поле на URI, можно указать область шифрования, которую может использовать клиентское приложение. Он обеспечивает серверное шифрование с указанным областью шифрования при загрузке blob (PUT) с помощью токена SAS. GET и HEAD не будут ограничены и выполняются как раньше.

Следующая таблица описывает, как обращаться к знаковому диапазону шифрования на URI:

Это поле поддерживается с версией 2020-12-06 и более поздней. Если вы добавите версию ses с предыдущей поддерживаемой, сервис возвращает код ответа на ошибку 403 (Запрещён).

Если вы установите область шифрования по умолчанию для контейнера или файловой системы, ses параметр запроса будет учитывать политику шифрования контейнера. Если между параметром запроса ses и заголовком x-ms-default-encryption-scope имеется несоответствие, а заголовок x-ms-deny-encryption-scope-override имеет значение true, служба возвращает код ответа на ошибку 403 (запрещено).

Когда вы указываете x-ms-encryption-scope заголовок и ses параметр запроса в запросе PUT, сервис возвращает код ответа на ошибку 400 (Плохой запрос), если возникает несоответствие.

Указание подписи

Вы используете подпись в URI для авторизации запроса, сделанного с помощью подписи общего доступа. Azure Storage использует схему авторизации Shared Key для авторизации сервиса SAS.

Следующая таблица описывает, как задать подпись на URI:

Постройте строку подписи

Чтобы построить строку подписи общего доступа, сначала постройте строку в знак из полей, составляющих запрос, закодуйте строку как UTF-8, а затем вычислите подпись с помощью алгоритма HMAC-SHA256. Поля, включенные в вход, должны быть декодированы ПО URL-адресу.

Версия 2020-12-06 и более поздних версий

Версия 2020-12-06 добавляет поддержку поля знакового шифрования. Для построения строк-to-sign для ресурсов Blob Storage используйте следующий формат:

StringToSign = signedPermissions + "\n" +  
               signedStart + "\n" +  
               signedExpiry + "\n" +  
               canonicalizedResource + "\n" +  
               signedIdentifier + "\n" +  
               signedIP + "\n" +  
               signedProtocol + "\n" +  
               signedVersion + "\n" +  
               signedResource + "\n" +
               signedSnapshotTime + "\n" +
               signedEncryptionScope + "\n" +
               rscc + "\n" +  
               rscd + "\n" +  
               rsce + "\n" +  
               rscl + "\n" +
               rsct

Версия 2018-11-09 и более поздние

Версия 2018-11-09 добавляет поддержку полей времени подписанного ресурса и подписанного снимка blob. Эти поля должны быть включены в систему string-to-sign. Для построения строк-to-sign для ресурсов Blob Storage используйте следующий формат:

StringToSign = signedPermissions + "\n" +  
               signedStart + "\n" +  
               signedExpiry + "\n" +  
               canonicalizedResource + "\n" +  
               signedIdentifier + "\n" +  
               signedIP + "\n" +  
               signedProtocol + "\n" +  
               signedVersion + "\n" +  
               signedResource + "\n"
               signedSnapshotTime + "\n" +
               rscc + "\n" +  
               rscd + "\n" +  
               rsce + "\n" +  
               rscl + "\n" +  
               rsct  

Версия 2015-04-05 и более поздние

Версия 2015-04-05 добавляет поддержку подписанного IP и подписанных протокольных полей. Эти поля должны быть включены в систему string-to-sign. Для построения строки в знак для ресурсов Blob Storage или Azure Files используйте следующий формат:

StringToSign = signedPermissions + "\n" +  
               signedStart + "\n" +  
               signedExpiry + "\n" +  
               canonicalizedResource + "\n" +  
               signedIdentifier + "\n" +  
               signedIP + "\n" +  
               signedProtocol + "\n" +  
               signedVersion + "\n" +  
               rscc + "\n" +  
               rscd + "\n" +  
               rsce + "\n" +  
               rscl + "\n" +  
               rsct  

Для построения строк-to-sign для ресурсов хранения таблиц используйте следующий формат:

StringToSign = signedPermissions + "\n" +  
               signedStart + "\n" +  
               signedExpiry + "\n" +  
               canonicalizedResource + "\n" +  
               signedIdentifier + "\n" +  
               signedIP + "\n" +  
               signedProtocol + "\n" +  
               signedVersion + "\n" +  
               startingPartitionKey + "\n"  
               startingRowKey + "\n"  
               endingPartitionKey + "\n"  
               endingRowKey  
  

Для построения строк-to-sign для ресурсов хранилища в очереди используйте следующий формат:

StringToSign = signedPermissions + "\n" +  
               signedStart + "\n" +  
               signedExpiry + "\n" +  
               canonicalizedResource + "\n" +  
               signedIdentifier + "\n" +  
               signedIP + "\n" +  
               signedProtocol + "\n" +  
               signedVersion  
  

Версии 2013-08-15 по 2015-02-21

Чтобы построить строку для ресурсов Blob Storage или Azure Files с помощью версий 2013-08-15 по 2015-02-21, используйте следующий формат. Для Azure Files поддерживается SAS с версии 2015-02-21.

StringToSign = signedPermissions + "\n" +  
               signedStart + "\n" +  
               signedExpiry + "\n" +  
               canonicalizedResource + "\n" +  
               signedIdentifier + "\n" +  
               signedVersion + "\n" +  
               rscc + "\n" +  
               rscd + "\n" +  
               rsce + "\n" +  
               rscl + "\n" +  
               rsct  

Для построения строки в знак таблицы используйте следующий формат:

StringToSign = signedPermissions + "\n" +  
               signedStart + "\n" +  
               signedExpiry + "\n" +  
               canonicalizedResource + "\n" +  
               signedIdentifier + "\n" +  
               signedVersion + "\n" +  
               startPk + "\n" +  
               startRk + "\n" +  
               endPk + "\n" +  
               endRk  
  

Для построения строки в знак очереди используйте следующий формат:

StringToSign = signedPermissions + "\n" +  
               signedStart + "\n" +  
               signedExpiry + "\n" +  
               canonicalizedResource + "\n" +  
               signedIdentifier + "\n" +  
               signedVersion 

Версия 2012-02-12

Для построения строк-to-sign для ресурсов Blob Storage для версии 2012-02-12 используйте следующий формат:

StringToSign = signedPermissions + "\n" +  
               signedStart + "\n" +  
               signedExpiry + "\n" +  
               canonicalizedResource + "\n" +  
               signedIdentifier + "\n" +  
               signedVersion  

Версии, ранее 12.02.2012

Для построения строк-to-sign для ресурсов Blob Storage для версий, более ранних за 12.02.2012, используйте следующий формат:

StringToSign = signedPermissions + "\n" +  
               signedStart + "\n" +  
               signedExpiry + "\n" +  
               canonicalizedResource + "\n" +  
               signedIdentifier  
  

Когда вы строите строку для подписания, имейте в виду следующее:

• Если поле необязательно и не предусмотрено в запросе, укажите пустую строку для этого поля. Не забудьте включить новый символ (\n) после пустой строки.

• String-to-sign для таблицы должны включать дополнительные параметры, даже если это пустые строки.

• signedpermission Часть строки должна содержать обозначения разрешений в фиксированном порядке, специфичном для каждого типа ресурса. Любая комбинация этих разрешений допустима, но порядок писем должен совпадать с порядком в следующей таблице.

  Тип ресурса	Порядок разрешений
  блоб	RACWD
  Контейнер	racwdl
  Очередь	raup
  Файл	rcwd
  Поделиться	rcwdl
  таблица	Рауд

  Например, примеры допустимых настроек разрешений для контейнера включают rw, rd, rl, wd, wl, и rl. Примеры недопустимых параметров включают wr, dr, lrи dw. Указание назначения разрешений несколько раз не разрешено.

• Укажите значение для части signedIdentifier строки, если вы связываете запрос с политикой сохранённого доступа.

• Подпись общего доступа, указывающая версию сервиса хранения, выпущенную раньше 2012-02-12, может использовать только blob или контейнер, и должна опускать signedVersion символ newline перед ним.

• canonicalizedResource часть строки является каноническим путем к подписанному ресурсу. Он должен содержать имя сервиса (Blob Storage, Table Storage, Queue Storage или Azure Files) для версии 2015-02-21 и более поздне, имя аккаунта хранения и имя ресурса, при этом должен быть декодирован по URL. Названия blob должны включать контейнер blob. Имена таблиц должны быть строчными.

Канонизированная строка ресурса для контейнера, очереди, таблицы или общего файла должна опускать слэш (/) для SAS, предоставляющего доступ к этому объекту.

В следующих примерах показано, как создать canonicalizedResource часть строки в зависимости от типа ресурса.

Контейнеры

Для версии 2015-02-21 и более позднее:

URL = https://myaccount.blob.core.windows.net/music  
canonicalizedResource = "/blob/myaccount/music"  

Для версий до 21.02.2015:

URL = https://myaccount.blob.core.windows.net/music
canonicalizedResource = "/myaccount/music"  

Blobs

Для версии 2015-02-21 и более позднее:

URL = https://myaccount.blob.core.windows.net/music/intro.mp3  
canonicalizedResource = "/blob/myaccount/music/intro.mp3"  

Для версий до 21.02.2015:

URL = https://myaccount.blob.core.windows.net/music/intro.mp3
canonicalizedResource = "/myaccount/music/intro.mp3"  

Файловые ресурсы

URL = https://myaccount.file.core.windows.net/music
canonicalizedResource = "/file/myaccount/music"  

Files

URL = https://myaccount.file.core.windows.net/music/intro.mp3
canonicalizedResource = "/file/myaccount/music/intro.mp3"  

Queues

Для версии 2015-02-21 и более позднее:

URL = https://myaccount.queue.core.windows.net/thumbnails  
canonicalizedResource = "/queue/myaccount/thumbnails"  

Для версий до 21.02.2015:

URL = https://myaccount.queue.core.windows.net/thumbnails  
canonicalizedResource = "/myaccount/thumbnails"  

Tables

Если подписанный ресурс является таблицей, убедитесь, что название таблицы строчным в канонизированном формате.

Для версии 2015-02-21 и более позднее:

URL = https://myaccount.table.core.windows.net/Employees(PartitionKey='Jeff',RowKey='Price')  
canonicalizedResource = "/table/myaccount/employees"  

Для версий до 21.02.2015:

URL = https://myaccount.table.core.windows.net/Employees(PartitionKey='Jeff',RowKey='Price')  
canonicalizedResource = "/myaccount/employees"  

Срок жизни и отмена подписи общего доступа

Подписи общего доступа предоставляют пользователям права на доступ к ресурсам хранения аккаунтов. Когда вы планируете использовать SAS, подумайте о сроке действия SAS и о том, может ли ваше приложение потребовать отмену прав доступа при определённых обстоятельствах.

Ad hoc политика SAS против сохранённого доступа

Сервисный SAS может иметь одну из двух форм:

• Ad hoc SAS: Когда вы создаёте ad hoc SAS, время запуска, срок действия и разрешения для SAS указаны в URI SAS (или подразумеваются, если время запуска опущено). SAS любого типа может быть одноразовым.

  Вы можете управлять сроком службы ad hoc SAS, используя поле signedExpiry . Если вы хотите продолжать предоставлять клиенту доступ к ресурсу после истечения срока действия, необходимо выпустить новую подпись. Мы рекомендуем ограничивать срок действия подписи с общим доступом коротким. До версии 2012-02-12 подпись общего доступа, не связанная с политикой сохранённого доступа, не могла иметь активный период, превышающий один час.

• SAS с политикой сохранённого доступа: В контейнере ресурсов определяется политика доступа к хранилищу, который может быть blob-контейнером, таблицей, очередью или файловым ресурсом. Вы можете использовать политику сохранённого доступа для управления ограничениями для одной или нескольких подписей общего доступа. Когда вы связываете SAS с сохранённой политикой доступа, SAS наследует ограничения (то есть время запуска, срок действия и разрешения), которые определяются для политики сохранённого доступа.

  Политика сохранённого доступа представлена полем signedIdentifier на URI. Политика сохранённого доступа обеспечивает дополнительный контроль над одной или несколькими подписями общего доступа, включая возможность отзыва подписи при необходимости.

Отменить SAS

Поскольку SAS URI — это URL, любой, кто получит SAS, может им пользоваться, независимо от того, кто его создал. Если SAS публикуется публично, им может пользоваться любой человек в мире. SAS предоставляет доступ к ресурсам каждому, кто ими владеет, пока не произойдёт одно из четырёх вещей:

• Срок истечения, указанный в ad hoc SAS, достигнут.

• Время истечения, указанное в политике сохраненного доступа, на которую ссылается SAS, достигается, если ссылка на сохраненную политику доступа и политика доступа указывает время истечения.

  Срок истечения можно достичь либо из-за истечения интервала, либо потому, что вы изменили политику сохранённого доступа, добавив срок действия в прошлом, что является одним из способов отменить SAS.

• Политика сохранённого доступа, на которую ссылается SAS, удаляется, что аннулирует SAS. Если Azure Storage не может найти политику доступа, указанную в подписи общего доступа, клиент не сможет получить доступ к ресурсу, указанному URI.

  Если вы заново создаёте политику доступа с точно таким же именем, как и удалённая политика, все существующие токены SAS снова станут действительными согласно разрешениям, связанным с этой политикой доступа. Это предполагает, что срок годности SAS ещё не истёк. Если вы собираетесь отменить SAS, обязательно используйте другое имя при повторном создании политики доступа с истечением срока действия в будущем.

• Ключ аккаунта, использованный для создания SAS, генерируется. Восстановление ключа учетной записи приводит к тому, что все компоненты приложения, использующие этот ключ, не авторизуются, пока не будут обновлены для использования либо другого действительного ключа аккаунта, либо вновь восстановленного ключа аккаунта. Восстановление ключа аккаунта — единственный способ сразу отменить ad hoc SAS.

В качестве лучшей практики мы рекомендуем использовать политику сохранённого доступа с сервисом SAS. Если вы решите не использовать политику сохранённого доступа, обязательно сократите период, в течение которого ad hoc SAS действует. Для получения дополнительной информации о связи сервиса SAS с политикой сохранённого доступа см. раздел «Определить политику сохранённого доступа».

Пример SAS службы

Следующий пример показывает blob URI с добавленным токеном сервиса SAS. Токен сервиса SAS предоставляет разрешения на чтение и запись blob.

https://myaccount.blob.core.windows.net/sascontainer/blob1.txt?sp=rw&st=2023-05-24T01:13:55Z&se=2023-05-24T09:13:55Z&sip=198.51.100.10-198.51.100.20&spr=https&sv=2022-11-02&sr=b&sig=<signature>

Каждая часть URI описана в следующей таблице:

См. также

• Делегирование доступа с помощью подписанного URL-адреса
• Создание SAS для делегирования прав пользователя
• Создать учетную запись SAS
• SAS error codes (Коды ошибок SAS)