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".

Note

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"
    }
  ]
}

Note

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.

selfservice.terms.json Details

Property	Description
`version`	Specifies a version number (must be unique).
`termsTranslations`	Supports Terms & Conditions in different languages. Note 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"
      }
    }
  ],
  ...
}

Configuring Terms & Conditions in the Admin UI

From the Admin UI, select Configure > Terms & Conditions. You can then create a new version, which prompts you to configure the following:

Version number (must be unique).
If there are existing Terms & Conditions, you'll see a Make active switch for the new 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.

Once you've added Terms & Conditions in all desired locales, select Save to save them in the selfservice.terms.json file.

Note

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

Once you have at least one set of Terms & Conditions, you should see a Settings tab, where you can:

Require acceptance; the next time any end user logs into IDM, that user will see a copy of your Terms & Conditions, with the Header, Description, and Button Text.
To make sure new users have to accept these Terms & Conditions, select Configure > User Registration in the Admin UI. Enable Terms & Conditions under the Options tab. For more information, see Self-Registration. Users who self-register will see the following message, with a link to those Terms & Conditions:
```
By creating an account, you agree to the Terms & Conditions
```

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".