Using RaaS with Drupal

Skip to end of metadata
Go to start of metadata

Overview

Registration-as-a-Service (RaaS) is Gigya's end-to-end user management system. The following sections give instructions for using RaaS within your Drupal site.

Note that enabling Gigya RaaS will override Drupal's user management system. See the Drupal Configuration section below for more information.

Guide to Implementing RaaS

After installing the module (see Drupal 7 main page), you are ready to set up Gigya RaaS in your site.

To implement RaaS, complete the following steps:

1. (Optional) Migrate User Data

If you are already using Drupal user management, as a first step, you will need to migrate your Drupal user DB to RaaS. Please contact your Gigya Account Manager to perform this migration.

2. Configure RaaS in Gigya

Before you can use Gigya RaaS with Drupal:

  1. Make sure that RaaS is enabled for your site: RaaS is a premium package that requires separate activation. If it is not part of your site package please contact your Gigya Account Manager.
  2. Set Email to be the Primary User Identifier: Email is the required user identifier for a Drupal site by default. To configure your Gigya account appropriately:
    1. Log into the Gigya Admin Console, go to the Settings page for your site, select Registration-as-a-Service and select Policies or click here.
    2. Set Login Identifier to Email. This will make sure that Email is your site's unique login identifier (for more information on this setting see here).
    3. Set Link Accounts Support to All identities. This ensures email uniqueness: if any account in the system uses an email address that has been entered by the user as a login identifier, the user is prompted to link the social network to that account. Note: If your site was created before Feb 2015, upgrade your screen-sets in the Gigya console.
      Click to enlarge screenshot
    4. Select the Enable retrieving email addresses permission in the Permissions page in the console: This permission is required in order to get the user's email as he registers using a social network. This permission is not checked by default.
      Click to enlarge screenshot
  3. Edit your screen-sets to remove the Create new account link from the Link Account screen: Since Drupal requires a unique email per account, clicking this link would lead to an error, because it allows creating a second account with the same email.

    1. Go to the Screen-sets page in the Gigya console.

    2. Locate the Default-LinkAccounts screen-set and click its UI Builder link.

    3. In the UI Builder window's Screens list (on the left), select the Link Account screen.

    4. Locate the To create new account, click here at the bottom of the screen (see screenshot), and erase it by clicking the X next to it.

    5. Click the Save Button.

      Click to enlarge screenshot

  4. Edit your screen-sets to mark Email as a required field when completing registration: Even though you have specified that Email is the primary user identifier, it may not appear as a required field in the registration dialogs. To make sure, do the following:

    1. Go to the Screen-sets page in the Gigya console.

    2. Locate the Default-RegistrationLogin screen-set and click its UI Builder link.

    3. Go to the Registration Completion screen.

    4. Click on the Email text box in the design canvas to open its settings.

    5. Select the Required checkbox (see screenshot below). A red asterisk should appear next to the Email label to mark it as a required field.

    6. Click the Save button and close the UI Builder window.

      Click to enlarge screenshot

  5. Optional (recommended) - add a required and unique username field to RaaS: Drupal requires a unique username field. By default the module sets the username field in Drupal to be the user's email address. To promote privacy and enable users to define their own usernames, follow the instructions in Adding a Unique Required Username Field .

3. Configure Drupal for RaaS

To set up RaaS in Drupal, do the following:

  1. Make sure you have downloaded and installed the latest Gigya module for Drupal.
  2. In the Global Settings of the Gigya module (Administration > Configuration > Web services > Gigya Settings > Global Settings), make sure that the Gigya API Key field contains the key of a RaaS-enabled site.
  3. Go to the User Management settings of the Gigya module (Administration >Configuration >Web services >Gigya Settings > User Management) and select the Registration-as-a-Service radio button.

    Make sure that the screen-set IDs defined in your integration's settings match the screen-set IDs defined for your site in the Screen-Sets page in the Gigya console.

    • If your site was set up with Gigya after October 26, 2015, it will not be using any mobile-specific screen-sets for RaaS. In the integration settings, you should remove the mobile screen-set names (leave those fields empty).
    • If your site was set up with Gigya before September 2014, it will be using older screen-set names.

    See Default Screen-Sets for more information.

  4. Hide Drupal's default User Login block and show Gigya RaaS links instead:
    1. In Drupal, go to Administration > Structure > Blocks. Find the User Login block, and change the region to None.
    2. Make sure that Gigya login block is also hidden.
    3. Find the Gigya RaaS links block and select your preferred region. Our suggestion is to select the Header region, as shown below:
      Click to enlarge screenshot
  5. Optional (Recommended): Make sure that visitors can't register for accounts directly through Drupal. Go to Administration > Configuration > People and make sure that the Administrators only radio button is selected under Who can register accounts? The reason for this is that actions performed directly through the Drupal user management are not synched with the Gigya database.
  6. If you wish to hide user's Email addresses and use a username as a unique identifier, go to the Raas configuration panel under administration. From the Map Drupal username field drop-down, select RaaS username field . Make sure to set the username as a required field in Gigya's database, as explained in the Gigya configuration section.

Note on views: Working with user profile information within views is not supported.

4. (Optional) Customize RaaS Settings

The following settings are displayed for RaaS.

Make sure that the screen-set IDs defined in your integration's settings match the screen-set IDs defined for your site in the Screen-Sets page in the Gigya console.

  • If your site was set up with Gigya after October 26, 2015, it will not be using any mobile-specific screen-sets for RaaS. In the integration settings, you should remove the mobile screen-set names (leave those fields empty).
  • If your site was set up with Gigya before September 2014, it will be using older screen-set names.

See Default Screen-Sets for more information.

FieldDefault Description
Login/Registration Screen-SetsThe screens used for new user registration and existing user login. For more information, see the Screen-sets tool and the Default Screen-Sets. Changes to these settings require prior definition of screen-sets.
Web Screen Set IDDefault-RegistrationLogin

Name of a web screen-set containing the screens used in managing user login.

Sites installed before September 2014 should set this parameter to "Login-web".

Mobile Screen Set IDDefaultMobile-RegistrationLogin

Name of a mobile screen-set containing the screens used in managing user login.

  • Sites installed after October 2015 should delete this value and leave the field empty.
  • Sites installed before September 2014 should set this parameter to "Mobile-login".
Login Screen IDgigya-login-screenName of the initial user login screen. This is a screen defined in the web and mobile screen-sets (with the same name in both). The default screen-set uses the same screens with different CSS.
Register Screen IDgigya-register-screenName of the new user registration screen. This is a screen defined in the web and mobile screen-sets (with the same name in both). The default screen-set uses the same screens with different CSS.
Profile Screen-Sets The screens used for entering and updating user profile information.
Web Screen Set IDDefault-ProfileUpdate

Name of a web screen-set containing the screens used in entering user profile details.

  • Sites installed before September 2014 should set this parameter to "Profile-web".
Mobile Screen Set IDDefaultMobile-ProfileUpdate

Name of a mobile screen-set containing the screens used in entering user profile details.

  • Sites installed after October 2015 should delete this value and leave the field empty.
  • Sites installed before September 2014 should set this parameter to "Profile-mobile".

Link's Labels The labels of the links that will invoke the screen-sets.
LoginloginWithin Drupal's login page.
RegisterregisterWithin Drupal's Registration page.
ProfileprofileWithin Drupal's Profile page.
Post Login Redirect(no default)

This parameter defines where the users will be redirected to once they have successfully logged in to the site.

You can enter any URL, or leave the field empty. If the field is left empty, the page will reload after the user logs in.

Map Drupal username fieldRaaS email address

Options are RaaS email address and RaaS username field.

Drupal requires a unique username field. By default the module sets the field with the user's email. If you select RaaS username field, the Drupal username field will be set with the user's RaaS username. When selecting this option please make sure to define the username field in RaaS to be required and unique. Learn more in Adding a Unique Required Username Field.

Mapping RaaS Fields to Drupal Fields Gigya provides the ability to push user data fields from RaaS to Drupal, by mapping corresponding fields from Gigya (source) to Drupal (target). Read more in Updating Profile Data from Gigya to Drupal.

Enabling Registration-as-a-Service activates Gigya's complete user management feature. After completing configuration of RaaS, as explained in the Gigya configuration section, the standard Drupal login link will no longer appear. The RaaS login | register links will appear instead (assuming you have enabled the Gigya RaaS links block). Clicking them will open the RaaS login/register pop-up screen (see example below) to allow users to login/register using RaaS.

Note:

  • To access the Drupal dashboard after activating Gigya's RaaS enter /user after your site's URL, as in http://www.example.com/user
  • If you use Gigya RaaS, you will not be able to remove user accounts through the Drupal dashboard (user accounts that you delete through the Drupal dashboard will not be removed from the RaaS database).

Setting Up Field Mapping

The Gigya module supports pushing data from RaaS user fields into Drupal user entity. Among other things, this data may be used by the Acquia Lift service, which can be used by Drupal websites to target specific content to the most relevant website visitors and provide a personal and contextualized user experience.

Site administrators can define mapping between Gigya account fields and Drupal fields.

You can import data into Drupal's built-in user entity fields, or create new custom fields and populate them by mapping from the fields in RaaS. The Gigya module can also populate native fields from the Profile2 module.

Once mapped, the Drupal fields will be populated and updated from the corresponding RaaS fields each time:

  • User registers/logs in.
  • User updates their profile (using RaaS update profile screen)
  • It is not mandatory to map Gigya's UID field to a Drupal field, but recommended. Mapping the UID enables using this field in Drupal reports and when working with 3rd party platforms (e.g., Lift).
  • Gigya stores the UID field in a table called gigya_ids, for the purpose of session management. This has no relation to the field mapping you define.

 

To map fields:

  1. In the Drupal administration panel, go to Administration > Configuration > Web services > Gigya Settings > User Management.
  2. Expand the Mapping RaaS Fields to Drupal Fields section.
  3. To map a pair:
    1. In the Source (RaaS) dropdown list, select a Gigya field.

      The Gigya fields in the Source (RaaS) dropdown list are divided into three categories, based on the way Gigya stores different types of user information:

      • Account - general data about the Gigya user account. Currently, this category includes the UID field.
      • Profile - personal user data fields such as first and last name, age, address etc. See the Profile object documentation for more information.
      • Data - custom fields.
    2. In the Target (Drupal) dropdown list, select the corresponding field in Drupal.

      In Drupal, the name (username), email, user ID and Status fields can not be populated or modified after registration, hence they will not appear in the Target (Drupal) dropdown list.

    3. Select Add. The new mapping is added to the Mapped Fields table in the same section.

  4. When you are done mapping all the fields you need, select Save Configuration.

Click to enlarge screenshot

 

To remove a mapping:

  1. In the Mapped Fields table, select the checkbox next to the pair(s) you want to remove.
  2. Select the Save configuration button.

Once you have mapped RaaS fields to corresponding Drupal Fields, you can configure the Acquia Lift Drupal Module to personalize your website and dynamically provide contextualized content according to the values passed in to Drupal from the RaaS fields. This means you can run campaigns with personalized content based on fields like age, gender, zip code or any other field that maps from the RaaS to a Drupal field.

For more information on how to create campaigns with personalized content and more, please refer to the Acquia Lift documentation.

Supported Data Types and Data Type Conversion

Field values from Gigya will be converted into the data type set for the field in Drupal.

Supported Drupal data types: 

  • int
  • string
  • bool
  • Date (unix timestamp)
  • Date (ISO Format)
    Note: The Drupal field type "date" is not supported for conversion. Values from Gigya can be synchronized into this type of field as simple strings.

Date/time values from Gigya are in the UTC 0 timezone and will be synchronized to Drupal as such. Drupal will display these values according to the system timezone settings.

Creating Custom Fields in Drupal

In order to create new custom fields in Drupal, go to Configuration > People > Account Settings and click on the Manage Fields tab in the top right side of your screen. Now all you have to do is go to the Add new field row, name the field you wish to create, and select a type for it. For example, if I want to map the user's physical address, I will name the field Address and give it a type of text to match the it's corresponding type in Gigya (String). Go to the profile object page to view a list of RaaS profile fields and their data types.

Click to enlarge screenshot

Once you are done, click Save to save the newly created fields.

Newly added profile fields will appear only after the cache is cleared.

Mapping Profile Image (Avatar)

Importing users' profile images to Drupal requires you to create a new user entity field and map it to the user's photo URL field in RaaS. You shouldn't map Drupal's default avatar field, since this field is designed to hold a pointer to an image in Drupal file system, while RaaS's profile.photoURL field hold a URL to the user's profile image. Follow the steps explained in the Drupal field creation section to create a new text field in Drupal that will hold the user's profile picture URL. Lets say your new field is called field_profile_image_url. Map RaaS's profile.photoURL field to your newly created field_profile_image_url field as explained in the Mapping RaaS Fields to Drupal Fields section. This will make sure that the field_profile_image_url field will hold the user's profile picture URL. Now you can use this field throughout your site to display the user image.

Setting Up Admin Users, Roles and Permissions

RaaS provides a user management system but does not manage user roles and permissions.

Therefore, site admins should:

  • Log in via native Drupal login at domain.com/user.
  • Manage user roles and permissions via the Drupal admin console at (Administration > People).

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.

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 Administration > People > Permissions and enables the Bypass Registation-as-a-Service permission for a desired role group, e.g. for Administrators.
    Click to enlarge screenshot
  3. The admin goes to Administration > People, finds the new user and grants them a role that has the Bypass Registration-as-a-Service permission.
  4. The admin also enters a password for the user.
    Click to enlarge screenshot
  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.

Advanced Customization

Embedding RaaS Screen-Sets within a Page

By default, Gigya's RaaS screen-sets are designed to be popup dialogs.

If you wish to embed them within a page, do the following:

  1. Add a RaaS block to the area of your choice.
    In /admin/structure/block you may find the following Gigya blocks:
    • Gigya embedded RaaS login screen
    • Gigya embedded RaaS registration screen
    • Gigya embedded RaaS profile screen
    Each of these blocks shows the corresponding RaaS screen-set embedded. You may add each of these block to the area of your choice.
  2. Remove the Gigya RaaS links block from the header.

To customize the look and feel of the Gigya RaaS links, you may use the following CSS classes:

  • gigya-raas-login - to customize the login link
  • gigya-raas-reg - to customize the registration link
  • gigya-raas-prof - to customize the profile link

For example, the following link opens the login screen when it is clicked :

<a href="#" class="gigya-raas-login">Sign-in</a> 

Adding a Unique Required Username Field

To enable users to define their own usernames, thus promoting privacy, do the following:

In the Gigya system, add a username text field to your Registration and Registration Completion RaaS screens:

  1. Log into the Gigya Admin Console and go to the Screen-sets page.
  2. Locate the Default-RegistrationLogin screen-set and click its UI Builder link.
  3. In the UI Builder window's Screens list (on the left), select the Registration screen.
    1. Drag a new textbox into the screen (from the Controls on the bottom left).
    2. Click on the textbox to select it. Its details will appear on the right under Properties (see image).
    3. Change the Mapped Field to Special Fields > username; change the Label to Username. Tip: the field is actually mapped to profile.username, but the Special Field identifies it as a login ID.
      Click to enlarge screenshot
  4. Repeat the stage 3 procedure in the Registration Completion screen.
  5. Select the Save button.

Make sure that the screen-set IDs defined in your integration's settings match the screen-set IDs defined for your site in the Screen-Sets page in the Gigya console.

  • If your site was set up with Gigya after October 26, 2015, it will not be using any mobile-specific screen-sets for RaaS. In the integration settings, you should remove the mobile screen-set names (leave those fields empty).
  • If your site was set up with Gigya before September 2014, it will be using older screen-set names.

See Default Screen-Sets for more information.

In the Drupal configuration, in the Registration-as-a-Service Settings, set the Map Drupal username field to RaaS username field.

Connectivity between RaaS fields and Drupal tokens

You may define Drupal tokens that extract their values from RaaS fields

Click to enlarge screenshot

To add tokens that extract their values from RaaS custom data fields use the hook_gigya_tokens_alter (see the definition in gigya.api.php). For example:

function my_module_gigya_tokens_alter(&$replacements, $tokens, $gigya_user_info) {
  //When using RaaS you would have the custom data fields under data
  $replacements['[gigya:subscribe]'] = $gigya_info['data']['subscribe'];
}

Save