Configura Google Cloud y OAuth

Se proporciona acceso a la API de Google Health a través de Google Cloud. Para habilitar la API y autorizar una Cuenta de Google, necesitarás un proyecto de Google Cloud.

Ya seas un desarrollador de la API de Fitbit o nuevo en la API de Google Health deberás completar este paso para realizar llamadas a la API.

Crea un proyecto y un cliente de OAuth

Usa el botón Habilitar la API y obtener un ID de cliente de OAuth 2.0 para habilitar la API de Google Health y obtener un ID de cliente de OAuth 2.0:

  1. Si tienes un proyecto de Google Cloud existente que deseas usar para la API de Google Health, primero asegúrate de haber accedido a la cuenta de administrador de ese proyecto. Luego, selecciona el proyecto existente de la lista de proyectos disponibles después de hacer clic en el botón. De lo contrario, crea un proyecto nuevo.
  2. Selecciona Servidor web cuando te pregunte "¿Desde dónde llamas?".
  3. Ingresa https://www.google.com como el valor de URIs de redireccionamiento autorizados. Se requiere un URI de redireccionamiento para obtener un código de autorización con OAuth 2.0.
  4. Una vez que se complete la configuración, copia los valores del ID de cliente y el secreto del cliente de OAuth 2.0, y descarga el archivo JSON de credenciales en tu máquina local.
Habilita la API y obtén un ID de cliente de OAuth 2.0

Si deseas configurar manualmente tu proyecto de Google Cloud o verificar la configuración y recuperar tus credenciales nuevamente, haz lo siguiente:

  1. Habilita la API de Google Health en la página Habilitación de la API.
  2. Obtén un ID de cliente de OAuth 2.0 en la página Credenciales.

Para obtener más información sobre la configuración de OAuth 2.0 con la consola de Google, consulta Usa OAuth 2.0 para acceder a las APIs de Google.

Agrega usuarios de prueba

De forma predeterminada, los clientes de OAuth recién creados se encuentran en un estado no verificado con un límite de 100 usuarios para fines de prueba y producción. Para habilitar la autorización durante este período, debes agregar manualmente la dirección de correo electrónico de cada usuario a la lista de usuarios de prueba en la configuración de tu proyecto.

Actualiza la lista de usuarios de prueba en la página Público:

  1. En esta página, deberías ver el "Estado de publicación" establecido en Prueba y el "Tipo de usuario" establecido en Externo.
  2. En la sección "Usuarios de prueba", haz clic en + Agregar usuarios. Ingresa la dirección de correo electrónico de los usuarios de prueba a los que se les debe permitir otorgar permiso a tu app para acceder a sus datos de salud.
  3. Haz clic en Guardar.

Para admitir más de 100 usuarios con la API de Google Health, se debe completar una revisión de seguridad de terceros. Puedes encontrar información adicional en el Centro de ayuda de Verificación de apps de OAuth.

Agrega permisos

Debes especificar los permisos a los que tu cliente puede llamar en la página Acceso a los datos:

  1. En esta página, haz clic en Agregar o quitar permisos.
  2. En la columna API, busca "API de Google Health". Selecciona los permisos que necesitas para tu aplicación.
  3. Después de seleccionar todos los permisos que necesitas, haz clic en Actualizar para volver a la página Acceso a los datos.
  4. Haz clic en Guardar.

Antes de seleccionar tus permisos, revisa la implementación de los permisos.

Terminaste de configurar tu ID de cliente y ahora deberías poder realizar llamadas a la API de Google Health.

Actualiza los permisos

Puedes pedirle al usuario que vuelva a autorizar tu app configurando el parámetro prompt como consentimiento en tu solicitud de autenticación. Cuando se incluye prompt=consent, la pantalla de consentimiento se muestra cada vez que tu app solicita autorización de permisos de acceso, incluso si todos los permisos se otorgaron anteriormente a tu proyecto de APIs de Google.

Para agregar o cambiar permisos con el parámetro prompt=consent, sigue estos pasos:

  1. Identifica la lista completa de permisos que necesita tu aplicación. Esto debe incluir los permisos existentes y los nuevos que necesitas agregar.

  2. Modifica el parámetro de permiso en la URL de autorización para incluir la lista actualizada de valores de permiso separados por espacios.

  3. Agrega prompt=consent a los parámetros del URI de autenticación. Esto obliga al servidor de autorización a pedirle al usuario su consentimiento antes de mostrar información a tu cliente.

    En el siguiente ejemplo, se muestra una solicitud HTTPS GET al extremo de autorización de OAuth 2.0 de Google que solicita varios permisos con prompt=consent agregado:

    https://accounts.google.com/o/oauth2/v2/auth?client_id=client-id&redirect_uri=redirect-uri&response_type=code&access_type=offline&scope=https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly%20https://www.googleapis.com/auth/googlehealth.sleep.readonly&prompt=consent

  4. Cuando el usuario siga el vínculo actualizado, se mostrará una página de consentimiento en la que se enumeran todos los permisos solicitados. Una vez que el usuario haga clic en "Continuar" o "Permitir", recibirás un nuevo código de autorización que se puede intercambiar por tokens que cubran el conjunto completo de permisos.

    Incluye prompt=consent solo cuando sea necesario, por ejemplo, cuando necesites obtener un nuevo token de actualización o cuando hayan cambiado los permisos solicitados.

Bibliotecas cliente de OAuth2

La lista de bibliotecas cliente de OAuth2 disponibles que se usan para la integración con frameworks populares se puede encontrar en Usa OAuth 2.0 para acceder a las APIs de Google.

Tokens de actualización

Para mantener el acceso a largo plazo a las APIs de Google sin requerir la reautenticación constante del usuario, tu aplicación debe usar un token de actualización. Para obtener detalles de implementación completos, incluidas las solicitudes y los parámetros HTTP específicos requeridos, consulta la documentación de la plataforma de identidad de Google.

Para intercambiar un token de actualización por un token de acceso, realiza una llamada HTTPS POST al extremo de token de OAuth 2.0 de Google. En el siguiente fragmento, se muestra un ejemplo de solicitud y respuesta:

Solicitud

curl -L -X POST 'https://oauth2.googleapis.com/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'client_id=client-id&client_secret=client-secret&refresh_token=refresh-token&grant_type=refresh_token'

Respuesta

{
  "access_token": "access-token",
  "expires_in": 3599,
  "scope": "scope-list",
  "token_type": "Bearer",
  "refresh_token": "refresh-token",
  "refresh_token_expires_in": 112154
}

Cuándo actualizar un token

Actualiza los tokens de actualización a pedido como parte de la progresión natural de la sesión activa de un usuario cuando los tokens de acceso vencen o están por vencer. Evita actualizar los tokens en lotes (por ejemplo, usar un servicio o trabajo cron programado para actualizar los tokens de todos los usuarios a una hora fija).

No se recomienda actualizar los tokens en lotes por los siguientes motivos:

  • La actualización por lotes impide alinear las actualizaciones de tokens con los patrones de sincronización de usuarios activos. Si bien puedes usar la llamada Get Devices para ver la última hora de sincronización de un usuario, esto requiere un permiso de OAuth adicional que los usuarios no están obligados a aprobar.
  • El procesamiento por lotes actualiza los tokens que no necesitan actualizarse, lo que genera una sobrecarga de procesamiento redundante para tus sistemas y los servidores de Google.
  • Si se produce un problema de red o una interrupción del servidor durante una actualización por lotes, todos los tokens de usuario afectados se verán afectados a la vez. La actualización de tokens de forma individual durante la progresión natural de las sincronizaciones de usuarios aísla el impacto de las fallas transitorias en un solo usuario.
  • Diagnosticar problemas es más difícil con los trabajos por lotes. Debido a que las solicitudes por lotes ocurren con menos frecuencia y generan una gran cantidad de entradas de registro a la vez, es más difícil identificar el inicio de un incidente.
  • Los picos de alta simultaneidad en las solicitudes de tokens durante las ejecuciones por lotes aumentan la probabilidad de alcanzar los límites de frecuencia o experimentar errores de autenticación intermitentes.

Comportamiento de los tokens durante las pruebas

Ten en cuenta cómo se comportan los tokens de actualización según el estado de publicación de tu proyecto de Google Cloud:

  • Modo de prueba: Si tu pantalla de consentimiento de OAuth está configurada con un estado de publicación "Prueba", los tokens de actualización emitidos se basan en el tiempo y vencen después de 7 días. Durante este período, recibirás un solo token de actualización que seguirá siendo válido y utilizable para obtener tokens de acceso nuevos hasta que llegue a su fecha de vencimiento.
  • Modo publicado: Una vez que tu app se mueve al estado "En producción", los tokens de actualización no vencen, a menos que se revoquen o permanezcan sin usar durante un período prolongado (por lo general, seis meses).

Para garantizar una experiencia del usuario sin problemas, asegúrate de publicar tu aplicación antes de que se mueva a un entorno de producción para evitar el vencimiento de tokens de 7 días.

Protección integral de la cuenta (API de RISC)

Habilita el uso compartido y la coordinación de riesgos e incidentes (RISC) si deseas recibir notificaciones sobre los cambios en los tokens de eventos o la vinculación de cuentas, como cuentas desconectadas o tokens revocados, para limpiar los tokens almacenados y actualizar el estado de conexión de la IU. Habilitar la API de RISC es opcional.

Para habilitar la API de RISC en tu proyecto de Google Cloud, haz lo siguiente:

  1. Abre la API de RISC página en la consola de Google Cloud. Asegúrate de que esté seleccionado el proyecto que usas para la API de Google Health.
  2. Lee las Condiciones de RISC y asegúrate de comprender los requisitos.
  3. Haz clic en Habilitar si aceptas las condiciones.

Después de habilitar la API, debes crear y registrar un extremo HTTPS para recibir y validar los tokens de eventos que envía Google.

Para obtener más información sobre la Protección integral de la cuenta y RISC, consulta Protege las cuentas de usuario con la Protección integral de la cuenta.