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 tienes algún problema cuando usas la biblioteca, infórmalo en 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 conocer las diferentes propiedades configurables. Por ejemplo: { client_id: 'CLIENT_ID.apps.googleusercontent.com' }. |
Devuelve | |
---|---|
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
se inicializa
por completo. 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 llamó con el objeto GoogleAuth cuando se inicializó por completo.
|
onError |
La función a la que se llamó con un objeto que contiene una propiedad error , si GoogleAuth no se pudo inicializar.
|
Devuelve | |
---|---|
Promesa | Una Promise que se completa cuando se completa la función onInit, o que se rechaza si se genera un error de inicialización. Se resuelve con el valor mostrado 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 un entorno
no compatible. 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 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 APIs de Google. |
cookie_policy |
string |
Los dominios para los que se crean las cookies de acceso. Un URI, single_host_origin o none . Si no se especifica, el valor predeterminado es single_host_origin . |
scope |
string |
Los alcances que se solicitarán, como una string delimitada por espacios. Es 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 acceden. 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. Esto puede ser modificado por los clientes, por lo que debes asegurarte de verificar la propiedad de dominio alojado del usuario que se mostró. Usa GoogleUser.getHostedDomain() en el cliente y la reclamación hd en el token de ID del servidor para verificar que el dominio es el esperado.
|
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 |
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 parámetros de consulta ni fragmentos de hash.
|
enable_granular_consent |
boolean |
Opcional. Establece si se deben habilitar los permisos detallados. Si se establece como 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 hay efecto para los IDs de cliente de OAuth creados durante 2019 o después de esa fecha, ya que siempre se habilitan permisos más detallados para ellos.
|
plugin_name |
string |
Opcional. Si se establece este valor, los nuevos IDs de cliente creados antes del 29
de julio de 2022 podrán usar la biblioteca de Google Platform anterior.
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, deben usar la biblioteca más reciente de Google Identity Services. Puedes elegir cualquier valor; se recomienda usar un nombre descriptivo, como
el de producto o 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.
Devuelve | |
---|---|
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ó.
Devuelve | |
---|---|
Booleano |
true si el usuario ya accedió o false si 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 sale de su cuenta.
|
GoogleAuth.signIn()
Permite que el usuario acceda con las opciones especificadas para gapi.auth2.init()
.
Devuelve | |
---|---|
Promesa | Una Promise que se entrega con la instancia de GoogleUser cuando el usuario se autentica y otorga de forma correcta 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 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:
|
Devuelve | |
---|---|
Promesa | Una Promise que se entrega con la instancia de GoogleUser cuando el usuario se autentica y otorga 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 finalizar el flujo de acceso.
access_denied
- El usuario rechazó el permiso a los permisos necesarios.
immediate_failed
-
No se pudo seleccionar automáticamente ningún usuario sin solicitar el flujo de consentimiento. Se genera un error cuando se usa
signIn
con la opciónprompt: 'none'
. No es necesario usar esta opción, ya quegapi.auth2.init
hará que el usuario acceda automáticamente si accedió anteriormente durante una sesión anterior.
gapi.auth2.SignInOptions
Interfaz que representa los diferentes parámetros de configuración para el 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:
|
scope |
string |
Los permisos que se solicitarán, 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 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 parámetros de consulta ni fragmentos de hash.
|
GoogleAuth.signOut()
Sale de la cuenta actual de la aplicación.
Devuelve | |
---|---|
Promesa | Una Promise que se entrega cuando el usuario sale de su cuenta. |
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 objeto gapi.auth2.OfflineAccessOptions que contiene pares clave-valor de parámetros. Por ejemplo: { scope: 'profile email' } |
Devuelve | |
---|---|
Promesa | Una Promise que se completa cuando el usuario otorga los permisos solicitados y pasa un objeto que contiene el código de autorización al 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 rechazó el permiso a los permisos necesarios.
immediate_failed
-
No se pudo seleccionar automáticamente ningún usuario sin solicitar el flujo de consentimiento. Se genera un error cuando se usa
signIn
con la opciónprompt: 'none'
. No debería ser obligatorio usar esta opción, ya quegapi.auth2.init
hará que el usuario acceda automáticamente si accedió anteriormente durante una sesión anterior.
gapi.auth2.OfflineAccessOptions
Interfaz que representa los diferentes parámetros de configuración para el 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:
|
scope |
string |
Los permisos que se solicitarán, 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)
Adjunta el flujo de acceso al controlador de clics del contenedor especificado.
Argumentos | |
---|---|
container | Es el ID o una referencia del elemento div al que se adjunta 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 a GoogleAuth.currentUser.get().
GoogleAuth.currentUser.get()
Muestra un objeto GoogleUser
que representa al usuario actual. Ten en cuenta que, en una instancia GoogleAuth
recién inicializada, no se configuró el usuario actual. Usa el método currentUser.listen()
o GoogleAuth.then()
para obtener una instancia de GoogleAuth
inicializada.
Devuelve | |
---|---|
GoogleUser |
El usuario actual |
GoogleAuth.currentUser.listen(listener)
Detecta cambios en currentUser.
Argumentos | |
---|---|
listener |
Una función que toma un parámetro GoogleUser
listen le pasa a esta función una instancia de GoogleUser en cada cambio que modifique currentUser .
|
GoogleUser.getId()
Obtén la cadena del ID único del usuario.
Devuelve | |
---|---|
String | El ID único del usuario |
GoogleUser.isSignedIn()
Muestra true si el usuario accedió.
Devuelve | |
---|---|
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.
Devuelve | |
---|---|
String | El dominio de G Suite del usuario |
GoogleUser.getGrantedScopes()
Obtén los permisos que el usuario otorgó como una string delimitada por espacios.
Devuelve | |
---|---|
String | Los permisos otorgados por el usuario |
GoogleUser.getBasicProfile()
Obtén la información básica de perfil del usuario.
Devuelve | |
---|---|
gapi.auth2.BasicProfile |
Puedes recuperar las propiedades de gapi.auth2.BasicProfile con los siguientes métodos:
|
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 deben mostrar siempre 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 permisos adicionales. |
Devuelve | |
---|---|
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.
Devuelve | |
---|---|
Promise |
Una Promise que se entrega con el gapi.auth2.AuthResponse recargado cuando se vuelve a cargar el token de OAuth.
|
gapi.auth2.AuthResponse
Es la respuesta que se muestra cuando se llama a los métodos 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. |
Devuelve | |
---|---|
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 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ó 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 determinado mediante la configuración especificada por 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:
|
Avanzado
gapi.auth2.authorize(params y callback)
Realiza una autorización única de OAuth 2.0. Según los parámetros utilizados, se abrirá una ventana emergente en el flujo de Acceso con 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 necesita solicitar un extremo de la 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 datos de configuración. Consulta 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 a la que se llama con un objeto gapi.auth2.AuthorizeResponse después de que se completó 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
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 rechazó el permiso a los permisos necesarios.
immediate_failed
-
No se pudo seleccionar automáticamente ningún usuario sin solicitar el flujo de consentimiento. Se genera un error cuando se usa
signIn
con la opciónprompt: 'none'
.
gapi.auth2.AuthorizeConfig
Interfaz que representa los diferentes parámetros de configuración para el 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 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 valores posibles son los siguientes:
|
prompt |
string |
Fuerza un modo específico para el flujo de consentimiento. Los valores posibles son los siguientes:
|
cookie_policy |
string |
Los dominios para los que se crean las cookies de acceso. Un URI, single_host_origin o none . Si no se especifica, el valor predeterminado es single_host_origin .
|
hosted_domain |
string |
El dominio de G Suite al que deben pertenecer los usuarios para acceder. Los clientes pueden modificar esta configuración, por lo que debes asegurarte de verificar la propiedad del dominio alojado del usuario que se mostró. |
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. El usuario puede modificarla, 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 los permisos solicitados en la llamada actual. La configuración predeterminada es true .
|
enable_granular_consent |
boolean |
Opcional. Establece si se deben habilitar los permisos detallados. Si se establece como 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 hay efecto para los IDs de cliente de OAuth creados durante 2019 o después de esa fecha, 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 recién creados 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 usar un nombre descriptivo, como el de producto o complemento, para facilitar la identificación.
Ejemplo: plugin_name: 'YOUR_STRING_HERE'
|
gapi.auth2.AuthorizeResponse
Es la respuesta que se muestra a la devolución de llamada del método gapi.auth2.authorize
.
Propiedades | ||
---|---|---|
access_token |
string |
El token de acceso otorgado. Solo está presente si se especificó permission o token 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 se especificó permission o 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 se especificó 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 el 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 el 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 que también se muestra. |