Site User Profile Mapping

Once a user has authenticated, certain details are passed back to us from the provider (assuming the user gave their consent). These details may be used to update the user profile at first user registration and/or at every user login. Refer to the Update Profiles section of the Linking Providers, Account and Profile Management documentation for further information.

For most providers we know exactly which details we'll get back. These details are listed in the articles for each provider.

For example, we know that Facebook will give us details in properties called id, email, first_name, middle_name, last_name. This means we can automatically map those details to the standard user profile class of the Authentication worker.

However for certain providers, like ADFS, SAML2 and LDAPSSO, an additional custom mapping must be supplied as the data returned will differ from provider to provider.

The mapping process has two stages. First each provider maps profile attributes to the base user profile class (generally via a property called userProfileAttributeMapping), then the Authentication worker root configuration maps the fields in the base class to the site's user profile form via the userProfileToObjectFieldMapping.

The UserProfile Class

Data returned from providers is mapped to a provider agnostic intermediary user profile class. This class looks like this:

class UserProfile {
    // UNIQUEID is the only required value, and the value mapped to it must
    // be unique to the given user (eg the ID used by the external
    // system). It is used to construct the name of the corresponding iCM
    // site user that will be created.
    String UNIQUEID;

    // Commonly used fields.
    String TITLE;
    String PREFERREDNAME;
    String FORENAMES;
    String MIDDLENAMES;
    String SURNAME;
    String EMAIL;
}

Example User Profile Attribute Mapping

If you are setting up an ADFS provider, your provider configuration will include something like:

"userProfileAttributeMapping": {
    "mapping": {
        "UPN": {
            "mappings": ["UNIQUEID"]
        },
        "WINACCOUNTNAME": {
            "mappings": ["SAMACCOUNTNAME"]
        },
        "TITLE": {
            "mappings": ["TITLE"]
        },
        "GIVEN_NAME": {
            "mappings": ["FORENAMES", "PREFERREDNAME"]
        },
        "MNAME": {
            "mappings": ["MIDDLENAMES"],
            "defaultValue": "EXAMPLE_DEFAULT_VALUE",
            "setDefaultValueForNull": true
        }
        "FAMILY_NAME": {
            "mappings": ["SURNAME"]
        },
        "EMAIL": {
            "mappings": ["EMAIL"]
        }
    }
}

The elements in italics are properties in whatever store of user data you are connecting to. They are mapped to fields in the base user profile class (not fields on your site user profile form).

Note that all values are uppercased and spaces replaced with underscores. Receiving the claim Employee ID would require the following mapping:

"userProfileAttributeMapping": {
    "mapping": {
        "EMPLOYEE_ID": {
            "mappings": ["UNIQUEID"]
        },

The MNAME mapping above shows how default values can be set:

• If a defaultValue is supplied and no data is returned from the service for the mapping then default value will be passed through
• If setDefaultValueForNull is true (default: false) then if a null is returned for MNAME the default value will be passed through

From UserProfile Class to Site User Profile

iCM site user profiles are defined by a form. While this makes them very flexible - you can decide exactly what fields you want on your user profile form and what they're called - it also makes it very difficult for us to write a standard "off the shelf" authentication provider that will put all of the correct details in the correct user profile fields.

To get around this problem a mapping needs to be added to the root Worker Configuration Properties that will take the properties of the user profile class and map them to your user profile form. This is done using the userProfileToObjectFieldMapping property.

In the following example the UserProfile class fields (on the left) are mapped to the "old style" iCM Site User USERPROFILE object, including one additional field returned by the MyGovScot SAML2 provider:

"userProfileToObjectFieldMapping": {
    "mapping": {
      "TITLE":      { "mappings": ["CONTACT.NAME.TITLE"] },    
      "PREFERREDNAME": { "mappings": ["CONTACT.NAME.PREFNAME"] },    
      "FORENAMES":  { "mappings": ["CONTACT.NAME.FIRSTNAME"] },
      "SURNAME":    { "mappings": ["CONTACT.NAME.LASTNAME"] },
      "EMAIL":      { "mappings": ["CONTACT.WEBADDRESS.EMAIL"] },
      "BIRTHDAY":   { "mappings": ["CONTACT.BIRTHDAY"], "inputDateFormat": "yyyyMMddHHmmss.SSS'Z'" },   
      // An additional field returned from the MyGovScot provider,
      // mapped to a USERPROFILE object field.
      // Must be defined in the user profile object definition.
      "UCPN":       { "mappings": ["CONTACT.CUSTOM.UCPN"] }
   }
}

It's possible to map class fields to multiple profile fields if you need to. For example, FORENAMES could be mapped to two profile fields using:

"FORENAMES":  { "mappings": ["CONTACT.NAME.FIRSTNAME", "CONTACT.NAME.SECONDARYFIRSTNAMEFIELD"] },

Unfortunately it's not currently possible to map multiple class fields to a single profile field (for example you cannot combine FORENAMES and SURNAME and insert them both into the PREFNAME).

Usernames

The usernames of the users that get created are never revealed to the end user. The names are a combination of the userPrefix you set in the configuration of your provider, plus the UNIQUEID of the user profile class. So, for a Facebook provider with "userPrefix": "FB_" you'd see site users called: