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

Note: At this time, the PingOne API does not support a POST request to the signOnPolicies service to create new sign-on policy resources.

The examples that follow show common actions to find 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/0bda42bc-d54f-449f-8d46-d5b8990c43ba/signOnPolicies" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken'

The response data looks like this:

{
    "_links": {
        "self": {
            "href": "https://api-staging.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/signOnPolicies"
        }
    },
    "_embedded": {
        "signOnPolicies": [
            {
                "_links": {
                    "self": {
                        "href": "https://api-staging.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/signOnPolicies/1c006010-a765-448b-84bf-32199c4af3c3"
                    },
                    "environment": {
                        "href": "https://api-staging.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba"
                    },
                    "actions": {
                        "href": "https://api-staging.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-staging.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/signOnPolicies/7bf52bba-ef9a-47ac-9163-4310f3208409"
                    },
                    "environment": {
                        "href": "https://api-staging.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. Here is a sample:

curl -X GET "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/signOnPolicies/1c006010-a765-448b-84bf-32199c4af3c3" \
-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/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"
}

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. Here is a sample:

curl -X GET "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/signOnPolicies/1c006010-a765-448b-84bf-32199c4af3c3/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/1c006010-a765-448b-84bf-32199c4af3c3/actions"
        }
    },
    "_embedded": {
        "actions": [
            {
                "_links": {
                    "self": {
                        "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/signOnPolicies/1c006010-a765-448b-84bf-32199c4af3c3/actions/8dbbc945-7304-44eb-89c4-18871cca9406"
                    },
                    "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/1c006010-a765-448b-84bf-32199c4af3c3"
                    }
                },
                "id": "8dbbc945-7304-44eb-89c4-18871cca9406",
                "environment": {
                    "id": "0bda42bc-d54f-449f-8d46-d5b8990c43ba"
                },
                "signOnPolicy": {
                    "id": "1c006010-a765-448b-84bf-32199c4af3c3"
                },
                "priority": 1,
                "type": "LOGIN",
                "conditions": {
                    "ipAddress": null,
                    "session": {
                        "idleLongerThanMinutes": 480
                    }
                }
            },
            {
                "_links": {
                    "self": {
                        "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/signOnPolicies/1c006010-a765-448b-84bf-32199c4af3c3/actions/340ad9b1-1917-4124-9868-5fe88516c27e"
                    },
                    "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/1c006010-a765-448b-84bf-32199c4af3c3"
                    }
                },
                "id": "340ad9b1-1917-4124-9868-5fe88516c27e",
                "environment": {
                    "id": "0bda42bc-d54f-449f-8d46-d5b8990c43ba"
                },
                "signOnPolicy": {
                    "id": "1c006010-a765-448b-84bf-32199c4af3c3"
                },
                "priority": 2,
                "type": "MULTI_FACTOR_AUTHENTICATION",
                "conditions": {
                    "ipAddress": null,
                    "session": {
                        "idleLongerThanMinutes": 60
                    }
                },
                "sms": {
                    "enabled": true
                },
                "email": {
                    "enabled": true
                }
            }
        ]
    },
    "count": 2,
    "size": 2
}

Update sign-on policy actions

The PUT /environments/{environmentId}/signOnPolicies/{policyId}/actions/{actionId} operation updates idleLongerThanMinutes model property for the specified action. The sign-on policy resource and the Environment resource IDs are specified in the request URL. Here is a sample:

curl -X "PUT" "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/signOnPolicies/1c006010-a765-448b-84bf-32199c4af3c3/actions/8dbbc945-7304-44eb-89c4-18871cca9406" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d $'{
  "id": "8dbbc945-7304-44eb-89c4-18871cca9406",
  "type": "LOGIN",
  "conditions": {
                    "session": {
                        "idleLongerThanMinutes": 100
                    }
                }
}'

In addition to specifying a new value for the idleLongerThanMinutes property, the request body requires values for the id and type properties. The values for the id and type properties do not need to change, but they 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/1c006010-a765-448b-84bf-32199c4af3c3/actions/8dbbc945-7304-44eb-89c4-18871cca9406"
     },
     "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/1c006010-a765-448b-84bf-32199c4af3c3"
     }
   },
   "id" : "8dbbc945-7304-44eb-89c4-18871cca9406",
   "environment" : {
     "id" : "0bda42bc-d54f-449f-8d46-d5b8990c43ba"
   },
   "signOnPolicy" : {
     "id" : "1c006010-a765-448b-84bf-32199c4af3c3"
   },
   "type" : "LOGIN",
   "conditions" : {
     "ipAddress" : null,
     "session" : {
       "idleLongerThanMinutes" : 100
     }
   }
 }