PingIDM 7.5.0

Privacy and consent

As an end user, you might want to control what happens to your personal data. For IDM, that means control of how your data is shared with external systems. The example in Marketo connector shows how you can generate a marketing leads database, only for those users who have selected a specific preference. Also read Privacy and consent.

IDM allows you to regulate access to two different kinds of personal data:

  • User information: while marketers want user information such as addresses and telephone numbers, IDM allows you to let individual users decide whether to share that data. For more information, refer to Regulating HTTP Access to Personal Data.

  • Account information: by default, IDM prevents REST-based access to passwords with the private scope, as defined in the managed.json file. You can extend this protection to other properties. For more information, refer to Restricting HTTP Access to Sensitive Data.

You can configure Privacy and Consent for users who register directly through IDM, or through a social identity provider. For more information on the registration process, refer to User self-registration and Social registration.

When you have configured Privacy and Consent, end users must agree to share their data before they can obtain a registered account.

To configure Privacy and Consent, edit the following configuration files:

  • In selfservice-registration.json , add the following JSON object:

    {
    "name" : "consent",
    "consentTranslations" : {
     "en" : "<Substitute appropriate Privacy and Consent wording>",
     "fr" : "<Substitute appropriate Privacy and Consent wording, in French>"
    }
},

    Add custom privacy and consent notices for all your required languages in the consentTranslations property.

    Alternatively, send the corresponding request over REST to the /openidm/config/selfservice/registration endpoint.

  • In the mapping configuration, include:

    "consentRequired" : true,

  1. From the navigation bar, click Configure > Mappings, and select a mapping.

    Although the admin UI includes the Privacy & Consent switch for all mappings, it makes sense to configure Privacy and Consent only for mappings from the Managed Object source to an external target resource. In other words, end users give their consent to transfer some or all of their managed user data to an external system.

  2. Click the Advanced tab, activate Enable Privacy & Consent, and then click Save.

  3. From the navigation bar, click Configure > User Registration.

    If Enable User Registration is inactive, refer to User Self-Registration.

  4. Click the Options tab, and activate Privacy & Consent.

  5. In the Configure Privacy & Consent window, add privacy notices for any necessary languages, and click Save.

In some cases, you might want to allow users to choose whether to share their personal data. User preferences describes how to allow users to select basic preferences for updates and marketing. They can select these preferences when they register and in the End User UI.

Examine the managed.json file for your project. Every relevant property should include two settings that determine whether a user can choose to share or not share that property:

  • isPersonal: When set to true, specifies personally identifying information. By default, the isPersonal option for userName and postalAddress is set to true.

    usageDescription: Includes additional information that can help users understand the sensitivity of a specific property such as telephoneNumber.

The consentedMappings property in a managed user object enables the user to specify an array of mappings (target systems) with which they consent to sharing their identifying information. The following sample excerpt of the default managed user object schema shows the consentedMappings property definition:

"consentedMappings": {
    "title": "Consented Mappings",
    "description": "Consented Mappings",
    "type": "array",
    "viewable": false,
    "searchable": false,
    "userEditable": true,
    "usageDescription": "",
    "isPersonal": false,
    "items": {
      "type": "object",
      "title": "Consented Mapping",
      "properties": {
        "mapping": {
          "title": "Mapping",
          "description": "Mapping",
          "type": "string",
          "viewable": true,
          "searchable": true,
          "userEditable": true
        },
        "consentDate": {
          "title": "Consent Date",
          "description": "Consent Date",
          "type": "string",
          "viewable": true,
          "searchable": true,
          "userEditable": true
        }
      },
      "order": [
        "mapping",
        "consentDate"
      ],
      "required": [
        "mapping",
        "consentDate"
      ]
    },
    "returnByDefault": false,
    "isVirtual": false
}

You can protect specific sensitive managed data by marking the corresponding properties as private. Private data, whether it is encrypted or not, is not accessible over the REST interface. Properties that are marked as private are removed from an object when that object is retrieved over REST.

To mark a property as private, set its scope to private in the conf/managed.json file.

The following extract of the managed.json file shows how HTTP access is prevented on the password property:

{
    "objects": [
        {
            "name": "user",
            "schema": {
                "id" : "http://jsonschema.net",
                "title" : "User",
                ...
                "properties" : {
                    ...
                    "password" : {
                        "title" : "Password",
                        ...
                        "encryption" : {
                            "purpose": "idm.password.encryption"
                        },
                        "scope" : "private",
                        ...
        }
    ]
}

To configure private properties using the admin UI:

  1. Select Configure > Managed Objects, and select the object type whose property values you want to make private (for example, User).

  2. On the Properties tab, select the property that must be private, and select the Private checkbox.

A potential caveat relates to private properties. If you use an HTTP GET request, you won’t even refer to private properties. Even if you know all relevant private properties, a PUT request would replace the entire object in the repository. In addition, that require would effectively remove all private properties from the object. To work around this limitation, use a POST request to update only those properties that require change.

For example, to update the givenName of user jdoe, you could run the following command:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--cacert ca-cert.pem \
--request POST \
--data '[
  {
    "operation": "replace",
    "field": "/givenName",
    "value": "Jon"
  }
]' \
"https://localhost:8443/openidm/managed/user?_action=patch&_queryId=for-userName&uid=jdoe"

The filtering of private data applies only to direct HTTP read and query calls on managed objects. No automatic filtering is done for internal callers, and the data that these callers choose to expose.