--- title: Default policy for managed objects description: Policies applied to managed objects are configured in two places: component: pingidm version: 8.1 page_id: pingidm:objects-guide:configuring-default-policy canonical_url: https://docs.pingidentity.com/pingidm/8.1/objects-guide/configuring-default-policy.html keywords: ["Data Object Model", "Policy"] 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. Learn more in the [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. Learn more in the [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. Learn more in [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. Learn more in the [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. Learn more in [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 | Description | | ---------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `required` | | The property is required. | | `not-empty` | | The property can't be empty. | | `not-null` | | The property can't be null. | | `unique` | | The property must be unique. | | `valid-username` | | The property must be unique and not have internal user conflicts. | | `no-internal-user-conflict` | | The property must not have internal user conflicts. | | `regexpMatches` | `regexp``flags` | The property must match a regular expression pattern. | | `valid-type` | `types` | The property must have valid, specified types. | | `valid-query-filter` | | This rule enforces that each `privilege` entry adheres to the privilege defined in [Policies related to privileges](../auth-guide/delegated-admin.html#privilege-policies). The policy validates that the query filter used to filter privileges is a valid query. | | `valid-array-items` | | This rule enforces that each `privilege` entry adheres to the privilege defined in [Policies related to privileges](../auth-guide/delegated-admin.html#privilege-policies). This policy validates that each item in an array contains the properties specified in `policy.json`, and that each of those properties satisfies any specific policies applied to it. By default, this policy verifies that each privilege contains `name`, `path`, `accessFlags`, `actions`, and `permissions` properties and that the `filter` property is valid if included.For example, the following parameters have a set of properties found within the array with individual policies for them:```json { "params": { "properties": [ { "name": "name", "policies": [ { "policyId": "required" }, { "policyId": "not-empty" }, { "params": { "types": [ "string" ] }, "policyId": "valid-type" } ] }, { "name": "path", "policies": [ { "policyId": "required" }, { "policyId": "not-empty" }, ... ``` | | `valid-date` | | The property must have a valid date. Learn more in [RFC 3339-5.6](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). | | `valid-formatted-date` | | The property must have a valid date format. Learn more in [RFC 3339-5.6](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). | | `valid-time` | | The property must have a valid time. Learn more in [RFC 3339-5.6](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). | | `valid-datetime` | | The property must have a valid date and time. Learn more in [RFC 3339-5.6](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). | | `valid-duration` | | The property must have a valid duration format. Learn more in [RFC 3339-appendix-A](https://datatracker.ietf.org/doc/html/rfc3339#appendix-A). | | `valid-email-address-format` | | The property must have a valid email address. Learn more in [RFC 5321-4.1.2](https://datatracker.ietf.org/doc/html/rfc5321#section-4.1.2). | | `valid-name-format` | | The property must have a valid name format. Learn more in [RFC 5321-3.5.1](https://datatracker.ietf.org/doc/html/rfc5321#section-3.5.1). | | `valid-phone-format` | | The property must have a valid phone number format. Learn more in [E.123](https://en.wikipedia.org/wiki/E.123). | | `at-least-X-capitals` | `numCaps` | The property must contain the minimum specified number of capital letters. | | `at-least-X-numbers` | `numNums` | The property value must contain the minimum specified number of numbers. | | `validNumber` | | The property value must be an integer or floating-point number. | | `minimumNumber` | `minimum` | The property value must be greater than the `minimum` value. | | `maximumNumber` | `maximum` | The property value must be less than the `maximum` value. | | `minimum-length` | `minLength` | The property's minimum string length. | | `maximum-length` | `maxLength` | The property's maximum string length. | | `cannot-contain-others` | `disallowedFields` | The property cannot contain values of the specified fields. 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` | `forbiddenChars` | The property cannot contain the specified characters. 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` | | This rule enforces that each `privilege` entry adheres to the privilege defined in [Policies related to privileges](../auth-guide/delegated-admin.html#privilege-policies). The policy enforces well-formed permissions that include essential permissions, such as viewing, modification, or creation and adhere to a consistent and expected structure. This policy checks:- `CREATE` permissions must have write access to all properties required to create a new object. - `CREATE` and `UPDATE` permissions must have write access to at least one property. - `ACTION` permissions must include a list of allowed actions with at least one action included. - If any attributes have write access, then the privilege must also have either the `CREATE` or `UPDATE` permission. - All permissions listed must be valid types of permission: `VIEW`, `CREATE`, `UPDATE`, `ACTION`, or `DELETE`. No permissions are repeated.For example, a policy failure of `PRIVILEGE_MISSING_REQUIRED_CREATE_ATTRIBUTES` means that the privilege to create a managed object lacks access to that object's required attributes. | | `valid-accessFlags-object` | | This rule enforces that each `privilege` entry adheres to the privilege defined in [Policies related to privileges](../auth-guide/delegated-admin.html#privilege-policies). This policy validates if the `accessFlags` for a privilege matches the defined schema. The `accessFlag` entry must:- Contain an `attribute` property with a `String` value that matches a property name defined within the managed object's schema. The string value, such as "firstName", must be a property of the managed object for IDM to reference. - Contain a `readOnly` property with a boolean value. - Not contain any other attributes.For example, property names must be strings, such as "firstName", "lastName", "email". The property value must contain a property named `readOnly` whose value is a boolean, or `true` or `false`. The property value is invalid if it contains properties other than `readOnly`. | | `valid-privilege-path` | | This rule enforces that each `privilege` entry adheres to the privilege defined in [Policies related to privileges](../auth-guide/delegated-admin.html#privilege-policies). This policy validates that the `path` specified in the privilege is a valid object with a schema for IDM to reference. Only objects with a schema, such as `managed/user` can have privileges applied to them. | | `valid-temporal-constraints` | | The property must have valid temporal constraints. A non-empty array or a `ScriptableList` that must conform to a specific, predefined structure or pattern. | ## 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, or 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" ] } } ] } } } } ``` | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | 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, such as the number of capitals required, 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`. Learn more about data types in the [Type-specific Keywords](https://json-schema.org/understanding-json-schema/reference/type) section of the JSON Schema Reference. The `type` property is subject to policy validation when a managed object is created or updated. Validation fails if data doesn't 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 can 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 IDM admin UI, update the configuration of the object type: 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. In 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. On the Validation tab, click Add Policy. 5. In the Add/Edit Policy modal, enter information in the following fields, and click Add or Save: * Policy Id Refers to the unique `PolicyId` in the `policy.js` file. Learn more about default policies in the [Policy Reference](#policy-reference). * Parameter Name Refers to the parameters for the `PolicyId`. You can find a list of the default policy parameters in the [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, you should always set Return by Default to `false`. You can verify this setting 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`. |