Autorizar com a Chave Partilhada

Todos os pedidos feitos relativamente a um serviço de armazenamento têm de ser autorizados, a menos que o pedido seja para um recurso de blob ou contentor que tenha sido disponibilizado para acesso público ou assinado. Uma opção para autorizar um pedido é utilizar a Chave Partilhada, descrita neste artigo.

Dica

O Armazenamento do Azure fornece integração com Microsoft Entra ID para autorização baseada em identidade de pedidos para os serviços Blob, Ficheiro, Fila e Tabela. Com Microsoft Entra ID, pode utilizar o controlo de acesso baseado em funções (RBAC) para conceder acesso a recursos de blobs, ficheiros, filas e tabelas a utilizadores, grupos ou aplicações. Microsoft Entra ID podem ser utilizadas para autorizar o acesso aos recursos de armazenamento sem armazenar as chaves de acesso da conta nas suas aplicações, tal como faz com a Chave Partilhada. Para obter mais informações, veja Autorizar com Microsoft Entra ID.

Os serviços Blob, Fila, Tabela e Ficheiro suportam os seguintes esquemas de autorização de Chave Partilhada para a versão 2009-09-19 e posterior (para o serviço Blob, Fila e Tabela) e a versão 2014-02-14 e posterior (para o serviço Ficheiro):

  • Chave Partilhada para Blob, Fila e Serviços de Ficheiros. Utilize o esquema de autorização de Chave Partilhada para fazer pedidos relativamente aos serviços Blob, Fila e Ficheiro. A autorização de Chave Partilhada na versão 2009-09-19 e posterior suporta uma cadeia de assinatura aumentada para maior segurança e requer que atualize o seu serviço para autorizar a utilização desta assinatura aumentada.

  • Chave Partilhada para o Serviço de Tabelas. Utilize o esquema de autorização de Chave Partilhada para fazer pedidos no serviço Tabela com a API REST. A autorização de Chave Partilhada para o serviço Tabela na versão 2009-09-19 e posterior utiliza a mesma cadeia de assinatura que nas versões anteriores do serviço Tabela.

  • Chave Partilhada Lite. Utilize o esquema de autorização Lite de Chave Partilhada para fazer pedidos nos serviços Blob, Fila, Tabela e Ficheiro.

    Para a versão 2009-09-19 e posterior dos serviços Blob e Fila, a autorização Shared Key Lite suporta a utilização de uma cadeia de assinatura idêntica à que foi suportada em relação à Chave Partilhada em versões anteriores dos serviços Blob e Fila. Por conseguinte, pode utilizar a Chave Partilhada Lite para fazer pedidos nos serviços Blob e Fila sem atualizar a cadeia de assinatura.

Um pedido autorizado requer dois cabeçalhos: o Date cabeçalho ou x-ms-date e o Authorization cabeçalho. As secções seguintes descrevem como construir estes cabeçalhos.

Importante

O Armazenamento do Azure suporta HTTP e HTTPS, mas a utilização de HTTPS é altamente recomendada.

Nota

Um contentor ou blob pode ser disponibilizado para acesso público ao definir as permissões de um contentor. Para obter mais informações, veja Gerir o Acesso aos Recursos de Armazenamento do Azure. Um contentor, blob, fila ou tabela pode ser disponibilizado para acesso assinado através de uma assinatura de acesso partilhado; uma assinatura de acesso partilhado é autorizada através de um mecanismo diferente. Veja Delegar o acesso com uma assinatura de acesso partilhado para obter mais detalhes.

Especificar o cabeçalho Data

Todos os pedidos autorizados têm de incluir o carimbo de data/hora da Hora Universal Coordenada (UTC) do pedido. Pode especificar o carimbo de data/hora no x-ms-date cabeçalho ou no cabeçalho HTTP/HTTPS Date padrão. Se ambos os cabeçalhos forem especificados no pedido, o valor de x-ms-date é utilizado como a hora de criação do pedido.

Os serviços de armazenamento garantem que um pedido não tem mais de 15 minutos quando chega ao serviço. Isto protege contra certos ataques de segurança, incluindo ataques de repetição. Quando esta verificação falha, o servidor devolve o código de resposta 403 (Proibido).

Nota

O x-ms-date cabeçalho é fornecido porque algumas bibliotecas de cliente HTTP e proxies definem automaticamente o Date cabeçalho e não dão ao programador a oportunidade de ler o respetivo valor para o incluir no pedido autorizado. Se definir x-ms-date, construa a assinatura com um valor vazio para o Date cabeçalho.

Especificar o cabeçalho Autorização

Um pedido autorizado tem de incluir o Authorization cabeçalho. Se este cabeçalho não estiver incluído, o pedido é anónimo e só é efetuado com êxito num contentor ou blob marcado para acesso público ou num contentor, blob, fila ou tabela para o qual foi fornecida uma assinatura de acesso partilhado para acesso delegado.

Para autorizar um pedido, tem de assinar o pedido com a chave da conta que está a fazer o pedido e transmitir essa assinatura como parte do pedido.

O formato do cabeçalho é o Authorization seguinte:

Authorization="[SharedKey|SharedKeyLite] <AccountName>:<Signature>"  

em que SharedKey ou SharedKeyLite é o nome do esquema de autorização, AccountName é o nome da conta que pede o recurso e Signature é um Código de Autenticação de Mensagens (HMAC) baseado em Hash construído a partir do pedido e calculado através do algoritmo SHA256 e, em seguida, codificado através da codificação Base64.

Nota

É possível pedir um recurso que reside abaixo de uma conta diferente, se esse recurso estiver acessível publicamente.

As secções seguintes descrevem como construir o Authorization cabeçalho.

Construir a cadeia de assinatura

A forma como constrói a cadeia de assinatura depende do serviço e da versão que está a autorizar e do esquema de autorização que está a utilizar. Ao construir a cadeia de assinatura, tenha em atenção o seguinte:

  • A parte VERBO da cadeia é o verbo HTTP, como GET ou PUT, e tem de estar em maiúsculas.

  • Para autorização de Chave Partilhada para os serviços Blob, Fila e Ficheiro, cada cabeçalho incluído na cadeia de assinatura só pode aparecer uma vez. Se algum cabeçalho estiver duplicado, o serviço devolve o código de estado 400 (Pedido Incorreto).

  • Os valores de todos os cabeçalhos HTTP padrão têm de ser incluídos na cadeia pela ordem apresentada no formato de assinatura, sem os nomes dos cabeçalhos. Estes cabeçalhos podem estar vazios se não estiverem a ser especificados como parte do pedido; nesse caso, só é necessário o caráter de nova linha.

  • Se o x-ms-date cabeçalho for especificado, pode ignorar o Date cabeçalho, independentemente de estar especificado no pedido, e simplesmente especificar uma linha vazia para a Date parte da cadeia de assinatura. Neste caso, siga as instruções na secção Construir a cadeia de cabeçalhos canonizados para adicionar o x-ms-date cabeçalho.

    É aceitável especificar e x-ms-dateDate; neste caso, o serviço utiliza o valor de x-ms-date.

  • Se o x-ms-date cabeçalho não for especificado, especifique o Date cabeçalho na cadeia de assinatura, sem incluir o nome do cabeçalho.

  • Todos os carateres de nova linha (\n) apresentados são necessários na cadeia de assinatura.

  • A cadeia de assinatura inclui cabeçalhos canonizados e cadeias de recursos canonizadas. Canonizar estas cadeias coloca-as num formato padrão que é reconhecido pelo Armazenamento do Azure. Para obter informações detalhadas sobre a construção das CanonicalizedHeaders cadeias e CanonicalizedResource que constituem parte da cadeia de assinatura, consulte as secções adequadas mais à frente neste tópico.

Serviços de Blobs, Filas e Ficheiros (autorização de Chave Partilhada)

Para codificar a cadeia de assinatura de Chave Partilhada para um pedido na versão 2009-09-19 e posterior do serviço Blob ou Fila e na versão 2014-02-14 e posterior do serviço Ficheiro, utilize o seguinte formato:

StringToSign = VERB + "\n" +  
               Content-Encoding + "\n" +  
               Content-Language + "\n" +  
               Content-Length + "\n" +  
               Content-MD5 + "\n" +  
               Content-Type + "\n" +  
               Date + "\n" +  
               If-Modified-Since + "\n" +  
               If-Match + "\n" +  
               If-None-Match + "\n" +  
               If-Unmodified-Since + "\n" +  
               Range + "\n" +  
               CanonicalizedHeaders +   
               CanonicalizedResource;  

Importante

Na versão atual, o campo Content-Length tem de ser uma cadeia vazia se o comprimento do conteúdo do pedido for zero. Na versão 2014-02-14 e anterior, o comprimento do conteúdo foi incluído mesmo que zero. Veja abaixo para obter mais informações sobre o comportamento antigo.

O exemplo seguinte mostra uma cadeia de assinatura para uma operação Obter Blob . Quando não existe nenhum valor de cabeçalho, o caráter de nova linha só é especificado.

GET\n\n\n\n\n\n\n\n\n\n\n\nx-ms-date:Fri, 26 Jun 2015 23:39:12 GMT\nx-ms-version:2015-02-21\n/myaccount/mycontainer\ncomp:metadata\nrestype:container\ntimeout:20  

Dividir esta linha por linha mostra cada parte da mesma cadeia:

GET\n /*HTTP Verb*/  
\n    /*Content-Encoding*/  
\n    /*Content-Language*/  
\n    /*Content-Length (empty string when zero)*/  
\n    /*Content-MD5*/  
\n    /*Content-Type*/  
\n    /*Date*/  
\n    /*If-Modified-Since */  
\n    /*If-Match*/  
\n    /*If-None-Match*/  
\n    /*If-Unmodified-Since*/  
\n    /*Range*/  
x-ms-date:Fri, 26 Jun 2015 23:39:12 GMT\nx-ms-version:2015-02-21\n    /*CanonicalizedHeaders*/  
/myaccount /mycontainer\ncomp:metadata\nrestype:container\ntimeout:20    /*CanonicalizedResource*/  

Em seguida, codifica esta cadeia com o algoritmo HMAC-SHA256 através da cadeia de assinatura codificada utF-8, construa o Authorization cabeçalho e adicione o cabeçalho ao pedido. O exemplo seguinte mostra o Authorization cabeçalho da mesma operação:

Authorization: SharedKey myaccount:ctzMq410TV3wS7upTBcunJTDLEJwMAZuFPfr0mrrA08=  

Para utilizar a autorização de Chave Partilhada com a versão 2009-09-19 e posterior dos serviços Blob e Fila, tem de atualizar o código para utilizar esta cadeia de assinatura aumentada.

Se preferir migrar o código para a versão 2009-09-19 ou posterior dos serviços Blob e Fila com o menor número de alterações possíveis, pode modificar os cabeçalhos existentes Authorization para utilizar a Chave Partilhada Lite em vez da Chave Partilhada. O formato de assinatura exigido pela Chave Partilhada Lite é idêntico ao necessário para a Chave Partilhada por versões dos serviços Blob e Fila anteriores a 2009-09-19.

Importante

Se estiver a aceder à localização secundária numa conta de armazenamento para a qual a georreplicação de acesso de leitura (RA-GRS) está ativada, não inclua a -secondary designação no cabeçalho de autorização. Para fins de autorização, o nome da conta é sempre o nome da localização primária, mesmo para acesso secundário.

Cabeçalho Content-Length na versão 2014-02-14 e anterior

Ao utilizar a versão 2014-02-14 ou anterior, se Content-Length for zero, defina a Content-Length parte de StringToSign como 0. Normalmente, esta seria uma cadeia vazia.

Por exemplo, para o pedido seguinte, o valor do Content-Length cabeçalho é incluído no StringToSign mesmo quando é zero.

PUT http://myaccount/mycontainer?restype=container&timeout=30 HTTP/1.1  
x-ms-version: 2014-02-14  
x-ms-date: Fri, 26 Jun 2015 23:39:12 GMT  
Authorization: SharedKey myaccount:ctzMq410TV3wS7upTBcunJTDLEJwMAZuFPfr0mrrA08=  
Content-Length: 0

O StringToSign é construído da seguinte forma:

Version 2014-02-14 and earlier:
PUT\n\n\n\n0\n\n\n\n\n\n\n\nx-ms-date:Fri, 26 Jun 2015 23:39:12 GMT\nx-ms-version:2014-02-14\n/myaccount/mycontainer\nrestype:container\ntimeout:30

Enquanto nas versões posteriores a 2014-02-14, o StringToSign tem de conter uma cadeia vazia para Content-Length:

Version 2015-02-21 and later:
PUT\n\n\n\n\n\n\n\n\n\n\n\nx-ms-date:Fri, 26 Jun 2015 23:39:12 GMT\nx-ms-version:2015-02-21\n/myaccount/mycontainer\nrestype:container\ntimeout:30

Serviço Tabela (autorização de Chave Partilhada)

Tem de utilizar a autorização de Chave Partilhada para autorizar um pedido feito no serviço Tabela se o seu serviço estiver a utilizar a API REST para fazer o pedido. O formato da cadeia de assinatura da Chave Partilhada no serviço Tabela é o mesmo para todas as versões.

A cadeia de assinatura de Chave Partilhada para um pedido relativamente ao serviço Tabela difere ligeiramente da do pedido relativamente ao serviço Blob ou Fila, na qual não inclui a CanonicalizedHeaders parte da cadeia. Além disso, o Date cabeçalho neste caso nunca está vazio, mesmo que o pedido defina o x-ms-date cabeçalho. Se o pedido definir x-ms-date, esse valor também é utilizado para o valor do Date cabeçalho.

Para codificar a cadeia de assinatura de um pedido no serviço Tabela efetuada com a API REST, utilize o seguinte formato:

StringToSign = VERB + "\n" +
               Content-MD5 + "\n" +
               Content-Type + "\n" +  
               Date + "\n" +  
               CanonicalizedResource;  

Nota

A partir da versão 2009-09-19, o serviço Tabela requer que todas as chamadas REST incluam os DataServiceVersion cabeçalhos e MaxDataServiceVersion . Consulte Definir os Cabeçalhos de Versão do OData Data Service para obter mais informações.

Serviços blob, fila e ficheiro (autorização Lite de Chave Partilhada)

Pode utilizar a autorização Shared Key Lite para autorizar um pedido feito relativamente à versão 2009-09-19 e posterior dos serviços Blob e Fila e versão 2014-02-14 e posterior dos Serviços de ficheiros.

A cadeia de assinatura da Chave Partilhada Lite é idêntica à cadeia de assinatura necessária para a autorização de Chave Partilhada em versões dos serviços Blob e Fila antes de 2009-09-19. Por isso, se quiser migrar o código com o menor número de alterações para a versão 2009-09-19 dos serviços Blob e Fila, pode modificar o código para utilizar a Chave Partilhada Lite, sem alterar a própria cadeia de assinatura. Ao utilizar a Chave Partilhada Lite, não irá obter a funcionalidade de segurança melhorada fornecida com a Chave Partilhada com a versão 2009-09-19 e posterior.

Para codificar a cadeia de assinatura de um pedido no serviço Blob ou Queue, utilize o seguinte formato:

StringToSign = VERB + "\n" +  
               Content-MD5 + "\n" +  
               Content-Type + "\n" +  
               Date + "\n" +  
               CanonicalizedHeaders +   
               CanonicalizedResource;  

O exemplo seguinte mostra uma cadeia de assinatura para uma operação Put Blob . Tenha em atenção que a linha de cabeçalho Content-MD5 está vazia. Os cabeçalhos apresentados na cadeia são pares nome-valor que especificam valores de metadados personalizados para o novo blob.

PUT\n\ntext/plain; charset=UTF-8\n\nx-ms-date:Sun, 20 Sep 2009 20:36:40 GMT\nx-ms-meta-m1:v1\nx-ms-meta-m2:v2\n/testaccount1/mycontainer/hello.txt  

Em seguida, codifica esta cadeia com o algoritmo HMAC-SHA256 através da cadeia de assinatura codificada UTF-8, construa o Authorization cabeçalho e adicione o cabeçalho ao pedido. O exemplo seguinte mostra o Authorization cabeçalho da mesma operação:

Authorization: SharedKeyLite myaccount:ctzMq410TV3wS7upTBcunJTDLEJwMAZuFPfr0mrrA08=  

Serviço de tabela (autorização Lite de Chave Partilhada)

Pode utilizar a autorização Lite de Chave Partilhada para autorizar um pedido feito em relação a qualquer versão do serviço Tabela.

Para codificar a cadeia de assinatura de um pedido no serviço Tabela com a Chave Partilhada Lite, utilize o seguinte formato:

StringToSign = Date + "\n"
               CanonicalizedResource  

O exemplo seguinte mostra uma cadeia de assinatura para uma operação Criar Tabela .

Sun, 11 Oct 2009 19:52:39 GMT\n/testaccount1/Tables  

Em seguida, codifica esta cadeia com o algoritmo HMAC-SHA256, construa o Authorization cabeçalho e, em seguida, adicione o cabeçalho ao pedido. O exemplo seguinte mostra o Authorization cabeçalho da mesma operação:

Authorization: SharedKeyLite testaccount1:uay+rilMVayH/SVI8X+a3fL8k/NxCnIePdyZSkqvydM=  

Construir a cadeia de cabeçalhos canonizados

Para construir a CanonicalizedHeaders parte da cadeia de assinatura, siga estes passos:

  1. Obtenha todos os cabeçalhos para o recurso que começa com x-ms-, incluindo o x-ms-date cabeçalho.

  2. Converta cada nome de cabeçalho HTTP em minúsculas.

  3. Ordene os cabeçalhos lexicograficamente por nome de cabeçalho, por ordem ascendente. Cada cabeçalho só pode aparecer uma vez na cadeia.

    Nota

    A ordenação lexicográfica pode nem sempre coincidir com a ordenação alfabética convencional.

  4. Substitua qualquer espaço em branco linear no valor do cabeçalho por um único espaço.

O espaço em branco linear inclui o feed de retorno/linha de transporte (CRLF), espaços e separadores. Consulte RFC 2616, secção 4.2 para obter detalhes. Não substitua nenhum espaço em branco dentro de uma cadeia de carateres com aspas.

  1. Corte qualquer espaço em branco à volta dos dois pontos no cabeçalho.

  2. Por fim, acrescente um caráter de nova linha a cada cabeçalho canónico na lista resultante. Construa a CanonicalizedHeaders cadeia concatenando todos os cabeçalhos nesta lista numa única cadeia.

Segue-se um exemplo de uma cadeia de cabeçalhos canonizada:

x-ms-date:Sat, 21 Feb 2015 00:48:38 GMT\nx-ms-version:2014-02-14\n

Nota

Antes da versão de serviço 2016-05-31, os cabeçalhos com valores vazios eram omitidos da cadeia de assinatura. Estes são agora representados em CanonicalizedHeaders ao seguir imediatamente o caráter de dois pontos com a nova linha terminada.

Construir a cadeia de recursos canonizada

A CanonicalizedResource parte da cadeia de assinatura representa o recurso dos serviços de armazenamento visado pelo pedido. Qualquer parte da CanonicalizedResource cadeia derivada do URI do recurso deve ser codificada exatamente como no URI.

Existem dois formatos suportados para a CanonicalizedResource cadeia:

  • Um formato que suporta autorização de Chave Partilhada para a versão 2009-09-19 e posterior dos serviços Blob e Fila e para a versão 2014-02-14 e posterior do serviço Ficheiro.

  • Um formato que suporta a Chave Partilhada e a Chave Partilhada Lite para todas as versões do serviço Tabela e a Chave Partilhada Lite para a versão 2009-09-19 e posterior dos serviços Blob e Fila. Este formato é idêntico ao utilizado com versões anteriores dos serviços de armazenamento.

Para obter ajuda para construir o URI para o recurso a que está a aceder, veja um dos seguintes tópicos:

Importante

Se a sua conta de armazenamento for replicada com georreplicação de acesso de leitura (RA-GRS) e estiver a aceder a um recurso na localização secundária, não inclua a –secondary designação na CanonicalizedResource cadeia. O URI de recurso utilizado no URI da CanonicalizedResource cadeia deve ser o URI do recurso na localização primária.

Nota

Se estiver a autorizar contra o emulador de armazenamento, o nome da conta será apresentado duas vezes na CanonicalizedResource cadeia. Isto era esperado. Se estiver a autorizar os serviços de armazenamento do Azure, o nome da conta aparecerá apenas uma vez na CanonicalizedResource cadeia.

Formato de Chave Partilhada para 2009-09-19 e posterior

Este formato suporta autorização de Chave Partilhada para a versão 2009-09-19 e posterior dos serviços Blob e Fila, bem como a versão 2014-02-14 e posterior dos serviços de Ficheiros. Construa a CanonicalizedResource cadeia neste formato da seguinte forma:

  1. A partir de uma cadeia vazia (""), acrescente uma barra (/), seguida do nome da conta que detém o recurso que está a ser acedido.

  2. Acrescente o caminho de URI codificado do recurso, sem quaisquer parâmetros de consulta.

  3. Obtenha todos os parâmetros de consulta no URI do recurso, incluindo o comp parâmetro se existir.

  4. Converta todos os nomes de parâmetros em minúsculas.

  5. Ordene os parâmetros de consulta lexicograficamente pelo nome do parâmetro, por ordem ascendente.

  6. Descodificar cada nome e valor do parâmetro de consulta.

  7. Inclua um caráter de nova linha (\n) antes de cada par nome-valor.

  8. Acrescente cada nome e valor do parâmetro de consulta à cadeia no seguinte formato, certificando-se de que inclui os dois pontos (:) entre o nome e o valor:

    parameter-name:parameter-value

  9. Se um parâmetro de consulta tiver mais do que um valor, ordene todos os valores lexicograficamente e, em seguida, inclua-os numa lista separada por vírgulas:

    parameter-name:parameter-value-1,parameter-value-2,parameter-value-n

Tenha em atenção as seguintes regras para construir a cadeia de recursos canonizada:

  • Evite utilizar o caráter de nova linha (\n) em valores para parâmetros de consulta. Se tiver de ser utilizado, certifique-se de que não afeta o formato da cadeia de recursos canonizada.

  • Evite utilizar vírgulas em valores de parâmetros de consulta.

Eis alguns exemplos que mostram a CanonicalizedResource parte da cadeia de assinatura, uma vez que pode ser construída a partir de um determinado URI de pedido:

Get Container Metadata  
   GET http://myaccount.blob.core.windows.net/mycontainer?restype=container&comp=metadata
CanonicalizedResource:  
    /myaccount/mycontainer\ncomp:metadata\nrestype:container  
  
List Blobs operation:  
    GET http://myaccount.blob.core.windows.net/container?restype=container&comp=list&include=snapshots&include=metadata&include=uncommittedblobs  
CanonicalizedResource:  
    /myaccount/mycontainer\ncomp:list\ninclude:metadata,snapshots,uncommittedblobs\nrestype:container  
  
Get Blob operation against a resource in the secondary location:  
   GET https://myaccount-secondary.blob.core.windows.net/mycontainer/myblob  
CanonicalizedResource:  
    /myaccount/mycontainer/myblob

Formato de serviço Shared Key Lite e Table para 2009-09-19 e posterior

Este formato suporta Chave Partilhada e Chave Partilhada Lite para todas as versões do serviço Tabela e Chave Partilhada Lite para a versão 2009-09-19 e posterior dos serviços Blob e Fila e versão 2014-02-14 e posterior do serviço Ficheiro. Este formato é idêntico ao utilizado com versões anteriores dos serviços de armazenamento. Construa a CanonicalizedResource cadeia neste formato da seguinte forma:

  1. A partir de uma cadeia vazia (""), acrescente uma barra (/), seguida do nome da conta que detém o recurso que está a ser acedido.

  2. Acrescente o caminho de URI codificado do recurso. Se o URI do pedido abordar um componente do recurso, acrescente a cadeia de consulta adequada. A cadeia de consulta deve incluir o ponto de interrogação e o comp parâmetro (por exemplo, ?comp=metadata). Não devem ser incluídos outros parâmetros na cadeia de consulta.

Codificar a assinatura

Para codificar a assinatura, chame o algoritmo HMAC-SHA256 na cadeia de assinatura codificada UTF-8 e codifica o resultado como Base64. Tenha em atenção que também precisa de descodificar base64 da chave da sua conta de armazenamento. Utilize o seguinte formato (mostrado como pseudocódigo):

Signature=Base64(HMAC-SHA256(UTF8(StringToSign), Base64.decode(<your_azure_storage_account_shared_key>)))  

Ver também