Was this article helpful?

Social Login

Last modified 10:48, 15 Sep 2014

The Gigya service can be used as an external authentication system, allowing users to login/register to your site using an increasing number of platforms, such as Facebook, Twitter, Google, Yahoo, LinkedIn and more. We offer a simple and trusted external login service and follow all the guidelines that are required by the various platforms.
The implementation proposed in this document is targeted for sites that already have their own user management system, and wish to offer Social Login (login/register through social networks) side by side with their existing site login/registration.

Note: if you are using Gigya's Registration-as-a-Service package, in which Gigya provides the site's entire user management system (including site registration screens, site's storage, etc.), please skip this guide and focus entirely on the Registration-as-a-Service guide.

You may find an example of a site login form, alongside with Gigya's Login plugin on the Login page of Gigya's website (if you are logged in, log out to view the page). 

This document will guide you through the Implementation of our recommended best-practice step-by-step. Some of the steps are marked as optional, however we encourage you to implement all the steps. 

Note: for a quick start implementation, please refer to the Basic Social Login working code example.

 

Implementation

When a user opts to login or register to your site, he is offered to authenticate using either Gigya's Login plugin or your existing site Login/Register form. Each of these two options leads to a separate logic flow. The following two sections provide step-by-step instructions for implementing these two logic flows:

Below these two sections you may find sections dealing with complementary implementation issue:

 

BestPractice_LoginForm.gif
Note: the implementation includes usage of Gigya's API. Most Gigya API methods are supported both for client side (JavaScript API) and server side (REST API). We encourage you to work server to server whenever applicable. Please use one of our Server Side SDKs for server side API calls. If there is no SDK available for your preferred language, you may use direct REST API calls.

  

Integrating Gigya's Social Login  

Before diving into the implementation, please take a look at the Web Wireframes illustrating the following implementation from the user point of view.
Please note, this implementation proposes using the user's email address as the user identifier, in other words the email field is required and unique per user account. If this assumption is incorrect for your site, for example if you are using any string as the "username" and an email is not a required field, you can easily adjust the implementation accordingly. 

To integrate Gigya's social login/registration, please implement the flow presented in the following chart (the steps are described below):

SocialLogin-FlowChart2.png

  • Step 1: Add the Login plugin to your Sign-Up (registration) and Login pages. The easiest and quickest way is to use the Login Plugin wizard. The wizard lets you customize the plugin, while previewing the changes as you make them. Based on your modifications, the wizard generates code that you can insert into your application.
    Alternatively, you may design your own user interface and use the Login API method.
     

  • Step 2:  Upon successful Login you will be notified with an onLogin event. The onLogin event data includes a User object enfolding the user data, some of this data is used in the next steps. Please make sure to register to the onLogin event, using the socialize.addEventHandlers method, during page load. To learn more about how to register and handle events generated by the Gigya service, please refer to the Events page. 

    Note: You can trigger the login event from any plugin using the the connectWithoutLoginBehavior parameter of the global configuration object. Read more in the Using Plugins to Initiate Site Login guide.

     

  • Step 3: To avoid fraud, we highly recommend verifying the authenticity of the signature received from Gigya (with the onLogin event data from the previous step). To learn more about this subject, please refer to the Validate the UID Signature in the Social Login Process section of the Security guide.
     

  • Step 4: Check whether the user is new. To implement this, retrieve the UID field from the onLogin event data (from Step 2) and look up the UID in your user management system.
    An alternative and more efficient way to check if the user is new, is by inspecting the isSiteUID field, which is part of the User Object (received within the onLogin event data). If isSiteUID=='true' , this means that the UID in the UserObject is an ID that your site has provided using the socialize.notifyRegistration API method (see Step 10 below) in a previous login flow, hence the user is a returning user. If isSiteUID=='false' , this means the UID was generated by Gigya, hence the user is new.

    Note: The UID string must be encoded using the encodeURIComponent() function before sending it from your client to your server.

     

  • Step 5: If the UID already exists in your user management system, identify the user and complete his login process on your site - mark the user as logged-in, and move to your post-login page.

     

   "New User" Sub-Flow:

    If the UID is new, you should:

  • Step 6 (optional): Check whether any required data is missing. If so move to Step 8.b else move to Step 7. 
    Explanation: In many cases you have user data fields that you consider to be required. An example for that may be the email address. In Step 2 you received the User object that enfolds various user data. This user data may or may not  include all the data that you consider to be required. The user data that is available in the User Object may vary from one provider to another and from one user to another. For example, Facebook provides email address, while Twitter doesn't.
    Note: if you don't wish to implement this sub-flow (you don't require any data), you can skip to Step 7.

     

  • Step 7 (optional): Check whether the user's email address (received within the User object) exists in your system.  If so move to Step 8.a else move to Step 9. 
    Note: if you don't require email uniqueness in you system, or you don't wish to implement account linking, skip this step and move directly to Step 9. 
     
  • Step 9: Store the new user in your database. The site user ID you designate for the user in this step will be used in the next step.
     
  • Step 10: Call the socialize.notifyRegistration API method. The method receives a parameter named siteUID; please set this parameter with the user ID that you have designated to this user in the previous step.
    The siteUID parameter is retrieved from the user record either in Step 9 or in Step 9.a.

 

  • "Link Account" Sub-Flow (optional):
    • Step 8.a: The segment that is marked with the letter E in the  Web Wireframes provides the user with an option to link to his site account (by entering his credentials and pressing the "Link Accounts" button).  
      If the user pressed the "Link Accounts" button, you should authenticate the user's credentials in your database. If authenticated (i.e. the user identified as an existing site user), move to the next step (Step 9.a).
    • Step 9.a: Retrieve the old user siteUID from the database. In the previous step, you have identified the user, thus found his record in your database. Retrieve his site user ID from his record. It will be used in the next step. From here we continue to Step 10.
       
  • "Missing Required Data" Sub-Flow (optional): 
    • Step 8.b:  The segment that is marked with the letter D in the Web Wireframes, is a form that allows the user to fill in required fields (e.g. email address). You can use your standard registration form, pre-populated with data. The User Object that you receive from Gigya as part of the onLogin event data in Step 2 hold user-profile information extracted from social networks. You can use the information that is relevant to your site to pre-populate the form.
      If the user provided all the required data and pressed the "Submit" button, we go back to the regular "new user" case, i.e. proceed to Step 7.
       

 

 

Site Login - Synchronizing with Gigya Service

When a user authenticates using your existing Login form or when a new user registers using site registration, it is important to notify Gigya of the user's new state, so as to provide consistent user experience. To implement this, call the socialize.notifyLogin API method at the end of your existing login flow. This is illustrated in the following flowchart diagram:

AuthenticationFlowChartSite.gif

 
The socialize.notifyLogin method receives a required parameter named siteUID. Please set this parameter with the user ID that you have designated for this user in your database. The notifyLogin call registers a new user in Gigya in case the siteUID provided is new, or reconnects a returning user in case the siteUID already exists in our records.

If it is a new user, call the socialize.notifyLogin API method with the newUser parameter set to 'true'. This will enable Gigya to distinguish between a new site user and a returning site user, allowing Gigya to analyze users' login/registration behavior with or without Social Login and compare the ratio.

When receiving the notifyLogin response on server side, please make sure to create a session cookie, so as to maintain the client application synchronized with the user state. The notifyLogin response data includes the following fields: cookieName, cookieValue, cookiePath, cookieDomain. Please create a cookie using these fields.
For example, in PHP:

setcookie(cookieName,cookieValue,0,cookiePath,cookieDomain)

Please make sure that the page following the login includes Gigya's library i.e. gigya.js, in order for Gigya to read the cookie before it expires.

 

Synchronizing Gigya with the user's state has several benefits:

  • In calls to socialize.getUserInfo and socialize.getFriendsInfo Gigya will return your own site user ID as the UID for this user (as opposed to Gigya's user ID).
  • Gigya will set the isSiteUser flag for this user to "true", thus even if this user is referred to as a friend of another user you can easily tell he is a user of your site and not just a friend of the visiting user.
  • Any connections the user makes to social networks will be linked with the site account. The social graph will automatically be made available the next time the user logs in to the site.

 

Logging Out

When a user logs out from your site, it is important to notify Gigya of the user's new state, otherwise Gigya will still consider the user logged in and someone else who uses the same computer could gain access to that user's personal information and perform actions on his behalf.
Within your site logging out flow, please call the socialize.logout API method. We recommend calling the socialize.logout method from your client application, this way, Gigya will clear the relevant cookies, and your client application will know when the user is logged out without calling the server.
When calling socialize.logout method, Gigya will attempt to logout the user from all the providers to which the user is connected. In order to force logout from Facebook, you have to configure a Domain Alias (CNAME) for your site and enable automatic session renewal in our site's Settings page in the Facebook Configuration dialog.

 

Sessions Expiration

When a user logs in via Gigya, Gigya creates a login session for the user. By default the session stays valid forever, or until socialize.logout method is called.
Gigya gives you the option to change the default behavior and decide when to terminate a login session. Read more in Controlling Session Expiration section of the Security guide.

 

Using Social Plugins to Initiate Site Login

Please read the Using Plugins to Initiate Site Login to learn how to integrate Gigya's Plugins with the Social Login Process and leverage the Plugins to acquire new site users.

 

Adding Connections

After the user has logged-in to your site, you can give your user an option to add connections to multiple social networks, hence giving the possibility to interact with friends on multiple social networks. You can do that by adding the Add Connections plugin to your site pages. This is broadly explained in the Adding Connections to Social Networks guide.

Error Handling

Gigya uses an asynchronous programming model in which operations are triggered and then run in the background until they are completed. Upon successful or unsuccessful completion you receive a method response that includes the results of the operation. In case of using the JavaScript API, the operation invokes a callback function, which should be provided as a parameter to the API method call. The callback function receives a response object that includes the results of the operation.

To prevent an inconsistent user state it is vital to make sure that all the steps of the Login flow complete successfully. For this purpose, we recommend employing the following steps when calling an API method (i.e. showLoginUI, notifyRegistrationnotifyLoginlogout):

  1. Define a timeout.
  2. If after the timeout you did not receive a response, or if you received an error in the response, then retry calling the API method.
  3. In case of notifyRegistration, if after several retries the method has not successfully completed, rollback the database changes.

 

Important Notes:

  • When a user logs-in through Gigya you should not use the socialize.notifyLogin call because the user is already logged-in in Gigya's platform at that point.
  • Please do not call socialize.notifyRegistration nor socialize.setUID API methods after logging-in a returning user.
  • In most cases, a user only needs to be authenticated once per session, either with Gigya or with your site's Login system. Therefore, do not display Gigya's Login Plugin for users who have already logged in.

 

Working Examples

We offer several Social Login working code examples, from the most simplified to the most comprehensive:

  1. Basic Social Login - for a quick start implementation, please refer to the Basic Social Login working code example.
     
  2. Social Login Demo: in the Social Login Demo page you may find a working example that implements a simplified version of the algorithm that is described in Integrating Gigya's Social Login.
    The missing parts in the implementation are: the "Link Account" Sub-Flow, the "Missing Required Data" Sub-Flow and the parts that require interaction with your site's server and database.
     
  3. Comprehensive demo site: The Daily Recipe is a Gigya demo site written in PHP and JavaScript. This demo outlines how to make a web site social using Gigya's platform, and implements the best practice as described in this page. The demo site's code is available for you to download, use and learn about the site implementation. Examine how Gigya's Social Login best practice is implemented within the site.

Guidelines

Position the Login plugin in a prominent place on your registration and login forms - Many sites have different forms for registration and logging-in, this is reflected in the mock-up shown above. We advise to include the login plugin in a prominent position on both forms to increase the user registration rate. If your site has both registration and login on the same page we recommend adding the Gigya login plugin in both sections of the page, so it would appear once under each section.This makes it easier for users to understand their options, thus increasing registration rates.

Make sure your design helps users understand that they can either link to an existing account or registerWe recommend placing the linking option in a prominent spots in your step two registration page, for example side by side with your registration option.

Provide a consistent and coherent user experience - Make sure you sync your login system with Gigya, so that when a user login through your system or logs-out you notify Gigya of the user's state.

Storing social network user info - Make sure you that you prompt the user to confirm storing the pre-populated fields retrieved from his social network profile. A good way to do this is to include an "import" button that the user can press to import his personal info.

Following the social networks terms of use - Each social network has its own terms of use, developer's guidelines, and site policies and requires sites to implement their solutions in accordance to those. Gigya does most of the work for you, but there are a few basic rules that you should keep in mind when designing your site's social network integration:

  • Don't publish feed items to user's streams without first getting the user's consent.
  • Setup a dedicated social network external application per site, so that users can control their privacy settings.

Tags

This page has no custom tags.
This page has no classifications.

Comments

You must to post a comment.

Attachments