Gigya Job Openings

accounts.socialLogin REST

Skip to end of metadata
Go to start of metadata

 

 

This method serves as an end point for user authentication using the user's social network or webmail account. This method requires user interaction. To login/register the user to your site, redirect the user to the specified URL and pass the required parameters. The login URL shows the login screen of the requested provider. In some cases, such as Facebook login, users will also be asked to give the site permission to access their personal data.

When the login process completes - either successfully or with error - the Gigya server redirects the user to the URL defined in the redirect_uri parameter and appends response parameters. Read more in Using Gigya's REST API in compliance with OAuth 2.0.

You can also perform this operation using the Web SDK method accounts.socialLogin.

The social login operation is currently supported by the following providers: Amazon, Blogger, Facebook, FourSquare, GooglePlus, Instagram, Kakao, LINE, LinkedIn, Livedoor, Messenger, mixi, Naver, Netlog, Odnoklassniki, Orange France, PayPalOAuth, Tencent QQ, Renren, Sina Weibo, Spiceworks, Twitter, VKontakte, WeChat, WordPress, Xing, Yahoo, Yahoo Japan.

Note: If you plan on integrating Gigya's Accounts API, we highly recommend reading the Registration-as-a-Service Guide. Registration-as-a-Service (RaaS) is a premium platform that requires separate activation. If RaaS is not part of your site package, please contact Gigya by filling in a support form through the Console. You can access the support page by clicking Support on the upper menu after logging into the Gigya Console.

 

Social Registration

If the user is new to your site, the method attempts to register the user to your site. Gigya examines the site Policies and Schema and determines whether the registration process can be finalized or it is pending. In the first case, Gigya finalizes the registration and returns an "errorCode":0 in the response. In the second case, you will receive in the response a relevant error code and message, in addition you will receive a regToken string (registration token). You can identify the actual reason from the error code and message that you receive. 

After completing the registration process, you should call accounts.finalizeRegistration and pass the regToken.

The possible errors and reasons for them are described in the Errors section at the bottom of the page.  


Request URL

Where <Data_Center> is:
  • us1.gigya.com - For the US data center.
  • eu1.gigya.com - For the European data center.
  • au1.gigya.com - For the Australian data center.
  • ru1.gigya.com - For the Russian data center.
  • cn1.gigya-api.cn - For the Chinese data center.

If you are not sure of your site's data center, see Finding Your Data Center.

 

Parameters

RequiredNameTypeDescription
x_providerstringThe provider which will be used for authenticating the user. The following values are currently supported for use with this parameter:
amazon,  blogger, facebook, foursquare, googleplus, instagram, kakao, line, linkedin, livedoor, messenger, mixi, naver, netlog, odnoklassnikiorangefrance, paypaloauth, qq, renren, sina, spiceworks, twitter, vkontakte, wechat, wordpressxing, yahoo, yahoojapan.
 Also SAML providers are supported - the format of the provider name is "saml-".
client_idstringThe Gigya API key. You may obtain a Gigya API key from the Site Dashboard page on Gigya's website.
redirect_uristringThe URi to redirect to after the login completes. This must be verified against the registered domain for this API key.
response_typestringMay be either "token" or "code". See extended explanation below.
statestringA string that will be passed as another parameter to the redirect_uri after the login completes.
x_cidstringA context ID of the operation.
x_conflictHandlingstringHow the server handles a "login identifier exists" conflict on a new account:
  • fail - (default) returns a "login identifier exists" error.
  • saveProfileAndFail - profile data is saved, an access token is returned for account linking, and an error is returned "OK with error login identifier exists".
x_displayModestringThe display mode of of the Facebook login page. The valid values are:
  • 'popup' (default) - displays Facebook's popup login dialog
  • 'page' - displays Facebook's full login page
  • 'touch' - used on smartphone mobile devices, like iPhone and Android
x_extraPermissionsstringA comma delimited list of extended permissions to request from the user. This parameter gives the possibility to request extended permissions in addition to the permissions that Gigya is already requesting. 
Please refer to Facebook's extended permissions page, for the complete list of Facebook permissions. 
For example, if you wish to RSVP to events on the user's behalf and to to send sms messages to the user, define: x_extraPermissions="rsvp_event,sms".
To request Google wallet permissions define: x_extraPermissions="wallet".
Note: Use the socialize.getRawData method to pull the extra data. 
x_forceAuthenticationBooleanThe default value of this parameter is 'false'. If it is set to 'true', the user is forced to provide their social network credentials during login - even if the user is already connected to the social network. This parameter is currently supported by Facebook, Twitter, Renren, and LinkedIn. Note that the behavior of the various social networks may be slightly different: Facebook expects the current user to enter their password, and will not accept a different user name. Other networks prompt the user to re-authorize the application or allow a different user to log in.
Note: This parameter is also named "forceAuthentication".
x_googlePlayAppIDstringThe objective of this parameter is to support Over The Air app installs for Android devices during Google+ login. Set this parameter with the package name of your Android app (for example: "com.yourdomain.app"). As a result, after signing in with Google+, users have the option to send your Android app to their device instantly, without leaving your website. As a preliminary step you'll need to Utilize Google+ Native Android Sign-on on your Android app. The package name passed to this parameter is the same one you enter when enabling the Google+ API.
x_langstringDefines the language of Gigya's user interface and error message. For the list of supported languages, please refer to the languages table.
x_loginModestringThe type of login being performed:
  • standard - (default) the user is logging into an existing account.
  • link - the user is linking a social network to an existing account. The account being used to login will become the primary account.

    If you have not set the regToken parameter when accounts are conflicting, the request will not execute completely.

  • reAuth - the user is proving ownership of an existing account by logging into it. The loginID will be ignored and the password verified. Note that this option overrides the "x_forceAuthentication", setting, making it 'true'.
x_openIDProviderLogostringA URL of the provider logo to display in the OpenID popup. This parameter is used only when provider='openID' and x_openIDURL is specified.
x_openIDProviderNamestringThe provider name to display in the OpenID popup. This parameter is used only when provider='openID' and x_openIDURL is specified.
x_openIDURLstringWhen provider='openID' and this parameter is specified, the server should ask the user for his username, like it's done with known openID providers such as AOL. 
x_openIDUsernamestringThe username in the OpenID provider, if available. When this parameter is passed with a known OpenID provider, the username request screen is skipped.
x_regSourcestringA string representing the source of the registration. This would typically be the URL where it took place.
x_session_expirationintegerThis parameter defines the time in seconds that Gigya should keep the login session valid for the user. To end the session when the browser closes, please assign the value '0'. If this parameter is not specified, the session will be valid forever.
x_temporary_account BooleanThe default value of this parameter is false. Setting this parameter to true, indicates that the account is temporary and is only accessible with the associated access token. This means that it is not possible to access the same account, and get the same Gigya UID, again by using login. 

 

Response Data

When the login process completes (either successfully or with error), Gigya server redirects the user to the URL defined in the redirect_uri parameter and appends response parameters.

Response Type "token"

When the requested response_type is "token", the response parameters are appended as a URL fragment (following a # sign). The following parameters are appended, after a successful login:

FieldTypeDescription
access_tokenstringA Gigya session key. You may use this token to invoke Gigya's REST API methods. Pass this token as a parameter with each REST API method call. Read more in making an API call.
expires_innumberThe duration in seconds of the access token's lifetime. Note: This field is only returned when the token has an expiration time. If this field is not available then the token will not expire.
statestringThe state string passed by your application as parameter to the login end-point. (See table of Parameters above).
x_isNewUserBooleanIndicates whether the user logging in is new. The parameter is returned only when it is set to "true".

Response Type "code"

When the requested response_type is "code", the response parameters are appended as query string parameters (following a ? sign). The following parameters are appended, after a successful login:

FieldTypeDescription
codestringA Gigya authorization code. You may use this code to obtain an access token. The expiration time of this code is 2 minutes.
statestringThe state string passed by your application as parameter to the login end-point. (See table of Parameters above).

Error Response

If the login fails, Gigya will append the following parameters to the response URL (regardless of the response_type parameter value):

FieldTypeDescription
errorstringThe error code. For a complete list of error codes, see the Error Codes table below.
error_descriptionstringThe Gigya error code and error message (separated by a dash). For example: "500001 - Server error".
statestringThe state string passed by your application as parameter to the login end-point. (See table of Parameters above).

Error Codes

Error CodeDescription
invalid_requestThe request is missing a required parameter, includes an unknown parameter or parameter value, or is otherwise malformed.
invalid_client-idThe client identifier provided is invalid.
unauthorized_clientThe client is not authorized to use the requested response type.
redirect_uri_mismatchThe redirection URI provided does not match a pre-registered value.
access_deniedThe end-user or authorization server denied the request.
unsupported_response_typeThe requested response type is not supported by the authorization server.

Errors

Gigya defines specific error codes and messages that are used with the Accounts API. These errors are returned with the APIs, indicating that some information is incorrect or missing. 

This section describes the errors that are related to this API, the reasons for each error, and the expected next step.

  • Account pending registration (error code 206001) - returned when you call a method that performs social login, such as this method, and the registration process has not been finalized, or the schema defines fields as required and one or more of these fields are missing from the user Profile or custom data fields. The expected next step is: if the schema defines fields that are required and one or more of these fields are missing from the user profile or data, call accounts.setAccountInfo. If the registration process has not been finalized, call accounts.finalizeRegistration with the regToken
  • Account pending verification (error code 206002) - returned when the account has already been verified, and a user tries to log in with a loginID (usually an email address) that we have not yet verified that actually belongs to this person. When the accountOptions policy states that verifyEmail is "true", the account must be validated by using the available email addresses. When the policy states that allowUnverifiedLogin is "false", users are not allowed to login before they have verified their emails. So, in this case, when a user tries to login, and his account has not been verified yet, and verifyEmail is "true" in the policy and allowUnverifiedLogin is "false" in the policy, the "Account pending verification" error is returned. The expected next step is: call accounts.resendVerificationCode to resend a validation email to the unverified addresses associated with the account. The email format is according to the templates defined in the policy.
  • Account missing loginID - when the registration policy states that requireLoginID is "true", a loginID is required when a user uses Social Login to register to the site, so the "Account missing loginID" error is returned (error code 206003) if requireLoginID is configured in the registration policy and there are no login identifiers or a password associated with the account. The expected next step: ask the user to provide login identifier and call accounts.register to register the new user to your site, in accordance with the predefined site Policies and the Schema of the Accounts Storage.
  • Login identifier exists (error code 403043) - returned when email is defined as the loginIdentifier in the accountOptions policy, and the email address received from the provider exists in the system but is associated with a different user. The expected next step: call accounts.linkAccounts to merges between the account identified by the provided UID and the account identified by the provided login credentials (loginID + password).
  • Account Pending TFA Verification/Registration (error codes 403101/403102) - returned when a user calls this method and the policy (in the site Policies) requires 2-factor authentication, and the device is not in the verified device list for the account.