Create and verify SSO accounts with Auto Importer

When the Single Sign-On IdP sends an authorization, the Experience Cloud instance interprets the assertion to verify the account, and to optionally create or update an account if needed. There are two ways to process accounts based on the value in the assertion:

  • Verify existing accounts based on the Username or Company Account ID. This method only works when the value in the IdP response matches the value of an existing Username (case-insensitive) or Company ID (case-sensitive). For details, about using this method, see "Processing the response to identify the account" in:

  • Verify, update, and/or create accounts using an Auto Importer specification. This option is more flexible and can be used to process the ID value before performing the authorization activity, and can also be used to set data access in Experience Cloud for the user based on data sent in the assertion.

To process the assertion with an Auto Importer specification:

  1. Create an Auto Importer specification to map the attribute(s) to the field(s) in the account record. The rest of this section describes how to configure and test the specification.

  2. On the SAML Identity providers screen or OIDC Identity providers screen, set these properties:

    1. Autologon Enabled — turn it on.
      Tip: When you see the Service Provider Config screen on your instance, this option is enabled by default.

    2. Auto Importer — identify the importer specification.

  3. Click Save.

Warning: It is possible to update user-account passwords through Auto Importer. This feature may be deprecated in a future release. If your company requires this feature, contact your Medallia representative to have them validate the requirement with the Medallia Global Security and Compliance (GSC) team.
Note:

When using an import specification for account management, keep in mind:

  • The Auto Importer never updates accounts that have the Don't allow file uploads to automatically update user settings (No Automatic Update) option turned on. During SSO verification, when the account has No Automatic Update, Auto Importer generates an error for that record. The errors might include:

    Record discarded due to account not enabled for automatic updates: Issues associated with username ('Username'). or AutoImporter failed because automatic updates are disabled for the user, and lookup was unable to find the account

    However, under the following condition, the sign-on event does succeed, even though Auto Importer threw one of the above errors.

    To verify the existing account, the value of the Assertion Attribute Name field must not be empty, and it has to exactly match the attribute name from the SAML response; there can be no transformation of the name to make it match. This is only available when the identity provider is configured through the SAML Identity providers screen.

  • During create and update, if a required value is missing, or if a value does not match what is available for the account (such as an invalid role), the SSO sign-in fails.

  • The Auto Importer does not send admin emails after performing an SSO sign-in; there is no support for Send new account emails option.

  • The importer treats each SSO sign-in as a single-record import.

The rest of this topic describes how to use it Auto Importer to create and verify single sign-on accounts:

SAML assertions

When using SAML protocol, the SAML assertion from the IdP usually contains at least one XML attribute whose value is either the account's Username or Company ID. The attribute has a name defined by the IdP, and the identification value. In this example, the attribute name is CompID, and it has a single value (99.769.063):

<saml:AttributeStatement>
    <saml:Attribute
                    Name="CompID" ... >
        <ns2:AttributeValue ...>99.769.063</ns2:AttributeValue>
    </saml:Attribute>
    ...
</saml:AttributeStatement>

Sometimes the IdP passes the ID in the assertion Subject <nameId> instead of the <AttributeStatement>. This field can then be accessed in Auto Importer with the input column named: "saml.assertion.subject.name".

<saml:Subject>
    <saml:NameId ... Format="urn:oasis:names:tc:SAML:2.0:nameid-format:transient">99.769.063</saml:NameID>
</saml:Subject>

For a detailed example the of the XML in a SAML assertion, see SAML assertion example.

Important: All assertions include a Subject (saml.assertion.subject.name) value, regardless if the ID is in the attributes section. When the Auto Importer specification is not using the Subject for the ID, set columnsCheck="ALLOW_EXTRA_COLUMNS".

OIDC token claims

When using OIDC protocol, the ID token includes claims (JSON fields) that identify either the account's Username or Company ID. There is always are least one claim named "sub", and that claim is a unique identifier. Depending on the configuration, other claims might include email, name, or other identifying information.

{
  “iss”: “http://server.example.com“,
  “sub”: “248289761001",
  “aud”: “s6BhdRkqt3",
  “nonce”: “n-0S6_WzA2Mj”,
  “exp”: 1311281970,
  “iat”: 1311280970,
  “name”: “Jane Doe”,
  “given_name”: “Jane”,
  “family_name”: “Doe”,
  “gender”: “female”,
  “birthdate”: “0000-10-31",
  “email”: “janedoe@example.com”,
  “picture”: “http://example.com/janedoe/me.jpg”
}

Process single sign-on with Auto Importer specification

When using the Auto Importer, the system passes the attributes and values to the Account processor as a single record. In the Auto Importer specification:

  • The Input Type of the feed is XML (for SAML) or JSON (for OIDC), and columnsCheck must be set to ALLOW_EXTRA_OR_MISSING_COLUMNS.

    SAML:

    <import-spec inputType="XML" columnsCheck="ALLOW_EXTRA_OR_MISSING_COLUMNS"  ...

    OIDC:

    <import-spec inputType="JSON" columnsCheck="ALLOW_EXTRA_OR_MISSING_COLUMNS"  ...

  • There is one Input Column (input-column) for every field in the assertion. The column names match the field names.

  • The Update mode must be either

    • Creating and updating only (CREATE_AND_UPDATE) — Verify existing, update the record if necessary, and create a new account it doesn't exist.

    • Updating only (UPDATE) — Verify an existing account and update the record if necessary.

    Restriction: To update accounts, in the account turn the Don't allow file uploads to automatically update user settings (No Automatic Update) option.

  • One Output Field (output-column) identifies the account ID: it must be either Username (username) or Company Account Id (company_account_id).

    • The column must be marked Required, and marked Use for duplicate checking (REQUIRED_USED_FOR_DUPLICATE_CHECK).

    • When using Username, the value must be lowercase.

    • If the attributes include both Username and Company Account ID, only one can be used for duplicate checking. And to be safe, do not make the other field Required to avoid unexpected conflicts.

    Note: Medallia strongly recommends using Username as the account ID because it is guaranteed to be unique per account within a company. Company Account Id, however, has no uniqueness guarantee, and some companies have been known to reassign the IDs.

  • Optionally, there are Output Field for the remaining attributes. This is only necessary when the spec can create or update accounts, in which case these fields are also required:

    • Username (username)

    • Firstname (firstname)

    • Lastname (lastname)

    • User Group (primary_role)

    When an account already exists, the additional fields are updated in the existing record.

    Note: If the primary role does not include enough permissions for the user to access necessary reports, the spec will also need to declare the account's data access mappings or permission list.

Verify an existing account

This import specification verifies an existing account by performing an update on the Company Account ID field. If the record does not exist, the update fails and the user is not authorized.

<!-- 
    Name:    SSO SAML Account: Verify
    Type:    Authenticates users through SAML/SSO

    Notes: This AI Processor validates existing accounts based on the 
           Company Account ID field.
 -->
<import-spec inputType="XML" columnsCheck="ALLOW_EXTRA_OR_MISSING_COLUMNS" 
        name="ACCOUNT: SSO Account; Verify" 
        description="Handles SSO verification sign-ins">

    <input-column heading="CompID" />

    <output-column-group pluginName="Account" recordUpdateMode="UPDATE">
        <output-column>
            <input-column heading="CompID" />
            <target-field fieldId="company_account_ID" fieldName="Company ID" 
                requiredness="REQUIRED" type="STRING" />
        </output-column>
    </output-column-group>
</import-spec>

Creating and updating accounts

Here is a simple SAML import specification that creates new and updates existing accounts. Note that during an update, all fields marked OPTIONAL are replaced by the values in the assertion. If the assertion value is blank or missing, the field in the account record will be emptied of any existing data.

<!-- 
    Name:    SSO SAML Account: Create and Update
    Type:    Create/Update Users through SAML/SSO

    Notes: This AI Processor validates existing accounts, updating them if necessary,
    and creates a new account of the account does not already exist.
    
    These columns are required for CREATE: username, firstname, lastname, primary_role,
    and primary_role_access or permission_list
    But these are not required for UPDATE, hence they are 'OPTIONAL'.
 -->
<import-spec inputType="XML" columnsCheck="ALLOW_EXTRA_OR_MISSING_COLUMNS" 
        name="ACCOUNT: SSO Account: Create and update" description="Handles SSO sign-ins">
    <input-column heading="CompID" />
    <input-column heading="email" />
    <input-column heading="firstname" />
    <input-column heading="lastname" />
    <input-column heading="Group" />

    <output-column-group pluginName="Account" recordUpdateMode="CREATE_AND_UPDATE">
        <output-column>
            <input-column heading="CompID" />
            <target-field fieldId="company_account_ID" fieldName="Company ID" 
                requiredness="REQUIRED" type="STRING" />
        </output-column>
        <output-column>
            <input-column heading="email" />
            <target-field fieldId="email" fieldName="E-mail" 
                requiredness="OPTIONAL" type="EMAIL">
                <email-field-parse-options />
            </target-field>
        </output-column>
        <output-column>
            <input-column heading="firstname" />
            <target-field fieldId="firstname" fieldName="First Name" 
                requiredness="OPTIONAL" type="STRING" />
        </output-column>
        <output-column>
            <input-column heading="lastname" />
            <target-field fieldId="lastname" fieldName="Last Name" 
                requiredness="OPTIONAL" type="STRING" />
        </output-column>
        <output-column>
            <input-column heading="Group" />
            <target-field fieldId="primary_role" fieldName="Primary Role" 
                requiredness="OPTIONAL" type="ENUMERATED" />
        </output-column>
        <output-column>
            <target-field fieldId="primary_role_access" fieldName="primary_role Access" 
                requiredness="OPTIONAL" ignoreMissingValues="true" type="PERMISSION">
                <unit-group-permission-field-parse-options />
            </target-field>
        </output-column>
        <output-column>
            <target-field fieldId="permission_list" fieldName="Permission List" 
                requiredness="REQUIRED" type="PERMISSION_LIST">
                <unit-group-permission-field-parse-options delimiter=",">
                    <enumerated-field-parse-options mappingKey="IDENTIFIER" />
                </unit-group-permission-field-parse-options>
		<javascript-transform><![CDATA[
			permission("[RETAIL] Insights", null, "unittype_store", ADD_ROLE_TO_USER_IF_MISSING);
			permission("[RETAIL] Executive", null, "unittype_store", ADD_ROLE_TO_USER_IF_MISSING);
			permission("[CC] Insights", null, "unittype_cc_agent", ADD_ROLE_TO_USER_IF_MISSING);
			permission("[CC] Executive", null, "unittype_cc_agent", ADD_ROLE_TO_USER_IF_MISSING);
			permission("[CC] CLF Team", null, "unittype_cc_agent", ADD_ROLE_TO_USER_IF_MISSING);
			permission("[DIGITAL] Digital Team", null, "unittype_digital", ADD_ROLE_TO_USER_IF_MISSING);
			permission("[DIGITAL] CLF Team", null, "unittype_digital", ADD_ROLE_TO_USER_IF_MISSING);
			permission("[BRANCH] Corporate / Insights", null, "unittype_branch", ADD_ROLE_TO_USER_IF_MISSING);
			permission("[B2B] Regional / District Sales Manager", null, "unittype_b2b_account", ADD_ROLE_TO_USER_IF_MISSING);
			permission("[B2B] Account Manager / Sales Director", null, "unittype_b2b_account", ADD_ROLE_TO_USER_IF_MISSING);
			return permissions();
		]]></javascript-transform>
		</target-field>
        </output-column>
	<!-- OPTIONAL: To manually allow the user to sign-in with a password on the 
	     Login screen, set the 'blocked' field to false. Otherwise, omit this target. Users are blocked by default
	-->
	<output-column>
		<target-field fieldId="blocked" fieldName="Blocked" 
			requiredness="OPTIONAL" defaultValue="false" type="ENUMERATED">
			<enumerated-field-parse-options mappingKey="NAME" />
		</target-field>
	</output-column>
    </output-column-group>
</import-spec>

Test the Auto Importer specification

Note: These note are specific to testing the import specification. For general testing of SSO, see Testing SSO.

Test "sign-in" files can be processed in pretend mode through the auto importer spec to ensure the spec and records perform as expected without requiring the client to sign-in multiple times with different configurations. To test multiple combinations of attributes at a time, create a test file where the header names are the names of the attributes passed in the assertion. Multiple rows of user data can be tested at once.

The original XML of the SAML assertion, or the JSON of the OIDC token can also be directly uploaded and processed through Auto Importer on pretend to test a specific user’s sign-in attempt. This is especially useful when debugging sign-in issues as the XML or JSON can be copied directly from the Single sign-on failed attempts screen, copied to a text file, and uploaded and processed through Auto Importer. This allows you to confirm that the user will be able to sign-in with the correct information before asking them to sign-in again.

If the user is able to be authenticated but there is an issue when processing the SAML assertion through Auto Importer, the user will see the message "There were issues while processing the SAML permission attributes. Please contact your administrator." This message is not configurable.