--- title: Default policy for managed objects description: Policies applied to managed objects are configured in two places: component: pingidm version: 7.2 page_id: pingidm:objects-guide:configuring-default-policy canonical_url: https://docs.pingidentity.com/pingidm/8.1/objects-guide/configuring-default-policy.html llms_txt: https://docs.pingidentity.com/pingidm/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md superseded_by: https://docs.pingidentity.com/pingidm/8.1/objects-guide/configuring-default-policy.html section_ids: policy-script-file: Policy script policy-config-object: Policy configuration objects policy-function: Policy implementation functions policy-reference: Default policy reference policy-config-element: Policy configuration element policy-config-input: Validate managed object data types policy-config-ui: Configure policy validation using the admin UI --- # Default policy for managed objects Policies applied to managed objects are configured in two places: * A policy script that defines each policy and specifies how policy validation is performed. For more information, see [Policy Script](#policy-script-file). * A managed object policy element, defined in your managed object configuration *(tooltip: You can edit the managed object configuration over REST at the config/managed endpoint, or directly in the conf/managed.json file.)*, that specifies which policies are applicable to each managed resource. For more information, see [Policy Configuration Element](#policy-config-element). | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The policy configuration *(tooltip: You can edit the policy configuration over REST at the config/policy endpoint, or directly in the conf/policy.json file.)* determines which policies apply to resources *other than managed objects*. The default policy configuration includes policies that are applied to internal user objects, but you can extend the configuration to apply policies to system objects. | ## Policy script The policy script file (`openidm/bin/defaults/script/policy.js`) separates policy configuration into two parts: * A policy configuration object, which defines each element of the policy. For more information, see [Policy Configuration Objects](#policy-config-object). * A policy implementation function, which describes the requirements that are enforced by that policy. Together, the configuration object and the implementation function determine whether an object is valid in terms of the applied policy. The following excerpt of a policy script file configures a policy that specifies that the value of a property must contain a certain number of capital letters: ```javascript ... { "policyId": "at-least-X-capitals", "policyExec": "atLeastXCapitalLetters", "clientValidation": true, "validateOnlyIfPresent": true, "policyRequirements": ["AT_LEAST_X_CAPITAL_LETTERS"] }, ... policyFunctions.atLeastXCapitalLetters = function(fullObject, value, params, property) { var isRequired = _.find(this.failedPolicyRequirements, function (fpr) { return fpr.policyRequirement === "REQUIRED"; }), isString = (typeof(value) === "string"), valuePassesRegexp = (function (v) { var test = isString ? v.match(/[A-Z]/g) : null; return test !== null && test.length >= params.numCaps; }(value)); if ((isRequired || isString) && !valuePassesRegexp) { return [ { "policyRequirement" : "AT_LEAST_X_CAPITAL_LETTERS", "params" : {"numCaps": params.numCaps} } ]; } return []; } ... ``` To enforce user passwords that contain at least one capital letter, the `policyId` from the preceding example is applied to the appropriate resource (`managed/user/*`). The required number of capital letters is defined in the policy configuration element of the managed object configuration file (see [Policy Configuration Element](#policy-config-element)). ### Policy configuration objects Each element of the policy is defined in a policy configuration object. The structure of a policy configuration object is as follows: ```json { "policyId": "minimum-length", "policyExec": "minLength", "clientValidation": true, "validateOnlyIfPresent": true, "policyRequirements": ["MIN_LENGTH"] } ``` | | | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `policyId` | A unique ID that enables the policy to be referenced by component objects. | | `policyExec` | The name of the function that contains the policy implementation. For more information, see [Policy Implementation Functions](#policy-function). | | `clientValidation` | Indicates whether the policy decision can be made on the client. When `"clientValidation": true`, the source code for the policy decision function is returned when the client requests the requirements for a property. | | `validateOnlyIfPresent` | Notes that the policy is to be validated only if the field within the object being validated exists. | | `policyRequirements` | An array containing the policy requirement ID of each requirement that is associated with the policy. Typically, a policy will validate only one requirement, but it can validate more than one. | ### Policy implementation functions Each policy ID has a corresponding policy implementation function that performs the validation. Implementation functions take the following form: ```javascript function (fullObject, value, params, propName) { } ``` * `fullObject` is the full resource object that is supplied with the request. * `value` is the value of the property that is being validated. * `params` refers to the `params` array that is specified in the property's policy configuration. * `propName` is the name of the property that is being validated. The following example shows the implementation function for the `required` policy: ```javascript function required(fullObject, value, params, propName) { if (value === undefined) { return [ { "policyRequirement" : "REQUIRED" } ]; } return []; } ``` ## Default policy reference IDM includes the following default policies and parameters: | Policy Id | Parameters | | | ----------------------------------------------------------------------------------------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `required`The property is required; not optional. | | | | `not-empty`The property can't be empty. | | | | `not-null`The property can't be null. | | | | `unique`The property must be unique. | | | | `valid-username`Tests for uniqueness and internal user conflicts. | | | | `no-internal-user-conflict`Tests for internal user conflicts. | | | | `regexpMatches`Matches a regular expression. | `regexp``flags` | The regular expression pattern. | | `valid-type`Tests for the specified types. | `types` | | | `valid-query-filter`Tests for a valid query filter. | | | | `valid-array-items`Tests for valid array items. | | | | `valid-date`Tests for a valid date. | | | | `valid-formatted-date`Tests for a valid date format. | | | | `valid-time`Tests for a valid time. | | | | `valid-datetime`Tests for a valid date and time. | | | | `valid-duration`Tests for a valid duration format. | | | | `valid-email-address-format`Tests for a valid email address. | | | | `valid-name-format`Tests for a valid name format. | | | | `valid-phone-format`Tests for a valid phone number format. | | | | `at-least-X-capitals`The property must contain the minimum specified number of capital letters. | `numCaps` | Minimum number of capital letters. | | `at-least-X-numbers`The property must contain the minimum specified number of numbers. | `numNums` | Minimum number of numbers. | | `validNumber`Tests for a valid number. | | | | `minimumNumber`The property value must be greater than the `minimum`. | `minimum` | The minimum value. | | `maximumNumber`The property value must be less than the `maximum`. | `maximum` | The maximum value. | | `minimum-length`The property's minimum string length. | `minLength` | The minimum string length. | | `maximum-length`The property's maximum string length. | `maxLength` | The maximum string length. | | `cannot-contain-others`The property cannot contain values of the specified fields. | `disallowedFields` | A comma-separated list of the fields to check against. For example, the default managed user password policy specifies `userName,givenName,sn` as disallowed fields. | | `cannot-contain-characters`The property cannot contain the specified characters. | `forbiddenChars` | A comma-separated list of disallowed characters. For example, the default managed user `userName` policy specifies `/` as a disallowed character. | | `cannot-contain-duplicates`The property cannot contain duplicate characters. | | | | `mapping-exists`A sync mapping must exist for the property. | | | | `valid-permissions`Tests for valid permissions. | | | | `valid-accessFlags-object`Tests for valid access flags. | | | | `valid-privilege-path`Tests for a valid privilege path. | | | | `valid-temporal-constraints`Tests for valid temporal constraints. | | | ## Policy configuration element Properties defined in the managed object configuration *(tooltip: You can edit the managed object configuration over REST at the config/managed endpoint, or directly in the conf/managed.json file.)* can include a `policies` element that specifies how policy validation should be applied to that property. The following excerpt of the default managed object configuration shows how policy validation is applied to the `password` and `_id` properties of a managed/user object. | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | You can only declare policies on top-level managed object attributes. Nested attributes (those within an array or object) cannot have policy declared on them. | ```json { "name" : "user", "schema" : { "id" : "http://jsonschema.net", "properties" : { "_id" : { "description" : "User ID", "type" : "string", "viewable" : false, "searchable" : false, "userEditable" : false, "usageDescription" : "", "isPersonal" : false, "policies" : [ { "policyId" : "cannot-contain-characters", "params" : { "forbiddenChars" : [ "/" ] } } ] }, "password" : { "title" : "Password", "description" : "Password", "type" : "string", "viewable" : false, "searchable" : false, "userEditable" : true, "encryption" : { "purpose" : "idm.password.encryption" }, "scope" : "private", "isProtected": true, "usageDescription" : "", "isPersonal" : false, "policies" : [ { "policyId" : "minimum-length", "params" : { "minLength" : 8 } }, { "policyId" : "at-least-X-capitals", "params" : { "numCaps" : 1 } }, { "policyId" : "at-least-X-numbers", "params" : { "numNums" : 1 } }, { "policyId" : "cannot-contain-others", "params" : { "disallowedFields" : [ "userName", "givenName", "sn" ] } } ] } } } } ``` Note that the policy for the `_id` property references the function `cannot-contain-characters`, that is defined in the `policy.js` file. The policy for the `password` property references the functions `minimum-length`, `at-least-X-capitals`, `at-least-X-numbers`, and `cannot-contain-others`, that are defined in the `policy.js` file. The parameters that are passed to these functions (number of capitals required, and so forth) are specified in the same element. ## Validate managed object data types The `type` property of a managed object specifies the data type of that property, for example, `array`, `boolean`, `number`, `null`, `object`, or `string`. For more information about data types, see the [JSON Schema Primitive Types](https://json-schema.org/draft/2020-12/json-schema-core) section of the JSON Schema standard. The `type` property is subject to policy validation when a managed object is created or updated. Validation fails if data does not match the specified `type`, such as when the data is an `array` instead of a `string`. The default `valid-type` policy enforces the match between property values and the `type` defined in the managed object configuration *(tooltip: You can edit the managed object configuration over REST at the config/managed endpoint, or directly in the conf/managed.json file.)*. IDM supports multiple valid property types. For example, you might have a scenario where a managed user can have more than one telephone number, or a *null* telephone number (when the user entry is first created and the telephone number is not yet known). In such a case, you could specify the accepted property type as follows in your managed object configuration *(tooltip: You can edit the managed object configuration over REST at the config/managed endpoint, or directly in the conf/managed.json file.)*: ```json "telephoneNumber" : { "type" : "string", "title" : "Telephone Number", "description" : "Telephone Number", "viewable" : true, "userEditable" : true, "pattern" : "^\\+?([0-9\\- \\(\\)])*$", "usageDescription" : "", "isPersonal" : true, "policies" : [ { "policyId" : "minimum-length", "params" : { "minLength" : 1 } }, { "policyId": "maximum-length", "params": { "maxLength": 255 } } ] } ``` In this case, the `valid-type` policy from the `policy.js` file checks the telephone number for an accepted `type` and `pattern`, either for a real telephone number or a `null` entry. ## Configure policy validation using the admin UI To configure policy validation for a managed object type using the admin UI, update the configuration of the object type—a high-level overview: 1. Go to the managed object, and edit or create a property. 2. Click the Validation tab, and add the policy. > **Collapse: Show Me** > > ![createPolicyUI](_images/createPolicyUI.gif) 1. From the navigation bar, click Configure > Managed Objects. 2. On the Managed Objects page, [edit or create a managed object](creating-modifying-managed-objects.html). 3. On the Managed Object NAME page, do one of the following: * To edit an existing property, click the property. * To create a property, click Add a Property, enter the required information, and click Save. * Now click the property. 4. From the Validation tab, click Add Policy. 5. In the Add/Edit Policy window, enter information in the following fields, and click Add or Save: * Policy Id Refers to the unique `PolicyId` in the `policy.js` file. For a list of the default policies, see [Policy Reference](#policy-reference). * Parameter Name Refers to the parameters for the `PolicyId`. For a list of the default policy parameters, see [Policy Reference](#policy-reference). * Value The parameter's value to validate. | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Be cautious when using Validation Policies. If a policy relates to an array of relationships, such as between a user and multiple devices, Return by Default should always be set to `false`. You can verify this in your managed object configuration *(tooltip: You can edit the managed object configuration over REST at the config/managed endpoint, or directly in the conf/managed.json file.)*. Any managed object that has `items` of `"type" : "relationship"`, must also have `"returnByDefault" : false`. |