AEM + GIGYA Integration

Statement: How to integrate AEM with GIGYA.
Solution:
Overview
Adobe Experience Manager is an enterprise-class content management system for building websites, mobile apps, and forms while delivering consistent experiences across all channels.

The Gigya module for Adobe Experience Manager enables you to add Gigya’s Registration-as-a-Service (RaaS) to your AEM sites quickly and easily
As well as leverage Gigya’s user profile data for content personalization and optimization.

Features
The module enables integrating Gigya’s Registration-as-a-Service (RaaS) with websites and apps built and maintained using AEM. This means connecting your AEM sites to Gigya's user database, including out-of-the-box flows for registration, login and profile management, and providing user management tools for the administrator.

The module synchronizes Gigya's entire offering of profile and social data about a site visitor into AEM, automatically syncing identity data from Gigya to AEM. The information includes complex data fields, such as a user's list of Likes or Favorites.

The Gigya information is made available through a Session Store named "Gigya Profile Data".
The following screenshot from CRXDE Lite shows a user who has logged in through Gigya. The Gigya data is available in the user's gigya folder:

The user's favorites can be found under gigya > favorites:

The following is an example of how complex fields will be rendered by the Client Context object (in this case, Likes that belong to the subcategory "Causes"):

Versions and Compatibility

• The Gigya module is compatible with AEM 6.1, 6.2, 6.3 and 6.4.
• The module requires Gigya’s RaaS. RaaS is a premium service that requires separate activation. If it is not part of your site package please contact your Gigya Implementation Consultant.

Limitations

• This integration does not support deleting users.
• To use a multisite configuration with multiple Gigya API keys in the same instance of AEM, all sites must have the same Gigya data center.

Setup and Configuration

To add Gigya to your site, complete the following steps:
1. Install the Gigya Package --> 

2. Add Gigya Core as a Cloud Service -->

3. Add the Cloud Service to Your Site -->
4. Configure Your Gigya Account for RaaS

1. Install the Gigya Module
Contact your Gigya Implementation Consultant for information on activating the Gigya integration.

The Gigya module is available as a package for AEM.
To install the package:

• Download the package from here:
• Gigya Developer Downloads
• 
  
• In your AEM server, go to the CRX Package Manager at /crx/packmgr/.
• Select the Upload Package in the top menu.

• Browse for the package file and upload it.
• The package now appears in the packages list. Select it and click Install.

2. Add Gigya Core as a Cloud Service
First, configure the Gigya Core Cloud Service with your implementation details:

1. Go to Tools > Operations > Cloud > Cloud Services.
2. Find Gigya Core and click its Show Configurations link.
3. Click the + icon to add a new configuration.
4. In the Create Configuration window, give the new configuration a title and click Create.
5. In the settings page that opens, click the Edit button to enter your integration settings (see parameter table below).

Required?	Setting	Description
	API Key	Copy and paste the API key that was generated in the Gigya console for your domain. To view the API key go to your Gigya Dashboard, open Site Settings for your site and click Show API key. For more information on viewing the API key or adding your site to the console, see Site Setup.
	Application Key	Enter an Application Key and Application Secret that you have created in Gigya. These credentials enable the integration to access and work with the Gigya database. See instructions for generating/finding your application key and secret.
	Application Secret
	Gigya Secret Key	Optional (not recommended): instead of entering an App Key + App Secret, it is possible to use your Gigya Secret. To view the Secret key go to your Gigya Dashboard and click the Show Secret key link next to your Partner ID at the bottom of the site list. If you enter your Gigya Secret, you can leave the App Key and App Secret fields empty.
	Gigya Data Center	The Gigya data center associated with your account, as it was selected in the Gigya console when you set up your site.
		The options are:
		us1.gigya.com for the US data center (default)
		eu1.gigya.com for the European data center
		au1.gigya.com for the Australian data center
		ru1.gigya.com for the Russian data center
		cn1.gigya-api.cn for the Chinese data center
	Enabled Providers	The social networks and other identity providers to be used for social login, e.g. “Facebook,Yahoo,Twitter”. The default * setting includes all available networks. For the full list of available providers, refer to the global configuration object page.
		Default: *
	Language	Select a supported language for display on your website, or let the module recognize the site language automatically (default)
		Default: Auto
	Advanced Configuration	This box enables you to specify configuration options beyond those available in the fields above, in JSON format. The required format is {"key1": "value1", "key2": "value2", ...} .
		For example, the following code sets values for the Global Configuration enabledProviders and shortURLs keys:
		1	{
		2	"enabledProviders":"facebook, twitter",
		3	"shortURLs":"whenRequired"
		4	}
		For the list of available configuration options, see Global Configuration.
	Path in AEM User Directory	Leave this empty to use the default directory: home/users/.
		Enter a directory name to save users to a sub-folder under home/users/, with a nested depth of 2. For example, enter MySite to have users saved under home/users/MySite plus two additional sub-folders.
		Enter a directory name to save users to a sub-folder under home/users/, and an AEM User Directory Depth, to save users to the specified path with the specified depth.
	AEM User Directory Depth	When using a user directory path, defines how many intermediate levels user creation should make (for performance reasons). If left empty, the default depth is 2.

3. Add the Cloud Service to Your Site

• In the main menu, select Sites.
• Hover over your site until the toolbar appears, and select the View Properties icon.
• Click the Edit icon on the top left.
• Select the Cloud Services tab.
• Click Add Configuration and select Gigya Core from the list.
• In the drop-down list that appears, select your cloud.
• Save your settings by clicking the Done (V) icon in the top left.

4. Configure Your Gigya Account for RaaS
(i) Make Sure RaaS is Enabled for Your Account
RaaS is a premium package that requires separate activation. If it is not part of your site package please contact your Gigya Account Manager.
(ii) Set Email to be the Primary User Identifier
Email is the required user identifier for an AEM site by default. To configure your 

Gigya account appropriately:

• Open the Policies section of Gigya's Console.
• Set Login Identifier to Email. This will make sure that Email is your site's unique login identifier.
• 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.

Select the Enable retrieving email addresses permission in the Permissions page in the console. This permission is not checked by default, and it is required in order to get the user's email as they register using a social network. Check any other permissions you need (see information about all the available permissions).

Edit your screen-sets to remove the Create new account link from the Link Account screen: Since AEM 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 a new account, click here at the bottom of the screen (see screenshot) 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 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.

Adding Gigya RaaS Components to Pages
Gigya RaaS elements will be available as components you can add to your pages.

To add RaaS components:

1. In the main menu, select Sites and select your site from the list.
2. Click the Open icon to open the site in Site Editor. Make sure you are in Edit Mode.
3. If you are using the new UI:

• Select the Components tab.
• Scroll down to the Gigya category and find the component you want to add: RaaS Login, RaaS Registration, or RaaS Edit Profile. Each component corresponds to a specific Gigya RaaS Screen-Set.
• Add the components using drag-and-drop.

    4. If you are using the old UI:
In the AEM window, click the Design icon.

• Find the section on the page to which you want to add the RaaS component and click its Edit button.
• In the Allowed Components list, check the Gigya category and save your settings.
• Back in the AEM window, there is now a Gigya category displaying three components – RaaS Login, RaaS Registration, or RaaS Edit Profile. Each component corresponds to a specific Gigya RaaS Screen-Set.

• Drag the component into your page.
• In the component's settings window, you can configure the following settings:

Screen-Set ID: if you have edited your screen-sets in the Gigya Console and changed the default names, enter the new name here.
Mobile Screen-Set ID (Optional): if you have a separate screen-set for mobile devices, enter its ID here. This is relevant for older sites or if you have created a mobile screen-set yourself. By default, sites that are set up in the Gigya console after October 2015 use the same (adaptive) screen-set for desktop and mobile devices.
Screen ID: if you have edited your screen-sets in the Gigya Console and changed the name of the initial screen in this screen-set, enter the new name here.
Embed: By default, the component will be displayed in the page as a link, which can be clicked by the visitor to open the screen-set in a pop-up box. Check this option if you want the screen-set to be embedded within the page, instead.
Link Text: The text of the link that will be shown if the screen-set is not embedded.


Make sure that the screen-set IDs you specify here match the screen-set IDs defined for your site in the Screen-Sets page in the Gigya console.See Default Screen-Sets for more information.

To make sure Gigya's cookies aren't blocked, add the cookie "gigyaLogout" to "optout.whitelist.cookies" under com.adobe.granite.optout (see more information).

Publishing to the Storefront
When you are done making changes, publish them to the storefront as follows:

1. Replicate the package:

• Go to the CRX Package Manager.
• Select the Gigya package and select More > Replicate.

1. Activate the page:

• Go to the page in the admin site and add /cf#/ to the URL as follows: http://localhost:4502/cf#/content/geometrixx-media/en.html
• Select Page > Activate Page

Field Mapping
The following Gigya fields are synced by default to AEM fields:

They can be removed from the Custom Gigya Schema Fields dialog option if preferred.
Important!
Any implementations using a GConnector prior to 6.3.1.3, when migrating, will be required to re-configure all fields.

Gigya Profile Field                   AEM Field
firstName                                   givenName
lastName                                    familyName
gender                                       gender
email                                         email
city                                            city
country                                      country
state                                          state
zip                                             postalCode
birthDay, birthMonth, birthYear    birthday

Gigya UID Based User Creation
By default, users are created using their Gigya email address and, if it does not exist, their username. On some Gigya setups where the same email is allowed multiple times, this causes issues with user creation and maintenance, so users may be created based on their GigyaUID instead. This can be configured by logging into AEM and navigation to:

http://localhost:4502/system/console/configMgr

Then search for the Gigya RaaS Login Module Configuration, as shown below:


Warning!
If migrating to the UID based user creation sync of Gconnector 6.3.1.3, all accounts created using the new method will be new users. This means that all existing user history will be deleted!

Mapping Gigya Fields to AEM
You can map existing Gigya fields to AEM by using the Custom Gigya Schema Fields tool. You can map from any existing fields that would be returned from accounts.getAccountInfo.
Important
When mapping from custom data fields, ensure that the fields exist in the Gigya schema prior to mapping them in AEM.



Define Mapping
Source Path
The Source Path is the location of the field within the Gigya response from accounts.getAccountInfo, i.e., path/to/field/in/json/fieldName. For example, if the location of the field in the Gigya response is subscriptions.mySiteSubscription.isSubscribed, you would enter it like the following:

subscriptions/mySiteSubscription/isSubscribed

Destination Path
The Destination Path is the location in AEM that the value of the Gigya field will be stored, i.e., path/relative/to/usernode/newAEMFieldName. 

For example:
gigya/customFields/siteSubscriptionActive

Once your fields are saved, they can be accessed manually via CRXDE | Lite.


Reformatting Mapped Data
To reformat data you have received from Gigya, for instance, if you need to concatenate the 3 Gigya fields that make up the user's birthday into a single field for AEM, you can use a Custom User Data Sync hook.

The “Custom User Data Sync” functionality is used to allow custom handling of fields when syncing data from Gigya to AEM. This hook is run synchronously after the default user data sync is run during login, registration, and when updating their profile.

To implement a custom user data sync service, simply implement the Interface GigyaCustomUserDataSyncService and make sure the new class is registered in OSGi as a service of that type. This interface has 2 methods, getRanking, and syncCustomUserData. The getRanking method is used to determine what order the custom user data sync services should be run, and the syncCustomUserData method contains any custom handling of the data.

Getting Started with Custom User Data Sync
To help you get started, please follow these steps (if using maven):

1. Install the connector onto your AEM instance
2. Copy the example implementation from below and place in your own codebase
3. Update the code to your needs
4. Confirm you include the Adobe Maven Repository in your maven settings.xml (https://helpx.adobe.com/experience-manager/kb/SetUpTheAdobeMavenRepository.html)
5. Install the module code to your local maven repository

• Download the Gigya-AEM osgi bundle below (under “Maven Dependency”)
• Install to the local repository (https://maven.apache.org/guides/mini/guide-3rd-party-jars-local.html)

    6. Build using maven and install a new bundle

Interface Name and Location
All Custom User Data Sync Services must implement:
com.gigya.aem/raas/GigyaCustomUserDataSyncService

Service Name
You may name the service however you like.

Function Name, File Path Classname
The Custom User Data Sync Service interface requires 2 methods:

1. public int getRanking()

• Used to order the execution of GigyaCustomUserDataSyncService implementations.

1. public boolean syncCustomUserData(org.apache.jackrabbit.api.security.user.User user, com.gigya.aem.core.constants.GigyaUserObject gigyaUser, javax.jcr.ValueFactory valueFactory)

• Used to order the execution of GigyaCustomUserDataSyncService implementations. Returns whether sync was successful.

Example Data Transformation
In the following code example, we will take the Gigya firstName and lastName fields and concatenate them together into a single displayName field.

try {

    log.debug("Syncing " + user.getPath() + " custom user data");

    GigyaUserObject.Profile profile = gigyaUser != null ? gigyaUser.getProfile() : null;

    if (profile != null) {

        String firstName = profile.getFirstName(),

        lastName = profile.getLastName();

        if (firstName == null)

            firstName = "";

        else

            firstName = firstName.trim();

        if (lastName == null)

            lastName = "";

        else

            lastName = lastName.trim();

        String displayName = firstName + (firstName.length()>0 && lastName.length()>0 ? " " : "") + lastName;

        user.setProperty("myCustomFields/displayName", createValue(displayName, valueFactory));

        log.debug("Setting myCustomFields/displayName to " + displayName);

        return true;

    }

} catch (RepositoryException e) {

    log.error("Error creating value for myCustomFields/displayName", e);

}

return false;

Resources
Maven Dependency

• Download .jar snapshot

File Example

• Expand Sample File

Using Gigya in Multi-Tenant Installations
The integration supports the following multi-tenant (multi-site) installation configurations:

AEM Configuration	Tenant Configuration	Required Setup Process
One Instance of AEM	Tenants in same domain, in different sub-domains or sub-directories, e.g.:	Set up one site in the Gigya console (tenants use the same Gigya API key).
	blog.company.com	Set up the Gigya integration in AEM normally.
	store.company.com	Gigya will share the same user database between the different sites, and AEM should be configured to share the same users between the different sites, too.
	company.com/blog
	company.com/store
Tenants in separate domains, e.g.:	Set up a site for each tenant in the Gigya console (each tenant gets a separate Gigya API key), under the same partner.
company.com	Define the sites as a a site group and connect via Single Sign-On (SSO).
company-store.com	Set up the Gigya integration in AEM normally.
	Gigya will share the same user database between the different sites, and AEM should be configured to share the same users between the different sites, too.
	If you want to keep separate user lists for your tenants, do not connect the sites through site group/SSO in the Gigya console.
	For this configuration to work, the sites in Gigya must all be defined with the same data center (US, EU, etc.).
Multiple Instances (Installations) of AEM	Any	Set up a site for each tenant in the Gigya console (each tenant gets a separate Gigya API key), under the same partner.
		Define the sites as a a site group and connect via Single Sign-On (SSO).
		In each AEM installation, add the Gigya package and configure with the site's specific Gigya API key.
		Gigya will share the same user database between the different sites, and AEM should be configured to share the same users between the different sites, too.

Locating the Logout URL for a Site Group
The logout URL is necessary in order to set up Single Sign-On (SSO) properly. See the User Logout for more information.
To find the logout URL:

• In the Web Console, select OSGi > Configuration.
• Search for "Apache Sling Authentication Logout Servlet".
• The logout path is located in sling.servlet.paths.name: it's either sling.servlet.paths.description or sling.servlet.paths.description/system/sling/logout.

Troubleshooting
General

• The server clock must be set to GMT+0, otherwise, errors and unexpected behaviors may occur. We recommend using the NTP daemon to ensure that the server time is accurate.
• Gigya screen-sets must entirely replace any login, registration, the 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.

AEM-Related Troubleshooting
If you are using NotSoSerial to mitigate serialization issues, make sure you include gigya.com in the whitelisting configuration so that the connector can function properly.

Reference: https://developers.gigya.com/display/GD/AEM