Suporte de Partilha de Recursos Entre Origens (CORS) para o Armazenamento do Azure

A partir da versão 2013-08-15, os serviços de armazenamento do Azure suportam a Partilha de Recursos Entre Origens (CORS) para os serviços Blob, Tabela e Fila. O serviço Ficheiro suporta CORS a partir da versão 2015-02-21.

O CORS é uma funcionalidade HTTP que permite a execução de uma aplicação Web num domínio para aceder a recursos noutro domínio. Os browsers implementam uma restrição de segurança conhecida como política de origem idêntica que impede uma página Web de chamar APIs num domínio diferente; O CORS fornece uma forma segura de permitir que um domínio (o domínio de origem) chame APIs noutro domínio. Veja a especificação CORS para obter detalhes sobre CORS.

Pode definir regras CORS individualmente para cada um dos serviços de Armazenamento do Azure, ao chamar Definir Propriedades do Serviço blob, Definir Propriedades do Serviço de Ficheiros, Definir Propriedades do Serviço de Fila e Definir Propriedades do Serviço de Tabelas. Depois de definir as regras do CORS para o serviço, será feito um pedido devidamente autenticado para o serviço a partir de um domínio diferente, para determinar se é permitido, de acordo com as regras que especificou.

Compreender os pedidos CORS

Um pedido CORS de um domínio de origem pode consistir em dois pedidos separados:

• Um pedido de pré-voo, que consulta as restrições CORS impostas pelo serviço. O pedido de pré-voo é necessário, a menos que o método de pedido seja um método simples, o que significa GET, HEAD ou POST.

• O pedido real, feito em relação ao recurso pretendido.

Pedido de pré-voo

O pedido de pré-voo consulta as restrições CORS que foram estabelecidas para o serviço de armazenamento pelo proprietário da conta. O browser (ou outro agente de utilizador) envia um pedido OPTIONS que inclui os cabeçalhos do pedido, o método e o domínio de origem. O serviço de armazenamento avalia a operação pretendida com base num conjunto pré-configurado de regras CORS que especificam que domínios de origem, métodos de pedido e cabeçalhos de pedido podem ser especificados num pedido real contra um recurso de armazenamento.

Se o CORS estiver ativado para o serviço e existir uma regra CORS que corresponda ao pedido de pré-voo, o serviço responderá com o código de estado 200 (OK) e inclui os cabeçalhos de Access-Control necessários na resposta.

Se o CORS não estiver ativado para o serviço ou nenhuma regra CORS corresponder ao pedido de pré-voo, o serviço responderá com o código de estado 403 (Proibido).

Se o pedido OPTIONS não contiver os cabeçalhos CORS necessários (os cabeçalhos Origin e Access-Control-Request-Method), o serviço responderá com o código de estado 400 (Pedido incorreto).

Tenha em atenção que um pedido de pré-voo é avaliado relativamente ao serviço (Blob, Ficheiro, Fila ou Tabela) e não ao recurso pedido. O proprietário da conta tem de ter ativado o CORS ao definir as propriedades do serviço de conta adequadas para que o pedido seja bem-sucedido.

Pedido real

Assim que o pedido de pré-voo for aceite e a resposta for devolvida, o browser irá enviar o pedido real contra o recurso de armazenamento. O browser negará o pedido real imediatamente se o pedido de pré-voo for rejeitado.

O pedido real é tratado como um pedido normal relativamente ao serviço de armazenamento. A presença do cabeçalho Origem indica que o pedido é um pedido CORS e o serviço verificará as regras CORS correspondentes. Se for encontrada uma correspondência, os cabeçalhos de Access-Control são adicionados à resposta e enviados de volta para o cliente. Se não for encontrada uma correspondência, os cabeçalhos de Access-Control CORS não serão devolvidos.

Ativar o CORS para o Armazenamento do Azure

As regras CORS são definidas ao nível do serviço, pelo que tem de ativar ou desativar o CORS para cada serviço (Blob, Ficheiro, Fila e Tabela) separadamente. Por predefinição, o CORS está desativado para cada serviço. Para ativar o CORS, tem de definir as propriedades de serviço adequadas com a versão 2013-08-15 ou posterior para os serviços Blob, Fila e Tabela, ou versão 2015-02-21 ou para o serviço Ficheiro. Ativa o CORS ao adicionar regras CORS às propriedades do serviço. Para obter detalhes sobre como ativar ou desativar o CORS para um serviço e como definir regras CORS, consulte Definir Propriedades do Serviço blob, Definir Propriedades do Serviço de Ficheiros, Definir Propriedades do Serviço de Tabela e Definir Propriedades do Serviço de Fila.

Eis um exemplo de uma única regra CORS, especificada através de uma Set Service Properties operação:

<Cors>
    <CorsRule>  
        <AllowedOrigins>http://*.contoso.com, http://www.fabrikam.com</AllowedOrigins>  
        <AllowedMethods>PUT,GET</AllowedMethods>  
        <AllowedHeaders>x-ms-meta-data*,x-ms-meta-target*,x-ms-meta-abc</AllowedHeaders>  
        <ExposedHeaders>x-ms-meta-*</ExposedHeaders>  
        <MaxAgeInSeconds>200</MaxAgeInSeconds>  
    </CorsRule>  
<Cors>  
  

Cada elemento incluído na regra CORS é descrito abaixo:

• AllowedOrigins: os domínios de origem que estão autorizados a fazer um pedido contra o serviço de armazenamento através do CORS. O domínio de origem é o domínio a partir do qual o pedido é originado. Tenha em atenção que a origem tem de ser uma correspondência exata sensível às maiúsculas e minúsculas com a origem que a idade do utilizador envia para o serviço.

  Pode utilizar o caráter universal '*' em vez de um domínio especificado para permitir que todos os domínios de origem façam pedidos através do CORS. Também pode utilizar o caráter universal em vez de um subdomínio para permitir que todos os subdomínios de um determinado domínio façam pedidos através do CORS. No exemplo acima, todos os subdomínios de contoso.com podem fazer pedidos através de CORS, enquanto apenas os pedidos do www subdomínio de fabrikam.com são permitidos através do CORS.

• AllowedMethods: os métodos (verbos de pedido HTTP) que o domínio de origem pode utilizar para um pedido CORS. No exemplo acima, só são permitidos pedidos PUT e GET.

• AllowedHeaders: os cabeçalhos de pedido que o domínio de origem pode especificar no pedido CORS. No exemplo acima, todos os cabeçalhos de metadados que começam com x-ms-meta-data, x-ms-meta-targete x-ms-meta-abc são permitidos. Tenha em atenção que o caráter universal '*' indica que qualquer cabeçalho que comece com o prefixo especificado é permitido.

• ExposedHeaders: os cabeçalhos de resposta que podem ser enviados na resposta ao pedido CORS e expostos pelo browser ao emissor do pedido. No exemplo acima, o browser é instruído para expor qualquer cabeçalho a partir de x-ms-meta.

• MaxAgeInSeconds: o tempo máximo que um browser deve colocar em cache o pedido OPTIONS de pré-voo.

Os serviços de armazenamento do Azure suportam a especificação de cabeçalhos prefixados para os elementos AllowedHeaders e ExposedHeaders . Para permitir uma categoria de cabeçalhos, pode especificar um prefixo comum a essa categoria. Por exemplo, especificar x-ms-meta* como um cabeçalho com prefixo estabelece uma regra que corresponderá a todos os cabeçalhos que começam com x-ms-meta.

As seguintes limitações aplicam-se às regras CORS:

• Pode especificar até cinco regras CORS por serviço de armazenamento (Blob, Ficheiro, Tabela e Fila).

• O tamanho máximo de todas as definições de regras CORS no pedido, excluindo etiquetas XML, não deve exceder 2 KiB.

• O comprimento de um cabeçalho permitido, cabeçalho exposto ou origem permitida não deve exceder os 256 carateres.

• Os cabeçalhos permitidos e os cabeçalhos expostos podem ser:

  • Cabeçalhos literais, onde é fornecido o nome exato do cabeçalho, como x-ms-meta-processed. Pode ser especificado um máximo de 64 cabeçalhos literais no pedido.
  • Cabeçalhos com prefixo, em que é fornecido um prefixo do cabeçalho, como x-ms-meta-data*. Especificar um prefixo desta forma permite ou expõe qualquer cabeçalho que comece com o prefixo especificado. Pode ser especificado um máximo de dois cabeçalhos prefixos no pedido.

• Os métodos (ou verbos HTTP) especificados no elemento AllowedMethods têm de estar em conformidade com os métodos suportados pelas APIs do serviço de armazenamento do Azure. Os métodos suportados são DELETE, GET, HEAD, MERGE, POST, PATCH, OPTIONS e PUT.

Compreender a lógica de avaliação de regras CORS

Quando um serviço de armazenamento recebe um pré-voo ou um pedido real, avalia esse pedido com base nas regras CORS que estabeleceu para o serviço através da operação Set Service Properties adequada. As regras CORS são avaliadas pela ordem pela qual foram definidas no corpo do pedido da operação Definir Propriedades do Serviço.

As regras CORS são avaliadas da seguinte forma:

1. Em primeiro lugar, o domínio de origem do pedido é verificado em relação aos domínios listados para o AllowedOrigins elemento. Se o domínio de origem estiver incluído na lista ou todos os domínios forem permitidos com o caráter universal '*', a avaliação de regras prosseguirá. Se o domínio de origem não estiver incluído, o pedido falhará.

2. Em seguida, o método (ou verbo HTTP) do pedido é verificado em relação aos métodos listados no AllowedMethods elemento. Se o método estiver incluído na lista, a avaliação das regras prosseguirá; caso contrário, o pedido falha.

3. Se o pedido corresponder a uma regra no seu domínio de origem e ao respetivo método, essa regra é selecionada para processar o pedido e não são avaliadas mais regras. No entanto, antes de o pedido poder ser bem-sucedido, todos os cabeçalhos especificados no pedido são verificados em relação aos cabeçalhos listados no AllowedHeaders elemento. Se os cabeçalhos enviados não corresponderem aos cabeçalhos permitidos, o pedido falhará.

Uma vez que as regras são processadas pela ordem em que estão presentes no corpo do pedido, as melhores práticas recomendam que especifique as regras mais restritivas relativamente às origens primeiro na lista, para que estas sejam avaliadas primeiro. Especifique regras menos restritivas ( por exemplo, uma regra para permitir todas as origens ) no final da lista.

Exemplo – avaliação de regras CORS

O exemplo seguinte mostra um corpo de pedido parcial para uma operação para definir regras CORS para os serviços de armazenamento. Veja Definir Propriedades do Serviço blob, Definir Propriedades do Serviço de Ficheiros, Definir Propriedades do Serviço de Fila e Definir Propriedades do Serviço de Tabela para obter detalhes sobre a construção do pedido.

<Cors>  
    <CorsRule>  
        <AllowedOrigins>http://www.contoso.com</AllowedOrigins>  
        <AllowedMethods>PUT,HEAD</AllowedMethods>  
        <MaxAgeInSeconds>5</MaxAgeInSeconds>  
        <ExposedHeaders>x-ms-*</ExposedHeaders>  
        <AllowedHeaders>x-ms-blob-content-type, x-ms-blob-content-disposition</AllowedHeaders>  
    </CorsRule>  
    <CorsRule>  
        <AllowedOrigins>*</AllowedOrigins>  
        <AllowedMethods>PUT,GET</AllowedMethods>  
        <MaxAgeInSeconds>5</MaxAgeInSeconds>  
        <ExposedHeaders>x-ms-*</ExposedHeaders>  
        <AllowedHeaders>x-ms-blob-content-type, x-ms-blob-content-disposition</AllowedHeaders>  
    </CorsRule>  
    <CorsRule>  
        <AllowedOrigins>http://www.contoso.com</AllowedOrigins>  
        <AllowedMethods>GET</AllowedMethods>  
        <MaxAgeInSeconds>5</MaxAgeInSeconds>  
        <ExposedHeaders>x-ms-*</ExposedHeaders>  
        <AllowedHeaders>x-ms-client-request-id</AllowedHeaders>  
    </CorsRule>  
</Cors>

Em seguida, considere os seguintes pedidos CORS:

O primeiro pedido corresponde à primeira regra – o domínio de origem corresponde às origens permitidas, o método corresponde aos métodos permitidos e o cabeçalho corresponde aos cabeçalhos permitidos – e assim é bem-sucedido.

O segundo pedido não corresponde à primeira regra porque o método não corresponde aos métodos permitidos. No entanto, corresponde à segunda regra, pelo que é bem-sucedida.

O terceiro pedido corresponde à segunda regra no respetivo domínio e método de origem, pelo que não são avaliadas mais regras. No entanto, o x-ms-client-request-id cabeçalho não é permitido pela segunda regra, pelo que o pedido falha, apesar de a semântica da terceira regra ter permitido que fosse bem-sucedida.

Compreender como o cabeçalho Vary está definido

O Vary cabeçalho é um cabeçalho HTTP/1.1 padrão que consiste num conjunto de campos de cabeçalho de pedido que aconselham o browser ou o agente de utilizador sobre os critérios selecionados pelo servidor para processar o pedido. O Vary cabeçalho é utilizado principalmente para colocação em cache por proxies, browsers e CDNs, que o utilizam para determinar como a resposta deve ser colocada em cache. Para obter detalhes, veja a especificação do cabeçalho Vary.

Quando o browser ou outro agente de utilizador coloca em cache a resposta de um pedido CORS, o domínio de origem é colocado em cache como a origem permitida. Quando um segundo domínio emite o mesmo pedido para um recurso de armazenamento enquanto a cache está ativa, o agente de utilizador obtém o domínio de origem em cache. O segundo domínio não corresponde ao domínio em cache, pelo que o pedido falha quando, de outra forma, seria bem-sucedido. Em determinados casos, o Armazenamento do Azure define o Vary cabeçalho como para Origin instruir o agente de utilizador a enviar o pedido CORS subsequente para o serviço quando o domínio de pedido difere da origem em cache.

O Armazenamento do Azure define o Vary cabeçalho como Origin para pedidos GET/HEAD reais nos seguintes casos:

• Quando a origem do pedido corresponde exatamente à origem permitida definida por uma regra CORS. Para ser uma correspondência exata, a regra CORS pode não incluir um caráter universal "*".

• Não existe nenhuma regra que corresponda à origem do pedido, mas o CORS está ativado para o serviço de armazenamento.

No caso de um pedido GET/HEAD corresponder a uma regra CORS que permite todas as origens, a resposta indica que todas as origens são permitidas e a cache do agente do utilizador permitirá pedidos subsequentes de qualquer domínio de origem enquanto a cache estiver ativa.

Tenha em atenção que, para pedidos que utilizam métodos diferentes de GET/HEAD, os serviços de armazenamento não irão definir o Vary cabeçalho, uma vez que as respostas a estes métodos não são colocadas em cache pelos agentes do utilizador.

A tabela seguinte indica como o armazenamento do Azure irá responder aos pedidos GET/HEAD com base nos casos mencionados anteriormente:

Faturação de pedidos CORS

Os pedidos de verificação prévia bem-sucedidos são faturados se tiver ativado o CORS para qualquer um dos serviços de armazenamento da sua conta (ao chamar Definir Propriedades do Serviço Blob, Definir Propriedades do Serviço de Fila, Definir Propriedades do Serviço de Ficheiros ou Definir Propriedades do Serviço De Tabela). Para minimizar os custos, considere definir o MaxAgeInSeconds elemento nas regras CORS para um valor grande para que o agente do utilizador coloque o pedido em cache.

Os pedidos de verificação prévia sem êxito não serão faturados.

Ver também

Especificação de Partilha de Recursos Transversais à Origem W3C