Using Registration as a Service (RaaS) with WordPress - gigya/wordpress GitHub Wiki

Overview

Registration-as-a-Service (RaaS) is Gigya's end-to-end user management system package. The Gigya WordPress plugin supports all of its features. Using RaaS within a WordPress site requires several administrative steps that are detailed in this document.

Note that RaaS within WordPress replaces and overrides the WordPress user management system.

To access the WordPress dashboard and sign in as an administrator, after activating Gigya's RaaS, enter /wp-login.php?admin=true after your site's URL, as in http:///wp-login.php?admin=true.

Setup and Configuration

Migrating User Data

If you are already using WordPress user management, you will need to migrate your WordPress user database to RaaS. Please contact your Gigya Customer Engagement Executive to perform this migration.

Gigya Configuration

  • 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 Customer Engagement Executive.

  • Set Email to be the Primary User Identifier:

    Email is the required user identifier for a WordPress 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.

    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.

    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 they register using a social network. This permission is not checked by default.

    • Edit your screen-sets to remove the Create new account link from the Link Account screen:

      Since WordPress 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.

      • Go to the Screen-sets page in the Gigya console.
      • Locate the Default-LinkAccounts screen-set and click its UI Builder link.
      • In the UI Builder window's Screens list (on the left), select the Link Account screen.
      • Locate the To create new account, click here at the bottom of the screen (see screenshot below), and erase it by clicking the X next to it.
      • Click the Save button.

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

      • Go to the Screen-sets page in the Gigya console.
      • Locate the Default-RegistrationLogin screen-set and click its UI Builder link.
      • Go to the Registration Completion screen.
      • Click on the Email text box in the design canvas to open its settings.
      • Select the Required checkbox (see screenshot below). A red asterisk should appear next to the Email label to mark it as a required field.
      • Click the Save button and close the UI Builder window.

    • Optional (recommended) - add a required and unique username field to RaaS:

      WordPress requires a unique username field. By default, if a username field is not provided from RaaS, or is not unique, the module generates a unique username field based on the user's first name and an additional string, to make it unique. To enable users to define their own usernames, follow the instructions in Adding a Unique Required Username Field to the RaaS Registration Flow.

Initial WordPress Configuration

  • The Gigya WordPress plugin must be installed.

  • Your site's Gigya API keys must be entered in the Gigya plugin's Global Settings tab.

  • Go to the Gigya plugin's User Management Settings tab, select the Registration-as-a-Service radio button.

    Note: 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 Gigya RaaS was set up in the Gigya Console after 10/26/2015, it is using new default screen-set names, which do not match the screen-set names used by this integration out-of-the-box. To set up your integration to use the correct screen-sets names, go to your integration settings and select Registration-as-a-Service settings. In the screen-set IDs table, copy the ID of every Web Screen-Set into the matching Mobile Screen-Set. For example, in the integration's default settings, the Registration/Login screen-sets are set to Default-RegistrationLogin and DefaultMobile-RegistrationLogin, for web and mobile, respectively. They should both say Default-RegistrationLogin.

    - If your site was set up in the Gigya console before September 2014, it will be using older screen-set names.

    See Default Screen-Sets for more information.

To test your screen-set settings, go to your front-end site, find the WordPress default Meta block, and click the Login link. This link should pop up the RaaS login screen.

In addition, a RaaS screen-set replaces WordPress's default login UI at /wp-login.php. When you go to /wp-login.php, instead of seeing WordPress default Login UI:

You will see the RaaS Login screen:

To further customize your RaaS implementation, please refer to Registration-as-a-Service settings and Advanced Customization.

Customizing Your RaaS Implementation

In your WordPress dashboard, under Gigya > Screen-Set Settings, you will find options that enable you to customize your Customer Data Cloud implementation.

Here you can set which screens the GConnector will use for the associated actions.

  • Login/Registration Screen-Sets:

    This section enables you to specify your login/registration screen-sets if you are not using the default ones provided by Gigya. These screen-sets will be displayed instead of WordPress's default UI for login and registration. There is a login/registration screen-set for web and one for mobile devices. In addition, if you are not using the default screen-sets, you should specify the names of the specific screens for login and for registration. For more information, see UI Builder and Default Screen-Sets.

  • Profile Screen-Sets:

    This section enables you to specify your profile screen-sets if you are not using the default ones provided by Gigya. These screen-sets will be displayed instead of WordPress's default UI for displaying and editing the user profile. For more information, see UI Builder and Default Screen-Sets.

  • DIV IDs:

    By default, Gigya's RaaS screen-sets are embedded in the site in place of the original WordPress forms for login, registration and editing profiles. This is accomplished by finding the DIV elements that are known to contain these forms and replacing the original forms with RaaS screen-sets. The DIV IDs listed here must match the DIV IDs that actually appear in your site's HTML files. If you use a custom theme that has different names for the login, registration and edit profile DIVs, you must enter these names here for this feature to function.

  • Mapping Gigya User Fields to WordPress Fields:

    See full explanation in Mapping Additional Profile Fields from RaaS to WordPress below.

  • Admin Login Roles:

    See full explanation in Admin Users, Roles and Permissions below.

Mapping Additional Profile Fields from RaaS to WordPress

RaaS overrides WordPress User Management. The user profile is managed by RaaS, and some basic user profile are mirrored in WordPress's user database.

The following WordPress profile fields are required by WordPress, and so are automatically created and mirrored, regardless of configuration:

  • Email
  • Password
  • Username

On top of the basic required fields, you may configure which additional fields to map. Configuring mapped fields instructs the Gigya plugin to push data from RaaS Profile fields into WordPress user fields.

To configure this, go to WordPress Admin Panel under the Gigya entry select the User Management Settings tab, and roll down till you find the Mapping Gigya User Fields to WordPress Fields section. This section gives you the option to select which of the following WordPress user fields should be populated and updated from the RaaS Profile fields:

All of the above fields are selected by default, and therefore mapped (since Gigya-WordPress plugin version 5.1).

Once mapped, the WordPress field will be populated and updated from the RaaS field each time a user registers, logs in or updates his profile (using RaaS update profile screen).

Advanced Mapping - Using Hooks

If you want to mirror additional fields, such as custom fields, you can do so using the gigya_after_raas_login hook. Learn more about Gigya hooks [here]here.

In the following example, we update the age field from RaaS Profile object into WordPress's user entity. The update will occur each time the user logs in to the site:

    add_action( 'gigya_after_raas_login', 'gigyaAfterRaasLogin', 10, 2);
    function gigyaAfterRaasLogin( $gig_user, $wp_user ) {
    // Update the WordPress nickname from Gigya’s nickname.
    update_user_meta( $wp_user->ID, 'age', $gig_user['profile']['age'] );
    }

Please note that an age field does not exist out of the box in WordPress's user entity, and in order for the following example to work, you would need to add an age field to the WordPress user entity.

Admin Users, Roles and Permissions

By default, the RaaS integration embeds the RaaS login screen-set in the same DIV ID that is used for the WordPress login UI.

To access the WordPress dashboard and sign in as an administrator after activating Gigya's RaaS, enter /wp-login.php?admin=true after your site's URL, as in http:///wp-login.php?admin=true. Adding the ?admin=true overrides the above behavior, and brings back the WordPress login UI instead of RaaS.

Users that have Administrator role or Super Admin roles are allowed to log in via the WordPress default login UI. In addition to these roles, only the roles that are configured under Admin Login Roles will be allowed to log in via WordPress default login UI:

You may configure Admin Login Roles under the Registration-as-a-Service settings (within the WordPress Admin Panel under the Gigya entry).

Custom roles will be listed bellow the out-of-the-box WordPress roles (Author, Contributor, and Editor). You will not find the Subscriber role under the Admin Login Roles configuration, since Subscriber role is never allowed to log in via the WordPress default login UI. The reason for the limitation is - site users (end users) should always register&login using via RaaS screen-sets. Logging-in via WordPress default login would create inconsistency and harms the systems integrity.

RaaS provides a user management system but does not manage users' WordPress roles and permissions. Manage your users' roles and permissions via the WordPress Dashboard. Note that if an admin adds or edits a user in the WordPress dashboard, these changes are not synched with the Gigya database.

It is possible, though not recommended, to expose the WordPress default login UI on /wp-login.php (without adding the ?admin=true). To do that, change the default login DIV ID under the Registration-as-a-Service settings. Note that only the roles that are configured under Admin Login Roles will be allowed to log in via WordPress default login UI.

Using the Gigya RaaS Widget

Enabling RaaS in your WordPress site enables the RaaSwidget, which you can use to add a customized Login link anywhere in your site.

To use the widget:

  1. Go to Appearance > Widgets. If RaaS is enabled, the RaaS widget should be listed along with the other Gigya widgets.

  2. Click the Gigya RaaS widget.

  3. Select the location of the widget in the page and click the Add Widget button.

  4. The widget is added to the location you chose and a settings box is displayed. You can enter a Title for the link and/or choose Override to specify a custom height and width for the widget.

For details about the other widgets provided by the Gigya plugin, see Adding the Gigya Widgets to Your Site.

Using the Gigya Custom Screen-Set Widget

To use pre-configured Gigya custom screen-sets in WordPress, a widget should be created with the relevant screen-set configuration.

To add the widget:

  1. Go to Appearance > Widgets. Add the Gigya Custom Screen-Set widget to the relevant UI element (follow the below steps).

  2. Click the SAP CDC Screen-Set widget.

  3. Select the location of the widget in the page and click the Add Widget button.

The widget is added to the location you chose and a settings box is displayed.

For details about the other widgets provided by the Gigya plugin, see Adding the Gigya Widgets to Your Site.

Using the Gigya RaaS Shortcodes

The Gigya plugin provides a set of shortcodes as an alternative means for embedding Gigya's WordPress Widgets in your site. Using shortcodes allows a greater degree of flexibility in the placement and usage of Widgets on WordPress sites.

The RaaS-related shortcodes are:

  • [gigya-raas-login] - displays a RaaS widget that consists of two links: Login and Registration. Each link opens the corresponding RaaSscreen. The widget is displayed only for users who are not logged in, and it disappears once they log in.

  • [gigya-raas-profile] - displays a RaaS profile widget that includes the user's avatar and name as well as a Log Out link. The name is a link, and clicking it opens the RaaS Update Profile screen-set. This widget is displayed only for users who are logged in, and it disappears once they log out. There are no parameters for this shortcode, but you may customize its appearance using CSS.

These shortcodes will not work if the RaaS plugin is disabled in the Dashboard.

For details about the other shortcodes provided by the Gigya plugin, see Using Gigya's WordPress Shortcodes.

Adding a Unique Required Username Field to the RaaS Registration Flow

To enable users to define their own usernames, thus promoting privacy, 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 (see image), select the Registration screen.

    • Drag a new textbox into the screen (from the Controls on the bottom left).

    • Click on the textbox to select it, its details will appear on the right under Properties (see image).

    • Change the Mapped Field to Special Fields > username and change the Label to Username. Tip: the field is actually mapped to profile.username, but the Special Field identifies it as a login ID.

  4. Repeat the stage 3 procedure in the Registration Completion screen.

  5. Click the Save button.