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 em bytes UTF-8 e codificados com a codificação Base64url. Essa codificação oferece resiliência a mudanças 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 dois campos que indicam o algoritmo de assinatura e o formato da declaração. Ambos os campos são obrigatórios, e cada um tem apenas um valor. À medida que outros algoritmos e formatos são introduzidos, esse cabeçalho muda de acordo.

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"}

A representação Base64url disso é a seguinte:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9

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 solicitadas (escopos), o destino do token, o emissor, a hora em que o token foi emitido e o ciclo de vida dele. 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 reivindicações obrigatórias no conjunto de declarações JWT são mostradas abaixo. Elas podem aparecer em qualquer ordem no conjunto de reivindicações.

Veja a representação JSON dos campos obrigatórios em um conjunto de declarações JWT 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. A permissão para esse tipo de falsificação de identidade precisa ser concedida antes que um aplicativo possa representar um usuário e geralmente é realizada por um superadministrador. Para mais informações, consulte Controlar o acesso à API com delegação em todo o domínio.

Para receber um token de acesso que concede a um aplicativo acesso delegado a um recurso, inclua o endereço de e-mail do usuário na declaração JWT definida 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 incluir o campo sub será um erro.

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

{
  "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. 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 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 único algoritmo de assinatura compatível com o servidor de autorização do Google OAuth 2.0 é o RSA usando o algoritmo de hash SHA-256. Isso é expresso como RS256 no campo 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 Google API Console. A saída será uma matriz de bytes.

A assinatura precisa ter a codificação Base64url. O cabeçalho, o conjunto de declarações e a assinatura são concatenados com um caractere de ponto (.). O resultado é o JWT. Precisa ser o seguinte (quebras de linhas 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

Como fazer a solicitação do 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 pelo URL. 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 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 o JWT e a solicitação do token de acesso estiverem devidamente formados e a conta de serviço tiver permissão para realizar a operação, a resposta JSON do servidor de autorização 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 OAuth 2.0 do Google 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.