Drupal 8

Skip to end of metadata
Go to start of metadata

Overview

The GConnector for Drupal 8 allows you to easily integrate Gigya's Registration-as-a-Service with your Drupal site. With the GConnector, you easily implement such features as registration, authentication, profile management, data analytics and third-party integrations. Increase registration rates and identify customers across devices, consolidate data into rich customer profiles, and provide better service, products and experiences by integrating data into marketing and service applications.

Registration-as-a-Service (RaaS) is Gigya's end-to-end identity management system that offers cloud-based user registration as well as social login, allowing sites to maintain a unified user database for both social and traditional site authentication.

Registration-as-a-Service is a premium service that requires separate activation. If it is not part of your Gigya site package, please contact your Gigya account manager or contact us by filling in a support form.

Versions and Compatibility

This version of the Gigya Connector is compatible with Drupal 8.2.5 and 8.3, and PHP 7.0.13.

Note: For the Drupal 7 GConnector, see Drupal 7.

Installation and Basic Implementation

To install the GConnector for Drupal 8, complete the following steps:

1.Set Up Your Gigya Account for RaaS

See Setting Up Your Gigya Account for RaaS.

2. Upload Gigya Connector

Download the GConnector for Drupal 8 from the Drupal directory at https://www.drupal.org/project/gigya (at the bottom of the page, click on the latest version for Drupal 8), uncompress and save it in the modules folder of the Drupal root folder.

Place the Gigya Connector in the modules directory in your Drupal site.

3. Update the Composer  

  1. Run the following command to initiate the composer update:

    composer update
  2. Define drupal.org as the source of Drupal packages.
     

  3. Run the following command:

    composer config repositories.drupal composer https://packages.drupal.org/8
  4. Run the following command:

    composer require drupal/gigya
  5. Make sure the php_cms_kit library was downloaded to vendor/gigya/cms-­starter-­kit.

 

For more information, see Drupal documentation.

4. Create Encryption Key

In this step you create the encryption key file, which will later be referenced when configuring the key path. 

Go to vendor/gigya/cms­-starter-­kit/cli and run the following command:

php encryption.php ­gen abc > <PATH>/a.key

This command creates an a.key file which includes the encryption key, saved in the path you specified.  

In some cases the file may not be created. This may happen if you lack relevant permissions to create a folder or write a new file to the server. In this case, you can receive the encryption key, copy it and manually create the file:  

In vendor/gigya/cms­-starter-­kit/cli and run the following command:

php encryption.php -­gen

This command returns an encryption key. Save the key to a file in the server that contains only this key, and name it a.key

Note:

  • For security reasons, the a.key file should not be located in the public (www) directory.
  • Supported encryption is AES 256.
  • If you change settings that are related to the encryption key, such as the folder path, or re-generate the key, you may need to re-enter your application key and secret in the configuration settings.

5. Enable the GConnector

Enable the GConnector using the UI or by running

drush en gigya


The Connector cannot be disabled but you can uninstall it using drush pm-uninstall gigya

6. Configure Encryption Key Path

In this step you will edit the gigya.global YAML configuration file to enter the path to the encryption key. As in any change to the YAML file, you will have to export the file, make the change, and then import it back into Drupal.

  1. Export the configuration file:

    1. In the Administration console, go to Configuration > Development > Configuration Synchronization > Export > Single Item.

    2. In the Configuration Name drop-down list, select gigya.global.
  2. In the text box that displays the contents of gigya.global, set the keyPath parameter to a path to a file that contains an encryption key, e.g. '/a.key'.

  3. Copy the new configuration.
  4. To import the new configuration back into Drupal:
    1. Go to Configuration > Development > Configuration Synchronization > Import > Single Item.
    2. In the Configuration Type drop-down list, select Simple Configuration.
    3. In the Configuration Name box, enter 'gigya.global'.
    4. Paste the configuration you copied.
    5. Select the Import button.

If the file set in keyPath exists and is readable, it will be used for encryption. Otherwise, the Connector will produce an error message.

7. Enter Gigya Credentials

  1. In the Drupal Admin console, go to Extend.
  2. In the Gigya section, select Gigya Core Module to expand the options, and select Configure.
  3. The settings page is displayed.
    Click image to enlarge
    Enter the following details:
    1. The Gigya API Key for your site, as it is displayed in the Gigya admin console in the Dashboard screen (see screenshot)
      Click image to enlarge
    2. Gigya Application Key and Gigya Application Secret: A Gigya Application Key is a key that you create specifically for your Drupal implementation. The Gigya Application Secret is the accompanying passkey. Using this set of credentials helps to protect your Gigya data. See instructions for creating an Application Key and Application Secret.
    3. The Gigya Data Center with which your site is associated. See Finding Your Data Center for instructions. Note: If your Data Center is not USEU, or AU, select Other and enter the Data Center's URL, e.g. "ru1.gigya.com".
  4. Select the Save Configuration button.

8. Implement RaaS Screen-Sets

The Gigya Connector for Drupal 8 enables you to implement RaaS screen-sets through blocks.

  1. In the Drupal Admin, go to Structure > Block Layout.
  2. Choose the desired region in the page in which you want the Gigya interface element to be displayed, and select the Place Block button next to that region.
  3. In the Place Block window, type "gigya" to filter the blocks.
    Click to enlarge screenshot
  4. Choose the desired Gigya block and select the Place Block button next to it.

    The "Gigya RaaS links" block will add Gigya screens as a pop-up window. Any of the other options, e.g. "Gigya RaaS Login", embeds the relevant Gigya screen into the page.

  5. Edit the block settings if needed and select Save Block.

The available blocks are:

  1. Gigya RaaS Links: This block displays Gigya RaaS links that can be clicked by the site user to open any of the RaaS screen-sets in a pop-up window.
    1. When the site user is not logged in, the block displays Login and Registration links. Clicking a link opens the Login or Registration screen-set, respectively, in a pop-up window.

    2. When the site user is logged in, the block displays a Profile link. Clicking this link pops up the Edit Profile screen-set.
    The following screenshot shows the Registration screen-set opening in a pop-up window:
    Click to enlarge screenshot
  2. Gigya RaaS Login: Embeds the Login screen-set in the page.
    Click to enlarge screenshot
  3. Gigya RaaS Register: Embeds the Registration screen-set in the page.
    Click to enlarge screenshot
  4. Gigya RaaS Profile: Embeds the Edit Profile screen-set in the page.

Customization

Customization Options

There are two main ways to customize the GConnector:

(I) Editing the gigya.global YAML Configuration File

The Connector is installed with some default settings, contained in gigya.global.yml (view file).

To edit gigya.global:

  1. In the Admin console, go to Configuration > Development > Configuration Synchronization > Export > Single Item > gigya.global.
  2. Copy the configuration from the text box and edit it in a YAML Editor.
  3. Go to Configuration > Development > Configuration Synchronization > Import > Single Item. In Configuration Type, select Simple Configuration. In Configuration Name, enter 'gigya.global'.
  4. Copy the configuration from your YAML editor and paste it into the text box, and select Import.

(II) Implementing Hooks

The GConnector also offers a set of hook functions to enable more advanced customization. With hooks, you can dynamically change variable values and/or override the GConnector's functionality.

Every Gigya API call that is invoked by the GConnector passes through the hooks before being sent to Gigya's servers. To interact with or extend the Gigya module, simply implement corresponding hooks in your own module code. For each hook, the prefix 'hook' in the name of the function is a placeholder for the name of your module. For example, if you want to implement "hook_gigya_raas_map_data_alter" (see details of this hook) to customize field mapping, and your module is called "mymodule", create a function called "mymodule_gigya_raas_map_data_alter".

For more information on hooks, see the Drupal hooks documentation.

See the table below for the list of available hooks. They are all included in the file gigya.api.php in the root directory of the Connector.

Sample module: For an example of how to implement these hooks in your own code, download our sample "Gigya Client" module . This is a module for Drupal that builds on the GConnector by implementing some of the hooks. Review the code and use the module as a reference for your own hook implementations.

When you implement hook functions, they override any settings configured anywhere else in the Connector.

Summary of Customization Options

User Session Management and Session Expiration

After the GConnector is installed, the Drupal user session will mirror the Gigya user session:

  • When a user logs into Gigya in your site, they are also logged into Drupal.
  • When a user logs out from Gigya, they are also logged out from Drupal.

To configure session expiration, edit the globalParameters object in the gigya.global settings file to include sessionExpiration: <value>. For more information about Gigya global parameters, see Other Customization Options.

For example, the following configuration sets sessionExpiration to 3600 (seconds):

globalParameters: {bypassCookiePolicy: 'never', enabledProviders: '*', sessionExpiration: 3600}

By default, sessionExpiration is set to 0, meaning that the user session expires when the browser is closed.

You may change this value to set a fixed session expiration length (in seconds).

Language Settings

By default, the Gigya elements in every page will be displayed in the language that has been set for the specific page in Drupal. If the page's language in Drupal is not one of the languages offered by Gigya, the Gigya elements will be displayed in English.

How to Change Language Settings

To change language settings, change the following lines in the gigya.global settings file:

language: 'Auto'
languageFallback: 'en'

You may change these parameters as follows:

Required?Parameter NameTypeOptions
languagestring

Set to a language code such as 'en' or 'es-mx' to choose a language for all Gigya elements.

Set to 'Auto' (default) to use the language that has been set in Drupal for the specific page.

languageFallbackstringIf you have set language to 'Auto', use this parameter to specify the fallback language that will be used if the language set in Drupal for the specific page is not a language offered by Gigya.

For a list of interface languages supported by Gigya, see Language Support.

How to Use Hooks for Advanced Language Settings

The Gigya Connector offers the following hook (see general note on hooks above) to customize the language settings further:

Function Header
function hook_gigya_lang_alter(&$lang)
Parameters
  • $lang: Check the value of this parameter to see what language was selected by the Connector's logic based on all the settings. Assign another value to override the settings.
Example

The following code will cause all Gigya interface elements to use French, overriding all other language settings:

function myimplementation_gigya_lang_alter(&$lang) {
	$lang = "fr";
}

Field Mapping

By default, the following fields will be imported from Gigya into Drupal for every user who logs in through Gigya:

  • Gigya User ID
  • Email
  • Name

How to Add Fields

To change the field mapping and add fields, edit the following line in the gigya.global settings file:

fieldMapping: {uuid: 'UID', mail: 'profile.email', name: 'profile.firstName'}

To map any additional user field from Gigya:

  1. Locate the Gigya user field you want to map.
    • The Account object (see documentation) contains general fields such as the Gigya UID, time created, last login etc.
      This object also contains:
      • The Profile object (see documentation), which holds personal data such as name, gender, age, address and more.
      • The Data object, which can be used to hold custom data about the user.
    For our purposes, you will refer to the field as 'fieldname' if it's in the Account object, 'profile.fieldname' if it's in the Profile object, and 'data.fieldname' if it's in the Data object.
  2. Find the appropriate field in Drupal or create a custom field if necessary.
  3. Add the mapping to gigya.global using the format <drupalfield>: 'gigyafield'. For example:

    fieldMapping: {uuid: 'UID', mail: 'profile.email', name: 'profile.firstName', lastname: 'profile.lastName'}

This method works for simple field types such as numbers and strings.

To map array or object fields, such as Gigya's profile.phones, or to add any advanced mapping functionality, use the field mapping hook.

Mapping Boolean fields also requires a hook, in order to map the true/false values provided by Gigya into the 1/0 values used in Drupal.

Name is a required field in Drupal.

How to Use Hooks for Advanced Field Mapping

The GConnector offers the following hook (see general note on hooks above) to enable you to create more complex field mapping:

Function Header
function hook_gigya_raas_map_data_alter(array &$gigya_data, User &$drupal_user, array &$field_map)
Parameters
  • $gigya_data: An array of user data fields in Gigya. Use $gigya_data['fieldname'] to get the value of a specific field in Gigya.

  • $field_map: An array of user data fields in Drupal. To set these fields, assign values to $field_map['fieldname'].

  • $drupal_user: An object representing the Drupal user (see user in the Drupal API). You can also assign values to fields in this object.

Example

 Say you have a custom 'gender' field in Drupal that is Boolean and contains 'true' for male users and 'false' for female users. You want to map the Gigya gender field to it, but the Gigya field contains 'm' for male, 'f' for female, or 'u' for unspecified. You can use the following code in the hook to map the values correctly:

function myimplementation_gigya_raas_map_data_alter(array &$gigya_data, User &$drupal_user, array &$field_map) {
	if ($gigya_data['profile.gender']=='m') {
		$field_map['gender'] = true;
	} elseif ($gigya_data['profile.gender']=='f') {
		$field_map['gender'] = false;
	}
}

 

 

Advanced Screen-Set Customization

How to Use Hooks to Customize the Login and Registration Screen-Sets

The GConnector offers the following hook (see general note on hooks above) to configure settings for the Login and Registration Screen-Sets.

Function Header
function hook_gigya_raas_settings_alter(array &$raas_login, array &$raas_register)
Parameters
  • $raas_login: Array of parameters for displaying the Login screen-set.
  • $raas_register: Array of parameters for displaying the Registration screen-set.

See the accounts.showScreenSet API documentation for more details and the list of available parameters.

Example

If you have defined custom screen-sets in Gigya that use different IDs than the default screen-set IDs, you can use the hook to point the Connector to the right Login screen-set by changing the 'screenSet' parameter. You can also define a separate screen-set to use for mobile devices.

function myimplementation_gigya_raas_settings_alter(array &$raas_login, array &$raas_register) {
	$raas_login['screenSet'] = 'RegistrationLogin-new';
	$raas_login['mobileScreenSet'] = 'RegistrationLogin-mobile-new';
}

How to Use Hooks to Customize the Edit Profile Screen-Set

The GConnector offers the following hook (see general note on hooks above) to configure settings for the Edit Profile screen-set:

Function Header
function hook_gigya_raas_profile_settings_alter(array &$raas_profile)
Parameters
  • $raas_profile: Array of parameters for displaying the Edit Profilescreen-set.

See the accounts.showScreenSet API documentation for more details and the list of available parameters.

Example

See How to Use Hooks to Customize the Login and Registration Screen-Sets.

Other Customization Options

Disabling RaaS

To disable RaaS without removing the Connector, you can edit the gigya.global YAML file to set enableRaaS to false.

Adding Global Parameters

The gigya.global settings file includes the globalParameters setting, which allows you to control the global parameters with which any call to Gigya will be made.

For the list of available parameters, see Gigya's Global Conf Object documentation.

globalParameters: {bypassCookiePolicy: 'never', enabledProviders: '*', sessionExpiration: 3600}

How to Use Hooks for Advanced Global Parameters Configuration

The following hook (see general note on hooks above) is offered by the Connector for adjusting any Gigya global parameters that cannot be controlled by other options and hooks.

Function Header
function hook_gigya_global_parameters_alter(array &$gigya_global_parameters)
Parameters
  • $gigya_global_parameters: Array of parameters governing global Gigya behavior in your site. 

Example

The following implementation of the hook adjusts the policy for dealing with blocked third-party cookies and changes the date format displayed by Gigya interface elements.

For more information on these and other Gigya global parameters see the Global Conf Object documentation.

function myimplementation_gigya_global_parameters_alter(array &$gigya_global_parameters) {
  $gigya_global_parameters['bypassCookiePolicy'] = 'never';
  $gigya_global_parameters['dateFormat'] = '%d/%M/%yy';
}

Managing Roles and Permissions

Gigya RaaS does not manage user roles (such as Administrator) or permissions. These are still managed by Drupal.

To manage roles and permissions, you should:

  • Log in via native Drupal login at domain.com/user.
  • In the Drupal admin console, go to People > Roles or People > Permissions.

Notes:

  • When logging in via domain.com/user, the login is not synchronized with RaaS. From Gigya's perspective, the admin user is not logged into the site.
  • If an admin adds/removes/edits a user via the Drupal admin console, these changes are not synchronized with Gigya.

Gigya Connector Permissions

By default, users of the Connector who hold the Administrator role in the Drupal system are granted the following Gigya permissions:

PermissionDescription
Gigya Major Admin

Ability to edit the Gigya Application Secret (see Entering Gigya Credentials in the installation guide). This permission enables you to restrict access to this sensitive field for added security.

Bypass Registration-as-a-Service

Use Drupal's native login instead of Gigya RaaS login. Any Drupal admin user must have this permission assigned. Site admins also need this permissions in order to access the Drupal admin console (see Enabling Native Drupal Login for Privileged Users).

Other users do not receive any of these Gigya permissions by default.

You may choose to create a role such as Gigya Editor, configure it with some or all of the Gigya permissions listed above, and assign the role to certain users.

  Enabling Native Drupal Login for Privileged Users

Immediately after you enable Gigya RaaS, only the main site admin will be able log in through the native Drupal login (domain.com/user).

To enable any other user to log in via native Drupal login, that user has to be granted a special permission. In addition, if that user has registered through RaaS, they have to be given a Drupal password.

The process is as follows:

  1. The user registers to the site through RaaS.
  2. The admin goes to People > Permissions and enables the Bypass Registation-as-a-Service permission for a desired role group, e.g. for Administrators.
  3. The admin goes to People, finds the new user and grants them the Administrator role (or any role that has the Bypass Registration-as-a-Service permission).
  4. The admin also enters a password for the user.
  5. The user can then go to domain.com/user and log in with the username and password that have been set by the admin.

UID-Based Sync

When syncing identity data between Gigya and Drupal, the UID-based sync uses the emails stored in Gigya's loginID. Note that Drupal uses email as an identifier.

Single Sign-On (SSO)

The GConnector supports Single Sign-On (SSO) between your Gigya-enabled sites. For more information about SSO, see Site Groups and Single Sign-On.

Logs

Gigya Connector reports are written to the default logging service as set in the Drupal platform.

The logs are available in two modes:

 Regular ModeDebug Mode
Errors in API calls to Gigya

Logged along with the native error message

Logged along with the native error message

Every call to Gigya API 

Call ID + Gigya API method logged for every call

To turn on Debug mode, edit the gigya.global YAML file to set the parameter gigyaDebugMode to true. To return to regular mode, set the parameter back to false.

In addition you may use Gigya's various Debugging Tools.

Troubleshooting

General

  • The server clock must be set to GMT+0, otherwise errors and unexpected behaviors may occur. We recommend using NTP daemon to ensure that the server time is accurate.
  • Gigya screen-sets must entirely replace any login, registration etc. screen provided by the CMS. The CMS registration, login and edit profile screens should not be rendered at all. Otherwise, the Gigya screen is placed inside the CMS screen and both will behave unexpectedly. 
  • After changing the value of the application key, you should re-enter the application secret.

 

 

 

 

 

 

 

 

 

 

Save

Save

Save

Save

Save

Save

Save

Save

Save

Save

Save

Save

Save

Save

Save

Save

Save

Save

Save

Save


  • No labels