Referencia del cliente de JavaScript de Acceso con Google

En esta referencia, se describen los métodos y atributos del cliente de JavaScript que usarás para implementar el Acceso con Google en tus aplicaciones web.

Si encuentras algún problema al usar la biblioteca, infórmalo en nuestro repositorio de GitHub. .

Configuración de Auth

Carga la biblioteca de la plataforma de las APIs de Google para crear el objeto gapi:

<script src="https://apis.google.com/js/platform.js?onload=init" async defer></script>

Después de que se cargue la biblioteca de la plataforma, carga la biblioteca auth2:

function init() {
  gapi.load('auth2', function() {
    /* Ready. Make a call to gapi.auth2.init or some other API */
  });
}

gapi.auth2.init(params)

Inicializa el objeto GoogleAuth. Debes llamar a este método antes de llamar a los métodos de gapi.auth2.GoogleAuth.

Cuando inicializas el objeto GoogleAuth, lo configuras con tu ID de cliente de OAuth 2.0 y cualquier opción adicional que desees especificar. Luego, si el usuario ya accedió, el objeto GoogleAuth restablece el estado de acceso del usuario de la sesión anterior.

Argumentos
params Un objeto que contiene pares clave-valor de datos de configuración del cliente. Consulta gapi.auth2.ClientConfig para ver las diferentes propiedades configurables. Por ejemplo: 
{
  client_id: 'CLIENT_ID.apps.googleusercontent.com'
}
.
Muestra
gapi.auth2.GoogleAuth El objeto gapi.auth2.GoogleAuth Usa el método then() para obtener una promesa que se resuelve cuando finaliza la inicialización del objeto gapi.auth2.GoogleAuth.

GoogleAuth.then(onInit, onError)

Llama a la función onInit cuando el objeto GoogleAuth se inicializa por completo. Si se genera un error durante la inicialización (esto puede ocurrir en navegadores antiguos que no son compatibles), se llamará a la función onError.

Argumentos
onInit Es la función a la que se llama con el objeto GoogleAuth cuando se inicializa por completo.
onError La función a la que se llamó con un objeto que contiene una propiedad error, si no se pudo inicializar GoogleAuth.
Muestra
Promise Un Promise que se completa cuando se completa la función onInit o se rechaza si se generó un error de inicialización. Se resuelve con el valor que se muestra de la función onInit, si existe.

Códigos de error

idpiframe_initialization_failed
No se pudo inicializar un iframe obligatorio de Google, por ejemplo, debido a un entorno no compatible. Una propiedad details proporcionará más información sobre el error generado.

gapi.auth2.ClientConfig

Interfaz que representa los diferentes parámetros de configuración del método gapi.auth2.init.

Parámetros
client_id string Obligatorio. El ID de cliente de la app, que se encuentra y se crea en la Consola de API de Google
cookie_policy string Los dominios para los que se crearán las cookies de acceso. Es un URI, single_host_origin o none. Si no se especifica, el valor predeterminado es single_host_origin.
scope string Los permisos que se solicitarán, como una cadena delimitada por espacios. Es opcional si fetch_basic_profile no se establece como falso.
fetch_basic_profile boolean Recupera la información básica del perfil de los usuarios cuando acceden. Agrega "perfil", "correo electrónico" y "openid" a los permisos solicitados. Es verdadero si no se especifica.
hosted_domain string Es el dominio de G Suite al que deben pertenecer los usuarios para acceder. Los clientes pueden modificar esta propiedad, por lo que debes asegurarte de verificar la propiedad del dominio alojado del usuario que se muestra. Usa GoogleUser.getHostedDomain() en el cliente y la declaración hd en el token de ID en el servidor para verificar que el dominio sea el que esperabas.
use_fedcm boolean Opcional, el valor predeterminado es True. Habilita o inhabilita el uso de las APIs de FedCM del navegador durante el acceso.
ux_mode string Es el modo de UX que se usará para el flujo de acceso. De forma predeterminada, se abrirá el flujo de consentimiento en una ventana emergente. Los valores válidos son popup y redirect.
redirect_uri string Si usas ux_mode='redirect', este parámetro te permite anular el redirect_uri predeterminado que se usará al final del flujo de consentimiento. El redirect_uri predeterminado es la URL actual sin los parámetros de consulta ni el fragmento de hash.
enable_granular_consent boolean Opcional. Si se deben habilitar los permisos detallados. Si se establece en false, se inhabilitarán los permisos más detallados de la Cuenta de Google para los IDs de cliente de OAuth creados antes de 2019. No tiene efecto en los IDs de cliente de OAuth creados durante el 2019 o después, ya que siempre se habilitan permisos más detallados para ellos.
plugin_name string Opcional. Si se establece este valor, los IDs de cliente nuevos creados antes del 29 de julio de 2022 pueden usar la biblioteca de Google Platform anterior. De forma predeterminada, los IDs de cliente creados recientemente ya no pueden usar la biblioteca de la plataforma y, en su lugar, deben usar la biblioteca más reciente de Google Identity Services. Puedes elegir cualquier valor. Se recomienda un nombre descriptivo, como el nombre del producto o del complemento, para la identificación. Ejemplo: plugin_name: 'YOUR_STRING_HERE'

Autenticación

GoogleAuth es una clase singleton que proporciona métodos para permitir que el usuario acceda con una Cuenta de Google, obtenga su estado de acceso actual, obtenga datos específicos de su perfil de Google, solicite permisos adicionales y salga de la cuenta actual.

gapi.auth2.getAuthInstance()

Muestra el objeto GoogleAuth. Debes inicializar el objeto GoogleAuth con gapi.auth2.init() antes de llamar a este método.

Muestra
gapi.auth2.GoogleAuth El objeto gapi.auth2.GoogleAuth Usa este objeto para llamar a los métodos de gapi.auth2.GoogleAuth.

GoogleAuth.isSignedIn.get()

Muestra si el usuario actual accedió.

Muestra
Booleano true si el usuario accedió o false si el usuario salió de su cuenta o si no se inicializó el objeto GoogleAuth.

GoogleAuth.isSignedIn.listen(listener)

Detecta cambios en el estado de acceso del usuario actual.

Argumentos
listener Es una función que toma un valor booleano. listen() pasa true a esta función cuando el usuario accede y false cuando el usuario sale.

GoogleAuth.signIn()

Permite que el usuario acceda con las opciones especificadas en gapi.auth2.init().

Muestra
Promise Un Promise que se completa con la instancia de GoogleUser cuando el usuario autentica correctamente y otorga los permisos solicitados, o se rechaza con un objeto que contiene una propiedad error si se produce un error. Consulta la siguiente sección para ver los códigos de error.

Códigos de error

Consulta GoogleAuth.signIn(options).

GoogleAuth.signIn(options)

Permite que el usuario acceda con las opciones especificadas.

Argumentos
options Puede deberse a una de estas opciones:
  • Un objeto gapi.auth2.SignInOptions que contiene pares clave-valor de parámetros de acceso. Por ejemplo: 
    {
  scope: 'profile email'
}
  • Una instancia de gapi.auth2.SigninOptionsBuilder. Por ejemplo:
    options = new gapi.auth2.SigninOptionsBuilder();
options.setAppPackageName('com.example.app');
options.setFetchBasicProfile(True);
options.setPrompt('select_account');
options.setScope('profile').setScope('email');
Muestra
Promise Un Promise que se completa con la instancia de GoogleUser cuando el usuario autentica y otorga correctamente los permisos solicitados, o se rechaza con un objeto que contiene una propiedad error si se produce un error (consulta a continuación los códigos de error).

Códigos de error

popup_closed_by_user
El usuario cerró la ventana emergente antes de terminar el flujo de acceso.
access_denied
El usuario denegó el permiso para los permisos necesarios.
immediate_failed
No se podía seleccionar ningún usuario automáticamente sin mostrar el flujo de consentimiento. Se genera un error cuando se usa signIn con la opción prompt: 'none'. No debería ser necesario usar esta opción, ya que gapi.auth2.init accederá automáticamente al usuario si accedió anteriormente durante una sesión anterior.

gapi.auth2.SignInOptions

Interfaz que representa los diferentes parámetros de configuración del método GoogleAuth.signIn(options).

Parámetros
prompt string Fuerza un modo específico para el flujo de consentimiento. Opcional.
Los valores posibles son los siguientes:
  • consent
    El servidor de autorización le solicita el consentimiento al usuario antes de mostrarle información a la aplicación.
  • select_account
    El servidor de autorización le solicita al usuario que seleccione una Cuenta de Google. Esto permite que un usuario que tiene varias cuentas seleccione entre las múltiples cuentas en las que puede tener sesiones actuales.
  • none (no se recomienda)
    El servidor de autorización no mostrará ninguna pantalla de autenticación ni de consentimiento del usuario. Mostrará un error si el usuario aún no se autenticó y no otorgó su consentimiento para los permisos solicitados.
    Como gapi.auth2.init hará que un usuario acceda automáticamente a la aplicación si ya accedió, llamar a signIn({prompt: 'none'}) suele fallar.
scope string Los permisos que se solicitarán, como una cadena delimitada por espacios, además de los permisos definidos en los parámetros gapi.auth2.init. Es opcional si fetch_basic_profile no se establece como falso.
ux_mode string Es el modo de UX que se usará para el flujo de acceso. De forma predeterminada, se abrirá el flujo de consentimiento en una ventana emergente. Los valores válidos son popup y redirect.
redirect_uri string Si usas ux_mode='redirect', este parámetro te permite anular el redirect_uri predeterminado que se usará al final del flujo de consentimiento. El redirect_uri predeterminado es la URL actual sin los parámetros de consulta ni el fragmento de hash.

GoogleAuth.signOut()

Sale de la cuenta actual de la aplicación.

Muestra
Promise Un Promise que se entrega cuando el usuario salió de su cuenta.

GoogleAuth.disconnect()

Revoca todos los permisos que otorgó el usuario.

GoogleAuth.grantOfflineAccess(options)

Obtén el permiso del usuario para acceder a los permisos especificados sin conexión.

Argumentos
options Un objeto gapi.auth2.OfflineAccessOptions que contiene pares clave-valor de parámetros. Por ejemplo: 
{
  scope: 'profile email'
}
Muestra
Promise Un Promise que se entrega cuando el usuario otorga los permisos solicitados y pasa un objeto que contiene el código de autorización al controlador de entrega de Promise Por ejemplo: 
auth2.grantOfflineAccess().then(function(resp) {
  var auth_code = resp.code;
});

Códigos de error

popup_closed_by_user
El usuario cerró la ventana emergente antes de terminar el flujo de consentimiento.
access_denied
El usuario denegó el permiso para los permisos requeridos.
immediate_failed
No se podía seleccionar ningún usuario automáticamente sin mostrar el flujo de consentimiento. Se genera un error cuando se usa signIn con la opción prompt: 'none'. No debería ser necesario usar esta opción, ya que gapi.auth2.init accederá automáticamente al usuario si accedió anteriormente durante una sesión anterior.

gapi.auth2.OfflineAccessOptions

Interfaz que representa los diferentes parámetros de configuración del método GoogleAuth.grantOfflineAccess(options).

Parámetros
prompt string Fuerza un modo específico para el flujo de consentimiento. Opcional.
Los valores posibles son los siguientes:
  • consent
    El servidor de autorización le solicita el consentimiento al usuario antes de mostrarle información a la aplicación.
  • select_account
    El servidor de autorización le solicita al usuario que seleccione una Cuenta de Google. Esto permite que un usuario que tiene varias cuentas seleccione entre las múltiples cuentas en las que puede tener sesiones actuales.
scope string Los permisos que se solicitarán, como una cadena delimitada por espacios, además de los permisos definidos en los parámetros gapi.auth2.init. Es opcional si fetch_basic_profile no se establece como falso.

GoogleAuth.attachClickHandler(container, options, onsuccess, onfailure)

Conecta el flujo de acceso al controlador de clics del contenedor especificado.

Argumentos
container El ID o una referencia al elemento div al que se adjuntará el controlador de clics.
options Un objeto que contiene pares clave-valor de parámetros. Consulta GoogleAuth.signIn().
onsuccess Es la función a la que se debe llamar después de que se complete el acceso.
onfailure Es la función a la que se debe llamar si falla el acceso.

Usuarios

Un objeto GoogleUser representa una cuenta de usuario. Por lo general, los objetos GoogleUser se obtienen llamando a GoogleAuth.currentUser.get().

GoogleAuth.currentUser.get()

Muestra un objeto GoogleUser que representa al usuario actual. Ten en cuenta que, en una instancia de GoogleAuth inicializada recientemente, no se configuró el usuario actual. Usa el método currentUser.listen() o GoogleAuth.then() para obtener una instancia GoogleAuth inicializada.

Muestra
GoogleUser El usuario actual

GoogleAuth.currentUser.listen(listener)

Detecta cambios en currentUser.

Argumentos
listener Una función que toma un parámetro GoogleUser. listen pasa a esta función una instancia de GoogleUser en cada cambio que modifica currentUser.

GoogleUser.getId()

Obtén la cadena de ID único del usuario.

Muestra
String El ID único del usuario

GoogleUser.isSignedIn()

Muestra verdadero si el usuario accedió.

Muestra
Booleano Es verdadero si el usuario accedió.

GoogleUser.getHostedDomain()

Obtén el dominio de G Suite del usuario si accedió con una cuenta de G Suite.

Muestra
String El dominio de G Suite del usuario

GoogleUser.getGrantedScopes()

Obtén los permisos que otorgó el usuario como una cadena delimitada por espacios.

Muestra
String Los permisos otorgados por el usuario

GoogleUser.getBasicProfile()

Obtén la información básica del perfil del usuario.

Muestra
gapi.auth2.BasicProfile Puedes recuperar las propiedades de gapi.auth2.BasicProfile con los siguientes métodos:
  • BasicProfile.getId()
  • BasicProfile.getName()
  • BasicProfile.getGivenName()
  • BasicProfile.getFamilyName()
  • BasicProfile.getImageUrl()
  • BasicProfile.getEmail()

GoogleUser.getAuthResponse(includeAuthorizationData)

Obtén el objeto de respuesta de la sesión de autenticación del usuario.

Argumentos
includeAuthorizationData Opcional: Es un valor booleano que especifica si siempre se debe mostrar un token de acceso y los permisos. De forma predeterminada, el token de acceso y los permisos solicitados no se devuelven cuando fetch_basic_profile es verdadero (el valor predeterminado) y no se solicitan permisos adicionales.
Muestra
gapi.auth2.AuthResponse Un objeto gapi.auth2.AuthResponse.

GoogleUser.reloadAuthResponse()

Fuerza una actualización del token de acceso y, luego, muestra una promesa para la nueva AuthResponse.

Muestra
Promise Un Promise que se completa con el gapi.auth2.AuthResponse vuelto a cargar cuando se vuelve a cargar el token de OAuth.

gapi.auth2.AuthResponse

Es la respuesta que se muestra cuando se llaman a los métodos GoogleUser.getAuthResponse(includeAuthorizationData) o GoogleUser.reloadAuthResponse().

Propiedades
access_token string Se otorgó el token de acceso.
id_token string El token de ID otorgado
scope string Los permisos otorgados en el token de acceso
expires_in number Es la cantidad de segundos hasta que vence el token de acceso.
first_issued_at number Es la marca de tiempo en la que el usuario otorgó los permisos solicitados por primera vez.
expires_at number La marca de tiempo en la que vencerá el token de acceso.

GoogleUser.hasGrantedScopes(scopes)

Muestra verdadero si el usuario otorgó los permisos especificados.

Argumentos
scopes Una cadena de alcances delimitados por espacios.
Muestra
Booleano Es verdadero si se otorgaron los permisos.

GoogleUser.grant(options)

Solicitar permisos adicionales al usuario

Consulta GoogleAuth.signIn() para ver la lista de parámetros y el código de error.

GoogleUser.grantOfflineAccess(options)

Obtén el permiso del usuario para acceder a los permisos especificados sin conexión.

Argumentos
options Un objeto gapi.auth2.OfflineAccessOptions que contiene pares clave-valor de parámetros. Por ejemplo: 
{
  scope: 'profile email'
}

GoogleUser.disconnect()

Revoca todos los permisos que el usuario otorgó a la aplicación.

Elementos de la IU

gapi.signin2.render(id, options)

Renderiza un botón de acceso en el elemento con el ID determinado, con la configuración que especifica el objeto options.

Argumentos
id Es el ID del elemento en el que se renderizará el botón de acceso.
options Es un objeto que contiene la configuración que se usará para renderizar el botón. Por ejemplo: 
{
  scope: 'email',
  width: 200,
  height: 50,
  longtitle: true,
  theme: 'dark',
  onsuccess: handleSuccess,
  onfailure: handleFailure
}
Puedes especificar las siguientes opciones:
Parámetros
alcance Los permisos que se solicitarán cuando el usuario acceda (predeterminado: profile).
ancho Es el ancho del botón en píxeles (valor predeterminado: 120).
alto Es la altura del botón en píxeles (valor predeterminado: 36).
longtitle Muestra etiquetas largas, como "Acceder con Google", en lugar de "Acceder" (predeterminado: false). Cuando uses títulos largos, debes aumentar el ancho del botón desde su valor predeterminado.
tema Es el tema de color del botón: light o dark (predeterminado: light).
onsuccess Es la función de devolución de llamada a la que se llamará cuando un usuario acceda correctamente. Esta función debe tomar un argumento: una instancia de gapi.auth2.GoogleUser (predeterminado: ninguno).
onfailure Es la función de devolución de llamada a la que se debe llamar cuando falla el acceso. Esta función no toma argumentos (predeterminado: ninguno).

Avanzado

gapi.auth2.authorize(params, callback)

Realiza una autorización única de OAuth 2.0. Según los parámetros que se usen, se abrirá una ventana emergente en el flujo de acceso de Google o se intentará cargar la respuesta solicitada de forma silenciosa, sin interacción del usuario.

Estos son algunos casos de uso en los que este método es útil:

  • Tu aplicación solo debe solicitar un extremo de la API de Google una vez, por ejemplo, para cargar los videos de YouTube favoritos del usuario la primera vez que accede.
  • Tu aplicación tiene su propia infraestructura de administración de sesiones y solo requiere el token de ID una vez para identificar al usuario en tu backend.
  • Se usan varios IDs de cliente en la misma página.
Argumentos
params Un objeto que contiene pares clave-valor de datos de configuración. Consulta gapi.auth2.AuthorizeConfig para ver las diferentes propiedades configurables. Por ejemplo: 
{
  client_id: 'CLIENT_ID.apps.googleusercontent.com',
  scope: 'email profile openid',
  response_type: 'id_token permission'
}
.
callback Una función a la que se llama con un objeto gapi.auth2.AuthorizeResponse después de que se completa la solicitud (ya sea de forma correcta o con una falla).

Ejemplo

gapi.auth2.authorize({
  client_id: 'CLIENT_ID.apps.googleusercontent.com',
  scope: 'email profile openid',
  response_type: 'id_token permission'
}, function(response) {
  if (response.error) {
    // An error happened!
    return;
  }
  // The user authorized the application for the scopes requested.
  var accessToken = response.access_token;
  var idToken = response.id_token;
  // You can also now use gapi.client to perform authenticated requests.
});

Códigos de error

idpiframe_initialization_failed
No se pudo inicializar un iframe obligatorio de Google, por ejemplo, debido a un entorno no compatible. Una propiedad details proporcionará más información sobre el error generado.
popup_closed_by_user
El usuario cerró la ventana emergente antes de terminar el flujo de acceso.
access_denied
El usuario denegó el permiso para los permisos necesarios.
immediate_failed
No se podía seleccionar ningún usuario automáticamente sin mostrar el flujo de consentimiento. Se genera un error cuando se usa signIn con la opción prompt: 'none'.

gapi.auth2.AuthorizeConfig

Interfaz que representa los diferentes parámetros de configuración del método gapi.auth2.authorize.

Propiedades
client_id string Obligatorio. El ID de cliente de la app, que se encuentra y se crea en la Consola de API de Google
scope string Obligatorio. Los permisos que se solicitarán, como una cadena delimitada por espacios.
response_type string Una lista de tipos de respuesta delimitados por espacios. La configuración predeterminada es 'permission'. Los valores posibles son los siguientes:
  • id_token para recuperar un token de ID
  • permission (o token) para recuperar un token de acceso
  • code, para recuperar un código de autorización
prompt string Fuerza un modo específico para el flujo de consentimiento. Los valores posibles son los siguientes:
  • consent
    El servidor de autorización le solicita el consentimiento al usuario antes de mostrarle información a la aplicación.
  • select_account
    El servidor de autorización le solicita al usuario que seleccione una Cuenta de Google. Esto permite que un usuario que tiene varias cuentas seleccione entre las múltiples cuentas en las que puede tener sesiones actuales.
  • none
    El servidor de autorización no mostrará ninguna pantalla de autenticación ni de consentimiento del usuario. Mostrará un error si el usuario aún no se autenticó y no dio su consentimiento para los permisos solicitados.
    Si se solicita code como tipo de respuesta, el código que se devuelve solo se puede intercambiar por un access_token, no por un refresh_token.
cookie_policy string Los dominios para los que se crearán las cookies de acceso. Es un URI, single_host_origin o none. Si no se especifica, el valor predeterminado es single_host_origin.
hosted_domain string Es el dominio de G Suite al que deben pertenecer los usuarios para acceder. Los clientes pueden modificar esta propiedad, por lo que debes asegurarte de verificar la propiedad del dominio alojado del usuario que se muestra.
login_hint string Es el correo electrónico o el ID de usuario de un usuario que se preseleccionará en el flujo de acceso. El usuario puede modificarlo, a menos que se use prompt: "none".
include_granted_scopes boolean Indica si se debe solicitar un token de acceso que incluya todos los permisos que el usuario otorgó anteriormente a la app o solo los permisos solicitados en la llamada actual. La configuración predeterminada es true.
enable_granular_consent boolean Opcional. Si se deben habilitar los permisos detallados Si se establece en false, se inhabilitarán los permisos más detallados de la cuenta de Google para los IDs de cliente de OAuth creados antes de 2019. No tiene efecto en los IDs de cliente de OAuth creados durante o después de 2019, ya que siempre se habilitan permisos más detallados para ellos.
plugin_name string Opcional. Si se configuran, los IDs de cliente creados antes del 29 de julio de 2022 pueden usar la biblioteca de Google Platform. De forma predeterminada, los IDs de cliente creados recientemente no pueden usar la biblioteca de la plataforma y, en su lugar, deben usar la biblioteca más reciente de Google Identity Services. Puedes elegir cualquier valor. Se recomienda un nombre descriptivo, como el nombre del producto o del complemento, para facilitar la identificación. Ejemplo: plugin_name: 'YOUR_STRING_HERE'

gapi.auth2.AuthorizeResponse

La respuesta que se muestra a la devolución de llamada del método gapi.auth2.authorize

Propiedades
access_token string Se otorgó el token de acceso. Solo está presente si se especificó permission o token en response_type.
id_token string El token de ID otorgado Solo está presente si se especificó id_token en response_type.
code string Se otorgó el código de autorización. Solo está presente si se especificó code en response_type.
scope string Los permisos otorgados en el token de acceso Solo está presente si se especificó permission o token en response_type.
expires_in number Es la cantidad de segundos hasta que vence el token de acceso. Solo está presente si se especificó permission o token en response_type.
first_issued_at number Es la marca de tiempo en la que el usuario otorgó los permisos solicitados por primera vez. Solo está presente si se especificó permission o token en response_type.
expires_at number La marca de tiempo en la que vencerá el token de acceso. Solo está presente si se especificó permission o token en response_type.
error string Cuando la solicitud falla, contiene el código de error.
error_subtype string Cuando la solicitud falla, puede contener información adicional al código de error que también se muestra.