Apply policies to managed objects

In Identity Cloud, policies can be applied to managed objects using default policies.

You can add a policy using:

The IDM admin UI.
The policy configuration.

Be cautious when using validation policies. If a policy relates to an array of relationships Return by Default should always be set to false. You can verify this in your managed object configuration. Any managed object that has items of "type" : "relationship", must also have "returnByDefault" : false.

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 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, refer to 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 reference

You can apply policies defined by Identity Cloud to any managed or internal object.

Identity Cloud includes the following default policies and parameters:

Policy Id Parameters

Policy Id	Parameters
`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-query-filter` Tests for a valid query filter.
`valid-array-items` Tests for valid array items.
`valid-date` Tests for a valid date.
`valid-formatted-date` Tests for a valid date format.
`valid-time` Tests for a valid time.
`valid-datetime` Tests for a valid date and time.
`valid-duration` Tests for a valid duration format.
`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.	`numCaps`	Minimum number of capital letters.
`at-least-X-numbers` The property must contain the minimum specified number of numbers.	`numNums`	Minimum number of numbers.
`validNumber` Tests for a valid number.
`minimumNumber` The property value must be greater than the `minimum`.	`minimum`	The minimum value.
`maximumNumber` The property value must be less than the `maximum`.	`maximum`	The maximum value.
`minimum-length` The property’s minimum string length.	`minLength`	The minimum string length.
`maximum-length` The property’s maximum string length.	`maxLength`	The maximum string length.
`cannot-contain-others` The property cannot contain values of the specified fields.	`disallowedFields`	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` The property cannot contain the specified characters.	`forbiddenChars`	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` 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.

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-query-filter

Tests for a valid query filter.

valid-array-items

Tests for valid array items.

valid-date

Tests for a valid date.

valid-formatted-date

Tests for a valid date format.

valid-time

Tests for a valid time.

valid-datetime

Tests for a valid date and time.

valid-duration

Tests for a valid duration format.

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.

numCaps

Minimum number of capital letters.

at-least-X-numbers

The property must contain the minimum specified number of numbers.

numNums

Minimum number of numbers.

validNumber

Tests for a valid number.

minimumNumber

The property value must be greater than the minimum.

minimum

The minimum value.

maximumNumber

The property value must be less than the maximum.

maximum

The maximum value.

minimum-length

The property’s minimum string length.

minLength

The minimum string length.

maximum-length

The property’s maximum string length.

maxLength

The maximum string length.

cannot-contain-others

The property cannot contain values of the specified fields.

disallowedFields

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

The property cannot contain the specified characters.

forbiddenChars

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

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

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 id property of a managed/realm-name_user object.

You can only declare policies on top-level managed object attributes. Nested attributes (those within an array or object) cannot have policies 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
            }
        }
    }
}

The policy for the _id property references the function cannot-contain-characters. This is a default policy that you can apply.

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. For more information about data types, refer to 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 default valid-type policy enforces the match between property values and the type defined in the managed object configuration.

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 could 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 type is defined in the policy configuration. The policy 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 UI, update the configuration of the object type:

From the Identity Cloud admin UI, click Native Consoles > Identity Management.
From the navigation bar, click Configure > Managed Objects.
On the Managed Objects page, edit or create a managed object.
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.
  - Click the property.
From the Validation tab, click Add Policy.
In the Add/Edit Policy window, enter information in the following fields, and click Add or Save:

Policy Id

Refers to the unique PolicyId.

For a list of the default policies, refer to the Policy Reference.

Parameter Name

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

Value

The parameter’s value to validate.

Show Me

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 managed objects, add the policy to your project’s managed object configuration. To apply a conditional policy to other objects, add it to your project’s policy configuration.

The following managed object configuration shows a sample conditional policy for the password property of managed user objects. The policy indicates that sys-admin users have a more lenient password policy than regular employees:

{
    "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 (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 does not include an org attribute.

Scripted conditions do not apply to progressive profiling.