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:
|
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ónprompt: 'none'
. Esta opción no debe debe usar, ya quegapi.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:
|
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ónprompt: 'none'
. Esta opción no debe debe usar, ya quegapi.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:
|
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:
|
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 }
|
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ónprompt: '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:
|
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. 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. |