SAML Identity providers screen

Integration > Security > Inbound SSO > SAML Identity Providers

An identity provider (IdP) is an external system that companies use to host and authenticate user account information for Single sign-on (SSO). The Identity Providers screen configures IdPs for single sign-on.

Restriction: If your instance shows the Single sign-on screen instead of the Service Provider Config screen, changes made to this SAML Identity Providers screen are saved only when Use Multiple IdPs is on on the Single sign-on screen.

To create a new IdP, see Configure SAML single sign-on.

By default, in all instances there is a Medallia's employee authentication mechanism in the SAML Identity providers screen, this option is generally hidden, because the configuration does not need to be modified. When you access Medallia Experience Cloud, the login screen shows this authentication mechanism option only available for Medallia employees. When you select this option, no additional configuration steps are required. This option allows direct authentication with Medallia's employee authentication mechanism before applying role-based access controls (RBAC) policies.

To import an existing IdP configuration from the Single sign-on screen:

  1. On the Single sign-on screen, turn on the Multiple IdPs property. This activates the Identity Providers screen, which is active by default when your instance shows the Service Provider Config screen.

  2. On the Identity Providers screen, click Import existing Identity Provider configuration.

    Tip: When the Multiple IdPs property is not enabled on the Single sign-on screen, there is a section called IDP Configuration (Customer Side): when you click Import existing Identity Provider configuration — which is only available for SAML and is not recommended when there is an active IDP in the SAML Identity Providers screen — Medallia Experience Cloud imports the configuration from IDP Configuration (Customer Side) to SAML Identity Providers.

  3. Optionally customize the IdP, most notably with these options:

    • IdP Name and optional Logo image to appear on the sign-in screen.

    • Display Order to indicate where this IdP appears relative to others on the sign-in screen.

    • Active makes the IdP available on the sign-in screen.

    • If this is the only IdP to use for mobile devices, turn on the Automatically select this IdP for mobile devices option. For information about this option, see Automatic selection.

  4. Click Save.

Properties

IdP Name
(required) Name of this IdP to present on the sign-in page and in the configuration list of IdPs.
Logo
Image for this IdP to show on the sign-in screen. The image size must be 200px wide by 88px tall. When there is no image for the IdP, the sign-in screen shows the IdP Name and a generic image.

Generic image for the Gluu IdP on the sign-in screen

Description
Description of this IdP configuration for documentation purposes. This text does NOT appear on the sign-in screen.
Active
Whether or not the IdP is available to users at sign-in.
User IP allowlist
List of allowed user IP addresses. An allow-list is one or more IP addresses in full or subnet notation. Enter each address on a line by itself. Blank lines are ignored. Lines starting with octothorpes (#) are comments and also ignored, treated as "allow for any IP address". An empty list is ignored. For information about allow-lists, see IP allow-list format.

Use this parameter to restrict the availability of an IdP to only a set of IP addresses.

SSO Protocol
SSO protocol for this IdP. At this time only SAML is supported.

SAML IdP configuration

These properties configure the connection with the IdP. Many IdPs will provide a metadata file that defines these values. Upload and use that file to automatically define these properties. Alternatively you can provide them manually.

Metadata file
IdP-metadata file that describes the connection properties needed to communicate with the IdP. Uploading the file automatically fills in the values for the required properties in this section. For information on how to obtain this file from the IdP, see Obtaining the metadata file.

Initially this property has a Choose file option to upload the IdP-supplied file. Once uploaded, this property changes to Show file with an option to Delete the file and start over.

SSO Endpoint
URL Experience Cloud uses to connect and send requests to the IdP.
Warning: Unless otherwise agreed to with the IdP, the SSO service URL should be to the service that provides SP-initiated authorizations. It is important that correct URL is provided because some IdPs have multiple URLs, and using the wrong one does not always fail in obvious ways. See Single sign-on (SSO) for more information. 
Single Logout Endpoint
URL to the IdP where logout requests and responses are sent. This field is automatically populated when importing a SAML metadata file from the client.
Issuer Name
Identity of the IdP to appear in the SAML Assertion the IdP sends in response.
X.509 Certificate contents

The company's IdP certificate (the public key + identifying information about the IdP signing certificate), that allows Experience Cloud to trust SAML responses from the IdP. To include multiple certificates, separate them with a semi-colon (;).

A configuration typically has only one certificate. However, when a certificate is about to expire this property allows the instance to have both the old and a new certificate for when the expiration happens. It is good practice to remove the old certificate once it has expired.

Medallia fully manages certificate lifecycle.

  • Medallia automatically generates the certificate.

  • Medallia rotates certificates automatically.

  • Medallia requires no renewals from the client.

  • No certificate signing request or certificate files need to be managed.

  • There is no downtime during certificate rotation.

Important: The company's IdP certificate is a public certificate and is not considered sensitive information. It is vitally important, however, that the certificate is handled carefully so that a third party cannot substitute a different public certificate in the Experience Cloud IdP configuration. When handling a company’s IdP certificate, ensure proper chain of custody of the certificate by following these guidelines:

  • Ensure that you trust the source of the certificate. A direct e-mail or USB drive from a representative of the IdP team is preferred.

  • Restrict the number of people who have access to the IdP certificate's storage location. Avoid (for example) leaving this certificate in a Google Drive to which multiple people have write access.

  • Once the certificate has been uploaded to the Experience Cloud instance, have a user immediately attempt to sign in with an SSO SAML assertion signed by the key associated with the new IdP certificate. If the sign-in fails, troubleshoot immediately, and consider un-registering the new IdP certificate until the problem is resolved.

Inadvertently configuring Experience Cloud with a certificate from an untrusted source can allow a malicious third party to impersonate the company’s IdP, and therefore impersonate the company's users, which could in turn allow unauthorized access to the company's instance and its data.

Parameters

These properties configure how to process the information in the assertion from the IdP.

Auto Importer
(optional) Auto Importer specification to create and optionally update sign-on user's account. An import specification is required when the SSO event can create a user's account.

Set this to None when the IdP response contains the account's unique Username or Company ID of an existing account.

For detailed information see Create and verify SSO accounts with Auto Importer.

Assertion Attribute Name
Name of the attribute in the SAML response that identifies the user account Username or Company Account ID.
Restriction: This property must be set when Auto Importer property is set to none.

When using an Auto Importer set this property as a fallback from the NoAutomaticUpdate errors. The value in the SAML must exactly match a value in the username or company account field: there can be no Auto Importer transformations.

Warning: Failure to properly set this property can generate this error message:

Auto Importer failed because automatic updates are disabled for the user, and lookup was unable to find the account.

This error can also happen when a User account is blocked form allowing file uploads to update user settings. See Users.

Find by username
Use the SAML Assertion Attribute Name value as the Username instead of the Company account identifier when searching for an Account.

This option only works when Auto Importer is set to None.

  • When this option is on, the match is made by using the Assertion Attribute Name value and the account#username attribute in the assertion.

  • Otherwise, when off, the match is made by using the Assertion Attribute Name value and the account#company_account_id attribute in the assertion.

Advanced

The properties customize the IdP configuration.

Display Order
Order this IdP appears on the sign-in screen relative to other IdPs. Lower values appear higher on the list. When multiple IdP configurations have the same Display Order value, the IdPs appear in the order they were defined.
Use HTTP POST binding for authentication
(Required for SP-initiated sessions) Turn on when the IdP requires HTTP POST bindings instead of REDIRECT for authentication requests. Most IdPs use REDIRECT.
Important: This option must be on for SP-Initiated sessions, and for Medallia Mobile. Medallia, Inc. recommends using POST binding for web. 
Tip: If the IdP throws an HTTP 500 error when requesting an authentication, try turning this on.
Use HTTP POST binding for logout
Turn on when the IdP requires HTTP POST bindings instead of REDIRECT for logout requests. Most IdPs use REDIRECT.
Forward logout to IdP
Send logout a logout request to the IdP when the user logs out of Experience Cloud.
Restriction: This feature is inactive by default. Ask your Medallia expert to file a Feature activation request with Medallia Support.
Revoke OAuth tokens on logout request
Revoke OAuth tokens for the account the account session terminates (is logged off).
Restriction: This feature is inactive by default. Ask your Medallia expert to file a Feature activation request with Medallia Support.
Send logout request on mobile
Enable sending logout request for mobile clients. Enable users to log out of one app and be signed out of every other app on their phone with one click. This can originate from Experience Cloud or from any other app on the device.
Restriction: Mobile single logout requests to the IDP originate from Medallia's servers instead of the clients' servers. These requests will not go through the client browser. For this reason, the IDP must support SAML Single Logout request via backchannel to enable this option. Otherwise, the IDP will not receive the request. Note that some IDPs, such as Okta and PingOne, only support frontchannel requests, while other IDPs, such as PingFederate and Keycloak, support backchannel requests.
Process encrypted assertions in SAML Response
Look for an encrypted response and try to use it. Otherwise, if not present, or if this option is off, use the plain assertion.

Use this option only when the IdP is sending encrypted assertions in the SAML responses.

Sign SAML Requests sent to IdP

Use the configured SAML private key in the SSO authentication request sent to the IdP.

Use this option only when the IdP is expecting signed SAML authentication requests.

Signing Algorithm
Algorithm to use to sign SAML certificates. Change this in coordination with the client administrator.
Add AssertionConsumerServiceURL attribute in request

Set the AssertionConsumerServiceURL attribute in the SAML AuthnRequest sent to the IdP.

Assertion Values Separator

Character (string) that separates multiple values in the AssertionConsumerServiceURL attribute when the request contains more than one value. When there is no separator character and there are multiple values, only the first value is used and the rest are ignored.

This is especially useful when processing the SAML assertion with an Auto Importer specification

Error Redirect URL
URL to redirect the user to when there is a single sign-on error.
Logout Redirect URL
(avoid) URL to redirect the user to when the signs-out of the Medallia application.
Warning: Do not use this property if the IdP supports more applications than Experience Cloud applications, because using this property can cause the IdP to invalidate the user on all other applications.
Disable SP-initiated flow
Force the application to redirect to the IdP for authentication instead of using an SP-initiated session.
IDP home URL
The URL to the company's IdP home page. This is the URL users use to authenticate and launch applications.
SP Certificate
Identifies the configured certificates to use for SAML communications.

Medallia fully manages certificate lifecycle.

  • Medallia automatically generates the certificate.

  • Medallia rotates certificates automatically.

  • Medallia requires no renewals from the client.

  • No certificate signing request or certificate files need to be managed.

  • There is no downtime during certificate rotation.

When the primary certificate is due to expire, a new certificate will be created and installed on the instance as a "Secondary" certificate. After the certificate is installed:

  1. On the Single Sign-On screen, use Generate SAML Metadata File with secondary certificate to create a configuration, and share that with the client administrator.

  2. In coordination with the client administrator, change this setting from Primary to Secondary, and do it for this setting on both the Single Sign_on and SAML Identity Providers screens.

Eventually, when the old primary certificate expires and is removed, this setting will automatically be reset to Primary.

Seconds of clock drift to allow
Seconds before or after the assertion timestamp that the assertion is considered valid. Default is 10 (seconds). Use this property to account for clock-drift between the IdP and SP host machines.
Force one time use assertions
When this checkbox is selected, the OneTimeUse condition check is performed for all received assertions, so they cannot be reused after being processed. You cannot log in more than once with the same assertion.

Automatic selection

These properties define when to automatically use this IdP instead of redirecting you to the IdP select screen, where all the available IdPs are shown, letting you choose the IdP to use. For example, though a company might have multiple identity providers, these options can force all mobile device users to use just one specific IdP, while users on desktop devices might see a selection.

When more than one IdP have the automatic selection set:

  1. When two or more IdPs have automatic selection for mobile devices and the request is from a mobile device, Experience Cloud shows the IdP with the highest display order.

  2. When two or more IdPs have HTTP header selection criteria and it matches the request criteria, Experience Cloud shows the IdP with the highest display order.

  3. When there is an IdP with automatic selection and one without automatic selection, Experience Cloud does not show the one without automatic selection.

  4. When there is an IdP with automatic selection and this IdP has allow-listed IP addresses, the request must match both to be used in automatic redirection.

  5. When you select automatic selection for mobile devices, Experience Cloud ignores the HTTP header selection criteria.

  6. When one or more IdP have HTTP header selection criteria and it does not match the request criteria, Experience Cloud shows the IdP without defined criteria.

For Medallia employees:

  1. When the request is from an internal Medallia IP address and you have enabled automatic selection, Experience Cloud's login screen shows an external IdP and Medallia's employee authentication mechanism.

  2. When the request is from an internal Medallia IP address and you have defined HTTP header selection criteria, Experience Cloud's login screen shows an external IdP and Medallia's employee authentication mechanism.

Automatically select this IdP for mobile devices
Use this IdP for Medallia Mobile, Medallia Voices users, and for users accessing Medallia Web reporting via a mobile device. When this option is on, the HTTP Header selection criteria for all users accessing Medallia Web reporting is set to User-Agent=.*Mobi.* to detect mobile requests.
Note: When using a browser on a mobile device, almost all browsers include a User-Agent HTTP header that includes the string "Mobi" somewhere in the field value. As such, when this option is on, all users on mobile devices will only use this IdP configuration.
HTTP Header selection criteria

Use this IdP for users accessing Medallia Web reporting based on some criteria found in the HTTP header sent by the user's browser. The format is HeaderName=RegEx-pattern. For example, when the browser is set to request English language information, it includes a header like this:

Accept-Language: en-US,en;q=0.9

To route all "English language" request to the IdP, use this expression to catch all values that start with "en":

Accept-Language=^en*

This property is ignored when Automatically select this IdP for mobile devices is on.

Obtaining the metadata file

Each IdP (Okta, Ping, Keycloack, etc.) has its own specific process to obtain the metadata file, but generally, once you configure the IdP and save your data, the system shows a button or a URL to download the metadata. The format of the URL varies depending on the IdP and the authentication protocol selected (SAML, OIDC, etc.).

Download your IdP's metadata file in XML format:

  1. Click on the URL to access it with a web browser.

  2. Right-click on the browser screen, select Save as.

  3. Enter a filename and the ".xml" extension for the file.

  4. Click Save.

Optionally, using an IDE:

  1. Create a new flat file.

  2. Click on the URL to access it with a web browser.

  3. Select all the text that appears on the browser screen.

  4. Copy and paste the text in the flat file.

  5. Save it as an XML file.

For information on how to automatically configure the IdP settings with the IdP-metadata file, see Configure the IdP settings in the instance.