Default Policy for Managed Objects

Policies applied to managed objects are configured in two files:

  • A policy script file (openidm/bin/defaults/script/policy.js) that defines each policy and specifies how policy validation is performed. For more information, see "Policy Script File".

  • A managed object policy configuration element, defined in your project's conf/managed.json file, that specifies which policies are applicable to each managed resource. For more information, see "Policy Configuration Element".

    Note

    The configuration for determining which policies apply to resources other than managed objects is defined in your project's conf/policy.json file. The default policy.json file includes policies that are applied to internal user objects, but you can extend the configuration in this file to apply policies to system objects.

Policy Script File

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

  • 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 (see "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. For more information, see "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 it 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 IdParameters 

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

numCapsMinimum number of capital letters.

at-least-X-numbers

The property must contain the minimum specified number of numbers.

numNumsMinimum number of numbers.

validNumber

Tests for a valid number.

  

minimumNumber

The property value must be greater than the minimum.

minimumThe minimum value.

maximumNumber

The property value must be less than the maximum.

maximumThe maximum value.

minimum-length

The property's minimum string length.

minLengthThe minimum string length.

maximum-length

The property's maximum string length.

maxLengthThe maximum string length.

cannot-contain-others

The property cannot contain values of the specified fields.

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

forbiddenCharsA 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

The configuration of a managed object property (in the 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.json file shows how policy validation is applied to the password and _id properties of a managed/user object:

{
    "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, integer, number, null, object, or string. For more information about data types, see 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 does not match the specified type, such as when the data is an array instead of a string. The valid-type policy in the default policy.js file enforces the match between property values and the type defined in the 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.json file:

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

  1. From 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. 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 "Default Policy Reference".

    Parameter Name

    Refers to the parameters for the PolicyId. For a list of the default policy parameters, see "Default Policy Reference".

    Value

    The parameter's value to validate.

Important

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 ${managedConfig}. Any managed object that has items of "type" : "relationship", must also have "returnByDefault" : false.

Read a different version of :