PingOne Advanced Identity Cloud

Apply policies to managed objects

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

You can add a policy using:

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.

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

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

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

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:

"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 IDM admin console, update the configuration of the object type:

  1. In the Advanced Identity Cloud admin console, click Native Consoles > Identity Management.

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

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

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

  5. On the Validation tab, click Add Policy.

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

    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.

Show Me
createPolicyUI

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