PingIDM

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.

  • A managed object policy element, defined in your managed object configuration, that specifies which policies are applicable to each managed resource. Learn more in the Policy Configuration Element.

    The policy configuration 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.

  • 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:

...
{   "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 configuration objects

Each element of the policy is defined in a policy configuration object. The structure of a policy configuration object is as follows:

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

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:

function <name>(fullObject, value, params, propName) {
	<implementation_logic>
}

  • 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:

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

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

valid-formatted-date

The property must have a valid date format. Learn more in RFC 3339-5.6.

valid-time

The property must have a valid time. Learn more in RFC 3339-5.6.

valid-datetime

The property must have a valid date and time. Learn more in RFC 3339-5.6.

valid-duration

The property must have a valid duration format. Learn more in RFC 3339-appendix-A.

valid-email-address-format

The property must have a valid email address. Learn more in RFC 5321-4.1.2.

valid-name-format

The property must have a valid name format. Learn more in RFC 5321-3.5.1.

valid-phone-format

The property must have a valid phone number format. Learn more in 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. 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. 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. 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 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. 
{
    "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 JSON Schema Primitive Types 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.

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:

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

Show Me
createPolicyUI

  1. In the navigation bar, click Configure > Managed Objects.

  2. On the Managed Objects page, edit or create a managed object.

  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.

    Parameter Name

    Refers to the parameters for the PolicyId. You can find a list of the default policy parameters in the 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. Any managed object that has items of "type" : "relationship", must also have "returnByDefault" : false.