Uso de OAuth 2.0 para aplicaciones de servidor a servidor

Crea un JWT

Un JWT se compone de tres partes: un encabezado, un conjunto de reclamaciones y una firma. El encabezado y el conjunto de reclamaciones son objetos JSON. Estos objetos JSON se serializan en bytes UTF-8 y, luego, se codifican mediante la codificación Base64url. Esta codificación proporciona resiliencia contra los cambios de codificación debido a las operaciones de codificación repetidas. El encabezado, el conjunto de reclamaciones y la firma se concatenan con un carácter de punto (.).

Un JWT se compone de la siguiente manera:

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

La string base para la firma es la siguiente:

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

Crea el encabezado JWT

El encabezado consta de dos campos que indican el algoritmo de firma y el formato de la aserción. Ambos campos son obligatorios y cada campo tiene un solo valor. A medida que se incorporen algoritmos y formatos adicionales, este encabezado cambiará en consecuencia.

Las cuentas de servicio dependen del algoritmo SHA-256 de RSA y el formato de token JWT. Como resultado, la representación JSON del encabezado es la siguiente:

{"alg":"RS256","typ":"JWT"}

La representación Base64url es la siguiente:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9

Formación del conjunto de reclamaciones JWT

El conjunto de reclamaciones de JWT contiene información sobre el JWT, incluidos los permisos que se solicitan (alcances), el emisor, el emisor, la hora de emisión del token y el ciclo de vida del token. La mayoría de los campos son obligatorios. Al igual que el encabezado JWT, el conjunto de reclamaciones JWT es un objeto JSON y se usa para calcular la firma.

Reclamos obligatorios

Las reclamaciones requeridas en el conjunto de reclamaciones JWT se muestran a continuación. Pueden aparecer en cualquier orden en el conjunto de reclamos.

La representación JSON de los campos obligatorios en un conjunto de reclamaciones JWT se muestra a continuación:

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

Reclamos adicionales

En algunos casos empresariales, una aplicación puede usar la delegación de todo el dominio para actuar en nombre de un usuario específico en una organización. Se debe otorgar el permiso para realizar este tipo de robo de identidad antes de que una aplicación pueda robar la identidad de un usuario. Por lo general, debe contar con un administrador avanzado. Para obtener más información, consulta Cómo controlar el acceso a la API con la delegación de todo el dominio.

Para obtener un token de acceso que otorgue a una aplicación acceso delegado a un recurso, incluye la dirección de correo electrónico del usuario en la reclamación JWT establecida como el valor del campo sub.

Si una aplicación no tiene permiso para actuar en nombre de un usuario, la respuesta a una solicitud de token de acceso que incluya el campo sub será un error.

A continuación, se muestra un ejemplo de un conjunto de reclamaciones JWT que incluye el 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
}

Codifica el conjunto de reclamaciones de JWT

Al igual que el encabezado JWT, el conjunto de reclamaciones JWT se debe serializar en UTF-8 y se codificado en base64url segura. A continuación se muestra un ejemplo de una representación JSON de un conjunto de JWT:

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

Calcula la firma

La firma web de JSON (JWS) es la especificación que guía la mecánica de la generación del JWT. La entrada para la firma es el arreglo de bytes del siguiente contenido:

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

El algoritmo de firma en el encabezado JWT se debe usar cuando se calcula la firma. El único algoritmo de firma compatible con el servidor de autorización de Google OAuth 2.0 es RSA que usa el algoritmo de hash SHA-256. Esto se expresa como RS256 en el campo alg en el encabezado JWT.

Firma la representación UTF-8 de la entrada mediante SHA256withRSA (también conocida como RSASSA-PKCS1-V1_5-SIGN con la función de hash SHA-256) con la clave privada que se obtuvo de Google API Console. El resultado será un arreglo de bytes.

La firma debe estar codificada en Base64url. El encabezado, el conjunto de reclamaciones y la firma se concatenan con un carácter de punto (.). El resultado es el JWT. Debe ser la siguiente (se agregan saltos de línea para brindar mayor claridad):

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

A continuación, se muestra un ejemplo de un JWT antes de la codificación 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]

A continuación, se muestra un ejemplo de un JWT que se firmó y está listo para su transmisión:

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

Realiza la solicitud de token de acceso

Después de generar el JWT firmado, una aplicación puede usarlo para solicitar un token de acceso. Esta solicitud de token de acceso es una solicitud POST HTTPS y el cuerpo está codificado en URL. La URL se muestra a continuación:

https://oauth2.googleapis.com/token

Los siguientes parámetros son obligatorios en la solicitud POST de HTTPS:

A continuación, se muestra un volcado sin procesar de la solicitud POST de HTTPS que se usa en una solicitud de token de acceso:

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

A continuación, se muestra la misma solicitud con 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

Cómo manejar la respuesta

Si el JWT y la solicitud de token de acceso tienen el formato correcto y la cuenta de servicio tiene permiso para realizar la operación, la respuesta JSON del servidor de autorización incluirá un token de acceso. El siguiente es un ejemplo de respuesta:

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

Los tokens de acceso se pueden volver a usar durante el período de duración especificado en el valor expires_in.

Cuándo vencen los tokens de acceso

Los tokens de acceso emitidos por el servidor de autorización de Google OAuth 2.0 caducan después de la duración que proporciona el valor expires_in. Cuando un token de acceso caduca, la aplicación debe generar otro JWT, firmarlo y solicitar otro token de acceso.