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 uma 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, em seguida, codificados usando a codificação Base64url. Essa codificação oferece resiliência em relação a alterações de codificação devido a operações de codificação repetidas. O cabeçalho, o conjunto de declarações e a assinatura 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 da declaração e o [ID da chave da conta de serviço](https://cloud.google.com/iam/docs/reference/rest/v1/projects.serviceAccounts.keys) que foi usado para assinar o JWT. O algoritmo e o formato são obrigatórios, e cada campo tem apenas um valor. À medida que mais algoritmos e formatos são introduzidos, esse cabeçalho muda de acordo. 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 for 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 é esta:

{"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 do JWT contém informações sobre o JWT, incluindo as permissões solicitadas (escopos), o destino do token, o emissor, a hora em que o token foi emitido e a vida útil do token. A maioria dos campos é obrigatória. Assim como o cabeçalho JWT, o conjunto de declarações JWT é um objeto JSON e é 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. Elas podem aparecer em qualquer ordem no conjunto de declaraçõ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 app pode usar a delegação em todo o domínio para agir em nome de um determinado usuário de uma organização. A permissão para realizar esse tipo de representação precisa ser concedida antes que um aplicativo possa falsificar a identidade de um usuário e geralmente é processada por um superadministrador. Para mais informações, acesse Controlar o acesso da API com a delegação em todo o domínio.

Para receber um token de acesso que conceda a um aplicativo o 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 campo sub.

Se um aplicativo não tiver permissão para representar um usuário, a resposta a uma solicitação de token de acesso que inclui o campo sub será um erro.

Um exemplo de um conjunto de declarações do JWT que inclui o campo sub é mostrado 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 o cabeçalho JWT, o conjunto de declarações JWT precisa ser serializado para UTF-8 e codificado em Base64url safe. Veja abaixo um exemplo de uma 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

A JSON Web Signature (JWS) é a especificação que orienta a mecânica de geração da assinatura para o 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 deve ser usado ao calcular a assinatura. O único algoritmo de assinatura aceito pelo servidor de autorização do Google OAuth 2.0 é o RSA que usa o algoritmo de hash SHA-256. Isso é expresso como RS256 no campo alg do 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 de hash SHA-256) com a chave privada recebida de Google API Console. A saída será uma matriz de bytes.

A assinatura deve 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 precisa ser a seguinte (adicionar quebras de linha 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 que foi assinado e está pronto para transmissão:

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

Como 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 HTTPS POST e o corpo é codificado por URL. O URL é mostrado 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 HTTPS POST usada em uma solicitação de token de acesso:

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

Veja abaixo 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 a solicitação do JWT e o 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 vai incluir 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 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 fornecida pelo valor expires_in. Quando um token de acesso expira, o aplicativo precisa gerar outro JWT, assiná-lo e solicitar outro token de acesso.