Umbraco 6

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 Gigya Connector for Umbraco is designed to help you implement Gigya RaaS in your Umbraco websites as quickly and easily as possible.

Versions and Compatibility

  • The Connector is compatible with Umbraco 6.2.1 and above. See also: Umbraco 7.

  • The Connector requires Newtonsoft.Json 6.0.8 and above.

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

2. Upgrade Newtonsoft.Json

You will have to upgrade the Newtonsoft.Json file in your Umbraco installation if isn’t already 6.0.8 or higher. This can be done manually or with Nuget.

After upgrading Newtonsoft.Json you may see a screen like this:

Click to enlarge screenshot

 

To fix this you need to add the following binding redirect to the web.config file:

<dependentAssembly>
	<assemblyIdentity name="Newtonsoft.Json" publicKeyToken="30ad4fe6b2a6aeed" culture="neutral" />
	<bindingRedirect oldVersion="0.0.0.0-6.0.0.0" newVersion="6.0.0.0" />
</dependentAssembly>

3. Install the Gigya Package

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

  1. Download the package here: Gigya_Umbraco_6__2016_09_06.zip
  2. Go to the Developers tab and select Packages > Install Local Package.
    Click to enlarge screenshot
  3. Check the "I understand the security risks" box.
  4. Select Choose File and browse to the package .zip file.
  5. Select Load Package.
  6. Select Accept license and then Install Package.

The Gigya package will be installed.

4. Enable the Gigya Tab for User

To enable the Gigya section for some users:

  1. Go to the Users tab and select Users > admin.
  2. In the Sections list, check the "[gigya]" checkbox.
    Click to enlarge screenshot
  3. Save the user and refresh the page. You can now access the Gigya tab.

5. Configure Settings in web.config File

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.

Configure Member Type (OPTIONAL)

All members created by the Gigya module will use the “Member” member type by default.   To change this, edit web.config add an AppSetting with the key of “umbracoMemberTypeAlias”.

Configure Homepage DocType (OPTIONAL)

By default, the Gigya Connector lets you manage Gigya settings for each homepage, and assumes that a homepage has a doctype of “umbHomepage”. To use a different doctype, edit web.config to add an AppSetting with the key "umbracoHomepageAlias".

For example, the following line will let you manage Gigya settings for nodes with a doctype alias of umbBlog:

<add key="umbracoHomepageAlias" value="umbBlog" />

6. Configure Gigya Connector Settings

To configure the Gigya Connector settings, go to the Gigya tab, expand Settings 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 can only be managed by Administrators.

Multisite and Global Settings

In a multisite environment you can use the global settings page to configure multiple sites quickly.

To configure global settings:

  1. Go to the Gigya tab, expand Settings and select Global Settings.
  2. Choose your settings as needed and click Publish.

All your sites will inherit the global settings automatically.

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:
    Click to enlarge screenshot

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

7. Implement Gigya Macros

The Gigya Connector creates the following macros:

  • Gigya Settings
  • Login
  • Register
  • Edit Profile
  • Logout

Implementing the "Gigya Settings" Macro (Required)

To render the required client side JavaScript you need to add GigyaSettings to the head section of the master layout (it needs to run on all pages).   How you add it depends on whether you are using Web Forms or MVC.

If you are using...Add this code to implement Gigya Settings:Layout view example (click to enlarge)
WebForms
<umbraco:macro alias="GigyaSettings" runat="server"></umbraco:macro>

Click to enlarge screenshot

MVC
 @Html.Action("Index", "GigyaSettings")

Click to enlarge screenshot

Implementing the "Login"/"Register"/"Edit Profile" Macros

You can use these macros to display the various Gigya RaaS screen-sets in the appropriate spots in your site (see RaaS - Default Screen-Set Flows for an introduction).

You can choose between two display options:

  • Popup: Display a button which, when clicked, opens the screen-set in a popup window
  • Embedded: Display the screen-set embedded in the page.

 

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


To implement in the rich-text editor:

  1. In the Umbraco admin console, go to Content and select your desired site and page.
  2. In the right-hand panel, select the Content tab and click the Insert Macro button in the toolbar.
  3. Select the Login, Register, or Edit Profile macro and click OK.
    In the macro window that opens, configure the macro settings. For the Login, Register, and Edit Profile macros, you have the following settings:

    OptionDescription
    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
    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.
    Screen-SetIf you have created custom screen-sets for login, registration, and/or profile editing, enter the name of the screen-set here. See Screen-Sets 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.

To implement in the code:

If you want to render the macros directly from the code, add the following, depending on whether you are using Web Forms or MVC:

If you are using...Add this code to implement Gigya Settings:
WebForms
<umbraco:Macro Alias="GigyaLoginButton" runat="server"></umbraco:Macro>
MVC
@Umbraco.RenderMacro("GigyaRegisterButton", new { Label = "Hello" })

The markup for these views can be modified and is located in the /Views/MacroPartials folder.

The Gigya framework doesn’t work with embedded screens if rendered inside a <form> element. The workaround for this is to specify a container that is outside the <form> element or to use the Gigya popups. Alternatively, you can render the Umbraco macro through code and make sure it is rendered outside the <form>.

This won’t work because it’s inside a form:

<form id="umbMasterForm" runat="server">
   <umbraco:macro id="Macro3" alias="GigyaLoginButton" runat="server" ></umbraco:macro>
</form>

This will work because it’s outside a form:

 <form id="umbMasterForm" runat="server">
   <asp:contentplaceholder id="cp_content" runat="server"></asp:contentplaceholder>
</form>
<umbraco:macro id="Macro3" alias="GigyaLoginButton" runat="server" ></umbraco:macro>

Implementing the "Logout" Macro

You can use this macro to display a button to log the user out:

To implement in the rich-text editor:

  1. In the Umbraco admin console, go to Content and select your desired site and page.
  2. In the right-hand panel, select the Content tab and click the Insert Macro button in the toolbar.
  3. Select the Gigya Logout macro and click OK.
    In the macro window that opens, configure the macro settings. For the Logout macro, you have the following settings:

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

To implement in the code:

See code examples in "Implementing the Login/Register/Edit Profile Macros" section above.

Customization

Session Management and Expiration

When the Gigya Connector is enabled, the CMS user session is governed by the Gigya user session:

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

To set the maximum length of the user session, edit the Session Expiration field in the Gigya Settings page. 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).

Although Gigya controls the session, it is advisable to have the same session and authentication timeouts as Gigya. These can be updated in the web.config in the standard .NET way.

Field Mapping

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

  • Gigya UID
  • First name
  • Last name
  • email

To have additional fields mirrored into Umbraco:

  1. In the Umbraco admin console, go to the Gigya > Settings.
  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 alias of the Umbraco field into which you want to mirror the data. For example, for a field named "birthDate", the alias is "birthdate" (in lowercase), as you can see in the field properties:

    Click to enlarge screenshot
    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). The following screenshot shows the properties of a field named

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: profile.birthDay (Gigya Field) to birthdate (Umbraco Field Alias).
  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

  • 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.  
  • 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 may also be overridden to us a custom controller.

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. Gigya Connector messages begin with [Gigya].

The Gigya Connector also offers debug mode, in which it logs every call to the Gigya API and every response. 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 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.

  • Turn on Debug mode in the settings page and check the debug logs. If there are no entries, make sure Debug is enabled in log4net either at the global level or for GigyaUmbracoLogger (see Logs).
  • If the Login macro isn’t rendering, check that Enable RaaS has been checked in the Gigya settings page (either for the current site or in global settings if they are inherited).
  • If there is a “gigyaCms is undefined” JavaScript error: ensure that Gigya Settings has been added to the layout page (see Implementing the "Gigya Settings" Macro).
  • If the Login/Logout buttons aren’t working, make sure 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 in the Gigya settings page. Make sure the names are correct and that the field types match. Field mapping errors can be viewed in the logs if Debug Mode is enabled (see Logs).

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

Save

Save

Save

Save

Save

  • No labels