Gigya as SAML SP

Skip to end of metadata
Go to start of metadata

Introduction

In this guide Gigya functions as an SP, which means that Gigya receives an SSO login (or logout) from a third-party identity provider such as Active Directory Federation Services (ADFS). The SAML protocol supports different profiles and binding options, and Gigya supports the web browser SSO profile, with HTTP POST and HTTP Redirect binding. 

For configuring SAML for use with the Gigya Console, see Console Administration.

Watch an Instructional Video

If you have a Gigya Academy membership, you can watch instructional videos about this and other Gigya products. To access Gigya Academy content, you should first make sure you are logged into the Gigya Console

Gigya Academy is a premium product that requires separate activation. If it is not part of your site package, please contact your Account Manager or contact us by filling in a support form on our site. You can also access the support page by clicking "Support" on the upper menu of Gigya's site.

To watch a video about Gigya as a SAML SP, Gigya Academy members can use this link and this link.


SSO and SLO Flows

There are two Single Sign-On (SSO) and two Single Log Out (SLO) flows that Gigya supports,  in all four Gigya is the SP.

Single Sign-On (SSO)

1. SP initiated SSO: Login or connect to a SAML IdP:

  1. The user initiates a login or connect call to a SAML provider via Gigya’s login or connect endpoint.
  2. The server looks for the SAML configuration for the requested IdP name.
  3. The server issues an authentication request to the IdP.
  4. The user browser redirects or posts to the IdP.
  5. If needed the user logs into the IdP account.
  6. The user browser redirects back to the Gigya SAML ACS (Assertion Consumer service) endpoint with the SAML assertion.
  7. The server validates and extracts the user details from the SAML response. If user attribute mapping is defined, the server maps the requested attributes to the account object.
  8. The server continues the login process and returns the login response to the client.


2. IdP initiated SSO:

IdP initiated SSO is less common in consumer-facing scenarios, however, common in Enterprise environments.

Idp initiated SSO is most commonly used when an Enterprise has numerous vendors/partners with users that need to access your (the SP) site or resources, who maintain their own User Databases. Users would generally gain access to your (the SP) resources via a portal or landing page from within their home Enterprise's domain (the IdP). The user would click on a link within that portal or otherwise initiate a connection to the SP (your site), which would prompt the user to login via the IdP (if not already) and, upon successful authorization, the user would gain access to the requested resources on the SP (your site). 

  1. Use the first IdP configuration for the received entity ID. 

    You can have numerous IdPs configured for the same provider with unique Entity IDs.

  2. Get the redirect URL from the RelayState - it contains a URL to which to be redirect after the login.
  3. If the site has a customAPIDomainPrefix configured for it, Gigya first redirects to the correct domain prefix. The endpoint redirects back to itself under the domain prefix that correlates to the redirect URL.
    For example: the ACS endpoint gets  RelayState = http://a.com?login , and the  customAPIDomainPrefix  for this site is "gigya". 
    When getting the IdP initiated SSO request, the ACS endpoint first redirects to  http://gigya.a.com/saml/v2/0/sp/acs , and continues from there. 
    If the site does not have a custom domain prefix, but does have a CNAME, Gigya redirects to the CNAME.
  4. Perform a new "login" to the SP. This will replace any current logged in user, if it exists.
  5. Validate the redirect URL: 
    • If the redirect URL is on one of the allowed domains for the site, redirect to the redirect URL using the "redirect" auth flow.
    • If the URL is not an allowed domain, the flow terminates with an error response.

Since IdP initiated SSO uses a "redirect" authFlow mode to handle the login, it requires a CNAME or a customAPIDomainPrefix otherwise, the login will not work on the client side.

When using a CNAME, the login will succeed only for domains that are under the main site domain. If a site also has other domains configured for it that are not related to the main site domain, IdP initiated login will not succeed there.

Single Logout (SLO)

3. IdP initiated SLO:

  1. The user logs out on the external IdP site. The IdP redirects to the  Gigya SLO endpoint .
  2. The Server receives a SAML SLO logout request to the SLO endpoint from the IdP.
  3. The Server logs out the user (removes login sessions) from all active IdP's. 
  4. The server calls the partner's logout endpoint in an iframe (which must be configured in the management platform). Note: The iframe is written to the response stream by the server, with a client side script on the parent page that will automatically redirect back to the SLO endpoint again. 
  5. The server returns a SAML logout response via post or redirect.

Notes: The Web SDK is not involved in this scenario. The endpoint returns a page that calls the partner logout URL in an iframe, and after this is done, continues with the response back to the IdP (redirect/post).


4. SP initiated SLO (user logout):

  1. The  JS client calls accounts.logout or socialize.logout. The server returns an array of SAML connected providers that need to be logged out on the client side.
  2. The JS client issues a logout request for each connected provider. For a SAML provider the client issues a request to the SP SLO endpoint .  
  3. The SLO endpoint  redirects to the IdP SLO endpoint.

Note: User logout is supported only through the Web SDK.

Identity Provider Name

The use and implication of the name  field of the IdP configuration is important to understand. The IdP name is used as part of the provider name for this IdP; the provider is identified as "saml-". This means that once an IdP has been used in a site with a specific name, this name should not be changed. Changing a name of a configured IdP means changing the login provider, which results in "losing" all the users that had already logged in using the old name.

Another aspect is site groups and SSO. For sites that are part of a group to be able to use SSO with SAML, the same SAML IdP should be configured in all sites of the group with the same name. Otherwise it will not be considered the same provider and the user might not be recognized across sites.

Best practice is to configure the IdP within every child of the Site Group. However, in most circumstances, setting up the IdP within the Master site configuration will allow the children to connect, even if they are not individually configured.

 

Partners with group sites should use the same IdP alias (the "name" field of the external IdP configuration) across all sites that pertain to the same group, and intend to configure the same IdP (otherwise functionality of the group will break).

SAML APIs and Objects

APIs:

 

Objects:

  • ExternalIdP -  External IdP configuration parameters .
  • GigyaConfig - Gigya SAML configuration parameters.

Media-ID IdP Initiated SSO 

For details regarding the implementation of media-ID based IDP initiated SSO, please contact Gigya Support via the Support tab of the Dashboard.

See Gigya As An SP In Action

 
Click One Of The Buttons Below To Use Gigya As An SP with TestShib.org as IdP.

                     

Response:

Notes: Usernames and Passwords for test user accounts are available on the login screen, as this is only an example implementation. You should be careful not to connect any of your personal social network accounts while logged into one of these test accounts. DO NOT enter any Personally Identifiable Information in the Profile Completion screen, as the username and passwords are public!

If using the IdP with RaaS option, the correct login provider to choose for this example is the one labeled External IdP.

See The Code

<script>
    function loginCallback(response) {  // The callback that handles the response object from the IdP
        loginData = response;
        returnedObject = JSON.stringify(loginData,undefined,4);
        document.getElementById('JStext').innerHTML = returnedObject;
        console.log(loginData);
    }
    gigya.socialize.addEventHandlers({  // Support for handling the response in RaaS
       onLogin: loginCallback
   })
    function loginToIdp() {  // Logs into the IdP via the socialize.login method
        var login_params =  ({
           'provider': 'saml-testShib-gig02', 
           'callback': loginCallback
        });
        gigya.socialize.login(login_params);
    }
    function onLogout(response) {  // Handles user logout
        if ( response.errorCode == 0 ) {               
            alert('You are now logged out');
            //window.location = "yourSite/LogoutPage.html";
        }
        else {
            alert('Error :' + response.errorMessage);
        }
    }
    function logMeOut() {  // Logs out the user
        gigya.accounts.logout({callback:onLogout,
				forceProvidersLogout: true});
    }
function showRaasIdp() {  // Implements the IdP within a RaaS Screen-Set
customButtons = [{
	// The custom button object for the IdP within a RaaS Screen-Set
    "type": "saml",
    "providerName":"testShib-gig02",
    "idpName":"testShib-gig02",
    "iconURL": "http://developers.gigya.com/download/attachments/15795144/IDP.png",
    "logoURL": "http://developers.gigya.com/download/attachments/14650850/placeholderImage.png",
    "lastLoginIconURL":"http://developers.gigya.com/download/attachments/15795144/Externalidp_LastLogin.png",
    "position":"4"

}];
    
customButton_params =
{
    customButtons,
    "showTermsLink":false, // 'terms' link is hidden
    "screenSet":"NewRaas4nov15-RegistrationLogin"
}
gigya.accounts.showScreenSet(customButton_params);
}
</script>
Click One Of The Buttons Below To Use Gigya As An SP with <a href="http://www.testshib.org/" target="_blank">TestShib.org</a> as IdP.<br /><br />
<input type="button" class="gigyaDocButton" value="Test IdP Login" onclick="loginToIdp();" />&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
<input type="button" class="gigyaDocButton" value="IdP with RaaS" onclick="showRaasIdp();" />&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
<input type="button" class="gigyaDocButton" value="Logout" onclick="logMeOut();" />
<br /><br />Response:
<div class="responseDiv" id="responseDiv">
	<textarea id="JStext" value="" style="background-color: #EFEFEF; width: 80%; max-width: 80%; border: 3px inset grey; min-height: 300px; overflow: auto; border-radius: 7px;"></textarea>
</div>

 

SP Setup

The following guide walks through Gigya's SAML Login setup and serves as a reference document for the configuration options.

Introduction

The SAML Login section of Gigya's site includes:

 

Go to the SAML Login  section of Gigya's website. Please make sure you are signed in.

The SAML Login page may also be accessed by clicking Settings in the upper menu and then SAML Login in the left menu:

 

SAML Login

In order to configure a SAML Login, you must configure the Identity Providers (IdPs) with which authentication will be performed. 

You may add or import IdPs. Once you configure an IdP you can edit, test, and delete it.  This page displays the SAML IdPs table.

This  page also displays a link to the SAML SP Metadata . The metadata includes information about the Service Provider, which is Gigya in this case.  

 

When you click "add" or "edit" icons, the SAML IdP Settings form is displayed. 

 

SAML IdP Settings Using Gigya As SP

The IdP you configure here can be used as a login provider in Gigya's Login plugin and login API. The provider name will be the IdP name you provide here, with the prefix "saml-", for example if the IdP name is idp1, the provider will be "saml-idp1".

The IdP Settings form includes all the i nformation needed to perform Single Sign-on and Single Logout via the IdP:

 

The input fields are as follows:

  • Name - A custom name for this Identity Provider. The name with the prefix "saml-" will be the login provider.
  • Issuer - The Identity Provider’s entity ID.
  • Single-Sign-On Service URL - The Identity Provider’s SSO URL.
  • Single-Sign-On Service BindingThe type of SSO binding.
  • Single Logout Service URL - The IdP’s SLO URL.
  • Single Logout Service Binding - The type of SLO binding.
  • Name ID Format - The format of the nameID (SAML spec requires a nameID and Gigya uses the nameID field for the Gigya UID of the user).
  • Attribute Map - A mappping of IdP attributes to identity fields.
  • x509 Certificate - The IdP x509 certificate.

The IdP Settings are equivalent to the ExternalIdP object, where you can find the default values for these fields.

Note: If you map an IdP attribute to Gigya's ProviderUID, and upon login the mapped attribute cannot be retrieved from provider's auth response, the login will fail. You will have to either remove the mapping or change it to the appropriate available attribute of the IdP (if such exists).

IdP Attribute Map

In the IdP settings there is an Attribute Map table that holds the mapping of IdP attributes to existing Gigya Identity fields:

 

When you click Add attribute, the Add Attribute window will open:

 

When you click the edit icon  , the Edit Attribute window will open:

 

 

In both the Add Attribute and the Edit Attribute you can map IdP attributes to existing Gigya Identity fields. Gigya supports mapping IdP attributes to the following existing Gigya attributes:

  • ProviderUID
  • Country
  • City
  • Email
  • LastName
  • FirstName
  • Zip
  • Gender
  • samlData.customfield

Custom SAML fields

We also allow mapping to a custom identity field, not only to an existing one. An attribute can be mapped to this custom identity field by mapping it to a name like "samlData.customField".

You can also delete an attribute.

Note: Changes will be saved only if you click the save button on the page.

samlData object

The samlData object is any attribute that you can map to a custom identity field. Gigya has several built-in SAML Identity Fields, i.e., providerUID and LastName, for instance. However, Gigya also gives you the ability to create your own custom saml identity field by using the Add Attribute button within the Attribute Map section (see above). Here you can map any available attribute you have access to within the IdP to your SP as samlData.<customField>.

For instance, if you need to know the color of a users car when they register to your site, assuming the IdP has access to this attribute and you have permission to access it, you can map the custom attribute 'userCarColor' to the custom field 'samlData.userCarColor'. Then, when you are querying the server you can specify theextraProfileFields parameter with, for instance, ids.getAccountInfo, and the attribute will be mapped and returned in the response.

When using a samlData object, you must specifically request it with the  extraProfileFields parameter. All samlData fields you have mapped will be returned within a single array.

For example (using the instance described above):

http[s]://ids.<Data_Center_ID>.gigya.com/ids.getAccountInfo?UID=xxxxxxxx&extraProfileFields=samlData

 

will return the following:

{
  "UID": "ff3c8368d1c7e",
  ...
  },
"samlData": [
    {
      "userCarColor": "red",
    },
}

SAML SP Metadata

The main  SAML Login  page has a link to SAML SP Metadata:

 

This metadata ensures a secure transaction between the Identity Provider (IdP) and the Service Provider (SP). 
The SP metadata presents the SP details, and enables you to copy these details and configure them on the IdP service side.

Import SAML IdP

In the main  SAML Login  page, above the SAML IdPs table, there is an "Import" button, which opens the "Import SAML IdP" window:


In order to  import a SAML IdP configuration, you must provide its metadata URL.

Test SAML Login

In the main SAML Login page, in the SAML IdPs table, there is a Test button  , which opens the Test SAML Login page:

 

This page allows you to test your SAML Login using any one of the configured IdPs in the list. 

If you encounter an error in the process, you can use our Troubleshooting guide.

The "Login" button runs SAML login. If the login is successful, the user object data is displayed.

The "Logout" button runs SAML Logout. If the logout is successful, the "Successful SAML logout" message is displayed.

If your setup is successful, you will see a response within the provided window, similar to the image below:

 

The test IdP used in the above example does not have data associated for the available fields. Depending upon the IdP, you will receive the data available from that provider.

Additional Information

For instructions on converting the Gigya x509 certificate to a text file, please see here.

Microsoft ADFS does not include a Name Identifier assertion by default which is required for the SAML 2.0 protocol Gigya supports. For help configuring a nameid in an ADFS installation, see https://blogs.msdn.microsoft.com/card/2010/02/17/name-identifiers-in-saml-assertions/.

If using SAML and you want to enable the ability to Link Accounts, or socialize.addConnections you must set federation.allowMultipleIdentities to true using accounts.setPolicies. Read these important notes before enabling the allowMultipleIdentities parameter.

 

Any unique user can only be associated with a single SAML Identity at any given time. This means that if you offer login via multiple different SAML Identity Providers, a user can only use a single option to login to your site. Once the user is associated with a SAML IdP, they can not connect via any other SAML IdP.