This reference describes the JavaScript client methods and attributes you will use to implement Google Sign-In in your web applications.
If you encounter any issue using the library, please report it to our GitHub repository .
Auth Setup
Load the Google APIs platform library to create the gapi
object:
<script src="https://apis.google.com/js/platform.js?onload=init" async defer></script>
After the platform library loads, load the auth2
library:
function init() {
gapi.load('auth2', function() {
/* Ready. Make a call to gapi.auth2.init or some other API */
});
}
gapi.auth2.init( params )
Initializes the GoogleAuth
object. You must call this method before calling gapi.auth2.GoogleAuth
's methods.
When you initialize the GoogleAuth
object, you configure the object with your OAuth 2.0 client ID and any additional options you want to specify. Then, if the user has already signed in, the GoogleAuth
object restores the user's sign-in state from the previous session.
gapi.auth2.ClientConfig
for the different
properties configurable. For example: { client_id: 'CLIENT_ID.apps.googleusercontent.com' }
gapi.auth2.GoogleAuth
gapi.auth2.GoogleAuth
object. Use the then()
method to get a Promise
that is resolved when the gapi.auth2.GoogleAuth
object finishes
initializing.GoogleAuth.then( onInit , onError )
Calls the onInit
function when the GoogleAuth
object is fully
initialized. If an error is raised while initializing (this can happen in old unsupported browsers),
the onError
function will be called instead.
GoogleAuth
object when it is fully
initialized.error
property,
if GoogleAuth
failed to initialize.Promise
that is fulfilled when the onInit
function has completed, or rejected if an initialization error was raised. It resolves with the
returned value from the onInit
function, if any.Error Codes
-
idpiframe_initialization_failed
- Failed to initialize a required iframe from Google, for instance, due to an unsupported
environment. A
details
property will give more information on the error raised.
gapi.auth2.ClientConfig
Interface that represents the different configuration parameters for the gapi.auth2.init
method.
client_id
string
cookie_policy
string
single_host_origin
, or none
. Defaults to single_host_origin
if unspecified.scope
string
fetch_basic_profile
is not set to false.fetch_basic_profile
boolean
hosted_domain
string
hd
claim in the ID Token on the
server to verify the domain is what you expected.
ux_mode
string
popup
and redirect
.redirect_uri
string
ux_mode='redirect'
, this parameter allows you to override the
default redirect_uri
that will be used at the end of the consent flow. The
default redirect_uri
is the current URL stripped of query parameters and hash
fragment.enable_granular_consent
boolean
false
, the more granular Google
Account permissions will be disabled for OAuth client IDs created before
2019. No effect for OAuth Client IDs created during or after 2019, since
more granular permissions is always enabled for them.plugin_name
string
plugin_name: 'YOUR_STRING_HERE'
Authentication
GoogleAuth
is a singleton class that provides methods to allow the user to sign in with a Google account, get the user's current sign-in status, get specific data from the user's Google profile, request additional scopes, and sign out from the current account.
gapi.auth2.getAuthInstance()
Returns the GoogleAuth
object. You must initialize the GoogleAuth
object with gapi.auth2.init()
before calling this method.
gapi.auth2.GoogleAuth
gapi.auth2.GoogleAuth
object. Use this object to call gapi.auth2.GoogleAuth
's methods.GoogleAuth.isSignedIn.get()
Returns whether the current user is currently signed in.
true
if the user is signed in, or false
if the
user is signed out or the GoogleAuth
object isn't
initialized.GoogleAuth.isSignedIn.listen(listener)
Listen for changes in the current user's sign-in state.
listen()
passes true
to this function when the user signs in, and false
when the user signs out.GoogleAuth.signIn()
Signs in the user with the options specified to gapi.auth2.init()
.
Promise
that is fulfilled with the GoogleUser
instance when the
user successfully authenticates and grants the requested scopes, or rejected with an object
containing an error
property if an error happened (see below for error codes).Error codes
See GoogleAuth.signIn( options
)
.
GoogleAuth.signIn( options )
Signs in the user using the specified options.
- A
gapi.auth2.SignInOptions
object containing key-value pairs of sign-in parameters. For example:{ scope: 'profile email' }
- An instance of
gapi.auth2.SigninOptionsBuilder
. For example:options = new gapi.auth2.SigninOptionsBuilder(); options.setAppPackageName('com.example.app'); options.setFetchBasicProfile(True); options.setPrompt('select_account'); options.setScope('profile').setScope('email');
Promise
that is fulfilled with the GoogleUser
instance when the
user successfully authenticates and grants the requested scopes, or rejected with an object
containing an error
property if an error happened (see below for error codes).Error codes
-
popup_closed_by_user
- The user closed the popup before finishing the sign in flow.
-
access_denied
- The user denied the permission to the scopes required.
-
immediate_failed
- No user could be automatically selected without prompting the consent flow. Error raised when
using
signIn
withprompt: 'none'
option. This option should not be required to use, asgapi.auth2.init
will automatically sign in the user if previously signed in during a previous session.
gapi.auth2.SignInOptions
Interface that represents the different configuration parameters for the GoogleAuth.signIn( options
)
method.
prompt
string
The possible values are:
-
consent
The authorization server prompts the user for consent before returning information to the application. -
select_account
The authorization server prompts the user to select a Google account. This allows a user who has multiple accounts to select amongst the multiple accounts that they may have current sessions for. -
none
( not recommended )
The authorization server will not display any authentication or user consent screens; it will return an error if the user is not already authenticated and has not previously consented to the requested scopes.
Asgapi.auth2.init
will automatically sign in a user to the application if previously signed in, callingsignIn({prompt: 'none'})
will usually fail.
scope
string
gapi.auth2.init
params. Optional if fetch_basic_profile
is not set
to false.ux_mode
string
popup
and redirect
.redirect_uri
string
ux_mode='redirect'
, this parameter allows you to override
the default redirect_uri
that will be used at the end of the consent
flow. The default redirect_uri
is the current URL stripped of query
parameters and hash fragment.GoogleAuth.signOut()
Signs out the current account from the application.
Promise
that is fulfilled when the user has been signed
out.GoogleAuth.disconnect()
Revokes all of the scopes that the user granted.
GoogleAuth.grantOfflineAccess( options )
Get permission from the user to access the specified scopes offline.
gapi.auth2.OfflineAccessOptions
object containing key-value pairs of parameters. For example: { scope: 'profile email' }
Promise
that is fulfilled when the user grants the
requested scopes, passing an object containing the authorization code to
the Promise
's fulfillment handler.
For example: auth2.grantOfflineAccess().then(function(resp) { var auth_code = resp.code; });
Error codes
-
popup_closed_by_user
- The user closed the popup before finishing the consent flow.
-
access_denied
- The user denied the permission to the scopes required.
-
immediate_failed
- No user could be automatically selected without prompting the consent flow. Error raised when
using
signIn
withprompt: 'none'
option. This option should not be required to use, asgapi.auth2.init
will automatically sign in the user if previously signed in during a previous session.
gapi.auth2.OfflineAccessOptions
Interface that represents the different configuration parameters for the GoogleAuth.grantOfflineAccess( options
)
method.
prompt
string
The possible values are:
-
consent
The authorization server prompts the user for consent before returning information to the application. -
select_account
The authorization server prompts the user to select a Google account. This allows a user who has multiple accounts to select amongst the multiple accounts that they may have current sessions for.
scope
string
gapi.auth2.init
params. Optional if fetch_basic_profile
is not set
to false.GoogleAuth.attachClickHandler( container , options , onsuccess , onfailure )
Attaches the sign-in flow to the specified container's click handler.
div
element to which to
attach the click handler.Users
A GoogleUser
object represents one user account. GoogleUser
objects are typically obtained by calling GoogleAuth.currentUser.get()
.
GoogleAuth.currentUser.get()
Returns a GoogleUser
object
that represents the current user. Note that in a newly-initialized GoogleAuth
instance, the current user has not been set. Use the currentUser.listen()
method or the GoogleAuth.then()
to get an initialized GoogleAuth
instance.
GoogleUser
GoogleAuth.currentUser.listen( listener )
Listen for changes in currentUser.
GoogleUser
parameter. listen
passes this function a GoogleUser
instance on every change that modifies currentUser
.GoogleUser.getId()
Get the user's unique ID string.
GoogleUser.isSignedIn()
Returns true if the user is signed in.
GoogleUser.getHostedDomain()
Get the user's G Suite domain if the user signed in with a G Suite account.
GoogleUser.getGrantedScopes()
Get the scopes that the user granted as a space-delimited string.
GoogleUser.getBasicProfile()
Get the user's basic profile information.
gapi.auth2.BasicProfile
gapi.auth2.BasicProfile
with the following methods: - BasicProfile.getId()
- BasicProfile.getName()
- BasicProfile.getGivenName()
- BasicProfile.getFamilyName()
- BasicProfile.getImageUrl()
- BasicProfile.getEmail()
GoogleUser.getAuthResponse(includeAuthorizationData)
Get the response object from the user's auth session.
fetch_basic_profile
is true (the default value) and no additional scopes are
requested.gapi.auth2.AuthResponse
GoogleUser.reloadAuthResponse()
Forces a refresh of the access token, and then returns a Promise for the new AuthResponse.
Promise
Promise
that is fulfilled with the reloaded gapi.auth2.AuthResponse
when reloading the
OAuth token is done.gapi.auth2.AuthResponse
The response returned when calling GoogleUser.getAuthResponse( includeAuthorizationData
)
or GoogleUser.reloadAuthResponse()
methods.
access_token
string
id_token
string
scope
string
expires_in
number
first_issued_at
number
expires_at
number
GoogleUser.hasGrantedScopes( scopes )
Returns true if the user granted the specified scopes.
GoogleUser.grant( options )
Request additional scopes to the user.
See GoogleAuth.signIn()
for the list of
parameters and the error code.
GoogleUser.grantOfflineAccess( options )
Get permission from the user to access the specified scopes offline.
gapi.auth2.OfflineAccessOptions
object containing key-value pairs of parameters. For example: { scope: 'profile email' }
GoogleUser.disconnect()
Revokes all of the scopes that the user granted for the application.
UI elements
gapi.signin2.render( id , options )
Renders a sign-in button in the element with the given ID, using the settings specified by the options object.
{ scope: 'email', width: 200, height: 50, longtitle: true, theme: 'dark', onsuccess: handleSuccess, onfailure: handleFailure }You can specify the following options:
profile
).120
).36
).false
). When you use long titles,
you should increase the width of the button from its default.light
or dark
(default: light
).gapi.auth2.GoogleUser
(default: none).Advanced
gapi.auth2.authorize( params , callback )
Performs a one time OAuth 2.0 authorization. Depending on the parameters used, this will open a popup to the Google sign-in flow or try to load the requested response silently, without user interaction.
Some use cases where this method is useful include:
- Your application only needs to requests a Google API endpoint once, for instance to load the user's favorite YouTube videos the first time they sign in.
- Your application has its own session management infrastructure, and it only requires the ID Token once to identify the user in your backend.
- Several Client IDs are used within the same page.
gapi.auth2.AuthorizeConfig
for the
different properties configurable. For example: { client_id: 'CLIENT_ID.apps.googleusercontent.com', scope: 'email profile openid', response_type: 'id_token permission' }
gapi.auth2.AuthorizeResponse
object
after the request has been completed (either successfully or with a failure).Example
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.
});
Error codes
-
idpiframe_initialization_failed
- Failed to initialize a required iframe from Google, for instance, due to an unsupported
environment. A
details
property will give more information on the error raised. -
popup_closed_by_user
- The user closed the popup before finishing the sign in flow.
-
access_denied
- The user denied the permission to the scopes required.
-
immediate_failed
- No user could be automatically selected without prompting the consent flow. Error raised when
using
signIn
withprompt: 'none'
option.
gapi.auth2.AuthorizeConfig
Interface that represents the different configuration parameters for the gapi.auth2.authorize
method.
client_id
string
scope
string
response_type
string
'permission'
. The possible
values are: -
id_token
, to retrieve an ID Token -
permission
(ortoken
), to retrieve an Access Token -
code
, to retrieve an Authorization Code
prompt
string
-
consent
The authorization server prompts the user for consent before returning information to the application. -
select_account
The authorization server prompts the user to select a Google account. This allows a user who has multiple accounts to select amongst the multiple accounts that they may have current sessions for. -
none
The authorization server will not display any authentication or user consent screens; it will return an error if the user is not already authenticated and has not previously consented to the requested scopes.
Ifcode
is requested as response type, the code returned will only be exchangeable for anaccess_token
, not arefresh_token
.
cookie_policy
string
single_host_origin
, or none
. Defaults to single_host_origin
if unspecified.hosted_domain
string
login_hint
string
prompt: "none"
is used.include_granted_scopes
boolean
true
.enable_granular_consent
boolean
false
, the more granular Google
Account permissions will be disabled for OAuth client IDs created before
2019. No effect for OAuth Client IDs created during or after 2019, since
more granular permissions is always enabled for them.plugin_name
string
plugin_name: 'YOUR_STRING_HERE'
gapi.auth2.AuthorizeResponse
The response returned to the callback of the gapi.auth2.authorize
method.
access_token
string
permission
or token
was
specified in the response_type
.id_token
string
id_token
was specified in the response_type
.code
string
code
was specified in the response_type
.scope
string
permission
or token
was specified in the response_type
.expires_in
number
permission
or token
was specified in the response_type
.first_issued_at
number
permission
or token
was specified in the response_type
.expires_at
number
permission
or token
was specified in the response_type
.error_subtype
string