--- title: Apply policies to managed objects description: In Advanced Identity Cloud, you can apply policies to managed objects to ensure that their values meet specific requirements. For example, you can require a password to have a minimum length or ensure a username is unique. component: pingoneaic page_id: pingoneaic:idm-objects:configuring-default-policy canonical_url: https://docs.pingidentity.com/pingoneaic/idm-objects/configuring-default-policy.html keywords: ["Data Object Model", "Policy"] section_ids: policy-config-aic-ui: Configure policy validation in the Advanced Identity Cloud admin console policy-config-idm-ui: Configure policy validation in the IDM native admin console policy-config-object: Policy configuration objects policy-reference: Policy reference policy-config-element: Policy configuration element policy-config-input: Validate object data types conditional-policy-definitions: Add conditional policy definitions --- # Apply policies to managed objects In Advanced Identity Cloud, you can apply policies to managed objects to ensure that their values meet specific requirements. For example, you can require a password to have a minimum length or ensure a username is unique. You can add a policy using: * [The Advanced Identity Cloud admin console](#policy-config-aic-ui) (recommended) * [The IDM native admin console](#policy-config-idm-ui) * The policy configuration *(tooltip: You can edit the policy configuration over REST at the config/policy endpoint.)* | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Be cautious when using validation policies. If a policy relates to an array of [relationships](relationships.html), 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.)*. Any managed object that has `items` of `"type" : "relationship"`, must also have `"returnByDefault" : false`. | The policy configuration *(tooltip: You can edit the policy configuration over REST at the config/policy endpoint.)* 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. ## Configure policy validation in the Advanced Identity Cloud admin console 1. In the Advanced Identity Cloud admin console, go to Identities > Configure. 2. Select the managed object type, for example, Alpha realm - User or Bravo realm - User. 3. Click the Properties tab. 4. Do one of the following: * To edit an existing property, click the property. * To create a property, click Add a Property, select the property type and enter the required information, and click Save. Then, select the property you just created. 5. On the property's Validation tab, define the validation policy for the property. 6. Click Save. ## Configure policy validation in the IDM native admin console 1. In the Advanced Identity Cloud admin console, click Native Consoles > Identity Management. 2. Select the managed object type, for example, Alpha Realm - User or Bravo Realm - User. 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. Then, select the property you just created. 4. On 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`. You can find a list of the 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. ## 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. | | `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 reference You can apply policies defined by Advanced Identity Cloud to the properties of any managed object or internal object. Advanced Identity Cloud 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](https://docs.pingidentity.com/pingidm/8/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](https://docs.pingidentity.com/pingidm/8/auth-guide/delegated-admin.html#privilege-policies). This policy validates that each item in an array contains the properties specified in the 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 can't contain values of the specified fields. A comma-separated list of the fields to check against. For example, the default user password policy specifies `userName,givenName,sn` as disallowed fields. | | `cannot-contain-characters` | `forbiddenChars` | The property can't contain the specified characters. A comma-separated list of disallowed characters. For example, the default 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](https://docs.pingidentity.com/pingidm/8/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](https://docs.pingidentity.com/pingidm/8/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](https://docs.pingidentity.com/pingidm/8/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.)* 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 `id` property of a managed/realm-name\_user object. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | Policies have the following restrictions:- They may be declared **only** on top-level managed object attributes. - They may **not** be declared on an attribute that is an array or on any nested attributes (those within an array or object). | ```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 } } } } ``` The policy for the `_id` property references the function `cannot-contain-characters`. This is a [default policy](#policy-reference) that you can apply. ## Validate 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 [JSON Schema Primitive Types](https://json-schema.org/draft-04/draft-zyp-json-schema-04#rfc.section.3.5) 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 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.)*. Advanced Identity Cloud 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.)*: ```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 type is defined in the policy configuration *(tooltip: You can edit the policy configuration over REST at the config/policy endpoint.)*. The policy checks the telephone number for an accepted `type` and `pattern`, either for a real telephone number or a `null` entry. ## Add conditional policy definitions You can extend the policy service to support policies that are applied only under specific conditions. To apply a conditional policy to objects types, add the policy to your project's managed object configuration *(tooltip: You can edit the managed object configuration over REST at the config/managed endpoint.)*. To apply a conditional policy to other objects, add it to your project's policy configuration *(tooltip: You can edit the policy configuration over REST at the config/policy endpoint.)*. The following managed object configuration shows a sample conditional policy for the `password` property of user objects. The policy indicates that `sys-admin` users have a more lenient password policy than regular employees: ```json { "objects" : [ { "name" : "user", ... "properties" : { ... "password" : { "title" : "Password", "type" : "string", ... "conditionalPolicies" : [ { "condition" : { "type" : "text/javascript", "source" : "(fullObject.org === 'sys-admin')" }, "dependencies" : [ "org" ], "policies" : [ { "policyId" : "at-least-X-numbers", "params" : { "numNums" : ["1"] } } ] }, { "condition" : { "type" : "text/javascript", "source" : "(fullObject.org === 'employees')" }, "dependencies" : [ "org" ], "policies" : [ { "policyId" : "at-least-X-numbers", "params" : { "numNums" : ["2"] } } ] } ], "fallbackPolicies" : [ { "policyId" : "at-least-X-numbers", "params" : { "numNums" : ["1"] } } ] } ... } ``` There are two distinct scripted conditions that are defined in the `condition` elements. The first condition asserts that the user object, contained in the `fullObject` argument, is a member of the `sys-admin` org. If that assertion is true, the `at-least-X-numbers` policy is applied to the `password` attribute of the user object, and minimum numbers is set to `1`. The second condition asserts that the user object is a member of the `employees` org. If that assertion is true, the `at-least-X-numbers` policy is applied to the `password` attribute of the user object, and the minimum numbers is `2`. In the event that neither condition is met: the user object is not a member of the `sys-admin` org or the `employees` org, an optional fallback policy can be applied. In this example, the fallback policy also references the `at-least-X-numbers` policy and specifies that for such users, the minimum numbers is `1`. The `dependencies` field prevents the condition scripts from being run at all, if the user object doesn't include an `org` attribute. | | | | - | ---------------------------------------------------------- | | | Scripted conditions do not apply to progressive profiling. |