Usa OAuth 2.0 para aplicaciones de servidor a servidor

El sistema Google OAuth 2.0 admite interacciones servidor a servidor, como las que se producen entre un y un servicio de Google. Para este caso, necesitas una cuenta de servicio, que es una cuenta que pertenece a tu aplicación y no a un usuario final individual. Tu aplicación llama a las APIs de Google en nombre de la cuenta de servicio, así que los usuarios no involucradas. Esta situación suele llamarse “OAuth de dos segmentos”, o “2LO”. (El término relacionado “OAuth de tres segmentos” se refiere a situaciones en las que tu aplicación llama a las APIs de Google en nombre de los usuarios finales y para los que a veces se requiere su consentimiento).

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 de un usuario. Por ejemplo, una aplicación que usa Google Cloud para la persistencia de datos usaría una cuenta de servicio para autenticar sus llamadas API de Google Cloud Datastore

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

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

Descripción general

Para admitir interacciones servidor a servidor, primero crea una cuenta de servicio para tu proyecto en el objeto API Console. Si quieres acceder a los datos de usuarios de tu cuenta de Google Workspace y, luego, delega a la cuenta de servicio el acceso para todo el dominio.

Luego, tu aplicación se prepara para realizar llamadas autorizadas a la API usando los recursos 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 que tiene al menos un par de claves pública/privada. Si la delegación de todo el dominio está habilitada, también forma parte de un ID de cliente. de las credenciales de la cuenta de servicio.

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

Si tu aplicación se ejecuta en Google Compute Engine, también se configura una cuenta de servicio automáticamente cuando crees tu proyecto, pero debes especificar los permisos a los que aplicación necesita acceso cuando creas una instancia de Google Compute Engine. Para ver 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 Google API Console. Generar una cuenta de servicio o para ver las credenciales públicas que ya generaste, sigue estos pasos:

Primero, crea una cuenta de servicio:

  1. Abra el Service accounts page.
  2. If prompted, select a project, or create a new one.
  3. Haz clic en Crear cuenta de servicio .
  4. En Detalles de la cuenta de servicio , escriba un nombre, ID y descripción para la cuenta de servicio, luego haga clic en Crear y continuar .
  5. Opcional: en Otorgar a esta cuenta de servicio acceso al proyecto , seleccione las funciones de IAM para otorgar a la cuenta de servicio.
  6. Haga clic en Continuar .
  7. Opcional: en Otorgar acceso a los usuarios a esta cuenta de servicio , agregue los usuarios o grupos que pueden usar y administrar la cuenta de servicio.
  8. Haga clic en Listo .

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

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

Su nuevo par de claves pública/privada se genera y descarga en su máquina; sirve como la única copia de la clave privada. Usted es responsable de almacenarlo de forma segura. Si pierde este par de claves, deberá generar uno nuevo.

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

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

Delega autoridad de todo el dominio a la cuenta de servicio

Con una cuenta de Google Workspace, un administrador de Workspace de la organización puede autorizar un para acceder 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 del Calendario de Google para agregar eventos a los calendarios de todos los usuarios un dominio de Google Workspace usaría una cuenta de servicio para acceder a la API del Calendario de Google en en nombre de los usuarios. Autorizar una cuenta de servicio para acceder a datos en nombre de usuarios en un dominio a veces se denomina "delegación de autoridad de todo el dominio" a una cuenta de servicio.

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

  1. De la página de tu dominio de Google Workspace Consola del administrador, ve al 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 Add new (Agregar nuevo).
  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 Service accounts page
  5. En el campo Permisos de OAuth (delimitados por comas), ingresa la lista de alcances a los que acceso a la aplicación. Por ejemplo, si tu aplicación necesita recursos de todo el dominio, acceso completo a la API de Google Drive y a la API del 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 en tu dominio de Workspace (para "suplantar identidad" usuarios). Cuando te prepares para realizar estas llamadas delegadas a la API, deberás especificar explícitamente que el usuario debe o suplantar la identidad de otras personas.

Preparación para realizar una llamada a la API delegada

Java

Luego de obtener la dirección de correo electrónico del cliente y la clave privada del API Console, usa el Biblioteca cliente de las APIs de Google para Java para crear un objeto GoogleCredential a partir de las credenciales de la cuenta de servicio y los permisos a los que necesita acceder tu aplicación. Por ejemplo:

import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.services.sqladmin.SQLAdminScopes;

// ...

GoogleCredential credential = GoogleCredential.fromStream(new FileInputStream("MyProject-1234.json"))
    .createScoped(Collections.singleton(SQLAdminScopes.SQLSERVICE_ADMIN));

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

Delega autoridad en todo el dominio

Si delegaste el acceso para todo el dominio a la cuenta de servicio y quieres usar la identidad una cuenta de usuario, especifica la dirección de correo electrónico de la cuenta de usuario con el Método createDelegated del objeto GoogleCredential Por ejemplo:

GoogleCredential credential = GoogleCredential.fromStream(new FileInputStream("MyProject-1234.json"))
    .createScoped(Collections.singleton(SQLAdminScopes.SQLSERVICE_ADMIN))
    .createDelegated("workspace-user@example.com");

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

Python

Luego de obtener la dirección de correo electrónico del cliente y la clave privada del API Console, usa el 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 el 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/service.json'

credentials = service_account.Credentials.from_service_account_file(
        SERVICE_ACCOUNT_FILE, scopes=SCOPES)

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

  2. Delega autoridad en todo el dominio

    Si delegaste el acceso para todo el dominio a la cuenta de servicio y quieres usar la identidad de una cuenta de usuario, usar el método with_subject de una cuenta ServiceAccountCredentials. Por ejemplo:

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

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

HTTP o REST

Luego de obtener el ID de cliente y la clave privada del API Console, tu aplicación debe completar la 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 del servidor de autorización de Google OAuth 2.0.
  3. Maneja la respuesta JSON que muestra 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 una dirección token, es posible que tu solicitud de JWT y token no tengan el formato correcto, o bien que la cuenta de servicio no tienes permiso para acceder a los permisos solicitados).

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

Tu aplicación de servidor usa un JWT para solicitar un token al servidor El servidor de autorización usa el token para llamar a un extremo de la API de Google. No y el usuario final está involucrado.

El resto de esta sección describe los detalles para crear un JWT, firmarlo la formación de la solicitud de token de acceso y el manejo de la respuesta.

Crea un JWT

Un JWT se compone de tres partes: un encabezado, un conjunto de reclamaciones y un firma. El encabezado y el conjunto de reclamaciones son objetos JSON. Estos objetos JSON se serializan Bytes UTF-8, codificados con la codificación Base64url. Esta codificación proporciona resiliencia frente a cambios de codificación debido a operaciones de codificación repetidas. El encabezado, el conjunto de reclamos y 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 de la firma es la siguiente:

{Base64url encoded header}.{Base64url encoded claim set}
Formación del encabezado JWT

El encabezado consta de tres campos que indican el algoritmo de firma, el formato la aserción y el [ID de clave de la cuenta de servicio key](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 solo tiene un valor. A medida que se introduzcan algoritmos y formatos adicionales, este encabezado cambiará según corresponda. El ID de clave es opcional y, si se especifica un ID de clave incorrecto, GCP intentará todas las claves asociadas con la cuenta de servicio para verificar el token y rechazarlo si no se encontró ninguna clave válida. Google se reserva el derecho de rechazar tokens con IDs de clave incorrectos en el futuro.

Las cuentas de servicio dependen del algoritmo RSA SHA-256 y el formato del 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=
Formación del conjunto de reclamaciones de JWT

El conjunto de reclamaciones de JWT contiene información sobre el JWT, incluidos los permisos solicitados (alcances), el destino del token, la entidad emisora, la hora en que se emitió el 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 de JWT es un objeto JSON y se usa para calcular la firma.

Reclamos obligatorios

A continuación, se muestran las reclamaciones requeridas en el conjunto de reclamaciones de JWT. Pueden aparecer en cualquier orden en el conjunto de datos.

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

A continuación, se muestra la 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
}
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 en una organización. Permiso para realizar este tipo de suplantación de identidad debe otorgarse antes de que una aplicación pueda suplantar a un usuario y, por lo general, es manejada por 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, incluir la dirección de correo electrónico del usuario en la reclamación de JWT establecida como el valor del sub.

Nombre Descripción
sub La dirección de correo electrónico del usuario para el que se solicita la aplicación el acceso a los datos.

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

Se muestra un ejemplo de un conjunto de reclamaciones de JWT que incluye el campo sub a continuación:

{
  "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 de JWT debe serializarse en formato seguro para UTF-8 y Base64url. o codificado. A continuación, se muestra 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
}
Cómo calcular la firma

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 al procesar la firma. El Solo el algoritmo de firma compatible con el servidor de autorización de Google OAuth 2.0 es RSA con Algoritmo de hash SHA-256. Esto se expresa como RS256 en el archivo alg. en el encabezado 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 el objeto 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 se concatenan con un carácter de punto (.). El resultado es el JWT. Integra debe ser lo siguiente (se agregan saltos de línea para 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 que está listo para transmitirse:

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 es una URL. o codificado. La URL se muestra a continuación:

https://oauth2.googleapis.com/token

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

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

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

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

Controla la respuesta

Si la solicitud de JWT y token de acceso tienen el formato correcto y la cuenta de servicio 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 volver a usar durante el período de duración especificado por el Valor expires_in.

Llama a las APIs de Google

Java

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

  1. Crea un objeto de servicio para la API a la que deseas llamar con el comando GoogleCredential. Por ejemplo: 
    SQLAdmin sqladmin =
    new SQLAdmin.Builder(httpTransport, JSON_FACTORY, credential).build();
  2. Realizar solicitudes al servicio de API con el que proporciona el objeto de servicio. Por ejemplo, para enumerar las instancias de bases de datos de Cloud SQL en la proyecto: 
    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 los siguientes pasos:

  1. Compila un objeto de servicio para la API a la que deseas llamar. Creas un objeto de servicio llamando a la función build con el nombre y la versión de la API y las Credentials autorizado. Por ejemplo, para llamar a la versión 1beta3 de la API de Cloud SQL Administration: 
    import googleapiclient.discovery

sqladmin = googleapiclient.discovery.build('sqladmin', 'v1beta3', credentials=credentials)
  2. Realizar solicitudes al servicio de API con el que proporciona el objeto de servicio. Por ejemplo, para enumerar las instancias de bases de datos de Cloud SQL en la proyecto: 
    response = sqladmin.instances().list(project='exciting-example-123').execute()

HTTP o REST

Luego de que la aplicación obtenga un token de acceso, puedes usarlo para realizar llamadas a un servicio en nombre de una cuenta de servicio determinada o de usuario si se otorgaron los permisos de acceso que requiere la API. Para ello, incluye el token de acceso en una solicitud a la API mediante una consulta access_token o un valor de encabezado HTTP Bearer Authorization. Cuando sea posible, se prefiere el encabezado HTTP, ya que las cadenas de consulta tienden a ser visibles en los registros del servidor. En la mayoría puedes usar una biblioteca cliente para configurar las llamadas a las APIs de Google (por ejemplo, cuando llamar a la API de Drive Files).

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

Ejemplos de solicitudes GET de HTTP

Un llamado a la drive.files extremo (la API de Drive Files) con el HTTP Authorization: Bearer el encabezado 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

Esta es una llamada a la misma API para el usuario autenticado con access_token. Parámetro de cadena de consulta:

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. Este es un ejemplo que usa la opción de encabezado HTTP (preferida):

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

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 emitidos por el servidor de autorización de Google OAuth 2.0 caducan luego de la duración que proporciona el valor expires_in Cuando un token de acceso vence, el 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 de delegación de todo el dominio de la Consola del administrador del usuario en la Reclamo de sub (campo).

Si bien la autorización suele tardar unos minutos, es posible que demore hasta 24 horas en completarse se propagarán a todos los usuarios en 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 de cliente (numéricos) en la Consola del administrador. En el la página de delegación de todo el dominio de la Consola del administrador, quita el cliente y vuelve a agregarlo. con el ID numérico.
access_denied (cualquier valor) Si usas la delegación de todo el dominio, uno o más 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 de delegación de todo el dominio de la Consola del administrador del usuario en la sub (campo) y que incluya todos los alcances que solicitas en la reclamación scope de tu JWT.

Si bien la autorización suele tardar unos minutos, es posible que demore hasta 24 horas en completarse se propagarán a todos los usuarios en tu Cuenta de Google.
admin_policy_enforced (cualquier valor) La Cuenta de Google no puede autorizar uno o más permisos solicitados debido a la políticas de su administrador de Google Workspace.

Consulta el artículo de ayuda para administradores de Google Workspace Controla qué herramientas de terceros las apps internas acceden a los datos de Google Workspace para obtener más información sobre cómo una el administrador puede restringir el acceso a todos los permisos o a los permisos sensibles y restringidos hasta se otorga explícitamente a tu ID de cliente de OAuth.
invalid_client (cualquier valor)

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

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

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

Comprueba que la cuenta de servicio y el cliente de OAuth estén correctamente esté configurada correctamente y de que estés usando la dirección de correo electrónico correcta.

Comprueba que el token JWT sea correcto y se haya emitido para el ID de cliente en para cada solicitud.
invalid_grant Not a valid email. El usuario no existe. Comprueba que la dirección de correo electrónico que figura 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, significa que la hora del sistema local no es correcta. También puede ocurrir si El valor de exp está a más de 65 minutos en el futuro a partir del valor de iat, o que el valor de exp sea menor que el de iat.

Asegúrate de que el reloj del sistema donde se genera el JWT sea correcto. Si necesario, sincroniza tu tiempo 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 identificados por el correo electrónico del cliente o si la clave que se usó fue eliminada, inhabilitada o ha caducado.

Por otro lado, la aserción de JWT podría estar codificada de forma incorrecta. Debe ser Codificación en base64, sin saltos de línea ni signos igual de relleno.

Decodifica el conjunto de reclamaciones de JWT y verifica que esté asociada la clave que firmó la aserción 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 alcances (lista vacía de alcances), o bien uno de los permisos solicitados no existen (es decir, no es válido).

Asegúrate de que se propague la reclamación scope (campo) del JWT, y luego compara los alcances que contiene con los alcances documentados para las APIs que quieres usar, para asegúrate de que no haya errores o errores tipográficos.

Ten en cuenta que la lista de alcances de la reclamación scope debe separarse por espacios, no comas.
disabled_client The OAuth client was disabled. La clave que se usa para firmar la aserción de JWT está inhabilitada.

Ve a Google API Consoley, en IAM y Administrador > Cuentas de servicio, habilita la cuenta de servicio que contiene el “ID de clave”. usado 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 Google Cuentas en una ubicación Organización de Google Cloud.

Usa una cuenta de servicio de la organización para la autenticación. Confirma el tipo de usuario actual de tu aplicación de OAuth.

Anexo: Autorización de cuenta de servicio sin OAuth

Con algunas APIs de Google, puedes realizar llamadas autorizadas a la API usando un JWT firmado directamente como del portador, en lugar de un token de acceso de OAuth 2.0. Cuando esto sea posible, puedes evitar tener para 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 del servicio publicada en el Repositorio de GitHub de las APIs de Google, puedes realizar llamadas autorizadas a la API con un JWT en vez de un token de acceso. Para ello, sigue estos pasos:

  1. Crea una cuenta de servicio como se describió anteriormente. Asegúrate de y conservará el archivo JSON que obtiene cuando crea la cuenta.
  2. Usar cualquier biblioteca JWT estándar, como la que se encuentra en jwt.io, crea un JWT con un encabezado. y una carga útil, como en el 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
}
    • En el campo kid del encabezado, especifica la clave privada de tu cuenta de servicio ID. Puedes encontrar este valor en el campo private_key_id de tu cuenta de servicio Archivo JSON.
    • Para los campos iss y sub, especifica el correo electrónico de tu cuenta de servicio web. Puedes encontrar este valor en el campo client_email de tu servicio en el archivo JSON de la cuenta.
    • En el campo aud, especifica el extremo de la API. Por ejemplo: https://SERVICE.googleapis.com/
    • En el campo iat, especifica la hora de Unix actual y, para exp, especifica la hora exactamente 3,600 segundos después, cuando el JWT y vencer.

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

Por ejemplo:

Java

Usando google-api-java-client y java-jwt:

GoogleCredential credential =
        GoogleCredential.fromStream(new FileInputStream("MyProject-1234.json"));
PrivateKey privateKey = credential.getServiceAccountPrivateKey();
String privateKeyId = credential.getServiceAccountPrivateKeyId();

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 token del portador: 
    GET /v1/projects/abc/databases/123/indexes HTTP/1.1
Authorization: Bearer SIGNED_JWT
Host: firestore.googleapis.com

Cómo implementar la Protección integral de la cuenta

Un paso adicional que debes seguir para proteger las contraseñas de cuentas está implementando Protección con el Servicio de protección integral de la cuenta de Google Este servicio te permite suscribirse a las notificaciones de eventos de seguridad, que proporcionan información a su aplicación sobre cambios importantes en la cuenta de usuario. Luego, puedes usar la información para tomar medidas según cómo decides 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 Cómo proteger las cuentas de usuario con la página 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.