Gigya Job Openings

Social Login SSO Flow

Skip to end of metadata
Go to start of metadata

Integrating Gigya's Social Login

Before delving into the implementation, please take a look at the Screen-Sets illustrating the following implementation from the user's 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):

 

There are four possible flows that could occur depending upon the current status of the user and their information.

Initiate the Login Plugin

These initial steps will always occur regardless of which sub-flow ultimately succeeds.

  • Add the Login plugin to your Sign-Up (registration) and Login pages. The easiest and quickest way is to use the Login Plugin wizard. This 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.

  • 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. 
  • 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.
  • Check whether the user is new. To implement this, retrieve the UID field from the onLogin event data 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). 
  • Note: The UID string must be encoded using the encodeURIComponent() function before sending it from your client to your server.

    • 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 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.

"Existing User" Sub-Flow

If the UID already exists in your user management system:

  • Identify the user
  • Complete the login process on your site.
  • Mark the user as logged-in.
  • Move to your post-login page.

"New User" Sub-Flow

If the UID is new, you should:

  • Check whether any required data is missing. In many cases you have user data fields that you consider to be required. An example may be the email address. During the onLogin event 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 does not.

    • If data is missing:

      If you don't wish to implement this sub-flow (you don't require any data), you can skip this step.

    • If no data is missing:  

      If you don't require email uniqueness in you system, or you don't wish to implement account linking, you can skip this step.

      • Check whether the user's email address (received within the User object) exists in your system.
        • If the email exists in your database:
          • View the Link Accounts Flow. This 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.
          • 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 you complete the login process on your site - mark the user as logged-in, and move to your post-login page.
        • If the email does not exist in your database.

          • store the new user in your database. The site user ID you designate for the user in this step will be used when you call socialize.notifyRegistration.

  • Call the socialize.notifyRegistration API method. This method receives a parameter named siteUID. Set the siteUID parameter now or use the user ID that you have designated to this user in either of the previous steps.

  • Complete the login process on your site.
    Mark the user as logged-in.
    Move to your post-login page.

"Link Account" Sub-Flow

If the user's email already exists in your database and you need him to link his existing account to the site:

  • Present them with the "Already a Member" screen.

    • View the Link Accounts Flow.  This provides the user with an option to link to their existing site account (by entering his credentials and pressing the "Link Accounts" button).
      The user must press the "Link Accounts" button, you should then authenticate the user's credentials in your database.
      • If authenticated (i.e., the user identified as an existing site user).
        • Retrieve the old user siteUID from your 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 when you call socialize.notifyRegistration.
  • Call the socialize.notifyRegistration API method. This method receives a parameter named siteUID. Set the siteUID parameter now or use the user ID that you have designated to this user in either of the previous steps.

  • Complete the login process on your site.
  • Mark the user as logged-in.
  • Move to your post-login page.

"Missing Required Data" Sub-Flow

If the user's email does not exist in your database, or the current User object does not contain the necessary required information for your site:

  • Present them with the "We still need some details from you" screen.
    • View the Profile Completion option  in the Advanced Registration Flow. this form 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 must fill out the form and press "Submit".
      • The User Object that you receive from Gigya as part of the onLogin event data in the initial steps holds user-profile information extracted from social networks. You can use the information that is relevant to your site to pre-populate the form.
  • Call the socialize.notifyRegistration API method. This method receives a parameter named siteUID. Set the siteUID parameter now or use the user ID that you have designated to this user in any of the previous steps.

  • Complete the login process on your site.
  • Mark the user as logged-in.
  • Move to your post-login page.