En este documento se explica cómo usan las aplicaciones instaladas en dispositivos como teléfonos, tablets y ordenadores los endpoints de OAuth 2.0 de Google para autorizar el acceso a la API YouTube Analytics o a la API YouTube Reporting.
OAuth 2.0 permite a los usuarios compartir datos específicos con una aplicación manteniendo sus nombres de usuario, contraseñas y otra información privada. Por ejemplo, una aplicación puede usar OAuth 2.0 para obtener permiso para recuperar los datos de Estadísticas de YouTube de un canal.
Las aplicaciones instaladas se distribuyen a dispositivos concretos y se da por hecho que no pueden mantener secretos. Pueden acceder a las APIs de Google mientras el usuario está en la aplicación o cuando la aplicación se ejecuta en segundo plano.
Este flujo de autorización es similar al que se usa en las aplicaciones de servidor web. La principal diferencia es que las aplicaciones instaladas deben abrir el navegador del sistema y proporcionar un URI de redirección local para gestionar las respuestas del servidor de autorización de Google.
Bibliotecas y ejemplos
En el caso de las aplicaciones iOS, recomendamos usar la versión más reciente del SDK de Iniciar sesión con Google para iOS. El SDK gestiona la autorización de los usuarios y es más sencillo de implementar que el protocolo de nivel inferior que se describe en esta guía.
En el caso de las aplicaciones que se ejecutan en dispositivos que no admiten un navegador del sistema o que tienen funciones de entrada limitadas, como televisiones, consolas de videojuegos, cámaras o impresoras, consulta OAuth 2.0 para televisiones y dispositivos o Inicio de sesión en televisiones y dispositivos con funciones de entrada limitadas.
Requisitos previos
Habilitar APIs en tu proyecto
Cualquier aplicación que llame a las APIs de Google debe habilitarlas en la consola de APIs.
Para habilitar una API en tu proyecto, sigue estos pasos:
- Abre la biblioteca de APIs en la consola de APIs de Google.
- Si se te indica, selecciona un proyecto o crea uno.
- Usa la página Biblioteca para buscar y habilitar las APIs de Estadísticas de YouTube y de YouTube Reporting. Muchas aplicaciones que obtienen datos de Estadísticas de YouTube también interactúan con la API YouTube Data. Busca otras APIs que vaya a usar tu aplicación y habilítalas también.
Crear credenciales de autorización
Cualquier aplicación que use OAuth 2.0 para acceder a las APIs de Google debe tener credenciales de autorización que identifiquen la aplicación en el servidor OAuth 2.0 de Google. En los siguientes pasos se explica cómo crear credenciales para tu proyecto. Tus aplicaciones podrán usar las credenciales para acceder a las APIs que hayas habilitado en ese proyecto.
- Ve a la página Clientes.
- Haz clic en Crear cliente.
- En las siguientes secciones se describen los tipos de clientes que admite el servidor de autorización de Google. Elige el tipo de cliente recomendado para tu aplicación, asigna un nombre a tu cliente de OAuth y define los demás campos del formulario según corresponda.
iOS
- Selecciona el tipo de aplicación iOS.
- Introduce un nombre para el cliente de OAuth. Este nombre se muestra en la página Clientes de tu proyecto para identificar al cliente.
- Introduce el identificador de paquete de tu aplicación. El ID de paquete es el valor de la clave CFBundleIdentifier del archivo de recursos de la lista de propiedades de información de tu aplicación (info.plist). El valor se muestra con mayor frecuencia en el panel General o en el panel Firma y funciones del editor de proyectos de Xcode. El ID de paquete también se muestra en la sección Información general de la página Información de la aplicación del sitio App Store Connect de Apple.
Confirma que estás usando el ID de bundle correcto de tu aplicación, ya que no podrás cambiarlo si usas la función Comprobación de Aplicaciones.
- (Opcional)
Introduzca el ID de App Store de su aplicación si esta se ha publicado en el App Store de Apple. El ID de tienda es una cadena numérica que se incluye en todas las URLs del App Store de Apple.
- Abre la aplicación App Store de Apple en tu dispositivo iOS o iPadOS.
- Busca tu aplicación.
- Selecciona el botón Compartir (cuadrado con una flecha hacia arriba).
- Selecciona Copiar enlace.
- Pega el enlace en un editor de texto. El ID de App Store es la parte final de la URL.
Ejemplo:
https://apps.apple.com/app/google/id284815942
- (Opcional)
Introduce tu ID de equipo. Consulta la sección Localizar el ID de tu equipo de la documentación de la cuenta de desarrollador de Apple para obtener más información.
Nota: El campo ID de equipo es obligatorio si vas a habilitar App Check en tu cliente. - (Opcional)
Habilita Comprobación de aplicaciones en tu aplicación iOS. Cuando lo hagas, se usará el servicio App Attest de Apple para verificar que las solicitudes de OAuth 2.0 que proceden de tu cliente de OAuth son auténticas y provienen de tu aplicación. Esto ayuda a reducir el riesgo de suplantación de identidad de la aplicación. Consulta más información sobre cómo habilitar Comprobación de aplicaciones en tu aplicación iOS.
- Haz clic en Crear.
UWP
- Selecciona el tipo de aplicación Universal Windows Platform.
- Introduce un nombre para el cliente de OAuth. Este nombre se muestra en el proyecto para identificar al cliente.
- Introduzca el ID de 12 caracteres de Microsoft Store de su aplicación. Puede encontrar este valor en Microsoft Partner Center, en la página Identidad de la aplicación de la sección Gestión de aplicaciones.
- Haz clic en Crear.
En el caso de las aplicaciones UWP, el URI de redirección se forma mediante el identificador de seguridad (SID) único de la aplicación. Puedes encontrar el Package SID de tu aplicación en el archivo Package.appxmanifest de tu proyecto de Visual Studio.
Cuando crees tu ID de cliente en la consola de Google Cloud, debes especificar el URI de redirección en el siguiente formato, usando el valor en minúsculas del SID de tu paquete:
ms-app://YOUR_APP_PACKAGE_SID
En el caso de las aplicaciones UWP, el esquema de URI personalizado no puede tener más de 39 caracteres, tal como se especifica en la documentación de Microsoft.
Identificar los permisos de acceso
Los permisos permiten que tu aplicación solo solicite acceso a los recursos que necesita, al tiempo que permiten que los usuarios controlen la cantidad de acceso que conceden a tu aplicación. Por lo tanto, puede haber una relación inversa entre el número de ámbitos solicitados y la probabilidad de obtener el consentimiento del usuario.
Antes de empezar a implementar la autorización de OAuth 2.0, te recomendamos que identifiques los permisos a los que necesitará acceder tu aplicación.
La API de Estadísticas de YouTube usa los siguientes permisos:
| Alcance | Descripción |
|---|---|
https://www. |
Administrar tu cuenta de YouTube |
https://www. |
Permite ver tu cuenta de YouTube. |
https://www. |
Ver y administrar sus elementos y el contenido asociado en YouTube |
https://www. |
Permite ver los informes monetarios y no monetarios de YouTube Analytics relacionados con tu contenido de YouTube |
https://www. |
Ver informes de YouTube Analytics sobre su contenido de YouTube |
La API YouTube Reporting usa los siguientes permisos:
| Alcance | Descripción |
|---|---|
https://www. |
Permite ver los informes monetarios y no monetarios de YouTube Analytics relacionados con tu contenido de YouTube |
https://www. |
Ver informes de YouTube Analytics sobre su contenido de YouTube |
El documento Permisos de API de OAuth 2.0 contiene una lista completa de los permisos que puedes usar para acceder a las APIs de Google.
Obtener tokens de acceso OAuth 2.0
En los siguientes pasos se muestra cómo interactúa tu aplicación con el servidor OAuth 2.0 de Google para obtener el consentimiento de un usuario para realizar una solicitud a la API en su nombre. Tu aplicación debe tener ese consentimiento antes de poder ejecutar una solicitud a la API de Google que requiera la autorización del usuario.
Paso 1: Genera un verificador y un reto de código
Google admite el protocolo Proof Key for Code Exchange (PKCE) para que el flujo de la aplicación instalada sea más seguro. Se crea un verificador de código único para cada solicitud de autorización y su valor transformado, llamado "code_challenge", se envía al servidor de autorización para obtener el código de autorización.
Crea el verificador de código
Un code_verifier es una cadena aleatoria criptográfica de alta entropía que usa los caracteres no reservados [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~", con una longitud mínima de 43 caracteres y una longitud máxima de 128 caracteres.
El verificador de código debe tener suficiente entropía para que sea poco práctico adivinar el valor.
Crear el reto de código
Se admiten dos métodos para crear el reto de código.
| Métodos de generación de verificaciones de código | |
|---|---|
| S256 (recomendado) | El reto de código es el hash SHA256 codificado en Base64URL (sin relleno) del verificador de código.
|
| sin formato | El reto de código es el mismo valor que el verificador de código generado anteriormente.
|
Paso 2: Envía una solicitud al servidor OAuth 2.0 de Google
Para obtener la autorización del usuario, envía una solicitud al servidor de autorización de Google a https://accounts.google.com/o/oauth2/v2/auth. Este endpoint gestiona la búsqueda de sesiones activas, autentica al usuario y obtiene el consentimiento del usuario. Solo se puede acceder al endpoint a través de SSL y rechaza las conexiones HTTP (sin SSL).
El servidor de autorización admite los siguientes parámetros de cadena de consulta para aplicaciones instaladas:
| Parámetros | |||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
client_id |
Obligatorio
El ID de cliente de tu aplicación. Puedes encontrar este valor en la página Clientes de Cloud Console. |
||||||||||||||||||
redirect_uri |
Obligatorio
Determina cómo envía el servidor de autorización de Google una respuesta a tu aplicación. Hay varias opciones de redirección disponibles para las aplicaciones instaladas. Además, habrás configurado tus credenciales de autorización con un método de redirección concreto. El valor debe coincidir exactamente con una de las URIs de redirección autorizadas del cliente de OAuth 2.0, que has configurado en la página Clientes de la consola de Cloud de tu cliente. Si este valor no coincide con una URI autorizada, recibirás un error En la tabla se muestra el valor del parámetro
|
||||||||||||||||||
response_type |
Obligatorio
Determina si el endpoint de OAuth 2.0 de Google devuelve un código de autorización. Asigna el valor |
||||||||||||||||||
scope |
Obligatorio
Una lista de permisos delimitada por espacios que identifica los recursos a los que podría acceder tu aplicación en nombre del usuario. Estos valores informan a la pantalla de consentimiento que Google muestra al usuario. Los permisos permiten que tu aplicación solo solicite acceso a los recursos que necesita, al tiempo que permiten que los usuarios controlen la cantidad de acceso que conceden a tu aplicación. Por lo tanto, existe una relación inversa entre el número de ámbitos solicitados y la probabilidad de obtener el consentimiento del usuario. La API de Estadísticas de YouTube usa los siguientes permisos:
La API YouTube Reporting usa los siguientes permisos:
En el documento Permisos de la API OAuth 2.0 se incluye una lista completa de los permisos que puedes usar para acceder a las APIs de Google. |
||||||||||||||||||
code_challenge |
Recomendado
Especifica un |
||||||||||||||||||
code_challenge_method |
Recomendado
Especifica el método que se ha usado para codificar un |
||||||||||||||||||
state |
Recomendado
Especifica cualquier valor de cadena que utilice tu aplicación para mantener el estado entre tu solicitud de autorización y la respuesta del servidor de autorización.
El servidor devuelve el valor exacto que envías como par Puede usar este parámetro para varios fines, como dirigir al usuario al recurso correcto de su aplicación, enviar nonces y mitigar la falsificación de solicitudes entre sitios. Como se puede adivinar su |
||||||||||||||||||
login_hint |
Optional
Si tu aplicación sabe qué usuario está intentando autenticarse, puede usar este parámetro para proporcionar una sugerencia al servidor de autenticación de Google. El servidor usa la sugerencia para simplificar el flujo de inicio de sesión. Para ello, rellena automáticamente el campo de correo en el formulario de inicio de sesión o selecciona la sesión de inicio de sesión múltiple adecuada. Asigna al parámetro el valor de una dirección de correo o un identificador |
||||||||||||||||||
URLs de autorización de ejemplo
En las pestañas de abajo se muestran URLs de autorización de ejemplo para las diferentes opciones de URI de redirección.
Cada URL solicita acceso a un ámbito que permite recuperar los informes de estadísticas de YouTube del usuario.Las URLs son idénticas, excepto por el valor del parámetro redirect_uri. Las URLs también contienen los parámetros obligatorios response_type y client_id, así como el parámetro opcional state. Cada URL contiene saltos de línea y espacios para facilitar la lectura.
Esquema de URI personalizado
https://accounts.google.com/o/oauth2/v2/auth? scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyt-analytics.readonly& response_type=code& state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken& redirect_uri=com.example.app%3A/oauth2redirect& client_id=client_id
Dirección IP de bucle invertido
https://accounts.google.com/o/oauth2/v2/auth? scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyt-analytics.readonly& response_type=code& state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken& redirect_uri=http%3A//127.0.0.1%3A9004& client_id=client_id
Paso 3: Google pide el consentimiento del usuario
En este paso, el usuario decide si concede a tu aplicación el acceso solicitado. En esta fase, Google muestra una ventana de consentimiento que contiene el nombre de la aplicación y los servicios de la API de Google para los que se solicita permiso de acceso con las credenciales de autorización del usuario, así como un resumen de los permisos de acceso que se van a conceder. A continuación, el usuario puede aceptar el acceso a uno o varios de los permisos solicitados por tu aplicación o rechazar la solicitud.
Tu aplicación no tiene que hacer nada en esta fase, ya que espera la respuesta del servidor OAuth 2.0 de Google que indica si se ha concedido algún acceso. Esa respuesta se explica en el siguiente paso.
Errores
Las solicitudes al endpoint de autorización de OAuth 2.0 de Google pueden mostrar mensajes de error visibles para los usuarios en lugar de los flujos de autenticación y autorización esperados. Los códigos de error habituales y las soluciones sugeridas son los siguientes:
admin_policy_enforced
La cuenta de Google no puede autorizar uno o varios de los ámbitos solicitados debido a las políticas de su administrador de Google Workspace. Consulta el artículo de ayuda para administradores de Google Workspace Controlar qué aplicaciones internas y de terceros acceden a los datos de Google Workspace para obtener más información sobre cómo puede restringir un administrador el acceso a todos los ámbitos o a los ámbitos sensibles y restringidos hasta que se conceda explícitamente el acceso a tu ID de cliente de OAuth.
disallowed_useragent
El endpoint de autorización se muestra en un agente de usuario insertado que no permiten las políticas de OAuth 2.0 de Google.
Los desarrolladores de iOS y macOS pueden encontrarse con este error al abrir solicitudes de autorización en WKWebView.
En su lugar, los desarrolladores deben usar bibliotecas de iOS, como inicio de sesión de Google para iOS o AppAuth para iOS de OpenID Foundation.
Los desarrolladores web pueden encontrarse con este error cuando una aplicación iOS o macOS abre un enlace web general en un user-agent insertado y un usuario se desplaza al endpoint de autorización de OAuth 2.0 de Google desde su sitio. Los desarrolladores deben permitir que los enlaces generales se abran en el gestor de enlaces predeterminado del sistema operativo, que incluye tanto los gestores de enlaces universales como la aplicación del navegador predeterminado. La biblioteca SFSafariViewController también es una opción compatible.
org_internal
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. Para obtener más información sobre esta opción de configuración, consulta la sección Tipo de usuario del artículo de ayuda sobre cómo configurar la pantalla de consentimiento de OAuth.
deleted_client
Se ha eliminado el cliente de OAuth que se está usando para hacer la solicitud. La eliminación puede realizarse de forma manual o automática en el caso de los clientes no utilizados . Los clientes eliminados se pueden restaurar en un plazo de 30 días después de la eliminación. Más información
invalid_grant
Si usas un verificador de código y un
reto, el parámetro code_callenge no es válido o falta. Asegúrate de que el parámetro code_challenge esté configurado correctamente.
Al actualizar un token de acceso, puede que el token haya caducado o se haya invalidado. Vuelve a autenticar al usuario y pídele el consentimiento del usuario para obtener nuevos tokens. Si sigue viendo este error, asegúrese de que su aplicación se ha configurado correctamente y de que está usando los tokens y parámetros correctos en su solicitud. De lo contrario, es posible que la cuenta de usuario se haya eliminado o inhabilitado.
redirect_uri_mismatch
El redirect_uri enviado en la solicitud de autorización no coincide con una URI de redireccionamiento autorizada para el ID de cliente de OAuth. Revisa las URIs de redirección autorizadas en la
consola de Google Cloud
página Clientes.
El redirect_uri proporcionado puede no ser válido para el tipo de cliente.
El parámetro redirect_uri puede hacer referencia al flujo fuera de banda (OOB) de OAuth, que se ha retirado y ya no se admite. Consulta la guía de migración para actualizar tu integración.
invalid_request
Se ha producido un error en la solicitud que has enviado. Esto puede deberse a varios motivos:
- La solicitud no tiene el formato correcto
- Faltaban parámetros obligatorios en la solicitud
- La solicitud utiliza un método de autorización que Google no admite. Verificar que tu integración de OAuth utiliza un método de integración recomendado
- Se ha usado un esquema personalizado no admitido para el URI de redirección. Si ves el mensaje de error Custom URI scheme is not supported on Android or Chrome apps, learn more about custom URI scheme alternatives.
Paso 4: Gestionar la respuesta del servidor OAuth 2.0
La forma en que tu aplicación recibe la respuesta de autorización depende del esquema del URI de redirección que utilice. Independientemente del esquema, la respuesta contendrá un código de autorización (code) o un error (error). Por ejemplo, error=access_denied indica que el usuario ha rechazado la solicitud.
Si el usuario concede acceso a tu aplicación, puedes intercambiar el código de autorización por un token de acceso y un token de actualización, tal como se describe en el paso siguiente.
Paso 5: Intercambia el código de autorización por tokens de actualización y de acceso
Para intercambiar un código de autorización por un token de acceso, llama al endpoint https://oauth2.googleapis.com/token y define los siguientes parámetros:
| Campos | |
|---|---|
client_id |
El ID de cliente obtenido de la página Clientes de Cloud Console. |
client_secret |
Optional
El secreto de cliente obtenido en la página Clientes de la consola de Cloud. |
code |
El código de autorización devuelto por la solicitud inicial. |
code_verifier |
El verificador de código que has creado en el paso 1. |
grant_type |
Tal como se define en la especificación de OAuth 2.0, el valor de este campo debe ser authorization_code. |
redirect_uri |
Uno de los URIs de redirección que aparecen en la
página Clientes de la
consola de Cloud
para el client_id en cuestión. |
Aunque el uso de DPoP es opcional, se recomienda para aumentar la seguridad. La seguridad de DPoP se basa en que la clave privada esté restringida a un solo dispositivo. Recomendamos almacenarla de forma que no se pueda copiar fuera del dispositivo, por ejemplo, mediante TPMs, enclaves seguros u otros almacenes de claves respaldados por hardware. Para usar DPoP, tu aplicación debe generar un JWT de prueba de DPoP nuevo y único para cada solicitud al endpoint de token y añadirlo como encabezado de solicitud HTTP.
| Header | Obligatorio | Descripción |
|---|---|---|
DPoP |
Opcional | Una prueba de DPoP es un JWT que demuestra la posesión de una clave privada. Se trata de un encabezado, no de un parámetro. Si se proporciona, los tokens devueltos se vinculan a esta clave. Se debe generar una prueba nueva y única para cada solicitud, que debe incluir las reclamaciones htm (método HTTP) y htu (URI HTTP) que coincidan con la solicitud. |
En el siguiente fragmento se muestra una solicitud de ejemplo:
POST /token HTTP/1.1 Host: oauth2.googleapis.com Content-Type: application/x-www-form-urlencoded DPoP: eyJ0eXAiOiJkcG9wK2p3dCIsImFsZyI6IkVTMjU2IiwiandrIjp7Imt0eSI6Ik\ VDIiwieCI6Imw4dEZyaHgtMzR0VjNoUklDUkRZOXpDa0RscEJoRjQyVVFVZldWQVdCR\ nMiLCJ5IjoiOVZFNGpmX09rX282NHpiVFRsY3VOSmFqSG10NnY5VERWclUwQ2R2R1JE\ QSIsImNydiI6IlAtMjU2In19.eyJqdGkiOiItQndDM0VTYzZhY2MybFRjIiwiaHRtIj\ oiUE9TVCIsImh0dSI6Imh0dHBzOi8vc2VydmVyLmV4YW1wbGUuY29tL3Rva2VuIiwia\ WF0IjoxNTYyMjYyNjE2fQ.2-GxA6T8lP4vfrg8v-FdWP0A0zdrj8igiMLvqRMUvwnQg\ 4PtFLbdLXiOSsX0x7NVY-FNyJK70nfbV37xRZT3Lg code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7& client_id=your_client_id& redirect_uri=http://127.0.0.1:9004& grant_type=authorization_code
Construir una prueba de DPoP
En los siguientes pasos se muestra cómo crear una prueba de DPoP con OpenSSL desde la línea de comandos:
- Genera un par de claves EC P-256:
openssl ecparam -name prime256v1 -genkey -noout -out dpop_private.pem openssl ec -in dpop_private.pem -pubout -out dpop_public.pem
- Crea el encabezado DPoP:
La cabecera debe incluir las reclamaciones
typ,algyjwk(clave pública). Los valoresxyyson las coordenadas codificadas en Base64Url de tu clave pública EC. Codifica con Base64Url este JSON:{ "typ":"dpop+jwt", "alg":"ES256", "jwk": { "kty":"EC", "x":"YOUR_PUBLIC_KEY_X", "y":"YOUR_PUBLIC_KEY_Y", "crv":"P-256" } } - Crea la carga útil de DPoP:
La carga útil debe incluir
jti(un identificador único de la solicitud),htm(método HTTP, por ejemplo,POST),htu(URI HTTP, por ejemplo,https://oauth2.googleapis.com/token) yiat(hora de emisión). Si has recibido un nonce del servidor en una cabeceraDPoP-Nonceen la respuesta a una solicitud anterior, debes incluir ese valor de nonce en una reclamaciónnonce. La reclamación nonce es opcional para los intercambios de códigos de autorización y solo se usa cuando se ha recibido previamente el encabezado DPoP-Nonce. Codifica con Base64Url este JSON:{ "jti":"JTI_VALUE", "htm":"POST", "htu":"https://oauth2.googleapis.com/token", "iat":YOUR_JWT_ISSUED_TIME, "nonce":"SERVER_PROVIDED_NONCE" }El valor de
jtidepende del tipo de intercambio:- En el caso de los intercambios de códigos de autorización, el
jtidebe ser el hash SHA256 codificado con Base64Url del código de autorización:"jti":"BASE64URL(SHA256(AUTHORIZATION_CODE))". - En el caso de los intercambios de tokens de actualización, el
jtidebe ser un identificador único por solicitud:"jti":"YOUR_UNIQUE_PER_REQUEST_IDENTIFIER".
- En el caso de los intercambios de códigos de autorización, el
- Firma la prueba:
Concatena el encabezado y la carga útil codificados con un punto (
.) y, a continuación, firma el resultado con tu clave privada mediante ES256. Ten en cuenta que JWS requiere que la firma esté en formatoR | Ssin procesar concatenado (64 bytes para P-256). Si usas OpenSSL directamente, debes convertir la firma predeterminada codificada en DER de ASN.1 a este formato sin formato.
Un intercambio correcto se indica mediante una respuesta 200 OK
que contiene los tokens. Si se usa una prueba de DPoP válida durante el intercambio, el token de actualización que devuelva Google estará vinculado a tu clave, pero los tokens de acceso no lo estarán. Los tokens de acceso conservarán el token_type de
Bearer en lugar de DPoP.
Además, Google devuelve un encabezado HTTP DPoP-Nonce en la respuesta.
Tu cliente debe almacenar en caché este nonce e incluirlo en la reclamación nonce de la prueba DPoP en solicitudes posteriores (por ejemplo, al intercambiar un token de actualización por un token de acceso nuevo o al llamar a APIs protegidas por DPoP). Si usas este nonce emitido con antelación, puedes evitar un error de ida y vuelta adicional (use_dpop_nonce) en tu próxima solicitud.
Las pruebas de DPoP deben incluirse en las solicitudes de intercambio de tokens realizadas con tokens de actualización vinculados a DPoP.
Se produce un intercambio fallido si falta el encabezado DPoP cuando se espera, si no es válido o si la prueba usa una clave diferente a la vinculada al token. En estos casos, el servidor devuelve un error 400 Bad Request.
Si la prueba de DPoP tiene reclamaciones htm o htu que no coinciden, un iat caducado, un jti reutilizado o una firma no válida, Google devuelve un código de error invalid_dpop_proof.
Si se requiere un nonce de DPoP (por ejemplo, durante un intercambio de tokens de actualización) y la prueba de DPoP no incluye una reclamación nonce o el valor del nonce no es aceptable para el servidor (por ejemplo, ha caducado, ya se ha usado o es incorrecto), Google devuelve un código de error use_dpop_nonce junto con un encabezado HTTP DPoP-Nonce que contiene un nuevo nonce que puedes usar en una solicitud posterior.
Otros errores pueden devolver invalid_grant.
Google responde a esta solicitud devolviendo un objeto JSON que contiene un token de acceso de corta duración y un token de actualización.
La respuesta contiene los siguientes campos:
| Campos | |
|---|---|
access_token |
El token que tu aplicación envía para autorizar una solicitud a la API de Google. |
expires_in |
Tiempo de vida restante del token de acceso en segundos. |
id_token |
Nota: Esta propiedad solo se devuelve si tu solicitud incluye un ámbito de identidad, como openid, profile o email. El valor es un token web JSON (JWT) que contiene información de identidad firmada digitalmente sobre el usuario. |
refresh_token |
Un token que puedes usar para obtener un nuevo token de acceso. Los tokens de actualización son válidos hasta que el usuario revoca el acceso o hasta que caducan. Si se ha usado DPoP, el token de actualización se vincula a la clave privada usada para firmar la prueba de DPoP. Ten en cuenta que los tokens de actualización siempre se devuelven en el caso de las aplicaciones instaladas. |
refresh_token_expires_in |
Tiempo de vida restante del token de actualización en segundos. Este valor solo se define cuando el usuario concede acceso basado en el tiempo. |
scope |
Los ámbitos de acceso concedidos por el access_token expresados como una lista de cadenas delimitadas por espacios que distinguen entre mayúsculas y minúsculas. |
token_type |
El tipo de token devuelto. Este valor siempre es Bearer, incluso cuando se usa DPoP. |
El siguiente fragmento muestra un ejemplo de encabezados y cuerpo de respuesta correctos cuando se usa DPoP:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
DPoP-Nonce: AN3XwJjZsjnb0ZuWkRlek8QU7wY-Zhf-5IP6tO0tORz0KgtDT1Bo8FX-w4nz3r5lnepI
{
"access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
"expires_in": 3920,
"token_type": "Bearer",
"scope": "https://www.googleapis.com/auth/yt-analytics.readonly https://www.googleapis.com/auth/calendar.readonly",
"refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}Paso 6: Comprueba a qué permisos han dado acceso los usuarios
Cuando solicites varios permisos (scopes), es posible que los usuarios no concedan a tu aplicación acceso a todos ellos. Tu aplicación debe verificar qué scopes se han concedido y gestionar correctamente las situaciones en las que se deniegan algunos permisos. Para ello, normalmente se inhabilitan las funciones que dependen de esos scopes denegados.
Sin embargo, hay excepciones. Las aplicaciones de Google Workspace Enterprise con delegación de autoridad en todo el dominio o las aplicaciones marcadas como de confianza no muestran la pantalla de consentimiento de permisos granulares. En el caso de estas aplicaciones, los usuarios no verán la pantalla de consentimiento de permisos granulares. En su lugar, tu aplicación recibirá todos los ámbitos solicitados o ninguno.
Para obtener información más detallada, consulta Cómo gestionar permisos granulares.
Para comprobar si el usuario ha concedido a tu aplicación acceso a un permiso concreto, examina el campo scope de la respuesta del token de acceso. Los permisos de acceso concedidos por el token de acceso, expresados como una lista de cadenas delimitadas por espacios que distinguen entre mayúsculas y minúsculas.
Por ejemplo, la siguiente respuesta de token de acceso de ejemplo indica que el usuario ha concedido a tu aplicación acceso de solo lectura a los permisos de actividad de Drive y eventos de Calendar:
{ "access_token": "1/fFAGRNJru1FTz70BzhT3Zg", "expires_in": 3920, "token_type": "Bearer", "scope": "https://www.googleapis.com/auth/yt-analytics.readonly https://www.googleapis.com/auth/calendar.readonly", "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI" }
Llamar a las APIs de Google
Una vez que tu aplicación obtiene un token de acceso, puedes usarlo para hacer llamadas a una API de Google en nombre de una cuenta de usuario determinada si se han concedido los ámbitos de acceso que requiere la API. Para ello, incluye el token de acceso en una solicitud a la API. Puedes hacerlo mediante un parámetro de consulta access_token o un valor de encabezado HTTP Authorization Bearer. Cuando sea posible, es preferible usar 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 de cliente para configurar tus llamadas a las APIs de Google (por ejemplo, cuando llamas a la API de Estadísticas de YouTube).
Ten en cuenta que la API de Estadísticas de YouTube no admite el flujo de cuentas de servicio. La API YouTube Reporting solo admite cuentas de servicio para los propietarios de contenido de YouTube que tengan y gestionen varios canales de YouTube, como las discográficas y los estudios de cine.
Puedes probar todas las APIs de Google y ver sus permisos en OAuth 2.0 Playground.
Ejemplos de HTTP GET
Una llamada al endpoint
reports.query (la API de Estadísticas de YouTube) con el encabezado HTTP Authorization: Bearer podría tener el siguiente aspecto. Ten en cuenta que debes especificar tu propio token de acceso:
GET /youtube/analytics/v1/reports?ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views HTTP/1.1 Host: www.googleapis.com Authorization: Bearer access_token
A continuación, se muestra una llamada a la misma API para el usuario autenticado mediante el parámetro de cadena de consulta access_token:
GET https://www.googleapis.com/youtube/analytics/v1/reports?access_token=access_token&ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views
curl ejemplos
Puedes probar estos comandos con la aplicación de línea de comandos curl. A continuación, se muestra un ejemplo que usa la opción de encabezado HTTP (preferida):
curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/analytics/v1/reports?ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views
También puedes usar la opción de parámetro de cadena de consulta:
curl https://www.googleapis.com/youtube/analytics/v1/reports?access_token=access_token&ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views
Actualizar un token de acceso
Los tokens de acceso caducan periódicamente y se convierten en credenciales no válidas para una solicitud a la API relacionada. Puedes actualizar un token de acceso sin pedir permiso al usuario (incluso cuando no esté presente) si has solicitado acceso sin conexión a los ámbitos asociados al token.
Para actualizar un token de acceso, tu aplicación envía una solicitud HTTPS POST
al servidor de autorización de Google (https://oauth2.googleapis.com/token) que
incluye los siguientes parámetros en el cuerpo de la solicitud:
| Nombre | Valor |
|---|---|
client_id |
El ID de cliente obtenido de la consola de APIs. |
client_secret |
Optional
El secreto de cliente obtenido de la consola de APIs.
(El |
grant_type |
Tal como se define en la especificación de OAuth 2.0, el valor de este campo debe ser refresh_token. |
refresh_token |
El token de actualización devuelto del intercambio del código de autorización. |
Aunque el uso de DPoP es opcional, se recomienda para aumentar la seguridad. Para usar DPoP con un token de actualización, tu aplicación debe generar un JWT de prueba de DPoP nuevo y único para cada solicitud al endpoint de token. Esta prueba debe firmarse con la misma clave privada que se usó durante el intercambio inicial del código de autorización. Tu aplicación añade la prueba como encabezado de solicitud HTTP.
| Header | Obligatorio | Descripción |
|---|---|---|
DPoP |
Opcional | Una prueba de DPoP es un JWT que demuestra la posesión de una clave privada. Se trata de un encabezado, no de un parámetro. Si se proporciona, los tokens devueltos se vinculan a esta clave. Se debe generar una prueba nueva y única para cada solicitud, que debe incluir las reclamaciones htm (método HTTP) y htu (URI HTTP) que coincidan con la solicitud. |
En el siguiente fragmento se muestra una solicitud de ejemplo:
POST /token HTTP/1.1 Host: oauth2.googleapis.com Content-Type: application/x-www-form-urlencoded DPoP: DPOP_PROOF_JWT client_id=your_client_id& refresh_token=refresh_token& grant_type=refresh_token
Para usar DPoP con un token de actualización, debes generar un JWT de prueba de DPoP nuevo y único para la solicitud. Consulta Crear una prueba de DPoP para obtener instrucciones paso a paso sobre cómo generar el par de claves y crear el JWT.
Un intercambio correcto se indica mediante una respuesta 200 OK
que contiene un nuevo token de acceso. Cuando se usa DPoP, el valor de token_type es Bearer. Una respuesta correcta confirma que se ha aceptado la prueba de DPoP del token de actualización. Google también puede devolver un nuevo encabezado HTTP DPoP-Nonce en la respuesta. Si se devuelve, tu cliente debe almacenar en caché este nonce e incluirlo en la reclamación nonce de la prueba de DPoP en las solicitudes posteriores.
Se produce un intercambio fallido si falta el encabezado DPoP, no es válido o usa una clave incorrecta. Para obtener información sobre códigos de error de DPoP específicos y sobre cómo gestionar nonces, consulta Intercambio fallido.
El siguiente fragmento muestra un ejemplo de encabezados y cuerpo de respuesta correctos cuando se usa DPoP:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
DPoP-Nonce: AN3XwJjZsjnb0ZuWkRlek8QU7wY-Zhf-5IP6tO0tORz0KgtDT1Bo8FX-w4nz3r5lnepI
{
"access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
"expires_in": 3920,
"scope": "https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly",
"token_type": "Bearer"
}Ten en cuenta que hay límites en el número de tokens de actualización que se emitirán: un límite por combinación de cliente y usuario, y otro por usuario en todos los clientes. Debes guardar los tokens de actualización en un almacenamiento a largo plazo y seguir usándolos mientras sean válidos. Si tu aplicación solicita demasiados tokens de actualización, puede que alcance estos límites, en cuyo caso los tokens de actualización antiguos dejarán de funcionar.
Revocación de tokens
En algunos casos, los usuarios pueden querer revocar el acceso que han concedido a una aplicación. Para ello, deben visitar Configuración de la cuenta. Consulta la sección Quitar acceso a sitios o aplicaciones del artículo de asistencia Sitios y aplicaciones de terceros con acceso a tu cuenta para obtener más información.
Una aplicación también puede revocar de forma programática el acceso que se le ha concedido. La revocación programática es importante en los casos en los que un usuario se da de baja, elimina una aplicación o los recursos de la API que requiere una aplicación han cambiado significativamente. En otras palabras, parte del proceso de eliminación puede incluir una solicitud a la API para asegurarse de que se eliminan los permisos que se habían concedido a la aplicación.
Para revocar un token de forma programática, tu aplicación envía una solicitud a
https://oauth2.googleapis.com/revoke e incluye el token como parámetro:
curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
https://oauth2.googleapis.com/revoke?token={token}El token puede ser un token de acceso o de actualización. Si el token es un token de acceso y tiene un token de actualización correspondiente, este también se revocará.
Si la revocación se procesa correctamente, el código de estado HTTP de la respuesta es 200. En caso de error, se devuelve el código de estado HTTP 400 junto con un código de error.
Métodos de redirección de aplicaciones
Esquema de URI personalizado
Los esquemas de URI personalizados son una forma de enlace profundo que usa un esquema definido de forma personalizada para abrir tu aplicación.
Alternativa al uso de esquemas de URI personalizados en aplicaciones Chrome
Usa la API Chrome Identity, que envía la respuesta de OAuth 2.0 directamente a tu aplicación, lo que elimina la necesidad de una URI de redirección.
Dirección IP de bucle de retorno (macOS, Linux y Windows para ordenadores)
Para recibir el código de autorización mediante esta URL, tu aplicación debe estar escuchando en el servidor web local. Esto es posible en muchas plataformas, pero no en todas. Sin embargo, si tu plataforma lo admite, este es el mecanismo recomendado para obtener el código de autorización.
Cuando tu aplicación reciba la respuesta de autorización, para ofrecer la mejor experiencia de usuario posible, debe responder mostrando una página HTML que indique al usuario que cierre el navegador y vuelva a tu aplicación.
| Uso recomendado | Aplicaciones de escritorio para macOS, Linux y Windows (pero no para Universal Windows Platform) |
| Valores de formulario | Selecciona Aplicación para ordenadores como tipo de aplicación. |
Copiar y pegar manualmente (obsoleto)
Protege tus aplicaciones
Verificar la propiedad de una aplicación para Chrome
Puedes verificar la propiedad de tu aplicación para reducir el riesgo de suplantación de identidad.
Para completar el proceso de verificación, debes usar tu cuenta de desarrollador de Chrome Web Store. Para completar la verificación correctamente, debes cumplir los siguientes requisitos:
- Debes tener un elemento registrado en el Panel de control para desarrolladores de Chrome Web Store con el mismo ID de artículo que el cliente de OAuth de la extensión de Chrome para el que estás completando la verificación.
- Debes ser editor del elemento de Chrome Web Store. Más información sobre la gestión de acceso en el Panel de control para desarrolladores de Chrome Web Store
En la sección Verificar propiedad de la aplicación del cliente de la extensión de Chrome, haz clic en el botón Verificar propiedad para completar el proceso de verificación.
Nota: Espera unos minutos antes de completar el proceso de verificación después de conceder acceso a tu cuenta.
Si la verificación se realiza correctamente, se mostrará una notificación para confirmar que el proceso se ha completado correctamente. De lo contrario, se mostrará un mensaje de error.
Para solucionar un problema de verificación, prueba lo siguiente:
- Asegúrate de que haya un elemento registrado en el Panel de control para desarrolladores de Chrome Web Store con el mismo ID de artículo que el cliente de OAuth de la extensión de Chrome cuya verificación estás completando.
- Asegúrate de que eres el editor de la aplicación. Es decir, debes ser el editor individual de la aplicación o un miembro del editor de grupo de la aplicación. Más información sobre la gestión de accesos en el Panel de control para desarrolladores de Chrome Web Store.
- Si acabas de actualizar tu lista de editores de grupo, comprueba que la lista de miembros de editores de grupo se haya sincronizado en el Panel de control para desarrolladores de Chrome Web Store. Más información sobre cómo sincronizar tu lista de miembros del canal.
App Check (solo iOS)
La función Comprobación de aplicaciones te ayuda a proteger tus aplicaciones iOS frente a usos no autorizados mediante el servicio App Attest de Apple para verificar que las solicitudes realizadas a los endpoints de Google OAuth 2.0 proceden de tus aplicaciones auténticas. De esta forma, se reduce el riesgo de que se suplante la identidad de la aplicación.
Habilitar Comprobación de aplicaciones en el cliente de iOS
Para habilitar correctamente App Check en tu cliente iOS, debes cumplir los siguientes requisitos:- Debe especificar un ID de equipo para su cliente de iOS.
- No debes usar un comodín en tu ID de bundle, ya que puede resolverse en más de una aplicación. Esto significa que el ID de bundle no debe incluir el símbolo de asterisco (*).
Después de habilitar Comprobación de aplicaciones, empezarás a ver métricas relacionadas con las solicitudes de OAuth de tu cliente en la vista de edición del cliente de OAuth. Las solicitudes de fuentes no verificadas no se bloquearán hasta que apliques App Check. La información de la página de monitorización de métricas puede ayudarte a determinar cuándo empezar a aplicar las medidas.
Es posible que veas errores relacionados con la función App Check al habilitarla en tu aplicación iOS. Para solucionar estos errores, prueba lo siguiente:
- Verifica que el ID de bundle y el ID de equipo que has especificado sean válidos.
- Comprueba que no estés usando un comodín para el ID de bundle.
Requerir App Check en tu cliente de iOS
Habilitar Comprobación de aplicaciones en tu aplicación no bloquea automáticamente las solicitudes no reconocidas. Para aplicar esta protección, vaya a la vista de edición de su cliente iOS. En esa sección, verás las métricas de App Check a la derecha de la página, en la sección Google Identity para iOS. Las métricas incluyen la siguiente información:- Número de solicitudes verificadas: solicitudes que tienen un token de Comprobación de aplicaciones válido. Después de habilitar la medida de protección de App Check, solo se completarán las solicitudes de esta categoría.
- Número de solicitudes no verificadas: probablemente solicitudes de cliente obsoletas: solicitudes que no incluyen un token de Comprobación de Aplicaciones. Estas solicitudes pueden proceder de una versión anterior de tu aplicación que no incluya una implementación de Comprobación de Aplicaciones.
- Número de solicitudes sin verificar: solicitudes de origen desconocido: solicitudes sin un token de Comprobación de Aplicaciones que no parecen proceder de tu aplicación.
- Número de solicitudes sin verificar: solicitudes no válidas: solicitudes con un token de Comprobación de Aplicaciones no válido que pueden proceder de un cliente falso que intenta suplantar la identidad de tu aplicación, o de entornos emulados.
Para implementar obligatoriamente Comprobación de Aplicaciones, haz clic en el botón ENFORCE y confirma tu elección. Una vez que la implementación obligatoria esté activa, se rechazarán todas las solicitudes sin verificar de tu cliente.
Nota: Después de habilitar la medida, los cambios pueden tardar hasta 15 minutos en aplicarse.
Dejar de aplicar Comprobación de aplicaciones en tu cliente iOS
Si dejas de aplicar Comprobación de Aplicaciones en tu aplicación, se detendrá la aplicación y se permitirán todas las solicitudes de tu cliente a los endpoints de OAuth 2.0 de Google, incluidas las solicitudes sin verificar.
Para inhabilitar App Check en tu cliente de iOS, ve a la vista de edición del cliente de iOS, haz clic en el botón INHABILITAR y confirma tu elección.
Nota: Después de inhabilitar la aplicación de App Check, los cambios pueden tardar hasta 15 minutos en aplicarse.
Inhabilitar Comprobación de aplicaciones en el cliente de iOS
Si inhabilitas Comprobación de aplicaciones en tu aplicación, se detendrá toda la monitorización y la aplicación de Comprobación de aplicaciones. Considera la posibilidad de no aplicar Comprobación de Aplicaciones para poder seguir monitorizando las métricas de tu cliente.
Para inhabilitar Comprobación de Aplicaciones de Firebase en tu cliente de iOS, ve a la vista de edición del cliente de iOS y desactiva el botón Protege tu cliente de OAuth frente a abusos con Comprobación de Aplicaciones de Firebase.
Nota: Después de inhabilitar App Check, los cambios pueden tardar hasta 15 minutos en aplicarse.
Horario definido de acceso
El acceso temporal permite que un usuario conceda a tu aplicación acceso a sus datos durante un periodo limitado para completar una acción. El acceso temporal está disponible en determinados productos de Google durante el flujo de consentimiento, lo que ofrece a los usuarios la opción de conceder acceso durante un periodo limitado. Un ejemplo es la API Data Portability, que permite una transferencia de datos única.
Cuando un usuario concede a tu aplicación acceso basado en el tiempo, el token de actualización caducará tras el periodo especificado. Ten en cuenta que los tokens de actualización pueden invalidarse antes en circunstancias específicas. Consulta estos casos para obtener más información. El campo refresh_token_expires_in devuelto en la respuesta de intercambio de código de autorización representa el tiempo que queda hasta que caduque el token de actualización en esos casos.
Más información
La práctica actual recomendada de IETF OAuth 2.0 para aplicaciones nativas establece muchas de las prácticas recomendadas que se documentan en este artículo.
Implementar la protección multicuenta
Un paso adicional que debes dar para proteger las cuentas de tus usuarios es implementar la protección multicuenta mediante el servicio de protección multicuenta de Google. Este servicio te permite suscribirte a notificaciones de eventos de seguridad que proporcionan información a tu aplicación sobre los cambios importantes en la cuenta del usuario. Después, puedes usar la información para tomar medidas en función de cómo decidas responder a los eventos.
Estos son algunos ejemplos de los tipos de eventos que el servicio de protección multicuenta de Google envía a tu aplicación:
-
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 Proteger las cuentas de usuario con Protección multicuenta para obtener más información sobre cómo implementar Protección multicuenta y ver la lista completa de eventos disponibles.