Autentica con un servidor de backend

Si usas el Acceso con Google en una app o sitio que se comunica con un backend tal vez debas identificar al usuario con sesión activa en el servidor. Para hacerlo de forma segura, después de que un usuario acceda correctamente, envía el un token de ID al servidor con HTTPS. Luego, en el servidor, verifica la integridad del token de ID y usar la información del usuario contenida en el token para establecer una sesión o crea una cuenta nueva.

Envía el token de ID a tu servidor

Después de que un usuario accede correctamente, obtén su token de ID:

function onSignIn(googleUser) {
  var id_token = googleUser.getAuthResponse().id_token;
  ...
}

Luego, envía el token de ID a tu servidor con una solicitud HTTPS POST:

var xhr = new XMLHttpRequest();
xhr.open('POST', 'https://yourbackend.example.com/tokensignin');
xhr.setRequestHeader('Content-Type', 'application/x-www-form-urlencoded');
xhr.onload = function() {
  console.log('Signed in as: ' + xhr.responseText);
};
xhr.send('idtoken=' + id_token);

Verifica la integridad del token de ID

Luego de recibir el token de ID a través de HTTPS POST, debes verificar la integridad del token.

Para verificar que el token sea válido, asegúrate de que se cumplan los siguientes criterios:

  • Google firma correctamente el token de ID. Usa las claves públicas de Google (disponibles en formato JWK o PEM) para verificar la firma del token. Estas claves rotan con regularidad. Examina el encabezado Cache-Control en la respuesta para determinar cuándo debes recuperarlas de nuevo.
  • El valor de aud en el token de ID es igual a uno de los IDs de cliente de tu app. Esta verificación es necesaria para evitar que los tokens de ID emitidos para una app maliciosa se usen para acceder a datos sobre el mismo usuario en el servidor de backend de tu app.
  • El valor de iss en el token de ID es igual a accounts.google.com o https://accounts.google.com.
  • No pasó el tiempo de vencimiento (exp) del token de ID.
  • Si necesitas validar que el token de ID representa una cuenta de organización de Google Workspace o Cloud Identity, puedes verificar el reclamo hd, que indica el dominio alojado del usuario. Se debe usar cuando se restringe el acceso a un recurso solo a los miembros de ciertos dominios. La ausencia de este reclamo indica que la cuenta no pertenece a un dominio alojado por Google.

Con los campos email, email_verified y hd, puedes determinar si Google aloja una dirección de correo electrónico y es autoritativo para ella. En los casos en que Google es autoritativo, se sabe que el usuario es el propietario legítimo de la cuenta, por lo que puedes omitir la contraseña o cualquier otro método de desafío.

Casos en los que Google es una fuente acreditada:

  • Si email tiene el sufijo @gmail.com, se trata de una cuenta de Gmail.
  • email_verified es verdadero y hd está configurado, se trata de una cuenta de Google Workspace.

Los usuarios pueden registrarse para obtener Cuentas de Google sin usar Gmail ni Google Workspace. Cuando email no contiene un sufijo @gmail.com y hd está ausente, Google no es autoritativo y se recomiendan métodos de contraseña o de otro tipo para verificar al usuario. email_verified también puede ser verdadero, ya que Google verificó inicialmente al usuario cuando se creó la Cuenta de Google. Sin embargo, es posible que la propiedad de la cuenta de correo electrónico de terceros haya cambiado desde entonces.

En lugar de escribir tu propio código para realizar estos pasos de verificación, te recomendamos que uses una biblioteca cliente de las APIs de Google para tu plataforma o una biblioteca JWT de uso general. Para el desarrollo y la depuración, puedes llamar a nuestro extremo de validación tokeninfo.

Using a Google API Client Library

Using one of the Google API Client Libraries (e.g. Java, Node.js, PHP, Python) is the recommended way to validate Google ID tokens in a production environment.

Java

To validate an ID token in Java, use the GoogleIdTokenVerifier object. For example:

import com.google.api.client.googleapis.auth.oauth2.GoogleIdToken;
import com.google.api.client.googleapis.auth.oauth2.GoogleIdToken.Payload;
import com.google.api.client.googleapis.auth.oauth2.GoogleIdTokenVerifier;

...

GoogleIdTokenVerifier verifier = new GoogleIdTokenVerifier.Builder(transport, jsonFactory)
    // Specify the WEB_CLIENT_ID of the app that accesses the backend:
    .setAudience(Collections.singletonList(WEB_CLIENT_ID))
    // Or, if multiple clients access the backend:
    //.setAudience(Arrays.asList(WEB_CLIENT_ID_1, WEB_CLIENT_ID_2, WEB_CLIENT_ID_3))
    .build();

// (Receive idTokenString by HTTPS POST)

GoogleIdToken idToken = verifier.verify(idTokenString);
if (idToken != null) {
  Payload payload = idToken.getPayload();

  // Print user identifier. This ID is unique to each Google Account, making it suitable for
  // use as a primary key during account lookup. Email is not a good choice because it can be
  // changed by the user.
  String userId = payload.getSubject();
  System.out.println("User ID: " + userId);

  // Get profile information from payload
  String email = payload.getEmail();
  boolean emailVerified = Boolean.valueOf(payload.getEmailVerified());
  String name = (String) payload.get("name");
  String pictureUrl = (String) payload.get("picture");
  String locale = (String) payload.get("locale");
  String familyName = (String) payload.get("family_name");
  String givenName = (String) payload.get("given_name");

  // Use or store profile information
  // ...

} else {
  System.out.println("Invalid ID token.");
}

The GoogleIdTokenVerifier.verify() method verifies the JWT signature, the aud claim, the iss claim, and the exp claim.

If you need to validate that the ID token represents a Google Workspace or Cloud organization account, you can verify the hd claim by checking the domain name returned by the Payload.getHostedDomain() method. The domain of the email claim is insufficient to ensure that the account is managed by a domain or organization.

Node.js

To validate an ID token in Node.js, use the Google Auth Library for Node.js. Install the library: 

npm install google-auth-library --save
 Then, call the verifyIdToken() function. For example:

const {OAuth2Client} = require('google-auth-library');
const client = new OAuth2Client();
async function verify() {
  const ticket = await client.verifyIdToken({
      idToken: token,
      audience: WEB_CLIENT_ID,  // Specify the WEB_CLIENT_ID of the app that accesses the backend
      // Or, if multiple clients access the backend:
      //[WEB_CLIENT_ID_1, WEB_CLIENT_ID_2, WEB_CLIENT_ID_3]
  });
  const payload = ticket.getPayload();
  // This ID is unique to each Google Account, making it suitable for use as a primary key
  // during account lookup. Email is not a good choice because it can be changed by the user.
  const userid = payload['sub'];
  // If the request specified a Google Workspace domain:
  // const domain = payload['hd'];
}
verify().catch(console.error);

The verifyIdToken function verifies the JWT signature, the aud claim, the exp claim, and the iss claim.

If you need to validate that the ID token represents a Google Workspace or Cloud organization account, you can check the hd claim, which indicates the hosted domain of the user. This must be used when restricting access to a resource to only members of certain domains. The absence of this claim indicates that the account does not belong to a Google hosted domain.

PHP

To validate an ID token in PHP, use the Google API Client Library for PHP. Install the library (for example, using Composer): 

composer require google/apiclient
 Then, call the verifyIdToken() function. For example:

require_once 'vendor/autoload.php';

// Get $id_token via HTTPS POST.

$client = new Google_Client(['client_id' => $WEB_CLIENT_ID]);  // Specify the WEB_CLIENT_ID of the app that accesses the backend
$payload = $client->verifyIdToken($id_token);
if ($payload) {
  // This ID is unique to each Google Account, making it suitable for use as a primary key
  // during account lookup. Email is not a good choice because it can be changed by the user.
  $userid = $payload['sub'];
  // If the request specified a Google Workspace domain
  //$domain = $payload['hd'];
} else {
  // Invalid ID token
}

The verifyIdToken function verifies the JWT signature, the aud claim, the exp claim, and the iss claim.

If you need to validate that the ID token represents a Google Workspace or Cloud organization account, you can check the hd claim, which indicates the hosted domain of the user. This must be used when restricting access to a resource to only members of certain domains. The absence of this claim indicates that the account does not belong to a Google hosted domain.

Python

To validate an ID token in Python, use the verify_oauth2_token function. For example:

from google.oauth2 import id_token
from google.auth.transport import requests

# (Receive token by HTTPS POST)
# ...

try:
    # Specify the WEB_CLIENT_ID of the app that accesses the backend:
    idinfo = id_token.verify_oauth2_token(token, requests.Request(), WEB_CLIENT_ID)

    # Or, if multiple clients access the backend server:
    # idinfo = id_token.verify_oauth2_token(token, requests.Request())
    # if idinfo['aud'] not in [WEB_CLIENT_ID_1, WEB_CLIENT_ID_2, WEB_CLIENT_ID_3]:
    #     raise ValueError('Could not verify audience.')

    # If the request specified a Google Workspace domain
    # if idinfo['hd'] != DOMAIN_NAME:
    #     raise ValueError('Wrong domain name.')

    # ID token is valid. Get the user's Google Account ID from the decoded token.
    # This ID is unique to each Google Account, making it suitable for use as a primary key
    # during account lookup. Email is not a good choice because it can be changed by the user.
    userid = idinfo['sub']
except ValueError:
    # Invalid token
    pass

The verify_oauth2_token function verifies the JWT signature, the aud claim, and the exp claim. You must also verify the hd claim (if applicable) by examining the object that verify_oauth2_token returns. If multiple clients access the backend server, also manually verify the aud claim.

Llama al extremo de tokeninfo

Una manera sencilla de validar la firma de un token de ID para la depuración es usa el extremo tokeninfo. Llamar a este extremo implica una solicitud de red adicional que realice la mayor parte de la validación por ti mientras pruebas las y la extracción de cargas útiles en tu propio código. No es apto para uso en producción código, ya que las solicitudes pueden ser limitadas o estar sujetas a errores intermitentes.

Para validar un token de ID con el extremo tokeninfo, crea un protocolo HTTPS POST o GET al extremo y pasa tu token de ID en el Parámetro id_token. Por ejemplo, para validar el token “XYZ123”, realiza la siguiente solicitud GET:

https://oauth2.googleapis.com/tokeninfo?id_token=XYZ123

Si el token está firmado correctamente, y iss y exp tienen los valores esperados, recibirás una respuesta HTTP 200, contiene las reclamaciones de tokens de ID con formato JSON. Esta es una respuesta de ejemplo:

{
 // These six fields are included in all Google ID Tokens.
 "iss": "https://accounts.google.com",
 "sub": "110169484474386276334",
 "azp": "1008719970978-hb24n2dstb40o45d4feuo2ukqmcc6381.apps.googleusercontent.com",
 "aud": "1008719970978-hb24n2dstb40o45d4feuo2ukqmcc6381.apps.googleusercontent.com",
 "iat": "1433978353",
 "exp": "1433981953",

 // These seven fields are only included when the user has granted the "profile" and
 // "email" OAuth scopes to the application.
 "email": "testuser@gmail.com",
 "email_verified": "true",
 "name" : "Test User",
 "picture": "https://lh4.googleusercontent.com/-kYgzyAWpZzJ/ABCDEFGHI/AAAJKLMNOP/tIXL9Ir44LE/s99-c/photo.jpg",
 "given_name": "Test",
 "family_name": "User",
 "locale": "en"
}

Si necesitas validar que el token de ID representa una cuenta de Google Workspace, puedes verificarlo. La reclamación hd, que indica el dominio alojado del usuario Se debe usar cuando restringir el acceso a un recurso únicamente a los miembros de ciertos dominios. La ausencia de este reclamo indica que la cuenta no pertenece a un dominio alojado de Google Workspace.

Crea una cuenta o sesión

Después de que hayas verificado el token, comprueba si el usuario ya está en tu cuenta de usuario en la base de datos. Si es así, establece una sesión autenticada para el usuario. Si el usuario aún no está en tu base de datos de usuarios, crea un nuevo registro de usuario a partir de la en la carga útil del token de ID y establecer una sesión para el usuario. Puedes pedirle al usuario para obtener cualquier información de perfil adicional que necesites cuando detectes usuario recién creado en tu app.

Proteger las contraseñas de los usuarios con la Protección integral de la cuenta

Cuando confías en Google para que un usuario acceda, te beneficiarás automáticamente de todas las la infraestructura y las funciones de seguridad que Google creó para proteger los datos del usuario. Sin embargo, en el caso improbable de que se vulnere la Cuenta de Google del usuario o de que haya otro evento de seguridad significativo, tu app también puede ser vulnerable a ataques. Para proteger mejor tus de eventos de seguridad importantes, usa Varias cuentas Protección para recibir alertas de seguridad de Google. Cuando recibes estos eventos, obtener visibilidad sobre los cambios importantes en la seguridad de la cuenta de Google del usuario y podrás tomar medidas en el servicio para proteger tus cuentas.