Usar o OAuth 2.0 para aplicativos de servidor para servidor

Como criar um JWT

Um JWT é composto por três partes: um cabeçalho, um conjunto de declarações e um assinatura. O cabeçalho e o conjunto de declarações são objetos JSON. Esses objetos JSON são serializados para bytes UTF-8 e codificados usando a codificação Base64url. Essa codificação fornece resiliência contra alterações de codificação devido a operações de codificação repetidas. O cabeçalho, o conjunto de declarações e são concatenados com um caractere de ponto (.).

Um JWT é composto da seguinte maneira:

{Base64url encoded header}.{Base64url encoded claim set}.{Base64url encoded signature}

A string de base da assinatura é a seguinte:

{Base64url encoded header}.{Base64url encoded claim set}

Como formar o cabeçalho JWT

O cabeçalho consiste em três campos que indicam o algoritmo de assinatura, o formato de a declaração e o [ID da chave da conta de serviço key](https://cloud.google.com/iam/docs/reference/rest/v1/projects.serviceAccounts.keys) usado para assinar o JWT. O algoritmo e o formato são obrigatórios, e cada campo tem apenas um valor. À medida que algoritmos e formatos adicionais forem introduzidos, esse cabeçalho será alterado de maneira adequada. O ID da chave é opcional. Se um ID incorreto for especificado, o GCP tentará todas as chaves associadas à conta de serviço para verificar o token e rejeitar o token se nenhuma chave válida é encontrada. O Google se reserva o direito de rejeitar tokens com IDs de chave incorretos no futuro.

As contas de serviço dependem do algoritmo RSA SHA-256 e do formato de token JWT. Como resultado, a representação JSON do cabeçalho é a seguinte:

{"alg":"RS256","typ":"JWT", "kid":"370ab79b4513eb9bad7c9bd16a95cb76b5b2a56a"}

A representação Base64url disso é a seguinte:

          eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsICJraWQiOiIzNzBhYjc5YjQ1MTNlYjliYWQ3YzliZDE2YTk1Y2I3NmI1YjJhNTZhIn0=

Como formar o conjunto de declarações JWT

O conjunto de declarações JWT contém informações sobre o JWT, incluindo as permissões solicitado (escopos), o destino do token, o emissor, a hora em que o token foi emitido, e o ciclo de vida do token. A maioria dos campos é obrigatória. Assim como o cabeçalho JWT, O conjunto de declarações JWT é um objeto JSON usado no cálculo da assinatura.

Reivindicações obrigatórias

As declarações obrigatórias no conjunto de declarações JWT são mostradas abaixo. Eles podem aparecer em qualquer ordem o conjunto de reivindicações.

A representação JSON dos campos obrigatórios em um conjunto de declarações JWT é mostrada abaixo:

{
  "iss": "761326798069-r5mljlln1rd4lrbhg75efgigp36m78j5@developer.gserviceaccount.com",
  "scope": "https://www.googleapis.com/auth/devstorage.read_only",
  "aud": "https://oauth2.googleapis.com/token",
  "exp": 1328554385,
  "iat": 1328550785
}

Outras reivindicações

Em alguns casos corporativos, um aplicativo pode usar a delegação em todo o domínio para agir em nome de um determinado usuário em uma organização. Permissão para fazer esse tipo de falsificação de identidade deve ser concedido antes que um aplicativo possa falsificar a identidade de um usuário e geralmente é tratado por um e superadministrador. Para mais informações, consulte Controle o acesso às APIs com a delegação em todo o domínio.

Para receber um token de acesso que conceda a um aplicativo acesso delegado a um recurso, inclua o endereço de e-mail do usuário no conjunto de declarações JWT como o valor do parâmetro sub.

Se um aplicativo não tiver permissão para se passar por um usuário, a resposta a um solicitação de token de acesso que inclua o campo sub será uma error.

É mostrado um exemplo de um conjunto de declarações JWT que inclui o campo sub abaixo:

{
  "iss": "761326798069-r5mljlln1rd4lrbhg75efgigp36m78j5@developer.gserviceaccount.com",
  "sub": "some.user@example.com",
  "scope": "https://www.googleapis.com/auth/prediction",
  "aud": "https://oauth2.googleapis.com/token",
  "exp": 1328554385,
  "iat": 1328550785
}

Como codificar o conjunto de declarações JWT

Assim como no cabeçalho JWT, o conjunto de declarações JWT deve ser serializado para UTF-8 e Base64url seguro. codificados. Veja abaixo um exemplo de representação JSON de um conjunto de declarações JWT:

{
  "iss": "761326798069-r5mljlln1rd4lrbhg75efgigp36m78j5@developer.gserviceaccount.com",
  "scope": "https://www.googleapis.com/auth/prediction",
  "aud": "https://oauth2.googleapis.com/token",
  "exp": 1328554385,
  "iat": 1328550785
}

Como calcular a assinatura

Assinatura JSON da Web (JWS) é a especificação que orienta a mecânica de geração da assinatura do JWT. A entrada da assinatura é a matriz de bytes do seguinte conteúdo:

{Base64url encoded header}.{Base64url encoded claim set}

O algoritmo de assinatura no cabeçalho JWT precisa ser usado ao calcular a assinatura. O somente algoritmo de assinatura compatível com o servidor de autorização do Google OAuth 2.0 é RSA usando Algoritmo de hash SHA-256. Isso é expresso como RS256 no alg. no cabeçalho JWT.

Assine a representação UTF-8 da entrada usando SHA256withRSA (também conhecido como RSASSA-PKCS1-V1_5-SIGN com a função hash SHA-256) com a chave privada recebida de o Google API Console. A saída será uma matriz de bytes.

A assinatura precisa ser codificada em Base64url. O cabeçalho, o conjunto de declarações e a assinatura são concatenados com um caractere de ponto (.). O resultado é o JWT. Ela deve ser o seguinte (as quebras de linha foram adicionadas para maior clareza):

{Base64url encoded header}.
{Base64url encoded claim set}.
{Base64url encoded signature}

Veja abaixo um exemplo de JWT antes da codificação Base64url:

{"alg":"RS256","typ":"JWT"}.
{
"iss":"761326798069-r5mljlln1rd4lrbhg75efgigp36m78j5@developer.gserviceaccount.com",
"scope":"https://www.googleapis.com/auth/prediction",
"aud":"https://oauth2.googleapis.com/token",
"exp":1328554385,
"iat":1328550785
}.
[signature bytes]

Veja abaixo um exemplo de JWT assinado e pronto para transmissão:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI3NjEzMjY3OTgwNjktcjVtbGpsbG4xcmQ0bHJiaGc3NWVmZ2lncDM2bTc4ajVAZGV2ZWxvcGVyLmdzZXJ2aWNlYWNjb3VudC5jb20iLCJzY29wZSI6Imh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL2F1dGgvcHJlZGljdGlvbiIsImF1ZCI6Imh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL29hdXRoMi92NC90b2tlbiIsImV4cCI6MTMyODU1NDM4NSwiaWF0IjoxMzI4NTUwNzg1fQ.UFUt59SUM2_AW4cRU8Y0BYVQsNTo4n7AFsNrqOpYiICDu37vVt-tw38UKzjmUKtcRsLLjrR3gFW3dNDMx_pL9DVjgVHDdYirtrCekUHOYoa1CMR66nxep5q5cBQ4y4u2kIgSvChCTc9pmLLNoIem-ruCecAJYgI9Ks7pTnW1gkOKs0x3YpiLpzplVHAkkHztaXiJdtpBcY1OXyo6jTQCa3Lk2Q3va1dPkh_d--GU2M5flgd8xNBPYw4vxyt0mP59XZlHMpztZt0soSgObf7G3GXArreF_6tpbFsS3z2t5zkEiHuWJXpzcYr5zWTRPDEHsejeBSG8EgpLDce2380ROQ

Fazer a solicitação de token de acesso

Depois de gerar o JWT assinado, um aplicativo pode usá-lo para solicitar um token de acesso. Essa solicitação de token de acesso é uma solicitação POST HTTPS, e o corpo é URL codificados. O URL é exibido abaixo:

https://oauth2.googleapis.com/token

Os seguintes parâmetros são obrigatórios na solicitação HTTPS POST:

Veja abaixo um despejo bruto da solicitação POST HTTPS usada em um token de acesso solicitação:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI3NjEzMjY3OTgwNjktcjVtbGpsbG4xcmQ0bHJiaGc3NWVmZ2lncDM2bTc4ajVAZGV2ZWxvcGVyLmdzZXJ2aWNlYWNjb3VudC5jb20iLCJzY29wZSI6Imh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL2F1dGgvcHJlZGljdGlvbiIsImF1ZCI6Imh0dHBzOi8vYWNjb3VudHMuZ29vZ2xlLmNvbS9vL29hdXRoMi90b2tlbiIsImV4cCI6MTMyODU3MzM4MSwiaWF0IjoxMzI4NTY5NzgxfQ.ixOUGehweEVX_UKXv5BbbwVEdcz6AYS-6uQV6fGorGKrHf3LIJnyREw9evE-gs2bmMaQI5_UbabvI4k-mQE4kBqtmSpTzxYBL1TCd7Kv5nTZoUC1CmwmWCFqT9RE6D7XSgPUh_jF1qskLa2w0rxMSjwruNKbysgRNctZPln7cqQ

Abaixo está a mesma solicitação, usando curl:

curl -d 'grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI3NjEzMjY3OTgwNjktcjVtbGpsbG4xcmQ0bHJiaGc3NWVmZ2lncDM2bTc4ajVAZGV2ZWxvcGVyLmdzZXJ2aWNlYWNjb3VudC5jb20iLCJzY29wZSI6Imh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL2F1dGgvcHJlZGljdGlvbiIsImF1ZCI6Imh0dHBzOi8vYWNjb3VudHMuZ29vZ2xlLmNvbS9vL29hdXRoMi90b2tlbiIsImV4cCI6MTMyODU3MzM4MSwiaWF0IjoxMzI4NTY5NzgxfQ.RZVpzWygMLuL-n3GwjW1_yhQhrqDacyvaXkuf8HcJl8EtXYjGjMaW5oiM5cgAaIorrqgYlp4DPF_GuncFqg9uDZrx7pMmCZ_yHfxhSCXru3gbXrZvAIicNQZMFxrEEn4REVuq7DjkTMyCMGCY1dpMa8aWfTQFt3Eh7smLchaZsU
' https://oauth2.googleapis.com/token

Como processar a resposta

Se o JWT e a solicitação de token de acesso estiverem formatados corretamente e a conta de serviço tiver permissão para executar a operação, a resposta JSON do servidor de autorização inclui um token de acesso. Veja a seguir um exemplo de resposta:

{
  "access_token": "1/8xbJqaOZXSUZbHLl5EOtu1pxz3fmmetKx9W8CV4t79M",
  "scope": "https://www.googleapis.com/auth/prediction"
  "token_type": "Bearer",
  "expires_in": 3600
}

Os tokens de acesso podem ser reutilizados durante a janela de duração especificada pelo Valor de expires_in.

Quando os tokens de acesso expiram

Os tokens de acesso emitidos pelo servidor de autorização do Google OAuth 2.0 expiram após a duração fornecidos pelo valor expires_in. Quando um token de acesso expira, a aplicativo deve gerar outro JWT, assiná-lo e solicitar outro token de acesso.