Uso de OAuth 2.0 para aplicaciones de servidor a servidor

Cómo crear un JWT

Un JWT se compone de tres partes: un encabezado, un conjunto de reclamaciones y una firma. El encabezado y el conjunto de reclamos son objetos JSON. Estos objetos JSON se serializan en bytes UTF-8 y, luego, se codifican con 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 reclamos 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}

Cómo formar el encabezado JWT

El encabezado consta de tres campos que indican el algoritmo de firma, el formato de la aserción y el [ID de clave de la clave de la cuenta de servicio](https://cloud.google.com/iam/docs/reference/rest/v1/projects.serviceAccounts.keys) que se usó para firmar el JWT. El algoritmo y el formato son obligatorios, y cada campo tiene un solo valor. A medida que se incorporen algoritmos y formatos adicionales, este encabezado cambiará según corresponda. El ID de la clave es opcional y, si se especifica un ID de clave incorrecto, GCP probará todas las claves asociadas con la cuenta de servicio para verificar el token y lo rechazará si no se encuentra una clave válida. Google se reserva el derecho de rechazar los tokens con ID de clave incorrectos en el futuro.

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

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

La representación en Base64url es la siguiente:

          eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsICJraWQiOiIzNzBhYjc5YjQ1MTNlYjliYWQ3YzliZDE2YTk1Y2I3NmI1YjJhNTZhIn0=

Cómo formar el conjunto de reclamaciones de JWT

El conjunto de reclamaciones de JWT contiene información sobre el JWT, incluidos los permisos que se solicitan (permisos), el objetivo del token, la entidad emisora, la hora de emisión del token y la vida útil 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 en el cálculo de la firma.

Reclamos obligatorios

A continuación, se muestran los reclamos necesarios para el conjunto de reclamos de JWT. Pueden aparecer en cualquier orden en el conjunto de reclamos.

A continuación, se muestra la representación JSON de los campos obligatorios en un conjunto de reclamaciones JWT:

{
  "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 particular de una organización. Se debe otorgar el permiso para realizar este tipo de robo de identidad antes de que una aplicación pueda suplantar la identidad de un usuario. Por lo general, es controlado por un administrador avanzado. Si deseas 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 le 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 configurada 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
}

Codificar el conjunto de reclamaciones JWT

Al igual que el encabezado JWT, el conjunto de reclamaciones JWT debe serializarse en UTF-8 y tener codificación Base64url-safe. A continuación, se muestra un ejemplo de una representación JSON de un conjunto de reclamaciones JWT:

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

Cómo procesar la firma

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

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

El algoritmo de firma del encabezado JWT debe usarse cuando se calcula la firma. El único algoritmo de firma compatible con el servidor de autorización de Google OAuth 2.0 es RSA mediante el uso del 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 obtenida del Google API Console. El resultado será un array de bytes.

La firma debe estar codificada en Base64url. El encabezado, el conjunto de reclamos y la firma se concatenan con un carácter de punto (.). El resultado es el JWT. Debe ser el 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 HTTPS POST y el cuerpo está codificado por 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 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 la solicitud de token de acceso y JWT se forma correctamente y la cuenta de servicio tiene permiso para realizar la operación, la respuesta JSON del servidor de autorización incluye un token de acceso. La siguiente es una respuesta de ejemplo:

{
  "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 especificado por 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 vencen después de la duración proporcionada por el valor expires_in. Cuando un token de acceso vence, la aplicación debe generar otro JWT, firmarlo y solicitar otro token de acceso.