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.
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:
- The user initiates a login or connect call to a SAML provider via Gigya’s login or connect endpoint.
- The server looks for the SAML configuration for the requested IdP name.
- The server issues an authentication request to the IdP.
- The user browser redirects or posts to the IdP.
- If needed the user logs into the IdP account.
- The user browser redirects back to the Gigya SAML ACS (Assertion Consumer service) endpoint with the SAML assertion.
- 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.
- 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).
Use the first IdP configuration for the received entity ID.
You can have numerous IdPs configured for the same provider with unique Entity IDs.
- Get the redirect URL from the RelayState - it contains a URL to which to be redirect after the login.
- 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 = , and the customAPIDomainPrefix for this site is "gigya".
When getting the IdP initiated SSO request, the ACS endpoint first redirects to , and continues from there.
If the site does not have a custom domain prefix, but does have a CNAME, Gigya redirects to the CNAME.
- Perform a new "login" to the SP. This will replace any current logged in user, if it exists.
- 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.
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:
- The user logs out on the external IdP site. The IdP redirects to the Gigya SLO endpoint .
- The Server receives a SAML SLO logout request to the SLO endpoint from the IdP.
- The Server logs out the user (removes login sessions) from all active IdP's.
- 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.
- 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):
- 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.
- 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 .
- 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
- fidm.saml.delIdP - deletes a SAML Identity Provider (IdP).
- fidm.saml.getConfig - retrieves the Gigya site configuration for SAML.
- fidm.saml.getRegisteredIdPs - retrieves all the SAML IdP configuration objects that are defined for the site.
- fidm.saml.importIdPMetadata - imports a SAML Identity Provider (IdP) configuration from a SAML metadata XML.
- fidm.saml.registerIdP - updates (registers) a SAML configuration for a specific Identity Provider (IdP).
- fidm.saml.setConfig - updates the Gigya SAML site configuration.
- ExternalIdP - External IdP configuration parameters .
- GigyaConfig - Gigya SAML configuration parameters.
Media-ID IdP Initiated SSO
See Gigya As An SP In Action
See The Code
The following guide walks through Gigya's SAML Login setup and serves as a reference document for the configuration options.
The SAML Login section of Gigya's site includes:
- The main SAML Login page with a link to SAML SP Metadata, and a SAML IdPs table.
- A SAML IdP Settings form.
- An IdP Attribute Map table, with links to add, edit, and delete attributes.
- A SAML SP Metadata page.
- An Import IdP window.
- A Test SAML Login page.
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:
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 Binding - The 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:
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.
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
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):
will return the following:
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.
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/.
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.