Referencia del cliente de JavaScript con Acceso con Google

Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

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

Si tienes algún problema con el uso de la biblioteca, infórmalo a nuestro repositorio de GitHub.

Configuración de autenticación

Carga la biblioteca de la plataforma de las API 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 los 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'
}
Resultado que se muestra
gapi.auth2.GoogleAuth El objeto gapi.auth2.GoogleAuth. Usa el método then() para obtener una promesa que se resuelve cuando el objeto gapi.auth2.GoogleAuth termina de inicializarse.

GoogleAuth.then(onInit y onError)

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

Argumentos
onInit Se llama a la función con el objeto GoogleAuth cuando se inicializa por completo.
onError Es la función a la que se llamó con un objeto que contiene una propiedad error si no se pudo inicializar GoogleAuth.
Resultado que se muestra
Promesas Un Promise que se completa cuando se completa la función onInit, o bien se rechaza si se genera un error de inicialización Se resuelve con el valor que se muestra desde 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.

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 en Google Developers Console.
cookie_policy string Los dominios para los que se deben crear cookies de acceso. Puede ser un URI, single_host_origin o none. La configuración predeterminada es single_host_origin si no se especifica.
scope string Los permisos que se deben solicitar, como una string delimitada por espacios. Opcional si fetch_basic_profile no está configurado como falso
fetch_basic_profile boolean Recupera la información básica del perfil de los usuarios cuando accedan. Agrega "profile", "email" y "openid" a los permisos solicitados. 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 esto, 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 reclamación de hd en el token de ID del servidor para verificar que el dominio es lo que esperabas.
ux_mode string El modo de UX que se usa 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 la redirect_uri predeterminada que se usará al final del flujo de consentimiento. La redirect_uri predeterminada es la URL actual sin parámetros de consulta ni fragmento de hash.
plugin_name string Opcional. Si se establece este valor, los nuevos ID de cliente creados antes del 29 de julio de 2022 pueden usar la biblioteca antigua de Google Platform. De forma predeterminada, los ID de cliente recién creados no pueden usar la Biblioteca de la plataforma y, en su lugar, deben usar la biblioteca más reciente de los Servicios de identidad de Google. Puedes elegir cualquier valor; se recomienda un nombre descriptivo, como el nombre del producto o del complemento, para una identificación fácil. 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, obtener el estado de acceso actual del usuario, obtener datos específicos del perfil de Google del usuario, solicitar permisos adicionales y salir 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.

Resultado que se 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ó.

Resultado que se muestra
Booleano true si el usuario accedió o false si salió de la cuenta o no se inicializó el objeto GoogleAuth.

GoogleAuth.isSignedIn.listen(listener)

Escucha los cambios en el estado actual de acceso del usuario.

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

GoogleAuth.signIn().

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

Resultado que se muestra
Promesas Una Promise que se completa con la instancia GoogleUser cuando el usuario se autentica y otorga correctamente los permisos solicitados, o se rechaza con un objeto que contiene una propiedad error si se produjo un error (consulta los códigos de error a continuación).

Códigos de error

Consulta los GoogleAuth.signIn(options).

GoogleAuth.signIn(options)

Permite que el usuario acceda con las opciones especificadas.

Argumentos
options Sigue uno de estos pasos:
  • Un objeto gapi.auth2.SignInOptions que contiene pares clave-valor de los 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');
Resultado que se muestra
Promesas Una Promise que se completa con la instancia GoogleUser cuando el usuario se autentica y otorga correctamente los permisos solicitados, o se rechaza con un objeto que contiene una propiedad error si se produjo un error (consulta los códigos de error a continuación).

Códigos de error

popup_closed_by_user
El usuario cerró la ventana emergente antes de finalizar el flujo de acceso.
access_denied
El usuario rechazó el permiso para los permisos requeridos.
immediate_failed
No se pudo seleccionar a ningún usuario de forma automática sin solicitar el flujo de consentimiento. Se produjo un error cuando se usaba signIn con la opción prompt: 'none'. No debes usar esta opción, ya que gapi.auth2.init accederá al usuario de forma automática 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 solicita el consentimiento del usuario antes de mostrar 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 varias cuentas para las que puede tener sesiones actuales.
  • none (no se recomienda)
    El servidor de autorización no mostrará ninguna pantalla de autenticación o de consentimiento del usuario, por lo que mostrará un error si el usuario aún no está autenticado y no consintió anteriormente los permisos solicitados.
    Como gapi.auth2.init hará que un usuario acceda automáticamente a la aplicación si había accedido anteriormente, la llamada a signIn({prompt: 'none'}) fallará.
scope string Los permisos que se deben solicitar, como una string delimitada por espacios, además de los permisos definidos en los parámetros gapi.auth2.init. Es opcional si fetch_basic_profile no está configurado como falso.
ux_mode string El modo de UX que se usa 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 la redirect_uri predeterminada que se usará al final del flujo de consentimiento. El valor predeterminado de redirect_uri es la URL actual sin parámetros de consulta ni fragmento de hash.

GoogleAuth.signOut(),

Sal de la cuenta actual desde la aplicación.

Resultado que se muestra
Promesas Un Promise que se entrega cuando el usuario sale de su cuenta.

GoogleAuth.disconnect()

Revoca todos los alcances que el usuario otorgó.

GoogleAuth.grantOfflineAccess(options)

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

Argumentos
options Un objeto gapi.auth2.OfflineAccessOptions que contiene pares clave-valor de parámetros Por ejemplo: 
{
  scope: 'profile email'
}
Resultado que se muestra
Promesas 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 entregas del 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 finalizar el flujo de consentimiento.
access_denied
El usuario rechazó el permiso para los permisos requeridos.
immediate_failed
No se pudo seleccionar a ningún usuario de forma automática sin solicitar el flujo de consentimiento. Se produjo un error cuando se usaba signIn con la opción prompt: 'none'. No debes usar esta opción, ya que gapi.auth2.init accederá al usuario de forma automática 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 solicita el consentimiento del usuario antes de mostrar 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 varias cuentas para las que puede tener sesiones actuales.
scope string Los permisos que se deben solicitar, como una string delimitada por espacios, además de los permisos definidos en los parámetros gapi.auth2.init. Es opcional si fetch_basic_profile no está configurado como falso.

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

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

Argumentos
container El ID del elemento div al que se adjunta el controlador de clics, o una referencia a él.
options Un objeto que contiene pares clave-valor de parámetros Consulta GoogleAuth.signIn().
onsuccess La función a la que se debe llamar después de que se complete el acceso.
onfailure 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 mediante una llamada 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 recién inicializada, no se estableció el usuario actual. Usa el método currentUser.listen() o GoogleAuth.then() para obtener una instancia de GoogleAuth inicializada.

Resultado que se muestra
GoogleUser El usuario actual

GoogleAuth.currentUser.listen(listener)

Escucha los cambios en currentUser.

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

GoogleUser.getId().

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

Resultado que se muestra
String El ID único del usuario

GoogleUser.isSignedIn()

El resultado es verdadero si el usuario accedió a su cuenta.

Resultado que se muestra
Booleano Verdadero si el usuario accedió

GoogleUser.getHostedDomain().

Obtenga el dominio de G Suite del usuario si este accedió con una cuenta de G Suite.

Resultado que se muestra
String El dominio de G Suite del usuario

GoogleUser.getGrantedScopes().

Obtiene los alcances que el usuario otorgó como string delimitada por espacios.

Resultado que se muestra
String Los alcances otorgados por el usuario

GoogleUser.getBasicProfile().

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

Resultado que se 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(incluirAuthorizationData)

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 deben mostrar un token de acceso y permisos. De forma predeterminada, el token de acceso y los permisos solicitados no se muestran cuando fetch_basic_profile es verdadero (el valor predeterminado) y no se solicitan alcances adicionales.
Resultado que se 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.

Resultado que se muestra
Promise Una Promise que se completa con el gapi.auth2.AuthResponse recargado cuando se vuelve a cargar el token de OAuth.

gapi.auth2.AuthResponse

La respuesta que se muestra cuando se llama a los métodos GoogleUser.getAuthResponse(includeAuthorizationData) o GoogleUser.reloadAuthResponse()

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

GoogleUser.hasGrantedScopes(scopes)

Muestra true si el usuario otorgó los alcances especificados.

Argumentos
scopes Una string de alcances delimitados por espacios.
Resultado que se muestra
Booleano Verdadero si se otorgaron los permisos

GoogleUser.grant(options)

Solicitar alcances adicionales al usuario

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

GoogleUser.grantOfflineAccess(options)

Obtén permiso del usuario para acceder a los alcances 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 alcances que el usuario otorgó para la aplicación.

Elementos de la IU

gapi.signin2.render(id, options)

Renderiza un botón de acceso en el elemento con el ID proporcionado, con la configuración especificada por el objeto options.

Argumentos
id El ID del elemento en el que se renderiza el botón de acceso.
options Un objeto que contiene la configuración que se usará para procesar 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
permiso Los permisos que se deben solicitar cuando el usuario accede (valor predeterminado: profile).
ancho El ancho del botón en píxeles (valor predeterminado: 120).
alto La altura del botón en píxeles (valor predeterminado: 36).
título largo Muestra etiquetas largas, como "Acceder con Google", en lugar de "Acceder" (valor predeterminado: false). Cuando uses títulos largos, debes aumentar el ancho del botón de forma predeterminada.
tema El tema de color del botón: light o dark (valor predeterminado: light)
Éxito La función de devolución de llamada que se debe llamar cuando un usuario accede correctamente. Esta función debe tener un argumento: una instancia de gapi.auth2.GoogleUser (valor predeterminado: ninguno).
error Es la función de devolución de llamada que se llamará cuando falle el acceso. Esta función no acepta argumentos (valor predeterminado: ninguno).

Avanzado

gapi.auth2.authorized(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 con Google o se intentará cargar la respuesta solicitada de manera silenciosa, sin interacción del usuario.

Estos son algunos casos prácticos en los que este método es útil:

  • Tu aplicación solo necesita solicitar un extremo de API de Google una vez, por ejemplo, para cargar los videos favoritos de YouTube 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 ID de cliente en la misma página.
Argumentos
params Un objeto que contiene pares clave-valor de los 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 llamada con un objeto gapi.auth2.AuthorizeResponse después de que se haya completado la solicitud (ya sea de forma correcta o con un error).

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.
popup_closed_by_user
El usuario cerró la ventana emergente antes de finalizar el flujo de acceso.
access_denied
El usuario rechazó el permiso para los permisos requeridos.
immediate_failed
No se pudo seleccionar a ningún usuario de forma automática sin solicitar el flujo de consentimiento. Se produjo un error cuando se usaba signIn con la opción prompt: 'none'.

gapi.auth2.AutorizaConfig

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 en Google Developers Console.
scope string Obligatorio: Los permisos que se deben solicitar, como una string delimitada por espacios.
response_type string Una lista de tipos de respuesta delimitada 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 solicita el consentimiento del usuario antes de mostrar 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 varias cuentas para las que puede tener sesiones actuales.
  • none
    El servidor de autorización no mostrará ninguna pantalla de autenticación o de consentimiento del usuario, y se mostrará un error si el usuario aún no está autenticado y no consintió los permisos solicitados.
    Si se solicita code como tipo de respuesta, el código que se muestre solo se podrá intercambiar por un access_token, no por un refresh_token.
cookie_policy string Los dominios para los que se deben crear cookies de acceso. Puede ser un URI, single_host_origin o none. La configuración predeterminada es single_host_origin si no se especifica.
hosted_domain string Es el dominio de G Suite al que deben pertenecer los usuarios para acceder. Esto puede modificarse por los clientes, así que asegúrate de verificar la propiedad de dominio alojado del usuario que se muestra.
login_hint string El correo electrónico, o ID de usuario, de un usuario que se preseleccionará en el flujo de acceso. Esto es susceptible a las modificaciones por parte del usuario, a menos que se use prompt: "none".
include_granted_scopes boolean Si deseas solicitar un token de acceso que incluya todos los permisos otorgados anteriormente por el usuario a la app o solo los permisos solicitados en la llamada actual. La configuración predeterminada es true.
plugin_name string Opcional. Si se configura, los ID de cliente creados antes del 29 de julio de 2022 pueden usar la biblioteca de Google Platform. De forma predeterminada, los ID de cliente recién creados no pueden usar la Biblioteca de la plataforma y, en su lugar, deben usar la biblioteca más reciente de los Servicios de identidad de Google. 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 mostró 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 Se otorgó el token de ID. Solo está presente si se especificó id_token en response_type.
code string El código de autorización otorgado. Solo está presente si se especificó code en response_type.
scope string Los alcances otorgados en el token de acceso. Solo está presente si se especificó permission o token en response_type.
expires_in number La cantidad de segundos hasta que venza el token de acceso. Solo está presente si se especificó permission o token en response_type.
first_issued_at number La marca de tiempo en la que el usuario otorgó por primera vez los permisos solicitados. Solo está presente si se especificó permission o token en response_type.
expires_at number La marca de tiempo en la que caducará el token de acceso. Solo está presente si se especificó permission o token en response_type.
error string Cuando la solicitud falla, esto contiene el código de error.
error_subtype string Cuando la solicitud falla, puede contener información adicional para el código de error que también se muestra.