Usa OAuth 2.0 para aplicaciones de servidor a servidor

El sistema de Google OAuth 2.0 admite interacciones de servidor a servidor, como las que se producen entre una aplicación web y un servicio de Google. Para esta situación, necesitas una cuenta de servicio, que es una cuenta que pertenece a tu aplicación, no a un usuario final individual. Tu aplicación llama a las APIs de Google en nombre de la cuenta de servicio, por lo que los usuarios no participan directamente. A veces, esta situación se denomina "OAuth de dos segmentos" o "2LO". (El término relacionado "OAuth de tres segmentos" hace referencia a situaciones en las que tu aplicación llama a las APIs de Google en nombre de los usuarios finales y en las que, a veces, se requiere el consentimiento del usuario).

Consulta las prácticas recomendadas para las cuentas de servicio para obtener más información.

Por lo general, una aplicación usa una cuenta de servicio cuando usa las APIs de Google para trabajar con sus propios datos en lugar de los datos de un usuario. Por ejemplo, una aplicación que usa Google Cloud Datastore para la persistencia de datos usaría una cuenta de servicio para autenticar sus llamadas a la API de Datastore de Google Cloud.

Los administradores de dominio de Google Workspace también pueden otorgar autoridad para todo el dominio a las cuentas de servicio para que accedan a los datos de los usuarios en nombre de los usuarios del dominio.

En este documento, se describe cómo una aplicación puede completar el flujo de OAuth 2.0 de servidor a servidor con una biblioteca cliente de las APIs de Google (recomendado) o HTTP.

Descripción general

Para admitir interacciones de servidor a servidor, primero crea una cuenta de servicio para tu proyecto en la Consola de APIs. Si deseas acceder a los datos de los usuarios en tu cuenta de Google Workspace, delega el acceso de todo el dominio a la cuenta de servicio.

Luego, tu aplicación se prepara para realizar llamadas autorizadas a la API con las credenciales de la cuenta de servicio para solicitar un token de acceso del servidor de autenticación de OAuth 2.0.

Por último, tu aplicación puede usar el token de acceso para llamar a las APIs de Google.

Crea una cuenta de servicio

Las credenciales de una cuenta de servicio incluyen una dirección de correo electrónico generada que es única y, al menos, un par de claves públicas y privadas. Si se habilita la delegación de todo el dominio, un ID de cliente también forma parte de las credenciales de la cuenta de servicio.

Si tu aplicación se ejecuta en Google App Engine, se configura automáticamente una cuenta de servicio cuando creas el proyecto.

Si tu aplicación se ejecuta en Google Compute Engine, también se configura automáticamente una cuenta de servicio cuando creas tu proyecto, pero debes especificar los permisos a los que tu aplicación necesita acceder cuando creas una instancia de Google Compute Engine. Para obtener más información, consulta Prepara una instancia para usar cuentas de servicio.

Si tu aplicación no se ejecuta en Google App Engine ni en Google Compute Engine, debes obtener estas credenciales en la Consola de APIs de Google. Para generar credenciales de cuenta de servicio o ver las credenciales públicas que ya generaste, haz lo siguiente:

Primero, crea una cuenta de servicio:

  1. Abre la página Cuentas de servicio.
  2. Si se te solicita, selecciona un proyecto o crea uno nuevo.
  3. Haz clic en  Crear cuenta de servicio.
  4. En Detalles de la cuenta de servicio, escribe un nombre, un ID y una descripción para la cuenta de servicio y, luego, haz clic en Crear y continuar.
  5. Opcional: En Otorgar a esta cuenta de servicio acceso al proyecto, selecciona los roles de IAM que se otorgarán a la cuenta de servicio.
  6. Haz clic en Continuar.
  7. Opcional: En Otorga acceso a usuarios a esta cuenta de servicio, agrega los usuarios o grupos que tienen permiso para usar y administrar la cuenta de servicio.
  8. Haz clic en Listo.

A continuación, crea una clave de cuenta de servicio:

  1. Haz clic en la dirección de correo electrónico de la cuenta de servicio que creaste.
  2. Haz clic en la pestaña Claves.
  3. En la lista desplegable Agregar clave, selecciona Crear clave nueva.
  4. Haz clic en Crear.

Si quieres obtener más información, consulta Prácticas recomendadas para administrar claves de cuentas de servicio.

Puedes volver a la Consola de APIs en cualquier momento para ver la dirección de correo electrónico, las huellas digitales de la clave pública y otra información, o bien para generar pares de claves públicas y privadas adicionales. Para obtener más detalles sobre las credenciales de cuenta de servicio en la Consola de APIs, consulta Cuentas de servicio en el archivo de ayuda de la Consola de APIs.

Toma nota de la dirección de correo electrónico de la cuenta de servicio y almacena el archivo de claves privadas de la cuenta de servicio en una ubicación a la que pueda acceder tu aplicación. Tu aplicación las necesita para realizar llamadas autorizadas a la API.

Delega la autoridad para todo el dominio a la cuenta de servicio

Con una cuenta de Google Workspace, un administrador de Workspace de la organización puede autorizar que una aplicación acceda a los datos de los usuarios de Workspace en nombre de los usuarios del dominio de Google Workspace. Por ejemplo, una aplicación que usa la API de Calendario de Google para agregar eventos a los calendarios de todos los usuarios de un dominio de Google Workspace usaría una cuenta de servicio para acceder a la API de Calendario de Google en nombre de los usuarios. Autorizar a una cuenta de servicio para que acceda a los datos en nombre de los usuarios de un dominio a veces se denomina "delegar la autoridad para todo el dominio" a una cuenta de servicio.

Para delegar la autoridad en todo el dominio a una cuenta de servicio, un administrador avanzado del dominio de Google Workspace debe completar los siguientes pasos:

  1. En la Consola del administrador de tu dominio de Google Workspace, ve a Menú principal > Seguridad > Control de acceso y datos > Controles de API.
  2. En el panel Delegación de todo el dominio, selecciona Administrar la delegación de todo el dominio.
  3. Haz clic en Agregar nueva.
  4. En el campo ID de cliente, ingresa el ID de cliente de la cuenta de servicio. Puedes encontrar el ID de cliente de tu cuenta de servicio en la página Cuentas de servicio.
  5. En el campo Permisos de OAuth (delimitados por comas), ingresa la lista de permisos a los que se debe otorgar acceso a tu aplicación. Por ejemplo, si tu aplicación necesita acceso completo en todo el dominio a la API de Google Drive y a la API de Calendario de Google, ingresa lo siguiente: https://www.googleapis.com/auth/drive, https://www.googleapis.com/auth/calendar.
  6. Haz clic en Autorizar.

Ahora, tu aplicación tiene la autoridad para realizar llamadas a la API como usuarios de tu dominio de Workspace (para "suplantar" usuarios). Cuando te prepares para realizar estas llamadas a la API delegadas, especificarás de forma explícita el usuario que se suplantará.

Realiza una llamada a la API delegada

En las siguientes secciones, se muestra cómo realizar una llamada a la API autorizada con una biblioteca cliente de las APIs de Google o interactuando directamente con el sistema de OAuth 2.0 a través de HTTP.

Java

Después de obtener la dirección de correo electrónico del cliente y la clave privada de la Consola de APIs, usa la biblioteca de autenticación de Google para Java para crear un objeto GoogleCredentials a partir de las credenciales de la cuenta de servicio y los permisos a los que tu aplicación necesita acceder. Por ejemplo:

import com.google.auth.oauth2.GoogleCredentials;
import com.google.api.services.sqladmin.SQLAdminScopes;

// ...

GoogleCredentials credentials = GoogleCredentials.fromStream(new FileInputStream("ServiceAccountKey.json"))
    .createScoped(Collections.singleton(SQLAdminScopes.SQLSERVICE_ADMIN));

Si estás desarrollando una app en Google Cloud, puedes usar las credenciales predeterminadas de la aplicación, lo que puede simplificar el proceso.

Delega la autoridad para todo el dominio

Si delegaste el acceso a todo el dominio a la cuenta de servicio y deseas actuar en nombre de una cuenta de usuario, especifica la dirección de correo electrónico de la cuenta de usuario con el método createDelegated del objeto GoogleCredentials. Por ejemplo:

GoogleCredentials credentials = GoogleCredentials.fromStream(new FileInputStream("ServiceAccountKey.json"))
    .createScoped(Collections.singleton(SQLAdminScopes.SQLSERVICE_ADMIN))
    .createDelegated("workspace-user@example.com");

El objeto GoogleCredentials se usa para llamar al método createDelegated(). El argumento para el método createDelegated() debe ser un usuario que pertenezca a tu cuenta de Workspace. El código que realiza la solicitud usará esta credencial para llamar a las APIs de Google con tu cuenta de servicio.

Python

Después de obtener la dirección de correo electrónico del cliente de API y la clave privada de la Consola de APIs, usa la biblioteca cliente de las APIs de Google para Python para completar los siguientes pasos:

  1. Crea un objeto Credentials a partir de las credenciales de la cuenta de servicio y los permisos a los que tu aplicación necesita acceder. Por ejemplo:
    from google.oauth2 import service_account
    
    SCOPES = ['https://www.googleapis.com/auth/sqlservice.admin']
    SERVICE_ACCOUNT_FILE = '/path/to/ServiceAccountKey.json'
    
    credentials = service_account.Credentials.from_service_account_file(
            SERVICE_ACCOUNT_FILE, scopes=SCOPES)

    Si estás desarrollando una app en Google Cloud, puedes usar las credenciales predeterminadas de la aplicación, lo que puede simplificar el proceso.

  2. Delega la autoridad para todo el dominio

    Si delegaste el acceso de todo el dominio a la cuenta de servicio y deseas suplantar la identidad de una cuenta de usuario, usa el método with_subject de un objeto ServiceAccountCredentials existente. Por ejemplo:

    delegated_credentials = credentials.with_subject('user@example.org')

Usa el objeto Credentials para llamar a las APIs de Google en tu aplicación.

HTTP/REST

Después de obtener el ID de cliente y la clave privada de la Consola de APIs, tu aplicación debe completar los siguientes pasos:

  1. Crea un token web JSON (JWT, que se pronuncia "jot") que incluya un encabezado, un conjunto de reclamaciones y una firma.
  2. Solicita un token de acceso al servidor de autorización de Google OAuth 2.0.
  3. Controla la respuesta JSON que devuelve el servidor de autorización.

En las siguientes secciones, se describe cómo completar estos pasos.

Si la respuesta incluye un token de acceso, puedes usarlo para llamar a una API de Google. (Si la respuesta no incluye un token de acceso, es posible que tu JWT y la solicitud de token no estén formados correctamente o que la cuenta de servicio no tenga permiso para acceder a los permisos solicitados).

Cuando el token de acceso vence, tu aplicación genera otro JWT, lo firma y solicita otro token de acceso.

La aplicación de servidor usa un JWT para solicitar un token del servidor de autorización de Google y, luego, usa el token para llamar a un endpoint de API de Google. No
                  hay ningún usuario final involucrado.
Figura 1: La aplicación de servidor usa un JWT para solicitar un token del servidor de autorización de Google y, luego, usa el token para llamar a un endpoint de API de Google. No hay ningún usuario final involucrado.

En el resto de esta sección, se describen los detalles para crear un JWT, firmarlo, formar la solicitud de token de acceso y controlar la respuesta.

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 con la codificación Base64url. Esta codificación proporciona resiliencia contra los cambios de codificación debido a 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 cadena base de la firma es la siguiente:

{Base64url encoded header}.{Base64url encoded claim set}
Crea el encabezado del JWT

El encabezado consta de dos campos obligatorios: el algoritmo de firma y el formato de la aserción, y un ID de clave opcional:

  • El algoritmo es obligatorio y solo tiene un valor: "alg": "RS256".
  • El formato es obligatorio y solo tiene un valor: "typ": "JWT".
  • El ID de clave es opcional y es el ID de la clave de la cuenta de servicio que se usa para firmar el JWT. Si se especifica un ID de clave incorrecto, se prueban todas las claves asociadas con la cuenta de servicio. Si no se encuentra ninguna clave válida, se rechaza el token. Google se reserva el derecho de rechazar tokens con IDs de clave incorrectos.

Las cuentas de servicio se basan en el algoritmo RSA SHA-256 y 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 de esto es la siguiente:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsICJraWQiOiIzNzBhYjc5YjQ1MTNlYjliYWQ3YzliZDE2YTk1Y2I3NmI1YjJhNTZhIn0=
Crea 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 destino del token, la entidad emisora, la hora en que se emitió el token y la duración del token. La mayoría de los campos son obligatorios. Al igual que el encabezado de JWT, el conjunto de reclamaciones de JWT es un objeto JSON y se usa en el cálculo de la firma.

Reclamaciones obligatorias

Las reclamaciones obligatorias en el conjunto de reclamaciones del JWT pueden aparecer en cualquier orden en el conjunto de reclamaciones.

Nombre Descripción
iss Es la dirección de correo electrónico de la cuenta de servicio.
scope Es una lista delimitada por espacios de los permisos que solicita la aplicación.
aud Es un descriptor del objetivo previsto de la aserción. Cuando se realiza una solicitud de token de acceso, este valor siempre es https://oauth2.googleapis.com/token.
exp Es la hora de vencimiento de la aserción, especificada como segundos desde las 00:00:00 UTC del 1 de enero de 1970. Este valor tiene un máximo de 1 hora después de la hora de emisión.
iat Es la hora en que se emitió la aserción, especificada como segundos desde las 00:00:00 UTC del 1 de enero de 1970.

Este es un ejemplo de una representación JSON de los campos obligatorios en un conjunto de reclamaciones de 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
}
Declaraciones 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 de una organización. El permiso para realizar este tipo de robo de identidad se debe otorgar antes de que una aplicación pueda robar la identidad de un usuario, y, por lo general, lo administra un administrador avanzado. Para obtener más información, consulta Controla 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 el conjunto de reclamaciones del JWT como el valor del campo sub.

Nombre Descripción
sub Es la dirección de correo electrónico del usuario para el que la aplicación solicita acceso delegado.

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.

Este es un ejemplo de un conjunto de reclamaciones de 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 del JWT, el conjunto de reclamaciones del JWT debe serializarse en UTF-8 y codificarse en Base64url-safe. Este es un ejemplo de una representación JSON de un conjunto de reclamaciones 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 JSON (JWS) es la especificación que guía la mecánica de generación de la firma para el JWT. La entrada de la firma es el array de bytes del siguiente contenido:

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

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

Firma la representación UTF-8 de la entrada con SHA256withRSA (también conocido como RSASSA-PKCS1-V1_5-SIGN con la función hash SHA-256) con la clave privada obtenida de la Consola de APIs de Google. El resultado será un array de bytes.

Luego, la firma debe codificarse en Base64url. El encabezado, el conjunto de reclamaciones y la firma se concatenan con un carácter de punto (.). El resultado es el JWT. Debería ser el siguiente (se agregaron saltos de línea para mayor claridad):

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

Este es un ejemplo de un JWT antes de la codificación en 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]

Este es un ejemplo de un JWT que se firmó y está listo para la transmisión:

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

Solicita un 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 en la URL. Por ejemplo:

https://oauth2.googleapis.com/token

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

Nombre Descripción
grant_type Usa la siguiente cadena, codificada en URL según sea necesario: urn:ietf:params:oauth:grant-type:jwt-bearer
assertion El JWT, incluida la firma.

Este es un volcado sin procesar de la solicitud HTTPS POST 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

Esta es 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

Control de respuestas

Si el JWT y la solicitud de token de acceso se forman de manera correcta 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. A continuación, se muestra 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 reutilizar durante el período especificado por el valor expires_in.

Consideración de seguridad importante: Comprende la suplantación de identidad (impersonation)

Cuando delegas la autoridad para todo el dominio, no otorgas a la cuenta de servicio acceso directo a todos los datos del usuario. En su lugar, la autorizas para que actúe en nombre de usuarios específicos cuando realiza llamadas a la API.
  • El acceso se realiza en nombre de un usuario: Tu aplicación debe especificar qué usuario se debe suplantar para cada solicitud a la API. Luego, la aplicación actúa con los permisos de ese usuario específico, no con privilegios elevados o de todo el dominio.
  • Los permisos son limitados: El acceso de la cuenta de servicio está restringido por dos factores: los permisos del usuario suplantado y los permisos de OAuth que autorizas en la Consola del administrador. No puede acceder a los datos a los que el usuario suplantado no puede acceder.
  • Principio de privilegio mínimo: Debido a que esta función permite el acceso a los datos del usuario sin su consentimiento directo, es fundamental seguir las prácticas recomendadas de seguridad. Otorga solo los permisos de OAuth necesarios y asegúrate de comprender las implicaciones de seguridad.
Para obtener lineamientos de seguridad detallados, consulta las prácticas recomendadas para la delegación de todo el dominio.

Llama a las API de Google

Java

Usa el objeto GoogleCredentials para llamar a las APIs de Google. Para ello, completa los siguientes pasos:

  1. Crea un objeto de servicio para la API a la que deseas llamar con el objeto GoogleCredentials. Por ejemplo:
    SQLAdmin sqladmin =
        new SQLAdmin.Builder(httpTransport, JSON_FACTORY, credentials).build();
  2. Realiza solicitudes al servicio de la API con la interfaz que proporciona el objeto de servicio. Por ejemplo, para enumerar las instancias de las bases de datos de Cloud SQL en el proyecto exciting-example-123, haz lo siguiente:
    SQLAdmin.Instances.List instances =
        sqladmin.instances().list("exciting-example-123").execute();

Python

Usa el objeto Credentials autorizado para llamar a las APIs de Google. Para ello, completa los siguientes pasos:

  1. Crea un objeto de servicio para la API a la que deseas llamar. Para compilar un objeto de servicio, llama a la función build con el nombre y la versión de la API, y el objeto Credentials autorizado. Por ejemplo, para llamar a la versión 1beta3 de la API de Cloud SQL Admin, haz lo siguiente:
    import googleapiclient.discovery
    
    sqladmin = googleapiclient.discovery.build('sqladmin', 'v1beta3', credentials=credentials)
  2. Realiza solicitudes al servicio de la API con la interfaz que proporciona el objeto de servicio. Por ejemplo, para enumerar las instancias de las bases de datos de Cloud SQL en el proyecto exciting-example-123, haz lo siguiente:
    response = sqladmin.instances().list(project='exciting-example-123').execute()

HTTP/REST

Después de que tu aplicación obtenga un token de acceso, puedes usarlo para realizar llamadas a una API de Google en nombre de una cuenta de servicio o de usuario determinada si se otorgaron los permisos de acceso que requiere la API. Para ello, incluye el token de acceso en una solicitud a la API con un parámetro de consulta access_token o un valor de encabezado HTTP Authorization Bearer. Cuando sea posible, es preferible el encabezado HTTP, ya que las cadenas de consulta suelen ser visibles en los registros del servidor. En la mayoría de los casos, puedes usar una biblioteca cliente para configurar tus llamadas a las APIs de Google (por ejemplo, cuando llamas a la API de Drive Files).

Puedes probar todas las APIs de Google y ver sus permisos en OAuth 2.0 Playground.

Ejemplos de HTTP GET

Una llamada al extremo drive.files (la API de Drive Files) con el encabezado HTTP Authorization: Bearer podría verse de la siguiente manera. Ten en cuenta que debes especificar tu propio token de acceso:

GET /drive/v2/files HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

Aquí se muestra una llamada a la misma API para el usuario autenticado con el parámetro de cadena de consulta access_token:

GET https://www.googleapis.com/drive/v2/files?access_token=access_token

Ejemplos de curl

Puedes probar estos comandos con la aplicación de línea de comandos de curl. A continuación, se muestra un ejemplo en el que se usa la opción de encabezado HTTP (preferida):

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files

O, como alternativa, la opción de parámetro de cadena de consulta:

curl https://www.googleapis.com/drive/v2/files?access_token=access_token

Cuándo vencen los tokens de acceso

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

Códigos de error de JWT

Campo error Campo error_description Significado Cómo resolverlo
unauthorized_client Unauthorized client or scope in request. Si intentas usar la delegación de todo el dominio, la cuenta de servicio no está autorizada en la Consola del administrador del dominio del usuario.

Asegúrate de que la cuenta de servicio esté autorizada en la página Delegación de todo el dominio de la Consola del administrador para el usuario en la reclamación (campo) sub.

Si bien suele tardar unos minutos, la autorización puede demorar hasta 24 horas en propagarse a todos los usuarios de tu Cuenta de Google.

unauthorized_client Client is unauthorized to retrieve access tokens using this method, or client not authorized for any of the scopes requested. Se autorizó una cuenta de servicio con la dirección de correo electrónico del cliente en lugar del ID del cliente (numérico) en la Consola del administrador, o bien se usó un Grupo de Google para la autorización. En la página Delegación de todo el dominio de la Consola del administrador, quita el cliente y vuelve a agregarlo con el ID numérico, o quita el Grupo de Google y reemplázalo por la cuenta de servicio o de usuario individual.
access_denied (cualquier valor) Si usas la delegación de todo el dominio, uno o más de los permisos solicitados no están autorizados en la Consola del administrador.

Asegúrate de que la cuenta de servicio esté autorizada en la página Delegación para todo el dominio de la Consola del administrador para el usuario en la reclamación (campo) sub y que incluya todos los permisos que solicitas en la reclamación scope de tu JWT.

Confirma que el acceso a los servicios de Google no esté restringido. Para ello, revisa Administra el acceso a los servicios que no se controlan individualmente.

Si bien suele tardar unos minutos, la autorización puede demorar hasta 24 horas en propagarse a todos los usuarios de tu Cuenta de Google.

admin_policy_enforced (cualquier valor) La Cuenta de Google no puede autorizar uno o más de los permisos solicitados debido a las políticas de su administrador de Google Workspace.

Consulta el artículo de ayuda para administradores de Google Workspace Controla qué apps internas y de terceros acceden a los datos de Google Workspace para obtener más información sobre cómo un administrador puede restringir el acceso a todos los permisos o a los permisos sensibles y restringidos hasta que se otorgue acceso de forma explícita a tu ID de cliente de OAuth.

invalid_client (cualquier valor)

El cliente de OAuth o el token de JWT no son válidos o están configurados de forma incorrecta.

Consulta la descripción del error para obtener más detalles.

Asegúrate de que el token de JWT sea válido y contenga las reclamaciones correctas.

Verifica que el cliente de OAuth y la cuenta de servicio estén configurados correctamente y que uses la dirección de correo electrónico correcta.

Verifica que el token de JWT sea correcto y se haya emitido para el ID de cliente de la solicitud.

deleted_client (cualquier valor)

Se borró el cliente de OAuth que se usaba para realizar la solicitud. La eliminación puede ocurrir de forma manual o automática en el caso de clientes sin usar. Los clientes borrados se pueden restablecer en un plazo de 30 días a partir de la eliminación. Obtén más información.

Usa un ID de cliente que aún esté activo.

invalid_grant Not a valid email o Invalid email or User ID. El usuario no existe. Verifica que la dirección de correo electrónico en la reclamación (campo) sub sea correcta.
invalid_grant

Invalid JWT: Token must be a short-lived token (60 minutes) and in a reasonable timeframe. Check your 'iat' and 'exp' values and use a clock with skew to account for clock differences between systems.

Por lo general, esto significa que la hora del sistema local no es correcta. También podría suceder si el valor de exp es superior a 65 minutos en el futuro con respecto al valor de iat o si el valor de exp es inferior al valor de iat.

Asegúrate de que el reloj del sistema en el que se genera el JWT sea correcto. Si es necesario, sincroniza la hora con NTP de Google.

invalid_grant Invalid JWT Signature.

La aserción de JWT se firma con una clave privada que no está asociada con la cuenta de servicio identificada por el correo electrónico del cliente, o bien la clave que se usó se borró, se inhabilitó o venció.

Como alternativa, la aserción de JWT podría estar codificada de forma incorrecta: debe estar codificada en Base64, sin saltos de línea ni signos de igual de relleno.

Decodifica el conjunto de reclamaciones de JWT y verifica que la clave que firmó la aserción esté asociada con la cuenta de servicio.

Intenta usar una biblioteca de OAuth proporcionada por Google para asegurarte de que el JWT se genere correctamente.

invalid_scope Invalid OAuth scope or ID token audience provided. No se solicitaron permisos (lista vacía de permisos) o uno de los permisos solicitados no existe (es decir, no es válido).

Asegúrate de que se complete la reclamación (campo) scope del JWT y compara los permisos que contiene con los permisos documentados para las APIs que deseas usar, para garantizar que no haya errores ni errores tipográficos.

Ten en cuenta que la lista de permisos en la reclamación scope debe estar separada por espacios, no por comas.

disabled_client The OAuth client was disabled. La clave que se usa para firmar la aserción de JWT está inhabilitada.

Ve a la consola de APIs de Google y, en IAM y administración > Cuentas de servicio, habilita la cuenta de servicio que contiene el "ID de clave" que se usó para firmar la aserción.

org_internal This client is restricted to users within its organization. El ID de cliente de OAuth de la solicitud forma parte de un proyecto que limita el acceso a las Cuentas de Google en una organización de Google Cloud específica.

Usa una cuenta de servicio de la organización para autenticarte. Confirma la configuración del tipo de usuario para tu aplicación de OAuth.

Anexo: Autorización de la cuenta de servicio sin OAuth

Con algunas APIs de Google, puedes realizar llamadas a la API autorizadas con un JWT firmado directamente como un token del portador, en lugar de un token de acceso de OAuth 2.0. Cuando esto sea posible, puedes evitar tener que realizar una solicitud de red al servidor de autorización de Google antes de realizar una llamada a la API.

Si la API a la que deseas llamar tiene una definición de servicio publicada en el repositorio de GitHub de las APIs de Google, puedes realizar llamadas a la API autorizadas con un JWT en lugar de un token de acceso. Para ello, sigue estos pasos:

  1. Crea una cuenta de servicio. Asegúrate de conservar el archivo JSON que obtienes cuando creas la cuenta.
  2. Con cualquier biblioteca de JWT estándar, como la que se encuentra en jwt.io, crea un JWT con un encabezado y una carga útil como los del siguiente ejemplo:
    {
      "alg": "RS256",
      "typ": "JWT",
      "kid": "abcdef1234567890"
    }
    .
    {
      "iss": "123456-compute@developer.gserviceaccount.com",
      "sub": "123456-compute@developer.gserviceaccount.com",
      "aud": "https://firestore.googleapis.com/",
      "iat": 1511900000,
      "exp": 1511903600
    }
    • Para el campo kid en el encabezado, especifica el ID de la clave privada de tu cuenta de servicio. Puedes encontrar este valor en el campo private_key_id del archivo JSON de tu cuenta de servicio.
    • En los campos iss y sub, especifica la dirección de correo electrónico de tu cuenta de servicio. Puedes encontrar este valor en el campo client_email del archivo JSON de tu cuenta de servicio. Este valor identifica de forma única al cliente y, funcionalmente, es el ID de cliente.
    • En el campo aud, especifica el endpoint de API. Por ejemplo: https://SERVICE.googleapis.com/
    • En el campo iat, especifica el tiempo Unix actual y, en el campo exp, especifica la hora exactamente 3,600 segundos después, cuando venza el JWT.

Firma el JWT con RSA-256 usando la clave privada que se encuentra en el archivo JSON de tu cuenta de servicio.

Por ejemplo:

Java

Usa google-auth-library-java y java-jwt:

import com.google.auth.oauth2.ServiceAccountCredentials;
...
GoogleCredentials credentials =
        GoogleCredentials.fromStream(new FileInputStream("MyProject-1234.json"));
PrivateKey privateKey = ((ServiceAccountCredentials) credentials).getPrivateKey();
String privateKeyId = ((ServiceAccountCredentials) credentials).getPrivateKeyId();

long now = System.currentTimeMillis();

try {
    Algorithm algorithm = Algorithm.RSA256(null, privateKey);
    String signedJwt = JWT.create()
        .withKeyId(privateKeyId)
        .withIssuer("123456-compute@developer.gserviceaccount.com")
        .withSubject("123456-compute@developer.gserviceaccount.com")
        .withAudience("https://firestore.googleapis.com/")
        .withIssuedAt(new Date(now))
        .withExpiresAt(new Date(now + 3600 * 1000L))
        .sign(algorithm);
} catch ...

Python

Usa PyJWT:

iat = time.time()
exp = iat + 3600
payload = {'iss': '123456-compute@developer.gserviceaccount.com',
           'sub': '123456-compute@developer.gserviceaccount.com',
           'aud': 'https://firestore.googleapis.com/',
           'iat': iat,
           'exp': exp}
additional_headers = {'kid': PRIVATE_KEY_ID_FROM_JSON}
signed_jwt = jwt.encode(payload, PRIVATE_KEY_FROM_JSON, headers=additional_headers,
                       algorithm='RS256')
  1. Llama a la API con el JWT firmado como el token del portador:
    GET /v1/projects/abc/databases/123/indexes HTTP/1.1
    Authorization: Bearer SIGNED_JWT
    Host: firestore.googleapis.com

Implementa la Protección integral de la cuenta

Un paso adicional que debes seguir para proteger las cuentas de tus usuarios es implementar la Protección integral de la cuenta con el servicio de Protección integral de la cuenta de Google. Este servicio te permite suscribirte a notificaciones de eventos de seguridad que proporcionan información a tu aplicación sobre cambios importantes en la cuenta de usuario. Luego, puedes usar la información para tomar medidas según cómo decidas responder a los eventos.

Estos son algunos ejemplos de los tipos de eventos que el Servicio de protección integral de la cuenta de Google envía a tu app:

  • https://schemas.openid.net/secevent/risc/event-type/sessions-revoked
  • https://schemas.openid.net/secevent/oauth/event-type/token-revoked
  • https://schemas.openid.net/secevent/risc/event-type/account-disabled

Consulta la página Protege las cuentas de usuario con la Protección integral de la cuenta para obtener más información sobre cómo implementar la Protección integral de la cuenta y consultar la lista completa de eventos disponibles.