Referencia del cliente de JavaScript de Acceso con Google

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

Si tienes algún problema al usar la biblioteca, infórmalo a nuestro Repositorio de GitHub.

Configuración de autenticación

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, debes configurarlo 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 desde 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 los diferentes propiedades configurables. Por ejemplo: 
{
  client_id: 'CLIENT_ID.apps.googleusercontent.com'
}
Muestra
gapi.auth2.GoogleAuth El objeto gapi.auth2.GoogleAuth Usa el then() para obtener una promesa que se resuelve cuando el objeto gapi.auth2.GoogleAuth finaliza inicializando.

GoogleAuth.then(onInit, onError)

Llama a la función onInit cuando el objeto GoogleAuth está por completo. antes de que se inicialice. Si se produce un error durante la inicialización (esto puede suceder en navegadores antiguos no compatibles), en su lugar, se llamará a la función onError.

Argumentos
onInit La función a la que se llamó con el objeto GoogleAuth cuando la función está completamente antes de que se inicialice.
onError La función a la que se llamó con un objeto que contiene una propiedad error si no se pudo inicializar GoogleAuth.
Muestra
Promesa Un Promise que se entrega cuando el onInit se completó o se rechazó si se produjo un error de inicialización. Se resuelve con el El valor que se muestra de la función onInit, si corresponde.

Códigos de error

idpiframe_initialization_failed
No se pudo inicializar un iframe requerido de Google, por ejemplo, debido a una solicitud no admitida en un entorno de nube. Una propiedad details brindará más información sobre el error generado.

gapi.auth2.ClientConfig

interfaz que representa los diferentes parámetros de configuración para el 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 APIs de Google.
cookie_policy string Los dominios para los que se crean las cookies de acceso. Ya sea un URI, single_host_origin o none. La configuración predeterminada es single_host_origin si no se especifica.
scope string Los alcances que se solicitarán, como una string delimitada por espacios. Opcional si fetch_basic_profile no está configurado como falso.
fetch_basic_profile boolean Recupera las métricas de los usuarios información básica del perfil al acceder. Agrega “profile”, “email” y "openid" a los permisos solicitados. Es verdadero si no se especifica.
hosted_domain string El dominio de G Suite al que deben pertenecer los usuarios para acceder. Esta susceptible de sufrir modificaciones por parte de los clientes, así que asegúrese de verificar el propiedad de dominio alojado del usuario que se devolvió. Usa GoogleUser.getHostedDomain() activado cliente y la reclamación hd en el token de ID de la para verificar que el dominio es el esperado.
use_fedcm boolean Opcional; el valor predeterminado es True. Habilitar o inhabilitar el uso de las APIs de FedCM del navegador durante el acceso.
ux_mode string 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 la redirect_uri predeterminada que se usará al final del flujo de consentimiento. El El valor predeterminado redirect_uri es la URL actual sin parámetros de consulta ni hash. en ese fragmento.
enable_granular_consent boolean Opcional. Si se habilita o no detallado permisos. Si se establece en false, la vista más detallada de Google Se inhabilitarán los permisos de la cuenta para los IDs de cliente de OAuth creados antes del 2019. Sin efecto para los IDs de cliente de OAuth creados durante o después de 2019, ya que se habilitan permisos más detallados.
plugin_name string Opcional. Si se establece este valor, los nuevos IDs de cliente creados antes de julio del 29 de julio de 2022, se podrá usar la versión anterior de la Biblioteca de Google Platform. De forma predeterminada, los IDs de cliente recién creados ahora están bloqueados y no pueden usar la biblioteca de la plataforma y, en su lugar, debe usar la versión más reciente de Google Biblioteca de servicios. Puedes elegir cualquier valor, un nombre descriptivo como se recomienda 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 alcances 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 gapi.auth2.GoogleAuth.

GoogleAuth.isSignedIn.get()

Muestra si el usuario actual accedió.

Muestra
Booleano true si el usuario accedió o false si el el usuario salió o el objeto GoogleAuth no antes de que se inicialice.

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() pases true a esta función cuando el usuario acceda false cuando el usuario sale de su cuenta

GoogleAuth.signIn()

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

Muestra
Promesa Un Promise que se entrega con la instancia GoogleUser cuando la El usuario autentica y otorga los permisos solicitados, o los rechaza con un objeto. que contenga una propiedad error si ocurrió un error. Consulta la sección para los códigos de error.

Códigos de error

Consulta los GoogleAuth.signIn(options).

GoogleAuth.signIn(options)

Permite que el usuario acceda usando 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
Promesa Un Promise que se entrega con la instancia GoogleUser cuando la El usuario autentica y otorga los permisos solicitados, o los rechaza con un objeto. contener 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 denegó el permiso para acceder a los permisos necesarios.
immediate_failed
No se pudo seleccionar automáticamente ningún usuario sin solicitar el flujo de consentimiento. Se generó un error cuando usando signIn con la opción prompt: 'none'. Esta opción no debe debe usar, ya que gapi.auth2.init accederá automáticamente al usuario si a los que accediste en una sesión anterior.

gapi.auth2.SignInOptions

interfaz que representa los diferentes parámetros de configuración para el 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 de
    El servidor de autorización solicita el consentimiento del usuario antes de devolver información a la aplicación.
  • select_account de
    El servidor de autorización le solicita al usuario que seleccione una Cuenta de Google. Esta permite que un usuario que tiene varias cuentas seleccione una de las múltiples cuentas. para los que puede tener sesiones en curso.
  • none (no recomendado)
    El servidor de autorización no mostrará ninguna autenticación ni consentimiento del usuario pantallas; se mostrará un error si el usuario aún no está autenticado y no haya aceptado previamente los alcances solicitados.
    Dado que gapi.auth2.init permitirá que un usuario acceda automáticamente a la aplicación si ya accediste, llamar Por lo general, signIn({prompt: 'none'}) fallará.
scope string Los alcances a solicitar, como una cadena delimitada por espacios, sobre los alcances definidos en la Parámetros gapi.auth2.init Opcional si no se establece fetch_basic_profile como false.
ux_mode string 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 consentimiento de tu flujo de trabajo. El redirect_uri predeterminado es la URL actual sin consultas. parámetros y fragmento de hash.

GoogleAuth.signOut()

Sale de la cuenta actual de la aplicación.

Muestra
Promesa Una Promise que se entrega cuando se firma el usuario y sale de ella.

GoogleAuth.disconnect()

Revoca todos los permisos que otorgó el usuario.

GoogleAuth.grantOfflineAccess(options)

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

Argumentos
options Un gapi.auth2.OfflineAccessOptions que contiene pares clave-valor de parámetros. Por ejemplo: 
{
  scope: 'profile email'
}
Muestra
Promesa Es un Promise que se entrega cuando el usuario otorga el los permisos solicitados, pasar un objeto que contiene el código de autorización a el controlador de entregas 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 finalizar el flujo de consentimiento.
access_denied
El usuario denegó el permiso para acceder a los permisos necesarios.
immediate_failed
No se pudo seleccionar automáticamente ningún usuario sin solicitar el flujo de consentimiento. Se generó un error cuando usando signIn con la opción prompt: 'none'. Esta opción no debe debe usar, ya que gapi.auth2.init accederá automáticamente al usuario si a los que accediste en una sesión anterior.

gapi.auth2.OfflineAccessOptions

interfaz que representa los diferentes parámetros de configuración para el 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 de
    El servidor de autorización solicita el consentimiento del usuario antes de devolver información a la aplicación.
  • select_account de
    El servidor de autorización le solicita al usuario que seleccione una Cuenta de Google. Esta permite que un usuario que tiene varias cuentas seleccione una de las múltiples cuentas. para los que puede tener sesiones en curso.
scope string Los alcances a solicitar, como una cadena delimitada por espacios, sobre los alcances definidos en la Parámetros gapi.auth2.init Opcional si no se establece fetch_basic_profile como false.

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

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

Argumentos
container Es el ID del elemento div o una referencia al elemento al que se debe enviar. adjuntar el controlador de clics.
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 completa el acceso.
onfailure La función a la que se llamará si falla el acceso.

Usuarios

Un objeto GoogleUser representa una cuenta de usuario. Los objetos GoogleUser generalmente se obtienen llamando GoogleAuth.currentUser.get()

GoogleAuth.currentUser.get()

Muestra un objeto GoogleUser. que representa al usuario actual. Ten en cuenta que, en un entorno GoogleAuth, no se configuró el usuario actual. Usa el currentUser.listen() o GoogleAuth.then() para obtener una instancia de 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 un GoogleUser instancia en cada cambio que modifica currentUser.

GoogleUser.getId()

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

Muestra
String El ID único del usuario

GoogleUser.isSignedIn()

Muestra true si el usuario accedió.

Muestra
Booleano Verdadero si el usuario accedió

GoogleUser.getHostedDomain()

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

Muestra
String El dominio de G Suite del usuario

GoogleUser.getGrantedScopes()

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

Muestra
String Los permisos otorgados por el usuario

GoogleUser.getBasicProfile()

Obtén la información básica de 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 se debe mostrar siempre un token de acceso. de los permisos de acceso. 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 admite ningún permiso adicional. solicitado.
Muestra
gapi.auth2.AuthResponse Un objeto gapi.auth2.AuthResponse.

GoogleUser.reloadAuthResponse()

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

Muestra
Promise Un Promise que se completa con la recarga gapi.auth2.AuthResponse cuando vuelvas a cargar la El token de OAuth está listo.

gapi.auth2.AuthResponse

La respuesta que se muestra cuando se llama GoogleUser.getAuthResponse(includeAuthorizationData) o GoogleUser.reloadAuthResponse() .

Propiedades
access_token string El token de acceso otorgado.
id_token string El token de ID otorgado.
scope string Los permisos otorgados en el token de acceso.
expires_in number La cantidad de segundos que faltan hasta que el token de acceso caduque.
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 vencerá el token de acceso.

GoogleUser.hasGrantedScopes(scopes)

Muestra true si el usuario otorgó los alcances especificados.

Argumentos
scopes Una string de alcances delimitada por espacios.
Muestra
Booleano Verdadero si se otorgaron los permisos

GoogleUser.grant(options)

Solicita 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 permiso del usuario para acceder sin conexión a los permisos especificados.

Argumentos
options Un 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ó para la aplicación.

Elementos de la IU

gapi.signin2.render(id y options)

Renderiza un botón de acceso en el elemento con el ID proporcionado mediante la configuración que especifica el objeto options

Argumentos
id El ID del elemento en el que se renderizará el botón de acceso.
options 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 deben solicitar cuando el usuario accede (valor 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).
título largo Mostrar etiquetas largas, como "Acceder con Google" en lugar de "Acceder" (valor predeterminado: false). Cuando usas títulos largos, deberías aumentar el ancho del botón del valor predeterminado.
tema El tema de color del botón: light o dark (valor predeterminado: light)
onsuccess 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 (predeterminado: ninguno).
onfailure La función de devolución de llamada a la que se debe llamar cuando falla el acceso. Esta función no acepta argumentos (predeterminado: ninguno).

Avanzado

gapi.auth2.authorize(params y callback)

Realiza una autorización única de OAuth 2.0. Según los parámetros utilizados, se abrirá un al flujo de Acceso con Google o intenta cargar la respuesta solicitada en silencio, sin interacción del usuario.

Estos son algunos casos de uso 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 la 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 datos de configuración. Consulta gapi.auth2.AuthorizeConfig para el 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 gapi.auth2.AuthorizeResponse objeto una vez completada la solicitud (ya sea con éxito 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 requerido de Google, por ejemplo, debido a un en un entorno de nube. Una propiedad details brindará más información sobre el error generado.
popup_closed_by_user
El usuario cerró la ventana emergente antes de finalizar el flujo de acceso.
access_denied
El usuario denegó el permiso para acceder a los permisos necesarios.
immediate_failed
No se pudo seleccionar automáticamente ningún usuario sin solicitar el flujo de consentimiento. Se generó un error cuando usando signIn con la opción prompt: 'none'.

gapi.auth2.AuthorizeConfig

interfaz que representa los diferentes parámetros de configuración para el 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 APIs de Google.
scope string Obligatorio. Los alcances que se solicitarán, como una string delimitada por espacios.
response_type string Una lista de tipos de respuesta delimitados por espacios. La configuración predeterminada es 'permission'. Los 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 de
    El servidor de autorización solicita el consentimiento del usuario antes de devolver información a la aplicación.
  • select_account de
    El servidor de autorización le solicita al usuario que seleccione una Cuenta de Google. Esta permite que un usuario que tiene varias cuentas seleccione una de las múltiples cuentas. para los que puede tener sesiones en curso.
  • none de
    El servidor de autorización no mostrará ninguna autenticación ni consentimiento del usuario pantallas; se mostrará un error si el usuario aún no está autenticado y no haya dado su consentimiento anteriormente para los alcances solicitados.
    Si se solicita code como tipo de respuesta, el código que se muestra solo se se puede intercambiar por access_token, no por refresh_token.
cookie_policy string Los dominios para los que se crean las cookies de acceso. Ya sea un URI, single_host_origin o none. La configuración predeterminada es single_host_origin si no se especifica.
hosted_domain string El dominio de G Suite al que deben pertenecer los usuarios para acceder. Esto puede modificarse los clientes, así que asegúrate de verificar la propiedad de dominio alojado del usuario devuelto.
login_hint string El correo electrónico o ID de usuario de un usuario que se seleccionará de forma previa durante el flujo de acceso. Esto es susceptible de modificación por el usuario, a menos que se use prompt: "none".
include_granted_scopes boolean Si se debe solicitar un token de acceso que incluya todos los permisos otorgados anteriormente por el usuario a la app o solo a los permisos solicitados en la llamada actual. La configuración predeterminada es true.
enable_granular_consent boolean Opcional. Si se habilita o no detallado permisos. Si se establece en false, la vista más detallada de Google Se inhabilitarán los permisos de la cuenta para los IDs de cliente de OAuth creados antes del 2019. Sin efecto para los IDs de cliente de OAuth creados durante o después de 2019, ya que se habilitan permisos más detallados.
plugin_name string Opcional. Si se establece, los IDs de cliente creados antes del 29 de julio de 2022 podrán usar la Biblioteca de Google Platform. De forma predeterminada, los IDs de cliente creados recientemente se bloquean usar la biblioteca de la plataforma y, en su lugar, debe usar la versión más reciente de Identity Services. Puedes elegir cualquier valor, 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 de gapi.auth2.authorize.

Propiedades
access_token string El token de acceso otorgado. Solo está presente si se seleccionó permission o token especificadas en el response_type.
id_token string El token de ID otorgado. Solo está presente si se especificó id_token en el response_type
code string El código de autorización otorgado. Solo está presente si se especificó code en el response_type
scope string Los permisos otorgados en el token de acceso. Solo está presente si es permission o Se especificó token en el response_type.
expires_in number La cantidad de segundos que faltan hasta que el token de acceso caduque. Solo está presente si es permission o token en el 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 vencerá el token de acceso. Solo está presente si es permission o token en el response_type.
error string Cuando la solicitud falló, contiene los código de error.
error_subtype string Cuando la solicitud falla, también puede contener información adicional al código de error que se devuelven.