Referencia de cliente de JavaScript de inicio de sesión de Google

Esta referencia describe los métodos y atributos del cliente de JavaScript que utilizará para implementar el inicio de sesión de Google en sus aplicaciones web.

Si encuentra algún problema al usar la biblioteca, infórmelo a nuestro repositorio de GitHub .

Configuración de autenticación

Cargue la biblioteca de la plataforma de 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, cargue 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 . Debe llamar a este método antes de llamar a los métodos de gapi.auth2.GoogleAuth .

Cuando inicializa el objeto GoogleAuth , configura el objeto con su ID de cliente de OAuth 2.0 y cualquier opción adicional que desee especificar. Luego, si el usuario ya inició sesión, el objeto GoogleAuth restaura el estado de inicio de sesión del usuario de la sesión anterior.

Argumentos
params	Un objeto que contiene pares clave-valor de datos de configuración del cliente. Consulte gapi.auth2.ClientConfig para conocer las diferentes propiedades configurables. Por ejemplo: { client_id: 'CLIENT_ID.apps.googleusercontent.com' }

Devoluciones
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 , onError )

Llama a la función onInit cuando el objeto GoogleAuth está completamente inicializado. Si se genera un error durante la inicialización (esto puede suceder en navegadores antiguos no compatibles), se llamará a la función onError en su lugar.

Argumentos
onInit	La función llamada con el objeto GoogleAuth cuando está completamente inicializado.
onError	La función invocada con un objeto que contiene una propiedad de error , si GoogleAuth no se pudo inicializar.

Devoluciones
Promesa	Una Promise que se cumple cuando la función onInit se ha completado o se rechaza si se genera un error de inicialización. Se resuelve con el valor devuelto por la función onInit , si corresponde.

Advertencia: no llame a Promise.resolve() y similares con el resultado de gapi.auth2.init() . Como el objeto GoogleAuth devuelto implementa el método then() que se resuelve consigo mismo, creará una recursividad infinita.

Códigos de error

idpiframe_initialization_failed

No se pudo inicializar un iframe requerido de Google, por ejemplo, debido a un entorno no compatible. Una propiedad de details brindará 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	Requerido. El ID de cliente de la aplicación, encontrado y creado en Google Developers Console.
cookie_policy	string	Los dominios para los que crear cookies de inicio de sesión. Ya sea un URI, single_host_origin o none . El valor predeterminado es single_host_origin si no se especifica.
scope	string	Los ámbitos a solicitar, como una cadena delimitada por espacios. Opcional si fetch_basic_profile no se establece en falso.
fetch_basic_profile	boolean	Obtén la información básica del perfil de los usuarios cuando inician sesión. Agrega 'perfil', 'email' y 'openid' a los ámbitos solicitados. Verdadero si no se especifica.
hosted_domain	string	El dominio de G Suite al que los usuarios deben pertenecer para iniciar sesión. Esto es susceptible de modificación por parte de los clientes, así que asegúrese de verificar la propiedad del dominio alojado del usuario devuelto. Use GoogleUser.getHostedDomain() en el cliente y el reclamo hd en el token de ID en el servidor para verificar que el dominio es lo que esperaba. Debe solicitar el ámbito 'email' cuando utilice este parámetro junto con fetch_basic_profile: false .
ux_mode	string	El modo UX que se usará para el flujo de inicio de sesión. De forma predeterminada, abrirá el flujo de consentimiento en una ventana emergente. Los valores válidos son popup y redirect .
redirect_uri	string	Si usa ux_mode='redirect' , este parámetro le permite anular el redirect_uri predeterminado que se usará al final del flujo de consentimiento. El redirect_uri predeterminado es la URL actual sin parámetros de consulta ni fragmento 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 de Google Platform anterior. De forma predeterminada, los ID de cliente recién creados ahora no pueden usar la biblioteca de la plataforma y, en su lugar, deben usar la biblioteca más nueva de Google Identity Services. Puede 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'

Autenticación

GoogleAuth es una clase singleton que proporciona métodos que permiten al usuario iniciar sesión con una cuenta de Google, obtener el estado de inicio de sesión actual del usuario, obtener datos específicos del perfil de Google del usuario, solicitar ámbitos adicionales y cerrar sesión en la cuenta actual.

gapi.auth2.getAuthInstance()

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

Devoluciones
gapi.auth2.GoogleAuth	El objeto gapi.auth2.GoogleAuth . Utilice este objeto para llamar a los métodos de gapi.auth2.GoogleAuth .

GoogleAuth.esSignedIn.get()

Devuelve si el usuario actual ha iniciado sesión actualmente.

Devoluciones
booleano	true si el usuario ha iniciado sesión o false si el usuario no ha iniciado sesión o el objeto GoogleAuth no está inicializado.

GoogleAuth.isSignedIn.listen(oyente)

Escuche los cambios en el estado de inicio de sesión del usuario actual.

Argumentos
listener	Una función que toma un valor booleano. listen() pasa true a esta función cuando el usuario inicia sesión y false cuando el usuario cierra sesión.

GoogleAuth.iniciar sesión()

Inicia sesión en el usuario con las opciones especificadas para gapi.auth2.init() .

Devoluciones
Promesa	Una Promise que se cumple con la instancia de GoogleUser cuando el usuario se autentica correctamente y otorga los alcances solicitados, o se rechaza con un objeto que contiene una propiedad de error si se produce un error (consulte a continuación los códigos de error).

Códigos de error

Consulte GoogleAuth.signIn( options ) .

GoogleAuth.signIn ( options )

Inicia sesión en el usuario utilizando las opciones especificadas.

Argumentos

options

O: Un objeto gapi.auth2.SignInOptions que contiene pares clave-valor de parámetros de inicio de sesión. 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');

Devoluciones
Promesa	Una Promise que se cumple con la instancia de GoogleUser cuando el usuario se autentica correctamente y otorga los alcances solicitados, o se rechaza con un objeto que contiene una propiedad de error si se produce un error (consulte a continuación los códigos de error).

Códigos de error

popup_closed_by_user

El usuario cerró la ventana emergente antes de finalizar el flujo de inicio de sesión.

access_denied

El usuario denegó el permiso a los ámbitos requeridos.

immediate_failed

No se puede seleccionar automáticamente a ningún usuario sin solicitar el flujo de consentimiento. Se generó un error al usar el inicio de signIn con la opción prompt: 'none' . Esta opción no debería ser necesaria para usar, ya que gapi.auth2.init iniciará sesión automáticamente si el usuario inició sesión durante una sesión anterior.

gapi.auth2.SignInOptions

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

Parámetros
prompt	string	Fuerza un modo específico para el flujo de consentimiento. Opcional. Los valores posibles son: consent El servidor de autorización solicita al usuario su consentimiento antes de devolver información a la aplicación. select_account El servidor de autorización solicita al usuario que seleccione una cuenta de Google. Esto permite que un usuario que tiene múltiples cuentas seleccione entre las múltiples cuentas para las que puede tener sesiones actuales. none ( no recomendado ) El servidor de autorización no mostrará ninguna pantalla de autenticación o consentimiento del usuario; devolverá un error si el usuario aún no está autenticado y no ha dado su consentimiento previamente a los alcances solicitados. Como gapi.auth2.init iniciará automáticamente la sesión de un usuario en la aplicación si ha iniciado sesión anteriormente, llamar a signIn({prompt: 'none'}) generalmente fallará.
scope	string	Los ámbitos a solicitar, como una cadena delimitada por espacios, además de los ámbitos definidos en los gapi.auth2.init . Opcional si fetch_basic_profile no se establece en falso.
ux_mode	string	El modo UX que se usará para el flujo de inicio de sesión. De forma predeterminada, abrirá el flujo de consentimiento en una ventana emergente. Los valores válidos son popup y redirect .
redirect_uri	string	Si usa ux_mode='redirect' , este parámetro le permite anular el redirect_uri predeterminado que se usará al final del flujo de consentimiento. El redirect_uri predeterminado es la URL actual sin parámetros de consulta ni fragmento hash.

Autenticación de Google.cerrar sesión()

Cierra la cuenta actual de la aplicación.

Devoluciones
Promesa	Una Promise que se cumple cuando el usuario ha cerrado sesión.

GoogleAuth.desconectar()

Revoca todos los alcances que otorgó el usuario.

GoogleAuth.grantOfflineAccess ( options )

Obtenga permiso del usuario para acceder a los ámbitos especificados sin conexión.

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

Devoluciones
Promesa	Una Promise que se cumple cuando el usuario otorga los alcances solicitados, pasando un objeto que contiene el código de autorización al controlador de cumplimiento de la 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 a los ámbitos requeridos.

immediate_failed

No se puede seleccionar automáticamente a ningún usuario sin solicitar el flujo de consentimiento. Se generó un error al usar el inicio de signIn con la opción prompt: 'none' . Esta opción no debería ser necesaria para usar, ya que gapi.auth2.init iniciará sesión automáticamente si el usuario inició sesión durante una sesión anterior.

gapi.auth2.OfflineAccessOptions

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

Parámetros
prompt	string	Fuerza un modo específico para el flujo de consentimiento. Opcional. Los valores posibles son: consent El servidor de autorización solicita al usuario su consentimiento antes de devolver información a la aplicación. select_account El servidor de autorización solicita al usuario que seleccione una cuenta de Google. Esto permite que un usuario que tiene múltiples cuentas seleccione entre las múltiples cuentas para las que puede tener sesiones actuales. Tenga en cuenta que none no está disponible para el flujo de código sin conexión.
scope	string	Los ámbitos a solicitar, como una cadena delimitada por espacios, además de los ámbitos definidos en los gapi.auth2.init . Opcional si fetch_basic_profile no se establece en falso.

onsuccess ( container , options , en caso de éxito , en caso de onfailure )

Adjunta el flujo de inicio de sesión al controlador de clics del contenedor especificado.

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

Usuarios

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

GoogleAuth.usuarioactual.get()

Devuelve un objeto GoogleUser que representa al usuario actual. Tenga en cuenta que en una instancia de GoogleAuth recién inicializada, no se ha configurado el usuario actual. Utilice el método currentUser.listen() o GoogleAuth.then() para obtener una instancia GoogleAuth inicializada.

Devoluciones
GoogleUser	El usuario actual

GoogleAuth.currentUser.listen( listener )

Escuche los 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()

Obtenga la cadena de identificación única del usuario.

No utilice los ID de Google devueltos por getId() para comunicar el usuario actualmente conectado a su servidor backend. En su lugar, envíe tokens de identificación , que se pueden validar de forma segura en el servidor.

Devoluciones
Cuerda	La identificación única del usuario

GoogleUser.isSignedIn()

Devuelve verdadero si el usuario ha iniciado sesión.

Devoluciones
booleano	Verdadero si el usuario ha iniciado sesión

GoogleUser.getHostedDomain()

Obtenga el dominio de G Suite del usuario si el usuario inició sesión con una cuenta de G Suite.

Devoluciones
Cuerda	El dominio de G Suite del usuario

GoogleUser.getGrantedScopes()

Obtenga los ámbitos que el usuario otorgó como una cadena delimitada por espacios.

Devoluciones
Cuerda	Los alcances otorgados por el usuario

GoogleUser.getBasicProfile()

Obtenga la información básica del perfil del usuario.

No utilice la información de perfil del usuario para comunicar el usuario actualmente conectado a su servidor backend. En su lugar, envíe tokens de identificación , que se pueden validar de forma segura en el servidor.

Devoluciones
gapi.auth2.BasicProfile	Puede recuperar las propiedades de gapi.auth2.BasicProfile con los siguientes métodos: PerfilBásico.getId() PerfilBásico.getName() PerfilBásico.getGivenName() PerfilBásico.getFamilyName() PerfilBásico.getImageUrl() PerfilBásico.getEmail()

GoogleUser.getAuthResponse(includeAuthorizationData)

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

Argumentos
includeAuthorizationData	Opcional: un valor booleano que especifica si se devolverá siempre un token de acceso y ámbitos. De forma predeterminada, el token de acceso y los ámbitos solicitados no se devuelven cuando fetch_basic_profile es verdadero (el valor predeterminado) y no se solicitan ámbitos adicionales.

Devoluciones
gapi.auth2.AuthResponse	Un objeto gapi.auth2.AuthResponse .

GoogleUser.reloadAuthResponse()

Fuerza una actualización del token de acceso y luego devuelve una Promesa para la nueva AuthResponse.

Devoluciones
Promise	Se realiza una Promise que se cumple con el gapi.auth2.AuthResponse recargado al recargar el token de OAuth.

gapi.auth2.AuthResponse

La respuesta devuelta al llamar GoogleUser.getAuthResponse( includeAuthorizationData ) o GoogleUser.reloadAuthResponse() .

Propiedades
access_token	string	El token de acceso otorgado.
id_token	string	El token de identificación otorgado.
scope	string	Los alcances otorgados en el token de acceso.
expires_in	number	El número de segundos hasta que expire el token de acceso.
first_issued_at	number	La marca de tiempo en la que el usuario concedió por primera vez los ámbitos solicitados.
expires_at	number	La marca de tiempo en la que expirará el token de acceso.

GoogleUser.hasGrantedScopes( scopes )

Devuelve verdadero si el usuario otorgó los ámbitos especificados.

Argumentos
scopes	Una cadena de ámbitos delimitada por espacios.

Devoluciones
booleano	True si se concedieron los ámbitos

GoogleUser.grant ( options )

Solicitar alcances adicionales al usuario.

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

GoogleUser.grantOfflineAccess ( options )

Obtenga permiso del usuario para acceder a los ámbitos especificados sin conexión.

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

GoogleUser.desconectar()

Revoca todos los alcances que el usuario otorgó para la aplicación.

elementos de la interfaz de usuario

gapi.signin2.render( id , options )

Representa un botón de inicio de sesión en el elemento con el ID dado, usando la configuración especificada por el objeto de options .

Argumentos
id	El ID del elemento en el que se representará el botón de inicio de sesión.
options	Un objeto que contiene la configuración que se usará para representar el botón. Por ejemplo: { scope: 'email', width: 200, height: 50, longtitle: true, theme: 'dark', onsuccess: handleSuccess, onfailure: handleFailure } Puede especificar las siguientes opciones: Parámetros alcance Los ámbitos que se solicitarán cuando el usuario inicie sesión (predeterminado: profile ). ancho El ancho del botón en píxeles (predeterminado: 120 ). altura La altura del botón en píxeles (predeterminado: 36 ). título largo Muestre etiquetas largas como "Iniciar sesión con Google" en lugar de "Iniciar sesión" (predeterminado: false ). Cuando usa títulos largos, debe aumentar el ancho del botón desde su valor predeterminado. temática El tema de color del botón: light u dark (predeterminado: light ). sobre el exito La función de devolución de llamada para llamar cuando un usuario inicia sesión correctamente. Esta función debe tomar un argumento: una instancia de gapi.auth2.GoogleUser (predeterminado: ninguno). en caso de falla La función de devolución de llamada para llamar cuando falla el inicio de sesión. Esta función no acepta argumentos (predeterminado: ninguno).

Avanzado

Advertencia: esta sección cubre funciones que no se recomiendan para la mayoría de los casos de uso. Asegúrese de que los métodos descritos en las Guías no funcionen para su caso de uso antes de usar dichas funciones.

gapi.auth2.authorize( params , callback de llamada)

Realiza una autorización única de OAuth 2.0. Según los parámetros utilizados, esto abrirá una ventana emergente en el flujo de inicio de sesión de Google o intentará cargar la respuesta solicitada en silencio, sin interacción del usuario.

Algunos casos de uso donde este método es útil incluyen:

• Su aplicación solo necesita 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 inicia sesión.
• Su aplicación tiene su propia infraestructura de administración de sesiones y solo requiere el token de identificación una vez para identificar al usuario en su backend.
• Se utilizan varios ID de cliente dentro de la misma página.

Advertencia: no utilice este método junto con el gapi.auth2.init y el flujo signIn de sesión recomendados. Estos son dos comportamientos distintos (Autorización para gapi.auth2.authorize frente a Autenticación para gapi.auth2.init/signIn ) y tendrán problemas inesperados si se usan dentro de la misma aplicación.

Argumentos
params	Un objeto que contiene pares clave-valor de datos de configuración. Consulte gapi.auth2.AuthorizeConfig para conocer 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 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 entorno no compatible. Una propiedad de 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 inicio de sesión.

access_denied

El usuario denegó el permiso a los ámbitos requeridos.

immediate_failed

No se puede seleccionar automáticamente a ningún usuario sin solicitar el flujo de consentimiento. Se generó un error al usar el inicio de 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	Requerido El ID de cliente de la aplicación, encontrado y creado en Google Developers Console.
scope	string	Requerido Los ámbitos a solicitar, como una cadena delimitada por espacios.
response_type	string	Una lista de tipos de respuesta delimitados por espacios. El valor predeterminado es 'permission' . Los valores posibles son: id_token , para recuperar un token de identificación 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: consent El servidor de autorización solicita al usuario su consentimiento antes de devolver información a la aplicación. select_account El servidor de autorización solicita al usuario que seleccione una cuenta de Google. Esto permite que un usuario que tiene múltiples cuentas seleccione entre las múltiples cuentas para las que puede tener sesiones actuales. none El servidor de autorización no mostrará ninguna pantalla de autenticación o consentimiento del usuario; devolverá un error si el usuario aún no está autenticado y no ha dado su consentimiento previamente a los alcances solicitados. Si se solicita code como tipo de respuesta, el código devuelto solo se podrá canjear por un access_token de acceso, no por un refresh_token de actualización. Nota: bajo el capó, la biblioteca almacena en caché y actualiza automáticamente el último token de acceso obtenido. Cuando se usa prompt: 'none' , la mayoría de las veces, no será necesaria ninguna solicitud HTTP al backend para obtener un token válido.
cookie_policy	string	Los dominios para los que crear cookies de inicio de sesión. Ya sea un URI, single_host_origin o none . El valor predeterminado es single_host_origin si no se especifica.
hosted_domain	string	El dominio de G Suite al que los usuarios deben pertenecer para iniciar sesión. Esto es susceptible de modificación por parte de los clientes, así que asegúrese de verificar la propiedad del dominio alojado del usuario devuelto.
login_hint	string	El correo electrónico, o ID de usuario, de un usuario para preseleccionarlo en el flujo de inicio de sesión. Este es susceptible de modificación por parte del usuario, salvo que se utilice prompt: "none" .
include_granted_scopes	boolean	Si solicitar un token de acceso que incluya todos los alcances otorgados previamente por el usuario a la aplicación, o solo los alcances solicitados en la llamada actual. El valor predeterminado es true .
plugin_name	string	Opcional. Si se establece, 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 nueva de Google Identity Services. Puede 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 volvió a la devolución de llamada del método gapi.auth2.authorize .

Propiedades
access_token	string	El token de acceso otorgado. Solo presente si se especificó permission o token en el tipo de response_type .
id_token	string	El token de identificación otorgado. Solo presente si se especificó id_token en el tipo de response_type .
code	string	El Código de Autorización otorgado. Solo presente si code se especificó en el tipo de response_type .
scope	string	Los alcances otorgados en el token de acceso. Solo presente si se especificó permission o token en el tipo de response_type .
expires_in	number	El número de segundos hasta que expire el token de acceso. Solo presente si se especificó permission o token en el tipo de response_type .
first_issued_at	number	La marca de tiempo en la que el usuario concedió por primera vez los ámbitos solicitados. Solo presente si se especificó permission o token en el tipo de response_type .
expires_at	number	La marca de tiempo en la que expirará el token de acceso. Solo presente si se especificó permission o token en el tipo de response_type .
error	string	Cuando la solicitud falló, contiene el código de error .
error_subtype	string	Cuando la solicitud falló, esto puede contener información adicional al código de error también devuelto.