Terms & Conditions

Most entities require users to accept Terms & Conditions. By default, this feature is active for user self-registration in IDM. When a user accepts Terms & Conditions, IDM records relevant information in the _meta data for that user, as described in Identifying When a User Accepts Terms & Conditions.

To use this feature, auth.profile.json must be present in the /path/to/openidm/conf/ directory.

Terms & Conditions configuration files

selfservice.terms.json

Exists in the /path/to/openidm/conf/ directory and contains the default Terms & Conditions language:

{
  "versions": [
    {
      "version": "0.0",
      "termsTranslations": {
        "en": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum."
      },
      "createDate": "2019-10-28T04:20:11.320Z"
    }
  ],
  "active": "0.0",
  "uiConfig": {
    "displayName": "We've updated our terms",
    "purpose": "You must accept the updated terms in order to proceed.",
    "buttonText": "Accept"
  }
}

selfservice-termsAndConditions.json

To force existing IDM users to accept new Terms & Conditions during login, copy selfservice-termsAndConditions.json from your project’s conf directory to your project directory, and edit the file, as necessary.

The following example applies Terms & Conditions to the managed/user store:

{
  "stageConfigs" : [
    {
      "name" : "conditionaluser",
      "identityServiceUrl" : "managed/user",
      "condition" : {
        "type" : "terms"
      },
      "evaluateConditionOnField" : "user",
      "onConditionTrue" : {
        "name" : "termsAndConditions"
      }
    },
    {
      "name" : "patchObject",
      "identityServiceUrl" : "managed/user"
    }
  ]
}

IDM does not support <form> elements or <script> tags in Terms & Conditions text.

Substitute Terms & Conditions content to meet the legal requirements of your applicable governing entities.

Property Description

version

Specifies a version number (must be unique).

termsTranslations

Supports Terms & Conditions in different languages.

For Terms & Conditions in multiple languages, what the end user sees depends on their browser default language, based on ISO-639 language codes:

First, IDM determines the active version, as defined in the selfservice.terms.json file:

If the browser default language matches one of the configured Terms & Conditions languages, IDM displays it.
If the browser default language does not match any configured Terms & Conditions languages:
- IDM displays the en language.
- If there is no en language, IDM displays the first configured language for the active version.

createDate

Creation date.

active

Specifies the version of Terms & Conditions shown to users; must match an existing version.

displayName

The title of the Terms & Conditions page, as seen by end users.

purpose

Help text shown below the displayName.

buttonText

Button text shown to the end user for acceptance.

Preview Terms & Conditions as an end user

To preview Terms & Conditions in the End User UI:

Create a regular user.
Log in to the End User UI as the new user.

IDM prompts you to accept the default Terms & Conditions.

Updating Terms & Conditions over REST

You can manage the configuration for Terms & Conditions over the following endpoints:

openidm/config/selfservice.terms
openidm/config/selfservice/termsAndConditions

For example, the following command would replace the value of buttonText:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--request PATCH \
--data '[ {
  "operation" : "replace",
  "field" : "uiConfig/buttonText",
  "value" : "OK"
} ]' \
"http://localhost:8080/openidm/config/selfservice.terms"

Identifying when a user accepts Terms & Conditions

You can identify when a user accepts Terms & Conditions, as well as the associated version. To do so, take the following steps:

If needed, find identifying information for all managed users:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"http://localhost:8080/openidm/managed/user?_queryId=query-all"

Use REST to get a specific user’s information. This example illustrates how a user with a userName of kvaughan has already accepted a specific version of Terms & Conditions:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"http://localhost:8080/openidm/managed/user?_queryFilter=userName+eq+'kvaughan'&_fields=*,/_meta/*"
{
  "result": [
    {
      ...
      "userName": "kvaughan",
      ...
        "termsAccepted": {
          "acceptDate": "2018-04-12T22:55:33.370Z",
          "termsVersion": "2.0"
        },
        "createDate": "2018-04-12T22:55:33.395Z",
        "lastChanged": {
          "date": "2018-04-12T22:55:33.395Z"
        },
        "loginCount": 1,
        "_rev": "00000000776f8be1",
        "_id": "69124007-05ec-46e1-a8a8-ecc3d94db124"
      }
    }
  ],
  ...
}

Configure Terms & Conditions using the admin UI

The admin UI does not let you delete existing Terms & Conditions.

From the navigation bar, click Configure > Terms & Conditions.
Click New Version, and on the New Terms & Conditions Version page, configure the following:
- Version (must be unique).
- If there are existing Terms & Conditions, a Make active switch displays. If you activate this option, all users must accept the new, active Terms & Conditions.
- Locale, in ISO-639 format.
- Terms & Conditions, in the specified language locales. You can set up Terms & Conditions in text and/or basic HTML.
After you’ve added Terms & Conditions to all desired locales, click Save.

IDM saves your changes in the selfservice.terms.json file.
Once you have at least one set of Terms & Conditions, click the Settings tab, configure the following, and click Save:
- Require acceptance switch—the next time any end user logs into IDM, that user will refer to a copy of your Terms & Conditions, with the Header, Description, and Button Text.
- Header.
- Description.
- Button Text.
To make sure new users must accept the Terms & Conditions:
1. From the navigation bar, click Configure > User Registration, and select the Options tab.
2. Enable Terms & Conditions. For more information, refer to Self-registration.

These changes are recorded in _meta data for each user, and can be retrieved through REST calls described in Identifying When a User Accepts Terms & Conditions.

PingIDM 7.5.0