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 para usar 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
, lo configuras con tu ID de cliente de OAuth 2.0 y cualquier opción adicional que desees especificar. Luego, si el usuario ya accedió, el objeto GoogleAuth
restablece su estado de acceso de la sesión anterior.
Argumentos | |
---|---|
params |
Un objeto que contiene pares clave-valor de los datos de configuración del cliente. Consulta gapi.auth2.ClientConfig para ver las diferentes propiedades que se pueden configurar. 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 produce 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 a la que se llamó con el objeto GoogleAuth cuando se inicializa por completo.
|
onError |
La función a la que se llamó con un objeto que contiene una propiedad error , si no se pudo inicializar GoogleAuth
|
Devuelve | |
---|---|
Promesa | Un Promise que se entrega cuando la función onInit se completa, o que se rechaza si se produjo un error de inicialización. Se resuelve con el valor que muestra la función onInit, si corresponde. |
Códigos de error
idpiframe_initialization_failed
-
No se pudo inicializar un iframe obligatorio de Google, por ejemplo, debido a un entorno
no compatible. Una propiedad
details
proporcionará más información sobre el error 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 creó en Google Developers Console. |
cookie_policy |
string |
Los dominios para los que se crean las cookies de acceso. Es un URI, single_host_origin o none . El valor predeterminado es single_host_origin si no se especifica. |
scope |
string |
Los alcances que se solicitarán, como una string delimitada por espacios. Es opcional si fetch_basic_profile no se configura 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 |
Es el dominio de G Suite al que deben pertenecer los usuarios para acceder. Los clientes pueden modificar esto, por lo que debes asegurarte de verificar la propiedad de dominio alojada del usuario que se muestra. Usa GoogleUser.getHostedDomain() en el cliente y la reclamación hd en el token de ID del servidor para verificar que el dominio sea lo que esperabas.
|
ux_mode |
string |
El modo de UX que se usa para el flujo de acceso. De forma predeterminada, se abrirá el flujo de consentimiento
en una ventana emergente. Los valores válidos son popup y redirect . |
redirect_uri |
string |
Si usas ux_mode='redirect' , este parámetro te permite anular 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 de hash.
|
enable_granular_consent |
boolean |
Opcional. Indica si se deben habilitar permisos detallados. Si se configura 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 se produce ningún efecto para los IDs de cliente de OAuth creados durante el 2019 o después de este, ya que siempre se habilitan permisos más detallados para ellos.
|
plugin_name |
string |
Opcional. Si se establece este valor, los IDs de cliente nuevos creados antes del 29
de julio de 2022 pueden usar la biblioteca de Google Platform anterior.
De forma predeterminada, los IDs de cliente recién creados ahora tienen bloqueado el uso de la biblioteca de la plataforma y, en su lugar, deben usar la biblioteca de Google Identity Services más reciente. Puedes elegir cualquier valor; para facilitar su identificación, se recomienda un nombre descriptivo, como el nombre del producto o del complemento.
Ejemplo: plugin_name: 'YOUR_STRING_HERE'
|
Proporción de eficiencia energética (EER)
GoogleAuth
es una clase singleton que proporciona métodos para permitir que el usuario acceda con una Cuenta de Google, obtenga el estado de acceso actual del usuario, obtenga datos específicos de su perfil de Google, solicite permisos 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 accedió, o false si el usuario salió de la cuenta o no se inicializa el objeto GoogleAuth .
|
GoogleAuth.isSignedIn.listen(listener)
Detecta cambios en el estado de acceso del usuario actual.
Argumentos | |
---|---|
listener |
Función que toma un valor booleano. listen() pasa
true a esta función cuando el usuario accede y
false cuando sale de la cuenta.
|
GoogleAuth.signIn()
Permite que el usuario acceda con las opciones especificadas como gapi.auth2.init()
.
Devuelve | |
---|---|
Promesa | Un Promise que se entrega con la instancia GoogleUser cuando el usuario se autentica y otorga correctamente los permisos solicitados, o se rechaza con un objeto que contiene una propiedad error si se produce un error (consulta los códigos de error a continuación). |
Códigos de error
Consulta los GoogleAuth.signIn(options)
.
GoogleAuth.signIn(options)
Permite que el usuario acceda con las opciones especificadas.
Argumentos | |
---|---|
options |
Puede deberse a una de estas opciones:
|
Devuelve | |
---|---|
Promesa | Un Promise que se entrega con la instancia GoogleUser cuando el usuario se autentica y otorga correctamente los permisos solicitados, o se rechaza con un objeto que contiene una propiedad error si se produce 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 proceso de acceso.
access_denied
- El usuario rechazó los permisos necesarios.
immediate_failed
-
No se pudo seleccionar automáticamente ningún usuario sin solicitar el flujo de consentimiento. Se produjo un error cuando se usaba
signIn
con la opciónprompt: 'none'
. No es 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.SignInOptions
Interfaz que representa los diferentes parámetros de configuración del método GoogleAuth.signIn(options)
.
Parámetros | ||
---|---|---|
prompt |
string |
Fuerza un modo específico para el flujo de consentimiento. Opcional. Estos son los valores posibles:
|
scope |
string |
Los alcances que se solicitarán, como una string delimitada por espacios, además de los alcances definidos en los parámetros gapi.auth2.init . Es opcional si fetch_basic_profile no se configura como falso.
|
ux_mode |
string |
El modo de UX que se usa para el flujo de acceso. De forma predeterminada, se abrirá el flujo de consentimiento
en una ventana emergente. Los valores válidos son popup y redirect . |
redirect_uri |
string |
Si usas ux_mode='redirect' , este parámetro te permite anular el redirect_uri predeterminado que se usará al final del flujo de consentimiento. El valor predeterminado redirect_uri es la URL actual sin parámetros de consulta ni fragmento de hash.
|
GoogleAuth.signOut()
Cierra la sesión de la cuenta actual en la aplicación.
Devuelve | |
---|---|
Promesa | Un Promise que se entrega cuando el usuario sale de su cuenta. |
GoogleAuth.disconnect()
Revoca todos los permisos que el usuario otorgó.
GoogleAuth.grantOfflineAccess(options)
Obtén permiso del usuario para acceder a los permisos especificados sin conexión.
Argumentos | |
---|---|
options |
Un objeto gapi.auth2.OfflineAccessOptions que contiene pares clave-valor de parámetros. Por ejemplo: { scope: 'profile email' } |
Devuelve | |
---|---|
Promesa | Un Promise que se entrega cuando el usuario otorga los permisos solicitados y pasa un objeto que contiene el código de autorización al controlador de entregas 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ó los permisos necesarios.
immediate_failed
-
No se pudo seleccionar automáticamente ningún usuario sin solicitar el flujo de consentimiento. Se produjo un error cuando se usaba
signIn
con la opciónprompt: 'none'
. No es 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 del método GoogleAuth.grantOfflineAccess(options)
Parámetros | ||
---|---|---|
prompt |
string |
Fuerza un modo específico para el flujo de consentimiento. Opcional. Estos son los valores posibles:
|
scope |
string |
Los alcances que se solicitarán, como una string delimitada por espacios, además de los alcances definidos en los parámetros gapi.auth2.init . Es opcional si fetch_basic_profile no se configura como falso.
|
GoogleAuth.attachClickHandler(container, options, onsuccess, onfailure)
Adjunta el flujo de acceso al controlador de clics del contenedor especificado.
Argumentos | |
---|---|
container | El ID o una referencia al 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 llama si falla el acceso. |
Usuarios
Un objeto GoogleUser
representa una cuenta de usuario.
Los objetos GoogleUser
se suelen obtener llamando a GoogleAuth.currentUser.get().
GoogleAuth.currentUser.get()
Muestra un objeto GoogleUser
que representa al usuario actual. Ten en cuenta que, en una instancia de GoogleAuth
recién inicializada, no se 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 pasa a esta función una instancia de GoogleUser en cada cambio que modifica currentUser .
|
GoogleUser.getId()
Obtén la cadena de ID único del usuario.
Devuelve | |
---|---|
String | El ID único del usuario |
GoogleUser.isSignedIn()
Muestra el valor true si el usuario accedió.
Devuelve | |
---|---|
Booleano | Es 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 del 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: Un valor booleano que especifica si siempre se debe mostrar un token de acceso y permisos. Según la configuración predeterminada, no se muestran el token de acceso ni los permisos solicitados 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 nueva AuthResponse.
Devuelve | |
---|---|
Promise |
Se completó un Promise que se entrega con el gapi.auth2.AuthResponse que se volvió a cargar 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 |
Es la cantidad de segundos que faltan para que venza el token de acceso. |
first_issued_at |
number |
La marca de tiempo en la que el usuario otorgó los permisos solicitados por primera vez. |
expires_at |
number |
La marca de tiempo en la que vencerá el token de acceso. |
UsuariodeGoogle.hasGrantedScopes(scopes)
Muestra el valor true si el usuario otorgó los permisos especificados.
Argumentos | |
---|---|
scopes | Una string de permisos delimitada por espacios. |
Devuelve | |
---|---|
Booleano | Verdadero si se otorgaron los permisos |
GoogleUser.grant(options)
Solicitar 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 a los permisos especificados sin conexión.
Argumentos | |
---|---|
options |
Un objeto gapi.auth2.OfflineAccessOptions que contiene pares clave-valor de parámetros. Por ejemplo: { scope: 'profile email' } |
GoogleUser.disconnect()
Revoca todos los alcances que el usuario otorgó para la aplicación.
Elementos de la IU
gapi.signin2.render(id, options)
Renderiza un botón de acceso en el elemento con el ID determinado 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:
|
Avanzado
gapi.auth2.authorize(params, callback)
Realiza una autorización de OAuth 2.0 única. Según los parámetros que se usen, se abrirá una ventana emergente en el flujo de Acceso con Google o se intentará cargar la respuesta solicitada de forma silenciosa, sin interacción del usuario.
Estos son algunos casos de uso en los que resulta útil este método:
- 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 IDs de cliente dentro de la misma página.
Argumentos | |
---|---|
params |
Un objeto que contiene pares clave-valor de datos de configuración. Consulta gapi.auth2.AuthorizeConfig para ver las diferentes propiedades que se pueden configurar. 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 completa la solicitud (ya sea de forma correcta o con un error).
|
Ejemplo
gapi.auth2.authorize({
client_id: 'CLIENT_ID.apps.googleusercontent.com',
scope: 'email profile openid',
response_type: 'id_token permission'
}, function(response) {
if (response.error) {
// An error happened!
return;
}
// The user authorized the application for the scopes requested.
var accessToken = response.access_token;
var idToken = response.id_token;
// You can also now use gapi.client to perform authenticated requests.
});
Códigos de error
idpiframe_initialization_failed
-
No se pudo inicializar un iframe obligatorio de Google, por ejemplo, debido a un entorno
no compatible. Una propiedad
details
proporcionará más información sobre el error generado. popup_closed_by_user
- El usuario cerró la ventana emergente antes de finalizar el proceso de acceso.
access_denied
- El usuario rechazó los permisos necesarios.
immediate_failed
-
No se pudo seleccionar automáticamente ningún usuario sin solicitar el flujo de consentimiento. Se produjo un error cuando se usaba
signIn
con la opciónprompt: 'none'
.
gapi.auth2.AuthorizeConfig
Interfaz que representa los diferentes parámetros de configuración del método gapi.auth2.authorize
.
Propiedades | ||
---|---|---|
client_id |
string |
Obligatorio: El ID de cliente de la app, que se encuentra y se creó en Google Developers Console. |
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. Es un URI, single_host_origin o none . El valor predeterminado es single_host_origin si no se especifica.
|
hosted_domain |
string |
Es el dominio de G Suite al que deben pertenecer los usuarios para acceder. Los clientes pueden modificar esto, por lo que debes asegurarte de verificar la propiedad de dominio alojada del usuario que se muestra. |
login_hint |
string |
El correo electrónico, o ID de usuario, de un usuario que se preselecciona en el flujo de acceso. El usuario puede modificar esto, a menos que se use prompt: "none" .
|
include_granted_scopes |
boolean |
Indica si se debe solicitar un token de acceso que incluya todos los permisos que el usuario otorgó a la app con anterioridad o solo los permisos solicitados en la llamada actual. La configuración predeterminada es true .
|
enable_granular_consent |
boolean |
Opcional. Indica si se deben habilitar permisos detallados. Si se configura 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 se produce ningún efecto para los IDs de cliente de OAuth creados durante el 2019 o después de este, ya que siempre se habilitan permisos más detallados para ellos.
|
plugin_name |
string |
Opcional. Si se configura, 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 Platform y, en su lugar, deben usar la biblioteca de Google Identity Services más reciente. Puedes elegir cualquier valor; se recomienda un nombre descriptivo, como el nombre del producto o del complemento, para facilitar su 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 response_type .
|
id_token |
string |
El token de ID otorgado. Solo está presente si se especificó id_token en response_type .
|
code |
string |
El código de autorización otorgado. Solo está presente si se especificó code en response_type .
|
scope |
string |
Los permisos otorgados en el token de acceso Solo está presente si se especificó permission o token en response_type .
|
expires_in |
number |
Es la cantidad de segundos que faltan para que venza el token de acceso. Solo está presente si se especificó permission o token en response_type .
|
first_issued_at |
number |
La marca de tiempo en la que el usuario otorgó los permisos solicitados por primera vez. 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 se especificó permission o token en response_type .
|
error |
string |
Cuando falló la solicitud, este contiene el código de error. |
error_subtype |
string |
Cuando la solicitud falla, puede contener información adicional del código de error que también se mostró. |