Gigya as SAML IdP

Skip to end of metadata
Go to start of metadata

Note: Gigya as SAML IdP is a premium Gigya platform that requires separate activation and utilizes Gigya's Registration-as-a-Service (RaaS). If these are not yet a part of your existing site package, please contact Gigya Support via the Support link in the top menu of your Console Dashboard or email support@gigya.com.

Introduction

Gigya's SAML IdP service enables identity federation, on-top of Gigya's Customer Identity Management, via the SAML2.0 protocol. The SAML IdP makes it possible for any service providers that support SAML 2.0 to authenticate with Gigya's Customer Identity management. 

This functionality is supported for customers using Gigya's Registration-as-a-Service

In this guide Gigya functions as an IdP, which means that Gigya provides an SSO login (or logout) to a third-party service provider. The SAML protocol supports different profiles and binding options, and Gigya supports the web browser SSO profile, with HTTP POST and HTTP Redirect binding.

This guide walks through Gigya's SAML Identity Provider (IdP) setup and serves as a reference document for the configuration options.

SAML is not supported natively in iOS but does work in WebView.

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 SAML IdP, Gigya Academy members can use this link

Basic Login Flow

 

Specific 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 IdP.

SSO

1. SP initiated SSO: 

  1. The Gigya SAML endpoint receives a SAML SSO authentication request from an SP to the SAML SSO endpoint.
  2. The Gigya SAML endpoint redirects to a configured Gigya proxy page on the partner site.
  3. If the user is not logged in, or if ForceAuthn is requested, the user is redirected to the configured login page on the partner site (the proxy page holds the login page URL).
  4. Once the user is logged in, he should be redirected back to the Gigya SAML SSO endpoint via the proxy page.
  5. The Gigya SAML endpoint returns a SAML assertion to the SP with the user details.

* isPassive() is A SAML property indicating that no login UI should be presented to the user and may be used within the above flow if you simply want to send the completed SAML Assertion to the SP. Note that this will return an empty Assertion if the user is not logged in.

2. IdP initiated SSO:

The user needs to be already logged in for IdP initiated SSO.

  1. The SSO can be initiated from the JavaScript SDK or by redirecting to the SSO endpoint with the IdP initiated SSO parameters.
  2. The Gigya SAML endpoint generates an authentication response and redirects to the SP ACS endpoint. 

SLO

3. SP initiated SLO: 

  1. The Gigya SAML endpoint receives an SLO request to the SAML SLO endpoint.
  2. The Gigya SAML endpoint redirects to the proxy page on the partner site, and then the proxy page calls the configured IdP logout page and all the SAML SP SLO endpoints.
  3. The proxy page redirects back to the SLO endpoint and the Gigya SAML endpoint returns an SLO response to the SP.

 

4. IdP initiated SLO:

  1. When calling accounts.logout using Gigya's Web SDK, Gigya will initiate SAML SLO to all connected SPs.

 

Partner Integration for IdP

The following are pages required for the SAML protocol, which need to be configured by the partner and specified in the SAML IdP Settings page of the Gigya Console.

Partner Steps for Integrating SAML IdP

  1. The partner creates the Gigya HTML Proxy page:
    • Set the login and logout page URL parameters in the proxy page.
    • Place the proxy page in an accessible URL in the partner site.
    • Include the gigya.fidm.saml.continueSSO() method on the login page to redirect after a successful login.
  2. Configure the Gigya IdP parameters:
    • Proxy page URL
    • SAML error page URL (optional)
  3. Configure the SPs that are allowed to SSO with the site manually or, when possible, by using fidm.saml.importIdPMetadata API.

 

SAML Objects

Objects:

  • ExternalSP - External SP configuration parameters.

 

IdP Setup

The following guide walks through Gigya's SAML Identity Provider (IdP) setup and serves as a reference document for the configuration options.

Introduction

The SAML IdP section of Gigya's site includes:

  • The main SAML IdP page, which contains links to the configuration of the SAML IdP settings and to the SAML IdP Metadata, and also displays a SAML SPs table.
  • The Configure SAML IdP Settings  form, where you define the Proxy and Error Page URLs.
  • The   SAML IdP Metadata page, which contains the configuration data for the external SP.
  • SAML SP Settings, available via clicking on any existing SAML SP, or the Edit icon.
    • The connected page includes all the settings for the SP as well as the Add Attribute and Edit Attribute windows.
  • An Import SP window, for importing an SP's settings from a Metadata URL.

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

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

 

SAML Identity Provider

This  page links to the configuration of the SAML IdP settings, and also to the SAML IdP Metadata page. The metadata includes information about the IdP, which is Gigya in this case.

 You may add or import an unlimited number of SPs. Once you configure an SP you can edit and/or delete it.

This page displays the SAML SPs table. 

 

When you click the Add button or Edit icon, the SAML SP Settings form is displayed. 

 

Configure SAML IdP Settings

This section is used to configure the settings of the site SAML IdP.

 

The input fields are as follows:

  • Proxy Page URL - an HTML page that the partner places in his site in order to use the Gigya SAML IdP.
  • Error Page URL -  a URL for an error page to display errors.

 

SAML  IdP Metadata

The main SAML Identity Provider page has a link to SAML IdP  Metadata:

 

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

 

SAML SP Settings With Gigya As IdP

In order to act as a SAML IdP, you must configure approved Service Providers (SPs), enabling customers to provide SAML IdP services.
In the main SAML Identity Provider page, the SAML SPs table is displayed. You can click "Add" to add a new SAML SP, or "edit" to edit one of the existing SAML SPs.

Adding or editing a SAML SP opens the following SP settings form:

 

The input fields are as follows:

  • Name - A custom name for this External Service Provider. This field must be unique within the site (Gigya Console).
  • Issuer - The Service Provider’s entity ID.
  • Session Lifetime (minutes) - The time span for which SAML sessions are valid.
  • Assertion Consumer Service URL - The SP’s ACS URL.
  • Single Logout Service URL - The SP's SLO URL.
  • Single Logout Service Binding - The type of SLO binding.
  • Name ID - Define whether to auto-generate a unique ID for the SP, or define it manually by mapping to it*.
  • Sign Authentication Request - Specifies whether SAML requests should be signed.
  • Encrypt Assertion - Specifies whether SAML assertions should be encrypted. 
  • Signed Assertion - Specifies whether SAML assertions should be signed.
  • Attribute Map - A table that maps attribute names between the SP and the IdP.
  • x509 Certificate - The IdP x509 certificate.
  • x509 Encryption Certificate - The x509 certificate that is used to encrypt the assertions.

 

* Name ID - Once Name ID is set, all users that log into the SP will be associated with a variation of this unique ID. Replacing or changing this mapping at any point in the future will prevent the SP from associating users with their previously existing data and may lead to unauthorized access of a given user's personal data if their previous nameID is ever reassigned to a different user.

Recommended Best Practices:

  • Auto-generated unique ID per SP (Persistent Pseudonym)
    • This option should be used by an IdP that wants to prevent SPs from sharing data across accounts.
    • However, since the ID is derived from the site ID and IDs are not portable between sites, accounts exported from one IdP to another will be treated as a new account on the user's next login to the SP.
  • Map profile field
    • This option should be used in all other cases.

 

SSO Group Considerations

When using Multiple SPs within a Gigya SSO Group with a Gigya IdP:

  • All SPs within the SSO Group must use the exact same IdP configuration, assuring they all refer to the IdP by the same name.



  • In the Name ID section you must:
    • Select the Map profile field option and set the field to UID.
    • Select Persistent for the Profile field type.

This ensures that your users are always identified as the same user between the multiple SPs.

 

 

 

Adding SAML Attributes

You can add attributes to the attribute map by clicking the Add attribute button on top of the table.

Changes will be saved only if you click the Save Settings button on the parent page.

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

 

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




In the above example the Gigya profile.firstName field is mapped to the User.FirstName attribute name of the external SP. 

 

Supported Attributes

Profile Field can be any of the following Gigya supported attributes with or without the profile. prefix:

  • firstName
  • lastName
  • nickname
  • photoURL
  • profileURL
  • address
  • state
  • thumbnailURL
  • photoURL
  • URL
  • email
  • country
  • state
  • city
  • thumbnailURL
  • zip
  • gender
  • age
  • birthDay
  • birthMonth
  • birthYear
  • loginProvider
  • UID
  • uid
  • account.isVerified
  • data.customField

For information on determining Attribute names to map supported ID's to, we suggest reviewing the Shibboleth reference maintained by The Wharton School at the University of Pennsylvania.

Import SAML SP

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


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

 

Additional Information

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

When calling accounts.logout in an SSO group, it is important to note that the callback initiates when the response is received to the current site. This means that it is possible that the logout event has not completed on all other child sites. If you require that the user is logged out from all child sites prior to initiating the callback (i.e., when redirecting the user), you must set a timeout inside the callback of accounts.logout.

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.