Esta referencia describe los métodos y atributos del cliente 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 OAuth 2.0 y cualquier opción adicional que desee especificar. Luego, si el usuario ya ha GoogleAuth
, 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 . Utilice el método then () para obtener una Promesa que se resuelva cuando el objeto gapi.auth2.GoogleAuth termine de inicializarse. |
GoogleAuth.then ( onInit , onError )
Llama a la función onInit cuando el objeto GoogleAuth
está completamente inicializado. Si se onError un error durante la inicialización (esto puede suceder en navegadores antiguos no compatibles), se onError función onError su lugar.
Argumentos | |
---|---|
onInit | La función llamada con el objeto GoogleAuth cuando está completamente inicializado. |
onError | La función llamada con un objeto que contiene una propiedad de error , si GoogleAuth no se pudo inicializar. |
Devoluciones | |
---|---|
Promesa | Promise que se cumple cuando se completa la función onInit o se rechaza si se onInit un error de inicialización. Se resuelve con el valor devuelto por 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 de
details
dará 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 | Obtiene la información de perfil básica de los usuarios cuando inician sesión. Agrega 'perfil', 'correo electrónico' y 'openid' a los ámbitos solicitados. Verdadero si no se especifica. |
hosted_domain | string | El dominio de G Suite al que deben pertenecer los usuarios 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 el que esperaba. |
ux_mode | string | El modo UX que se utilizará 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 despojada de los parámetros de consulta y el fragmento hash. |
Autenticación
GoogleAuth
es una clase singleton que proporciona métodos para permitir al usuario GoogleAuth
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.isSignedIn.get ()
Devuelve si el usuario actual está conectado actualmente.
Devoluciones | |
---|---|
Booleano | true si el usuario ha GoogleAuth , o false si el usuario ha GoogleAuth la GoogleAuth 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 false y false cuando el usuario cierra la sesión. |
GoogleAuth.signIn ()
gapi.auth2.init()
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 y otorga los alcances solicitados correctamente, o se rechaza con un objeto que contiene una propiedad de error si se GoogleUser un error (consulte los códigos de error a continuación). |
Códigos de error
Consulte GoogleAuth.signIn( options )
.
GoogleAuth.signIn ( options )
Firma en el usuario usando las opciones especificadas.
Argumentos | |
---|---|
options | Ya sea:


Devoluciones | |
---|---|
Promesa | Una Promise que se cumple con la instancia de GoogleUser cuando el usuario se autentica y otorga los alcances solicitados correctamente, o se rechaza con un objeto que contiene una propiedad de error si se GoogleUser un error (consulte 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 inicio de sesión.
-
access_denied
- El usuario denegó el permiso para los ámbitos requeridos.
-
immediate_failed
- Ningún usuario podría ser seleccionado automáticamente sin solicitar el flujo de consentimiento. Se produjo un error al usar el
signIn
con elprompt: 'none'
opciónprompt: 'none'
. Esta opción no debería ser necesaria para su uso, ya quegapi.auth2.init
iniciará sesión automáticamente en el usuario si se registró previamente 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 posibles valores son:


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 utilizará 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 despojada de los parámetros de consulta y el fragmento hash. |
GoogleAuth.signOut ()
Cierra la cuenta corriente de la aplicación.
Devoluciones | |
---|---|
Promesa | Una Promise que se cumple cuando se cierra la sesión del usuario. |
GoogleAuth.disconnect ()
Revoca todos los ámbitos 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 manejador 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 para los ámbitos requeridos.
-
immediate_failed
- Ningún usuario podría ser seleccionado automáticamente sin solicitar el flujo de consentimiento. Se produjo un error al usar el
signIn
con elprompt: 'none'
opciónprompt: 'none'
. Esta opción no debería ser necesaria para su uso, ya quegapi.auth2.init
iniciará sesión automáticamente en el usuario si se registró previamente 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 posibles valores son:


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. |
GoogleAuth.attachClickHandler ( container , options , en caso de onsuccess , 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 clic. |
options | 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 la que se debe llamar si falla el inicio de sesión. |
Usuarios
Un objeto GoogleUser
representa una cuenta de usuario. GoogleUser
objetos GoogleUser
se obtienen normalmente llamando a GoogleAuth.currentUser.get () .
GoogleAuth.currentUser.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 de 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 esta función a una instancia de GoogleUser en cada cambio que modifica currentUser . |
GoogleUser.getId ()
Obtenga la cadena de identificación única del usuario.
Devoluciones | |
---|---|
Cuerda | La identificación única del usuario |
GoogleUser.isSignedIn ()
Devuelve verdadero si el usuario inició sesión.
Devoluciones | |
---|---|
Booleano | Verdadero si el usuario ha iniciado sesión |
GoogleUser.getHostedDomain ()
Obtén 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 alcances 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.
Devoluciones | |
---|---|
gapi.auth2.BasicProfile | Puede recuperar las propiedades de gapi.auth2.BasicProfile con los siguientes métodos:


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 siempre se debe devolver 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 | Una Promise que se cumple con el gapi.auth2.AuthResponse recargado cuando se realiza la recarga del token OAuth. |
gapi.auth2.AuthResponse
La respuesta regresó al llamar GoogleUser.getAuthResponse( includeAuthorizationData )
o GoogleUser.reloadAuthResponse()
métodos.
Propiedades | ||
---|---|---|
access_token | string | El token de acceso concedido. |
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 otorgó por primera vez los alcances solicitados. |
expires_at | number | La marca de tiempo en la que caducará el token de acceso. |
GoogleUser.hasGrantedScopes ( scopes )
Devuelve verdadero si el usuario otorgó los alcances especificados.
Argumentos | |
---|---|
scopes | Una cadena de ámbitos delimitada por espacios. |
Devoluciones | |
---|---|
Booleano | Verdadero si se concedieron los alcances |
GoogleUser.grant ( options )
Solicite ámbitos 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.disconnect ()
Revoca todos los ámbitos que el usuario otorgó a la aplicación.
Elementos de la interfaz de usuario
gapi.signin2.render ( id , options )
Muestra un botón de inicio de sesión en el elemento con el ID proporcionado, utilizando 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 utilizará 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:


Avanzado
gapi.auth2.authorize ( params , callback )
Realiza una autorización OAuth 2.0 única. Dependiendo de los parámetros utilizados, esto abrirá una ventana emergente para el flujo de inicio de sesión de Google o intentará cargar la respuesta solicitada de forma silenciosa, sin la interacción del usuario.
Algunos casos de uso en los que este método es útil incluyen:
- Su aplicación solo necesita solicitar un punto final de la API de Google una vez, por ejemplo, para cargar los videos favoritos de YouTube del usuario la primera vez que inicia sesión.
- Tu 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 tu backend.
- Se utilizan varios ID de cliente en la misma página.
Argumentos | |
---|---|
params | 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
dará más información sobre el error generado. -
popup_closed_by_user
- El usuario cerró la ventana emergente antes de finalizar el proceso de inicio de sesión.
-
access_denied
- El usuario denegó el permiso para los ámbitos requeridos.
-
immediate_failed
- Ningún usuario podría ser seleccionado automáticamente sin solicitar el flujo de consentimiento. Se produjo un error al usar el
signIn
con elprompt: 'none'
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 | 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 posibles valores son:


prompt | string | Fuerza un modo específico para el flujo de consentimiento. Los posibles valores son:


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 deben pertenecer los usuarios 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 preseleccionar en el flujo de inicio de sesión. Esto es susceptible de modificación por parte del usuario, a menos que se utilice el prompt: "none" . |
include_granted_scopes | boolean | Ya sea para 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. Por defecto es true . |
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 concedido. Solo está presente si se especificó el permission o el token en response_type . |
id_token | string | El token de identificación otorgado. Solo está presente si se especificó id_token en response_type . |
code | string | El código de autorización concedido. Solo está presente si el code se especificó en response_type . |
scope | string | Los alcances otorgados en el token de acceso. Solo está presente si se especificó el permission o el token en response_type . |
expires_in | number | El número de segundos hasta que expire el token de acceso. Solo está presente si se especificó el permission o el token en response_type . |
first_issued_at | number | La marca de tiempo en la que el usuario otorgó por primera vez los alcances solicitados. Solo está presente si se especificó el permission o el token en response_type . |
expires_at | number | La marca de tiempo en la que caducará el token de acceso. Solo está presente si se especificó el permission o el token en response_type . |
error | string | Cuando la solicitud falló, este 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 devuelve. |