Autenticar solicitações para Lote do Azure

Artigo
02/08/2024

Cada solicitação feita no serviço de lote deve ser autenticada. O serviço lote dá suporte à autenticação por meio de chave compartilhada ou Microsoft Entra ID.

Autenticação por meio de chave compartilhada

Uma solicitação autenticada requer dois cabeçalhos: o cabeçalho Date ou ocp-date e o cabeçalho Authorization . As seções a seguir descrevem como construir esses cabeçalhos.

Especificar o cabeçalho de data

Todas as solicitações autenticadas devem incluir o carimbo de data/hora de UTC (Tempo Universal Coordenado) para a solicitação. Você 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 a solicitação, o valor de ocp-date será usado como a hora de criação da solicitação.

O serviço de lote deve receber uma solicitação dentro de 15 minutos após ser criado. Ao fazer isso, o serviço é protegido contra ataques de segurança, como ataques de repetição. O cabeçalho ocp-date é fornecido porque algumas bibliotecas e proxies de cliente HTTP definem automaticamente o cabeçalho Date e não oferecem a oportunidade de ler seu valor para incluí-lo na solicitação autenticada. Se você definir ocp-date, construa a assinatura com um valor vazio para o cabeçalho Date .

Especificar o cabeçalho de autorização

Uma solicitação autenticada deve incluir o cabeçalho De autorização . Para autenticar uma solicitação, você deve assiná-la com a chave da conta que está fazendo a solicitação e passar essa assinatura como parte da solicitação.

O formato do cabeçalho Authorization é o seguinte:

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

SharedKey é o nome do esquema de autorização, AccountName é o nome da conta que solicita o recurso e Signature é um código HMAC (Hash-based Message Authentication Code) construído com base na solicitação e computado com o uso do algoritmo SHA256 e codificado usando a codificação Base64.

As seções a seguir descrevem como construir o cabeçalho Authorization .

Construir a cadeia de caracteres de assinatura

Ao construir a cadeia de caracteres de assinatura, tenha em mente o seguinte:

A parte VERB da cadeia de caracteres é o verbo HTTP, como GET ou PUT, e deve ser maiúscula.
Cada cabeçalho incluído na cadeia de assinatura pode aparecer apenas uma vez.
Os valores de todos os cabeçalhos HTTP padrão devem ser incluídos na cadeia de caracteres na ordem mostrada no formato de assinatura, sem os nomes de cabeçalho. Esses cabeçalhos poderão ficar vazios se não estiverem sendo especificados como parte da solicitação; nesse caso, somente o caractere de nova linha será necessário.
Quando o verbo for POST, os valores de tipo de conteúdo e comprimento do conteúdo são necessários como cabeçalhos de solicitação e valores na cadeia de caracteres de assinatura. Content-Type deve ser definido como application/json; odata=minimalmetadata.
Se o cabeçalho ocp-date for especificado, o cabeçalho Date não será necessário, basta especificar uma linha vazia para a parte Date da cadeia de caracteres de assinatura. Nesse caso, siga as instruções na seção Construir a cadeia de caracteres de cabeçalhos canônicos para adicionar o cabeçalho ocp-date .
Todos os caracteres de nova linha (\n) mostrados devem estar dentro da cadeia de caracteres da assinatura.
Para obter informações detalhadas sobre como construir as cadeias de caracteres CanonicalizedHeaders e CanonicalizedResource que fazem parte da cadeia de caracteres de assinatura, consulte as seções apropriadas posteriormente neste tópico.

Para codificar a cadeia de caracteres de assinatura para uma solicitação no serviço de lote, use 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 a seguir mostra uma cadeia de caracteres de assinatura para uma solicitação para Listar os trabalhos em uma conta com um tempo limite de 20 segundos. Quando um valor de cabeçalho não existir, apenas o caractere de nova linha será 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

A análise disso linha por linha mostra cada parte da mesma cadeia de caracteres:

  
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, codifique essa cadeia de caracteres usando o algoritmo HMAC-SHA256 sobre a cadeia de caracteres de assinatura codificada em UTF-8, construa o cabeçalho Authorization e adicione o cabeçalho à solicitação. O exemplo a seguir mostra o cabeçalho Authorization para a mesma operação:

Authorization: SharedKey myaccount:ctzMq410TV3wS7upTBcunJTDLEJwMAZuFPfr0mrrA08=

Construir a cadeia de caracteres de cabeçalhos canonizados

Para construir a parte CanonicalizedHeaders de cadeia de caracteres de assinatura, siga estas etapas:

Recupere todos os cabeçalhos do recurso que começam com ocp-, incluindo o cabeçalho ocp-date .
Converta cada nome de cabeçalho HTTP em minúsculas.
Classifique os cabeçalhos de modo lexicográfico pelo nome do cabeçalho, em ordem crescente. Observe que cada cabeçalho pode aparecer apenas uma vez na cadeia de caracteres.
Substitua qualquer quebra de espaço em branco por um único espaço.
Exclui todo o espaço em branco em torno de dois-pontos no cabeçalho.
Finalmente, acrescente um caractere de nova linha para cada cabeçalho canonizado na lista resultante. Construa a cadeia de caracteres CanonicalizedHeaders concatenando todos os cabeçalhos nessa lista em uma única cadeia de caracteres.

Construir a cadeia de caracteres de recurso canonizado

A parte CanonicalizedResource da cadeia de caracteres de assinatura representa o recurso do serviço de lote que é o destino da solicitação. Qualquer parte da cadeia de caracteres de CanonicalizedResource que seja derivada do URI do recurso deverá ser codificada exatamente como em seu URI.

Lembre-se das seguintes regras para construir a cadeia de caracteres de recurso canonizado:

Evite usar o caractere de nova linha (\n) nos valores para parâmetros de consulta. Se for necessário usá-lo, verifique se não afeta o formato da cadeia de caracteres de recurso canonizado.
Evite usar vírgulas em valores de parâmetro de consulta.

Você pode construir a cadeia de caracteres do CanonicalizedResource da seguinte maneira:

Começa com uma barra ("/"), seguida pelo nome da conta do proprietário do recurso que está sendo acessada.
Acrescente o caminho do URI codificado do recurso, sem nenhum parâmetro de consulta.
Recupere todos os parâmetros de consulta no URI do recurso, incluindo o parâmetro api-version .
Converta todos os nomes de parâmetro em minúsculas.
Classifique os parâmetros de consulta de modo lexicográfico pelo nome do parâmetro, em ordem crescente.
Decodifique com URL todos os nomes e valores de parâmetro de consulta.
Acrescente cada nome e valor de parâmetro de consulta à cadeia de caracteres no seguinte formato, certificando-se incluir os dois-pontos (:) entre o nome e o valor:
```
parameter-name:parameter-value  
```
Se um parâmetro de consulta tiver mais de um valor, classifique todos os valores de modo lexicográfico e inclua-os em uma lista separada por vírgulas:
```
parameter-name:parameter-value-1,parameter-value-2,parameter-value-n  
```
Acrescente um caractere de nova linha (\n) após cada par de nome-valor.

Codificar a assinatura

Para codificar a assinatura, chame o algoritmo HMAC-SHA256 na cadeia de caracteres de assinatura de com codificação UTF-8 codificar o resultado na Base64. Use o seguinte formato (mostrado como pseudocódigo):

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

Autenticação por meio de Microsoft Entra ID

Lote do Azure dá suporte à autenticação com Microsoft Entra ID, o serviço de gerenciamento de identidades e diretório baseado em nuvem multilocatário da Microsoft. O Azure usa Microsoft Entra ID para autenticar seus próprios clientes, administradores de serviços e usuários organizacionais.

Observação

A autenticação com Microsoft Entra ID é opcional, mas recomendada, ela só será necessária se sua conta do Lote estiver configurada para alocar pools em uma assinatura de usuário. A opção de alocação do pool está disponível quando você cria uma nova conta do Lote. Se sua conta estiver configurada para alocar pools em uma assinatura gerenciada pelo Lote, o uso de Microsoft Entra ID para autenticação será opcional. Para obter mais informações, consulte Lote – VNet e Suporte a imagens personalizadas para pools de máquinas virtuais.

Para obter informações gerais sobre como autenticar uma solicitação com Azure AD, consulte Referência da API REST do Azure. Para usar Azure AD com o serviço lote, você precisará dos seguintes pontos de extremidade.

O ponto de extremidade "comum" do ponto de extremidade Azure AD é:

https://login.microsoftonline.com/common

O ponto de extremidade de recursos para o serviço Lote é:

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

Para obter informações adicionais sobre como registrar seu aplicativo do Lote com Microsoft Entra ID, consulte Autenticar serviços Lote do Azure com Microsoft Entra ID.