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. |
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. |
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:
|
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ónprompt: 'none'
. Esta opción no debería ser necesaria para usar, ya quegapi.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:
|
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ónprompt: 'none'
. Esta opción no debería ser necesaria para usar, ya quegapi.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:
|
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.
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.
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 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:
|
Avanzado
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.
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ó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 valores posibles son:
|
prompt | string | Fuerza un modo específico para el flujo de consentimiento. Los valores posibles 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 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. |