Work with sign-on policies


Sign-On policies

Sign-on policies determine the account authentication flow users must complete to access applications secured by PingOne services. PingOne provides the following pre-configured sign-on policy configurations:

  • Single_Factor

    The configured single-factor sign-on policy is a basic authentication method that prompts users to enter a username and password to authenticate the account.

  • Multi_Factor

    The configured multi-factor sign-on policy is a two-step authentication method that prompts users to take the following actions:

    • Enter a username and password.
    • Enter a one-time password on a registered device.

Sign-on policies are defined by their associated actions. For example, the Single-Factor sign-on policy resource includes a defined LOGIN action that prompts users for a username and password. The actions associated with a sign-on policy resource can be modified using a PUT request.

Sign-on policy actions include a conditions attribute that determines when the action is executed. At least one condition must be met to execute the action. If no conditions are set, the action is always executed. For example, the single-factor sign-on policy action can be managed by the session attribute and its minutesSinceLastSignOn child attribute. If the value of the minutesSinceLastSignOn attribute value is set to 60 minutes, the login action is executed when the number of minutes since the last sign-on time exceeds the specified value.

These attributes can be set as a condition for the following sign-on policy action:

  • Single_Factor: minutesSinceLastSignOn
  • Multi_Factor: minutesSinceLastSignOn, ipAddress, user

The minutesSinceLastSignOn attribute includes the withAuthenticator child attribute to restrict the last sign-on time to a specific authenticator. The supported authenticator values are: pwd, sms, and email. If an authenticator is not specified, the last sign-on time is based on the last time a sign-on action was completed, even if no authentication was performed because of an existing session. When more than one authenticator value is specified, the last sign-on time is applied to any one of the values. The ipAddress attribute includes the notInRange child attribute, which evaluates to true if the request IP address of the application is outside one the networks specified by classless inter-domain routing (CIDR) strings. The user attribute includes the inPopulation child attribute, which evaluates to true if there is a user associated with the flow and the user is in one of the specified populations.

The examples that follow show common actions to create and manage sign-on policies resources. You need the Environment Admin role to perform operations on sign-on policy resources. For more information, see Manage user roles.

Get sign-on policies

The GET /environments/{environmentId}/signOnPolicies endpoint returns a list of all sign-on policy resources for the specified environment.

The following sample returns the complete list of sign-on policy resources associated with the environment ID specified in the request URL:

curl -X "GET" "https://api.pingone.com/v1/environments/{environmentId}/signOnPolicies" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken'

The response data looks like this:

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/signOnPolicies"
        }
    },
    "_embedded": {
        "signOnPolicies": [
            {
                "_links": {
                    "self": {
                        "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/signOnPolicies/1c006010-a765-448b-84bf-32199c4af3c3"
                    },
                    "environment": {
                        "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba"
                    },
                    "actions": {
                        "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/signOnPolicies/1c006010-a765-448b-84bf-32199c4af3c3/actions"
                    }
                },
                "id": "1c006010-a765-448b-84bf-32199c4af3c3",
                "environment": {
                    "id": "0bda42bc-d54f-449f-8d46-d5b8990c43ba"
                },
                "name": "Multi_Factor",
                "description": "A sign-on policy that requires primary username and password along with an out-of-band OTP"
            },
            {
                "_links": {
                    "self": {
                        "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/signOnPolicies/7bf52bba-ef9a-47ac-9163-4310f3208409"
                    },
                    "environment": {
                        "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba"
                    },
                    "actions": {
                        "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/signOnPolicies/7bf52bba-ef9a-47ac-9163-4310f3208409/actions"
                    }
                },
                "id": "7bf52bba-ef9a-47ac-9163-4310f3208409",
                "environment": {
                    "id": "0bda42bc-d54f-449f-8d46-d5b8990c43ba"
                },
                "name": "Single_Factor",
                "description": "A sign-on policy that requires username and password"
            }
        ]
    },
    "count": 2,
    "size": 2
}

To get data for a specific sign-on policy, the GET /environments/{environmentId}/signOnPolicies/{policyId} operation returns data for the sign-on policy resource with the specified ID.

curl -X GET "https://api.pingone.com/v1/environments/{environmentId}/signOnPolicies/{policyId}" \
-H "Content-type: application/json" \
-H "Authorization: Bearer jwtToken"

The response data looks like this:

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/signOnPolicies/7bf52bba-ef9a-47ac-9163-4310f3208409"
        },
        "environment": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba"
        },
        "actions": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/signOnPolicies/7bf52bba-ef9a-47ac-9163-4310f3208409/actions"
        }
    },
    "id": "7bf52bba-ef9a-47ac-9163-4310f3208409",
    "environment": {
        "id": "0bda42bc-d54f-449f-8d46-d5b8990c43ba"
    },
    "name": "Single_Factor",
    "description": "A sign-on policy that requires username and password"
}

Get sign-on policy actions

To get data about the actions associated with a specific sign-on policy, the GET /environments/{environmentId}/signOnPolicies/{policyId}/actions operation returns information about all actions associated with the specified sign-on policy resource.

curl -X GET "https://api.pingone.com/v1/environments/{environmentId}/signOnPolicies/{policyId}/actions" \
-H "Content-type: application/json" \
-H "Authorization: Bearer jwtToken"

The response data looks like this:

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/signOnPolicies/7bf52bba-ef9a-47ac-9163-4310f3208409/actions"
        }
    },
    "_embedded": {
        "actions": [
            {
                "_links": {
                    "self": {
                        "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/signOnPolicies/7bf52bba-ef9a-47ac-9163-4310f3208409/actions/0846615d-19f1-478c-8cff-f18b309ce664"
                    },
                    "environment": {
                        "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba"
                    },
                    "signOnPolicy": {
                        "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/signOnPolicies/7bf52bba-ef9a-47ac-9163-4310f3208409"
                    }
                },
                "id": "0846615d-19f1-478c-8cff-f18b309ce664",
                "environment": {
                    "id": "0bda42bc-d54f-449f-8d46-d5b8990c43ba"
                },
                "signOnPolicy": {
                    "id": "7bf52bba-ef9a-47ac-9163-4310f3208409"
                },
                "priority": 1,
                "type": "LOGIN",
                "conditions": {
                    "session": {}
                }
            }
        ]
    },
    "count": 1,
    "size": 1
}

Update sign-on policy actions

The PUT /environments/{environmentId}/signOnPolicies/{policyId}/actions/{actionId} operation updates the minutesSinceLastSignOn model property for the specified action. The sign-on policy resource and the environment resource IDs are specified in the request URL.

curl -X "PUT" "https://api.pingone.com/v1/environments/{environmentId}/signOnPolicies/{policyId}/actions/0846615d-19f1-478c-8cff-f18b309ce664" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d $'{
  "type": "LOGIN",
  "conditions": {
                    "session": {
                        "minutesSinceLastSignOn": 100
                    }
                }
}'

In addition to specifying a new value for the minutesSinceLastSignOn property, the request body requires a value for the type property. The value for the type property does not need to change, but it must be specified to execute the request. The response data looks like this:

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/signOnPolicies/7bf52bba-ef9a-47ac-9163-4310f3208409/actions/0846615d-19f1-478c-8cff-f18b309ce664"
        },
        "environment": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba"
        },
        "signOnPolicy": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/signOnPolicies/7bf52bba-ef9a-47ac-9163-4310f3208409"
        }
    },
    "id": "0846615d-19f1-478c-8cff-f18b309ce664",
    "environment": {
        "id": "0bda42bc-d54f-449f-8d46-d5b8990c43ba"
    },
    "signOnPolicy": {
        "id": "7bf52bba-ef9a-47ac-9163-4310f3208409"
    },
    "priority": 1,
    "type": "LOGIN",
    "conditions": {
        "session": {
            "minutesSinceLastSignOn": 100
        }
    }
}

Create sign-on policies

The POST /environments/{environmentId}/signOnPolicies operation creates a new sign-on policy resource. In the request body, the name property is required, and the sign-on policy name must be unique within the environment. All other properties are optional.

curl -X "POST" "https://api.pingone.com/v1/environments/{environmentId}/signOnPolicies" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d $'{
  "name": "Simple_Login",
  "default": "false",
  "description": "A new basic sign-on policy."
}'

The response data looks like this:

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/signOnPolicies/7bf52bba-ef9a-47ac-9163-4310f3208409"
        },
        "environment": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba"
        },
        "actions": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/signOnPolicies/7bf52bba-ef9a-47ac-9163-4310f3208409/actions"
        }
    },
    "id": "7bf52bba-ef9a-47ac-9163-4310f3208409",
    "environment": {
        "id": "0bda42bc-d54f-449f-8d46-d5b8990c43ba"
    },
    "default": "false",
    "description": "A new basic sign-on policy.",
    "name": "Simple_Login"
}

Update a sign-on policy

The PUT /environments/{environmentId}/signOnPolicies/{policyId} operation updates the sign-on policy resource specified by its ID in the request URL.

curl -X "PUT" "https://api.pingone.com/v1/environments/{environmentId}/signOnPolicies/{policyId}" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d $'{
  "default": "true",
  "description": "A more complex sign-on policy.",
  "name": "Complex_Login"
}'

The response data looks like this:

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/signOnPolicies/7bf52bba-ef9a-47ac-9163-4310f3208409"
        },
        "environment": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba"
        },
        "actions": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/signOnPolicies/7bf52bba-ef9a-47ac-9163-4310f3208409/actions"
        }
    },
    "id": "7bf52bba-ef9a-47ac-9163-4310f3208409",
    "environment": {
        "id": "0bda42bc-d54f-449f-8d46-d5b8990c43ba"
    },
    "default": "true",
    "description": "A new basic sign-on policy.",
    "name": "Complex_Login"
}

Create sign-on policy actions

The POST /environments/{environmentId}/signOnPolicies/{policyId}/actions operation creates a new sign-on policy action resource. The priority property specifies the order in which this action (and its conditions) is evaluated when evaluating the policy. Property values range from 1 to {maxInt}. The action with a priority value of 1 is evaluated first.

curl -X "POST" "https://api.pingone.com/v1/environments/{environmentId}/signOnPolicies{policyId}/actions" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d $'{
    "environment": {
        "id": "{environmentID}"
    },
    "signOnPolicy": {
        "id": "{policyID}"
    },
    "priority": 1,
    "type": "LOGIN"
}'

Update a sign-on policy action

The PUT /environments/{environmentId}/signOnPolicies/{policyId}/actions/{actionId} operation updates the sign-on policy action resource specified by its ID in the request URL.

curl -X "PUT" "https://api.pingone.com/v1/environments/{environmentId}/signOnPolicies/{policyId}/actions/{actionId}" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d $'{
    "priority": 2,
    "conditions": {
        "session": {
            "minutesSinceLastSignOn": 480,
            "withAuthenticator": [
                "pwd"
            ]
        }
}'

The conditions property for the action specifies the conditions associated with the action. At least one condition must be met to execute the action. If no conditions exist, the action is always executed.

Get sign-on policy assignments

The GET /environments/{environmentId}/applications/{applicationId}/signOnPolicyAssignments endpoint returns a list of all sign-on policy resources assigned to an application.

The following sample returns the list of sign-on policy resources associated with the application ID specified in the request URL:

curl -X "GET" "https://api.pingone.com/v1/environments/{environmentId}/applications/{applicationId}/signOnPolicyAssignments" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken'

The response data looks like this:

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/e4d7bcd3-7a00-4c4d-9ce0-88f4b1954474/applications/d64f66de-1502-4398-96a1-02f0d2a86f9c/signOnPolicyAssignments
        }
    },
    "_embedded": {
        "signOnPolicyAssignments": [
        {
              "_links": {
                  "self": {
                     "href": "https://api-staging.pingone.com/v1/environments/e4d7bcd3-7a00-4c4d-9ce0-88f4b1954474/applications/d64f66de-1502-4398-96a1-02f0d2a86f9c/signOnPolicyAssignments/ede42c6c-a97a-4c2c-aaeb-9cb38f13bb13"
              },
              "environment": {
                 "href": "https://api-staging.pingone.com/v1/environments/e4d7bcd3-7a00-4c4d-9ce0-88f4b1954474"
              },
              "application": {
                 "href": "https://api-staging.pingone.com/v1/environments/e4d7bcd3-7a00-4c4d-9ce0-88f4b1954474/applications/d64f66de-1502-4398-96a1-02f0d2a86f9c"
              },
              "signOnPolicy": {
                 "href": "https://api-staging.pingone.com/v1/environments/e4d7bcd3-7a00-4c4d-9ce0-88f4b1954474/signOnPolicies/54f11a8b-0e09-4f76-8cdc-2efa2c9c499e"
              }
          },
        "id": "ede42c6c-a97a-4c2c-aaeb-9cb38f13bb13",
        "environment": {
            "id": "e4d7bcd3-7a00-4c4d-9ce0-88f4b1954474"
         },
        "application": {
            "id": "d64f66de-1502-4398-96a1-02f0d2a86f9c"
        },
        "signOnPolicy": {
            "id": "54f11a8b-0e09-4f76-8cdc-2efa2c9c499e"
        },
        "priority": 1
       }
     }
   ]
},
"count": 1,
"size": 1
}

To get data for a specific sign-on policy assignment, the GET /environments/{environmentId}/applications/{applicationId}/signOnPolicyAssignments/{id} operation returns data for the sign-on policy assignment resource with the specified ID.

curl -X GET "https://api.pingone.com/v1/environments/{environmentId}/applications/{applicationId}/signOnPolicyAssignments/{id}" \
-H "Content-type: application/json" \
-H "Authorization: Bearer jwtToken"

Create sign-on policy assignments

The /environments/{environmentId}/applications/{applicationId}/signOnPolicyAssignments operation creates a new sign-on policy assignment resource. The id for the signOnPolicy property and the priority property are required in the request body.

curl -X "POST" "https://api.pingone.com/v1/environments/{environmentId}/applications/{applicationId}/signOnPolicyAssignments" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d $'{
    "signOnPolicy": {
      "id": "54f11a8b-0e09-4f76-8cdc-2efa2c9c499e"
    },
    "priority": 1
}'

The response data looks like this:

{
    "_links": {
        "self": {
            "href": "https://api-staging.pingone.com/v1/environments/e4d7bcd3-7a00-4c4d-9ce0-88f4b1954474/applications/d64f66de-1502-4398-96a1-02f0d2a86f9c/signOnPolicyAssignments/ede42c6c-a97a-4c2c-aaeb-9cb38f13bb13"
        },
        "environment": {
            "href": "https://api-staging.pingone.com/v1/environments/e4d7bcd3-7a00-4c4d-9ce0-88f4b1954474"
        },
        "application": {
            "href": "https://api-staging.pingone.com/v1/environments/e4d7bcd3-7a00-4c4d-9ce0-88f4b1954474/applications/d64f66de-1502-4398-96a1-02f0d2a86f9c"
        },
        "signOnPolicy": {
            "href": "https://api-staging.pingone.com/v1/environments/e4d7bcd3-7a00-4c4d-9ce0-88f4b1954474/signOnPolicies/54f11a8b-0e09-4f76-8cdc-2efa2c9c499e"
        }
    },
    "id": "ede42c6c-a97a-4c2c-aaeb-9cb38f13bb13",
    "environment": {
        "id": "e4d7bcd3-7a00-4c4d-9ce0-88f4b1954474"
    },
    "application": {
        "id": "d64f66de-1502-4398-96a1-02f0d2a86f9c"
    },
    "signOnPolicy": {
        "id": "54f11a8b-0e09-4f76-8cdc-2efa2c9c499e"
    },
    "priority": 1
}