Umbraco 7

Skip to end of metadata
Go to start of metadata


Overview

Umbraco is a leading .NET-based open source content management system that offers flexibility and a friendly, easy-to-use interface. The GConnector for Umbraco 7 is designed to help you implement Gigya RaaS in your Umbraco websites as quickly and easily as possible.

Versions and Compatibility

  • The Gigya Connector is compatible with Umbraco 7.2 and above (see Umbraco setup instructions).

  • Gigya RaaS is a premium service that requires separate activation. If it is not part of your site package please contact your Gigya Implementation Consultant.

Installation and Implementation Guide

 

1. Set Up Your Gigya Account

Before you begin setting up the Gigya Connector in your site, do the following:

  • Set up your Gigya account for RaaS (see guide).
  • Create an Application Key and Application Secret in the Gigya Console (see instructions).

2. Install the Gigya Package

After you have set up an Umbraco site, install the Gigya package as follows:

  1. Download the package here: Gigya_1.0.0.2.zip
  2. Navigate to the Developers section and expand Packages.
  3. Select Install local package:
    Click to enlarge screenshot
  4. Select Choose File and browse to the package .zip file.
  5. Accept the warning and select Load Package.
  6. Select Accept license and then Install Package.

The site should restart and the Gigya package will be installed.

3. Enable the Gigya Section for Selected Users

To enable the Gigya section for some users:

  1. Go to the Users section and expand the Users node.
  2. Select a user and check the Gigya section for that user (see image).
    Click to enlarge screenshot
  3. Save the user and refresh the page. You can now access the Gigya section.

All members created by the Gigya Connector will use the Member member type by default. To change this add an AppSetting with the key of umbracoMemberTypeAlias.

4. Create an Encryption Key

The GConnector encrypts your Gigya credentials using AES and stores them securely in the database.

In order to do this, you need to provide a secret string – this can be any string you want. The Gigya Connector will create an encryption key based on this string and use it to encrypt your Gigya credentials.

To provide the string:

  1. Go to your site's root directory and edit the web.config file.
  2. Choose one of the following options:
    • Option 1: Specify the string directly in the web.config file by adding a line like the following in the <appSettings> section. Instead of "my secret" enter a string of your choice.

      <add key="Gigya.Encryption.Key" value="my secret" />
    • Option 2: Specify the full path or relative path to a text file that contains the secret string by adding a line like the following in the <appSettings> section. You specify a relative path by using a tilde "~", e.g.: ~/App_Data/key.txt.:

      <add key="Gigya.Encryption.KeyLocation" value="\\server1\share\key.txt" />
  3. Save your changes.

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 CMS configuration settings.

5. Configure Gigya Connector Settings

In the Umbraco dashboard, go to the Settings section, select the Gigya section on the left and select your site.

See the table below for descriptions of all the parameters in this page.

Click to enlarge screenshot

 

Required

Parameter Name

Description

API Key

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

Application Key

The Gigya Application Key that the Gigya Connector will use to connect to Gigya. See instructions for creating an Application Key.

Application Secret

The Gigya Application Secret that was generated for you along with the Application Key.

This value will be encrypted in the database.

Language

Select the language that Gigya interface elements, such as screen-sets, will be displayed in.

Special options:

  • Select Other if your desired language does not appear in the list but it is supported by Gigya (e.g. a language that Gigya added after the current version of the Gigya Connector was released). You will then be able to enter the language code in a text box.
  • Select Auto to have the Gigya Connector choose the language based on the page language in the CMS.

Default: English.

Language Fallback

If you have set Language to Auto, select the language to be used if the page language is not supported by Gigya. Default: English.

For a list of the languages in which Gigya is available see Advanced Customizations and Localization.

Data Center

Select the Gigya Data Center with which your site is associated. If your site's Data Center is not on the list, select Other and specify the URL of your Data Center in the text box that is displayed. See Finding Your Site's Data Center for more information.

Redirect URL

A URL that the user will be redirected to after logging in or registering. If left blank, the current page will be reloaded.

Logout URL

A URL that the user will be redirected to after logging out. If left blank, the current page will be reloaded.

Session ManagementSelect whether user login sessions are led by Gigya or by the CMS. If Gigya leads the session, you may also want to configure the session expiration. If the CMS leads the session, some additional configuration may be required.

Session Expiration

The maximum Gigya login session length (in seconds). Default is 0, meaning that when Gigya manages the session, the user session expires when the browser is closed. See Session Management and Expiration below for more information. When the session is led by the CMS, you should set a relatively long Gigya session.

Global parameters

Any extra parameters to configure Gigya. These parameters will set Gigya's Global Conf object and should be specified in JSON format. See the Global Conf documentation for information on which parameters are available. For example:

{ "enabledProviders": "facebook,twitter" }

Global Parameters settings override any other settings. For example, if you set a session expiration value using the Global Parameters field, this will override whatever you set in the Session Expiration field. Use this field carefully.

Field Mapping

A table specifying which Gigya user data fields will be imported into the CMS. See the Field Mapping section below.

Debug Mode

Check to write debug information to the logs. See the Logs section below.

Enable Module

Uncheck to disable the Connector and prevent Gigya widgets from being rendered. Keep this checked to allow the Connector to work.

Save

Save

Save

Save

Save

Save

Save

Save

Save

Save

Save

Save

Save

Save

Save

Save

Save

Save

The Application Secret is only manageable by Administrators.

Multisite and Global Settings

In a multisite environment you can use the global settings page to configure multiple sites quickly. All your sites will inherit the global settings automatically (you can configure different settings for individual sites).

To configure global settings:

  1. In the Umbraco dashboard, go to the Settings section, select the Gigya section on the left and select Global Settings.
  2. Configure your settings as needed and click Publish.

If you have one or more sites that require their own settings, different from the global ones, configure them as follows:

  1. In the Umbraco dashboard, go to the Gigya tab, expand Settings and select your site.
  2. Uncheck the "Inherited from Global Settings" checkbox.

  3. Specify the settings for the site as needed and click Publish.

Session Management

User login sessions can be managed either by Gigya or by Umbraco. Generally, managing the session means that the period in which the user is logged in is determined by the configurations of the managing system. For example, if Gigya is the session manager, and the Gigya session is terminated (e.g. the browser was closed) even though the time-dependent Umbraco session is still running, Gigya will end the Umbraco session.  In the same manner, if the user is logged into Gigya but not into Umbraco, Gigya will log the user into Umbraco. 

To choose the session manager: 

  1. In the Gigya section, open the relevant settings page (usually the global settings page). 
  2. Under Session Management, choose the session manager. The default is Gigya. 

Gigya-Managed Session

You can set the maximum length of the user session under the Session Expiration field, or in the Global Parameters, whose definitions override all other definitions. Both are defined in the Gigya Settings screen. 

  • Session Expiration: By default, Session Expiration in Gigya 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 length (in seconds).
  • Global Parameters: Enter a value for the sessionExpiration parameter in JSON format:

    Unknown macro: { "sessionExpiration"}

    This will set the sessionExpiration parameter in Gigya's Global Conf object. See the Global Conf documentation. 

Umbraco-Managed Session

To define the Umbraco session: 

  1. Open the web.config file
  2. In the system.web section, find the sessionState element and within the element, make sure there is a timeout attribute with a value (in minutes). If it isn't there, add it manually: 

    <sessionState timeout="15" />
  3. In the <authentication> element which includes the Forms attribute, add the following definitions: 

    • timeout: The length of the session in minutes. 

    • slidingExpiration: Defines whether the session is fixed or sliding. Set to true or false. For example: 

      Example
      <authentication mode="Forms">
      	<forms name="yourAuthCookie" loginUrl="login.aspx" protection="All" path="/" timeout="5" slidingExpiration="true" /> // Sets the session to 1 minute long and defines it as a sliding session.
      </authentication>

When Umbraco manages the session, it is mandatory to set a specified time to the Gigya session as well, i.e., do not leave the Session Expiration definition set to zero. Either define a value for it, or define session expiration in the global parameters. When Umbraco leads the session, we recommend defining the Gigya session to be at least as long as the Umbraco definition and preferably longer.

6. Implement Gigya Macros

The Gigya Connector creates the following macros:

MacroDescription
Login

Displays the Gigya RaaS screen-set of the same name (see RaaS - Default Screen-Set Flows for an introduction to these screen-sets).

You can choose between two display options (see macro options below):

  • Display a button which, when clicked, opens the screen-set in a popup window
  • Display the screen-set embedded in the page.
Register
Edit Profile
LogoutDisplays a welcome message and a button which, when clicked, logs the user out.

 

 

Page with Login Macro as Popup

Click to enlarge screenshot

 

Page with Register Macro as Popup

Click to enlarge screenshot


Page with Register Macro Embedded

Click to enlarge screenshot


Each of these macros can be implemented using the Umbraco Grid or by adding to a view file.

How to Implement Macros through the Grid

  1. In the Developer section, expand Data Types and find the grid data type you want to change.
  2. Select a row configuration.
  3. Enable macros (see the relevant Umbraco documentation for more information).
  4. Go back to the Content section and select the + icon to add a control.
  5. Select Macro.
  6. Choose one of the Gigya macros.

  7. Select the macro options.

    For the Login, Registration, and Edit Profile macros, you are presented with the following options:

    OptionDescription
    Button LabelIf you want the macro to display a link which, when clicked, opens the screen-set in a popup window, you can use this option to change the text of the link.
    Container ID

    If you want the macro to be rendered directly on the page (embedded), you can either:

    • Use the Container ID field to specify the ID of an HTML container (such as a <div>) in which the screen-set will be displayed
    • OR check the Generate Container checkbox to have a container generated automatically. The screen-set will be rendered on page load.
    Generate Container
    Screen-SetIf you have created custom screen-sets for login, registration, and/or profile editing, enter the name of the screen-set here. See UI Builder for more information.
    Mobile Screen-SetIf you have created a separate screen-set for mobile devices, enter the name of the screen-set here. By default, Gigya uses the same (responsive) screen-sets for desktop and mobile screens.
    Start ScreenTo start the flow in a different screen than the default start screen of the screen-set, enter the name of the screen here.

    The Logout macro has the following options:

     OptionDescription
    Button LabelSpecify the label of the logout button (default: "Logout").
    GreetingThe greeting displayed to the user before the Logout link.

How to Add Macros Directly to a View

If you don’t want to use the grid you can add the macros directly in your MVC view file by inserting the following commands:

Login

@Umbraco.RenderMacro("GigyaLoginButton")

Register

@Umbraco.RenderMacro("GigyaRegisterButton")

Edit Profile@Umbraco.RenderMacro("GigyaEditProfile")
Logout

@Umbraco.RenderMacro("GigyaLogoutButton")

The macro code files (GigyaLoginButton.cshtml, GigyaRegisterButton.cshtml, GigyaEditProfile.cshtml, and GigyaLogoutButton.cshtml) are located in the <project root>/Views/MacroPartials folder and can be viewed and modified.

Important: You must add the following line to the head section of the master layout. This calls the Gigya JavaScript code which has to run on all pages.

 @HTML.Action("Index", "GigyaSettings")

Customization

Field Mapping

By default, the Gigya Connector mirrors the following data fields from Gigya to Umbraco for every user:

  • Gigya UID (this field is mandatory)
  • First name
  • Last name
  • email

To have additional fields mirrored into Umbraco:

  1. In the Umbraco admin console, go to the Settings section and select the Gigya section on the left.
  2. Under Field Mapping, click Add.

  3. Specify the Gigya field name that you want to mirror, e.g. profile.gender.

    Gigya offers a variety of user data fields, divided into three objects:
     DescriptionHow to Refer to These Fields
    Account object (see documentation)The main Account object contains general fields such as the Gigya UID, time created, last login etc.
    It also contains the Profile and Data objects.
    <fieldname>
    Profile Object (see documentation)Holds personal data such as name, gender, age, address and more.profile.<fieldname>
    Data objectCan be used to hold custom data about the user.data.<fieldname>

    The field you specify cannot be a complex object or array such as profile.phones. To map arrays and objects, use a hook function (see Using Hooks for Advanced Field Mapping).

  4. Specify the name of the Umbraco field into which you want to mirror the data. If you want to map a Gigya field that does not have a corresponding built-in field in Umbraco, you have to create a custom field first. See the Umbraco documentation for information about member data fields.

Notes:

  • If the field type in Gigya doesn't match the field type in Umbraco, the Connector will cast the value into the Umbraco field type.
  • In a multisite environment, you have the option of setting a global field mapping, and then overriding it for specific sites that need their own mapping.

Using Hooks for Advanced Field Mapping

Before a field value from Gigya is saved to Umbraco it can be modified by using a custom event. This allows you to customize your field mapping even further and to deal with complex object fields and/or fields that require reformatting.

For example, say you want to save the user's birth date in a Umbraco field called birthDate (type: DateTime). Gigya does not have a birth date field; instead, it offers three fields called "profile.birthDay", "profile.birthMonth", and "profile.birthYear".

To map Gigya's birthDay, birthMonth and birthYear fields into a single Umbraco field, do the following:

  1. Add this "dummy" or "placeholder" field mapping in the Gigya Settings page:

    Click to enlarge screenshot

  2. Add event-based code that will be carried out whenever "profile.birthDay" is being imported from Gigya. This code modifies profile.birthDay into a DateTime value that is composed of profile.birthDay, profile.birthMonth, and profile.birthYear. This new value will then be saved in the Umbraco field BirthDate according to the Field Mapping settings.

    See the code snippet below for an example (usually this code would be added to Global.asax.cs).

    public class Global : UmbracoApplication {
    
    	protected override void OnApplicationStarted(object sender, EventArgs e) {
    		base.OnApplicationStarted(sender, e);
    		GigyaMembershipHelper.GettingGigyaValue += GigyaMembershipHelper_GettingGigyaValue;
    		MemberService.Saved += MemberService_Saved;
    	}
        
    	private void MemberService_Saved(IMemberService sender,global::Umbraco.Core.Events.SaveEventArgs<global::Umbraco.Core.Models.IMember> e) {
    		var memberService = ApplicationContext.Current.Services.MemberService;
    		foreach (var member in e.SavedEntities) {
    			// this is a brand new member object
    			if (member.IsNewEntity()) {
    				// add member group for example:
    				memberService.AssignRole(member.Id, "Authenticated");
    			}
    		}
    	}
    
    	private void GigyaMembershipHelper_GettingGigyaValue(object sender, MapGigyaFieldEventArgs e) {
    		var profile = e.GigyaModel.profile;
    		switch (e.CmsFieldName) {
    			case "birthDate":
    				if (e.GigyaValue != null) {
    					try {                     
    						e.GigyaValue = new DateTime(Convert.ToInt32(profile.birthYear), 
    						Convert.ToInt32(profile.birthMonth), Convert.ToInt32(profile.birthDay));
    					}
    					catch {
    						// log
    					}
    				}
    			return;
    		}
    	}
    
    }

Code Locations

Views are located at /Views/MacroPartials.

Script is located at /Scripts/gigya-cms.js and /Scripts/gigya-cms-min.js (remember to update both as the minified version is used when not in debug mode).

Errors

By default, any errors are alerted to the user using gigyaCms.handleError(msg). This could be changed to display it in HTML or hide it completely.

To change the generic error message, update gigyaCms.genericErrorMessage. This could be set to a value stored in Umbraco for example.

Development considerations

  1. To add the event handlers to the login, register, logout and edit profile buttons/links, gigyaCms.init() is called. By default this is called on dom ready however it is advisable to call it as soon as the last button has been written to the page otherwise the buttons won’t work until the scripts and images have been downloaded.
  2. When a user performs Gigya actions (login, logout, profile update) the gigya-cms.js script is used to call actions on Gigya.Umbraco.Module.Mvc.Controllers.AccountController. The path to this controller is specified at gigyaCms.baseUrl: '/api/gigya/account/'. This could also be overridden to us a custom controller if you wanted to.
  3. Although Gigya controls the session it is advisable to have the same session and authentication timeouts as Gigya.

SSO

Gigya Single Sign-On (SSO) is supported. See Site Groups and Single Sign-On for more information.

Logs

The Gigya Connector logs its error messages to the default Umbraco log file at <project root>/App_Data/Logs/UmbracoTraceLog.txt.

Gigya Connector messages begin with [Gigya].

Debug Logs

The Gigya Connector also offers debug mode, in which it logs every call to the Gigya API and every response. Debug logs are also written to <project root>/App_Data/Logs/UmbracoTraceLog.txt, as in the following example:

Click to enlarge screenshot

However, Umbraco doesn’t support debug logs by default.

To enable debug mode:

  1. Open the file <project root>/Config/log4net.config
  2. Enable debug mode for Gigya by adding the following code:

    <logger name="GigyaUmbracoLogger">
        <level value="Debug">
    </logger>

    (It is also possible to enable debug mode at the global level. See the Umbraco documentation for more information.)

  3. Then, in the Umbraco admin console, go to Settings > Gigya.
  4. Check the Debug Mode checkbox.

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.

Umbraco-Related Troubleshooting

  • To check if the GConnector is installed, open the browser developer tools. In the console, run gigyaCms. If an error is displayed, the connector is not installed.
  • If you are experiencing login issues, open the browser developer tools. In the network tab, check the response to the login request. This should start with /api/gigya/account and the expected response code is 200. If this is the case, the login issue is unrelated to Gigya. 
  • If the login button widget isn’t rendering, check that Enable RaaS has been set to true on the settings page for the current site (or global settings if they are inherited).
  • If there is a “gigyaCms is undefined” JavaScript error, check the Gigya settings action has been added to the layout page. See the “Important” section above.
  • If the login / logout buttons aren’t working check that you haven’t changed the views and changed some of the button classes.
  • If a Gigya field is not being saved to Umbraco check the field mappings on the settings page. Make sure the names are correct and they are the same type, e.g. don’t try to map a Gigya field that’s a string to an Umbraco numeric. If this is attempted and debug mode is enabled, it will be logged.
  • When working with several Umbraco installations with a Gigya connector, it is not possible to simply copy Gigya settings from one installation to another, since configuring the settings requires running Umbraco processes for these settings to go into effect. 

  

Save

Save

Save

Save

Save

Save

Save

Save

Save

Save

Save

Save

Save

Save

Save

Save

Save

Save

Save

Save

Save

Save

Save

Save

Save

Save

Save

Save

Save

Save

Save

Save

Save

Save

Save

Save

Save

Save

Save

  • No labels