Chapter 7. Using Policies to Validate Data

The policy script file defines policy configuration in two parts:

Together, the configuration object and the implementation function determine whether an object is valid in terms of the policy. The following extract from the 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",
                "clientValidation": true,
                "policyExec" : "atLeastXCapitalLetters", 
                "policyRequirements" : ["AT_LEAST_X_CAPITAL_LETTERS"]
            },
...

function atLeastXCapitalLetters(fullObject, value, params, property) {
    var reg = /[(A-Z)]/g;
    if (typeof value !== "string" || !value.length || value.match(reg) 
        === null || value.match(reg).length < params.numCaps) {
        return [ { 
                   "policyRequirement" : "AT_LEAST_X_CAPITAL_LETTERS", 
                   "params" : {
                     "numCaps": params.numCaps
                   } 
                  } 
               ];
    }
    return [];
}     
...     
      

To enforce user passwords that contain at least one capital letter, the previous policy ID is applied to the appropriate resource and the required number of capital letters is defined in the policy configuration file, as described in Section 7.1.2, “Policy Configuration File”.

{   "policyId" : "minimum-length",
    "clientValidation": true,
    "policyExec" : "propertyMinLength",
    "policyRequirements" : ["MIN_LENGTH"]
}
      

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

function required(fullObject, value, params, propName) {
    if (value === undefined) {
        return [ { "policyRequirement" : "REQUIRED" } ];
    }
    return [];
}          
        

The policy configuration file includes a pointer to the policy script, and the configured policies for each component resource. The following extract of the default policy configuration file shows how the at-least-X-capitals policy is applied to user passwords, with a default value of 1.

{
    "type" : "text/javascript",
    "file" : "bin/defaults/script/policy.js",
    "resources" : [
        {
            "resource" : "managed/user/*",
            "properties" : [
...
                {
                    "name" : "password",
                    "policies" : [
                        {
                            "policyId" : "required"
                        },
                        {
                            "policyId" : "not-empty"
                        },
                        {
                            "policyId" : "at-least-X-capitals",
                            "params" : {
                                "numCaps" : 1
                            }
                        },
                ...
           }
       ]
}     
      

The configuration file includes the following properties:

You can specify that a particular policy does not apply to users with specific OpenIDM roles by setting the "exceptRoles" parameter of the policy ID. For example, the following extract from policy.json specifies that the reauthorization required policy definition does not apply to users with roles openidm-admin, or opendim-reg.

...      
    {
        "policyId" : "re-auth-required",
        "params" : {
            "exceptRoles" : [
                "openidm-admin",
                "openidm-reg"
            ]
        }
    }      
...      
      

The following REST call displays a list of all the defined policies:

$ curl
 --header "X-OpenIDM-Username: openidm-admin"
 --header "X-OpenIDM-Password: openidm-admin"
 --request GET
 "http://localhost:8080/openidm/policy"

The policy objects are returned in JSON format, with one object for each defined policy ID, for example:

{
  "resources": [
    {
      "resource": "managed/user/*",
      "properties": [
      {
        "policies": [
          {
            "policyId": "required",
            "policyFunction": "function required(fullObject, value, params, propName) {
              if (value === undefined) {
              return [{"policyRequirement":"REQUIRED"}];
                      }
              return [];
            }",
            "policyRequirements": [
              "REQUIRED"
            ]
          },
...

To display the policies that apply to a specific component, include the component name in the URL. For example, the following REST call displays the policies that apply to managed users.

$ curl
 --header "X-OpenIDM-Username: openidm-admin"
 --header "X-OpenIDM-Password: openidm-admin"
 --request GET
 "http://localhost:8080/openidm/policy/managed/user/*"

{
    "resource": "managed/user/*",
    "properties": [
        {
            "policies": [
                {
                    "policyId": "required",
                    "policyFunction": "
                        \nfunction required(fullObject, value, params, propName) {
                            \n    if (value === undefined) {
                            \n        return [{\"policyRequirement\":\"REQUIRED\"}];
                            \n    }
                            \n    return [];
                            \n}
                            \n",
                    "policyRequirements": [
                        "REQUIRED"
                    ]
                },
                {
                    "policyId": "not-empty",
                    "policyFunction": "
                    \nfunction notEmpty(fullObject, value, params, property) {
                    \n    if (typeof (value) !== \"string\" || !value.length) {
                    \n        return [{\"policyRequirement\":\"REQUIRED\"}];
                    \n    } else {
                    \n        return [];
                    \n    }
                    \n}
                    \n",
                    "policyRequirements": [
                        "REQUIRED"
                    ]
                },
                {
                    "policyId": "unique",
                    "policyRequirements": [
                        "UNIQUE"
                    ]
                },
...
}

Use the validateObject action to verify that an object adheres to the requirements of a policy.

The following example verifies that a new managed user object is acceptable in terms of the policy requirements.

$ curl
 --header "X-OpenIDM-Username: openidm-admin"
 --header "X-OpenIDM-Password: openidm-admin"
 --request POST      
 --data '{"familyName":"Jones",
          "givenName":"Bob",
          "_id":"bjones",
          "phoneNumber":"0827878921",
          "passPhrase":null,
          "email":"bjones@example.com",
          "accountStatus":"active",
          "roles":"admin",
          "userName":"bjones@example.com",
          "password":"123"}' 
 "http://localhost:8080/openidm/policy/managed/user/bjones?_action=validateObject"

{"result":false,
 "failedPolicyRequirements":[
    {"policyRequirements":[
         {"policyRequirement":"AT_LEAST_X_CAPITAL_LETTERS",
             "params":{"numCaps":1}
         },
         {"policyRequirement":"MIN_LENGTH",
             "params":{"minLength":8}
         }
         ],
      "property":"password"
    }
  ]
}

The result (false) indicates that the object is not valid. The unfulfilled policy requirements are provided as part of the response - in this case, the user password does not meet the validation requirements.

Use the validateProperty action to verify that a specific property adheres to the requirements of a policy.

The following example checks whether Barbara Jensen's new password (12345) is acceptable.

$ curl
 --header "X-OpenIDM-Username: openidm-admin"
 --header "X-OpenIDM-Password: openidm-admin"
 --request POST
 --data '{ "password" : "12345" }' 
 "http://localhost:8080/openidm/policy/managed/user/bjensen?_action=validateProperty"
 
{
    "result": false,
    "failedPolicyRequirements": [
        {
            "policyRequirements": [
                {
                    "policyRequirement": "AT_LEAST_X_CAPITAL_LETTERS",
                    "params": {
                        "numCaps": 1
                    }
                },
                {
                    "policyRequirement": "MIN_LENGTH",
                    "params": {
                        "minLength": 8
                    }
                }
            ],
            "property": "password"
        }
    ]
}
      

The result (false) indicates that the password is not valid. The unfulfilled policy requirements are provided as part of the response - in this case, the minimum length and the minimum number of capital letters.

Validating a property that does fulfil the policy requirements returns a true result, for example:

$ curl
 --header "X-OpenIDM-Username: openidm-admin"
 --header "X-OpenIDM-Password: openidm-admin"
 --request POST
 --data '{ "password" : "1NewPassword" }' 
 "http://localhost:8080/openidm/policy/managed/user/bjensen?_action=validateProperty"
 
{
    "result": true,
    "failedPolicyRequirements": []
}