Autenticar Pedidos para Azure Batch

  • Artigo

Todos os pedidos feitos no serviço Batch têm de ser autenticados. O serviço Batch suporta a autenticação através da Chave Partilhada ou Microsoft Entra ID.

Autenticação através da Chave Partilhada

Um pedido autenticado requer dois cabeçalhos: o cabeçalho Data ou data ocp e o cabeçalho Autorização . As secções seguintes descrevem como construir estes cabeçalhos.

Especificar o cabeçalho de data

Todos os pedidos autenticados têm de incluir o carimbo de data/hora universal coordenada (UTC) do pedido. Pode especificar o carimbo de data/hora no cabeçalho ocp-date ou no cabeçalho data HTTP/HTTPS padrão. Se ambos os cabeçalhos forem especificados para o pedido, o valor de ocp-date é utilizado como a hora de criação do pedido.

O serviço Batch tem de receber um pedido no prazo de 15 minutos após a sua criação. Ao fazê-lo, o serviço é protegido contra ataques de segurança, como ataques de repetição. O cabeçalho ocp-date é fornecido porque algumas bibliotecas de cliente HTTP e proxies definem automaticamente o cabeçalho Data e não lhe dão a oportunidade de ler o respetivo valor para incluí-lo no pedido autenticado. Se definir ocp-date, construa a assinatura com um valor vazio para o cabeçalho Data .

Especificar o cabeçalho de autorização

Um pedido autenticado tem de incluir o cabeçalho Autorização . Para autenticar 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 Autorização é o seguinte:

Authorization="SharedKey <AccountName>:<Signature>"

SharedKey é 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, calculado com o algoritmo SHA256 e, em seguida, codificado através da codificação Base64.

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

Construir a cadeia de assinatura

Quando construir a cadeia de assinatura, tenha em atenção o seguinte:

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

  • Cada cabeçalho incluído na cadeia de assinatura só pode aparecer uma vez.

  • Os valores de todos os cabeçalhos HTTP padrão têm de ser incluídos na cadeia na 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 novo caráter de linha.

  • Quando o verbo é POST, os valores Content-Type e Content-Length são necessários como cabeçalhos de pedido e como valores na cadeia de assinatura. O Tipo de Conteúdo tem de ser definido como aplicação/json; odata=minimalmetadata.

  • Se o cabeçalho ocp-date for especificado, o cabeçalho Data não é necessário, basta especificar uma linha vazia para a parte Data da cadeia de assinatura. Neste caso, siga as instruções na secção Construir a cadeia de cabeçalhos canónicos para adicionar o cabeçalho ocp-date .

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

  • Para obter informações detalhadas sobre como construir as CanonicalizedHeaders cadeias e CanonicalizedResource que constituem parte da cadeia de assinatura, veja as secções adequadas mais à frente neste tópico.

Para codificar a cadeia de assinatura de um pedido no serviço Batch, 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;

O exemplo seguinte mostra uma cadeia de assinatura para um pedido para Listar as tarefas numa conta com um tempo limite de 20 segundos. Quando um valor de cabeçalho não existe, apenas o novo caráter de linha é especificado.

GET\n\n\n\n\n\n\n\n\n\n\n\nocp-date:Tue, 29 Jul 2014 21:49:13 GMT\n /myaccount/jobs\napi-version:2014-01-01.1.0\ntimeout:20

Desagregar esta linha a linha mostra cada parte da mesma cadeia:

  
GET\n /*HTTP 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 */  
ocp-date:Tue, 29 Jul 2014 21:49:13 GMT\n    /*CanonicalizedHeaders*/  
/myaccount/jobs\napi-version:2014-04-01.1.0\ntimeout:20    /*CanonicalizedResource*/

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

Authorization: SharedKey myaccount:ctzMq410TV3wS7upTBcunJTDLEJwMAZuFPfr0mrrA08=

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 do recurso que começam com ocp-, incluindo o cabeçalho ocp-date .

  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.

  4. Substitua qualquer espaço em branco com um único espaço.

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

  6. Acrescente um novo caráter de linha a cada cabeçalho canonizado na lista resultante. Construa a CanonicalizedHeaders cadeia concatenando todos os cabeçalhos nesta lista numa única cadeia.

Construir a cadeia de recursos canonizada

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

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

  • Evite utilizar o novo caráter de 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.

Pode construir a cadeia da CanonicalizedResource seguinte forma:

  1. A partir de uma barra ("/"), seguido 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 parâmetro api-version .

  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. 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

  8. 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

  9. Acrescente um novo caráter de linha (\n) após cada par nome-valor.

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. Utilize o seguinte formato (mostrado como pseudocódigo):

Signature=Base64(HMAC-SHA256(UTF8(StringToSign)))

Autenticação através de Microsoft Entra ID

Azure Batch suporta a autenticação com Microsoft Entra ID, o diretório e o serviço de gestão de identidades baseado na cloud multi-inquilino da Microsoft. O Azure utiliza Microsoft Entra ID para autenticar os seus próprios clientes, administradores de serviços e utilizadores organizacionais.

Nota

A autenticação com Microsoft Entra ID é opcional, mas recomendada, só é necessária se a sua conta do Batch estiver configurada para alocar conjuntos numa subscrição de utilizador. A opção de alocação de conjuntos está disponível quando cria uma nova conta do Batch. Se a sua conta estiver configurada para alocar conjuntos numa subscrição gerida pelo Batch, a utilização de Microsoft Entra ID para autenticação é opcional. Para obter mais informações, veja Batch – Suporte de VNet e Imagem Personalizada para Conjuntos de Máquinas Virtuais.

Para obter informações gerais sobre como autenticar um pedido com Azure AD, veja Referência da API REST do Azure. Para utilizar Azure AD com o serviço Batch, precisará dos seguintes pontos finais.

O ponto final "comum" do ponto final Azure AD é:

https://login.microsoftonline.com/common

O ponto final do recurso para o serviço Batch é:

https://batch.core.windows.net/

Para obter informações adicionais sobre como registar a sua aplicação batch com Microsoft Entra ID, veja Authenticate Azure Batch services with Microsoft Entra ID (Autenticar serviços Azure Batch com Microsoft Entra ID).