Sign-on policy actions


Sign-on policy actions

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.

Sign-on policy actions API operations

The sign-on policy actions endpoints support the following operations:

For hands-on experience with the sign-on policies API endpoints, click the Run in Postman button below to download a Postman collection that you can import and open in your local Postman application.

Sign-on policy actions data model

Property Description
conditions.ipAddress.notInRange A string that specifies the supported network IP addresses expressed as classless inter-domain routing (CIDR) strings.
conditions.session.minutesSinceLastSignOn An integer that specifies the maximum number of minutes to wait since the last sign on before prompting for a new sign-on action.
conditions.session.withAuthenticator A string that specifies the type of sign-on action to restrict the last sign-on time attribute to the identified authenticator. Options are pwd, sms, and email.
environment.id A string that specifies the environment resource’s unique identifier associated with the sign-on policy.
id A string that specifies the sign-on policy assignment resource’s unique identifier.
priority An integer that specifies the order in which the policy referenced by this assignment is evaluated during an authentication flow relative to other policies. An assignment with a lower priority will be evaluated first. This is a required property.
signOnPolicy.id A string that specifies the sign-on policy resource’s unique identifier associate with this sign-on policy assignment.
type A string that specifies the type of action (for example, LOGIN).

Response codes

Code Message
200 Successful operation.
201 Successfully created.
204 Successfully removed. No content.
400 The request could not be completed.
404 The requested resource was not found.
409 A resource with the specified name already exists.

Endpoint examples

Get sign-on policy actions

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 "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
}

Get one sign-on policy action

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

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

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 sign-on policy actions

The PUT /environments/{environmentId}/signOnPolicies/{policyId}/actions/{actionId}/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.

Delete sign-on policy actions

The following sample shows the DELETE /environments/{environmentId}/signOnPolicies/{policyId}/actions/{actionId} operation to delete the sign-on policy action.

curl -X DELETE "https://api.pingone.com/v1/environments/{environmentId}/signOnPolicies/{policyId}/actions/{actionId}" \
-H "Authorization: Bearer jwtToken"

When successful, the DELETE request returns a code 204 No Content message.