Sign-on policy actions


Sign-on policy action types

Sign-on policy actions specify the particular sign-on action and the conditions that determine when the action is executed. PingOne supports the following sign-on policy actions:

  • LOGIN

    An action that prompts users for a username and password.

  • MULTI_FACTOR_AUTHENTICATION

    A two-step authentication method that prompts users to enter a username and password and then enter a one-time password received on a registered device or accept a push confirmation on a registered mobile device.

  • PASSWORDLESS

    PingOne also supports passwordless authentication. The authentication flow first identifies the user by the username property and determines the applicable authentication methods for this user.

Sign-on policy action conditions

PingOne sign-on policy actions support a policy condition language that allows both logical and data rules to construct a policy condition statement. Logical rules reflect the combined result of their contained rules. A logical rule can contain other logical rules or data rules. Data rules do not contain other rules; they are used for straightforward comparison.

Policy condition logical rules

There are three logical operations. The JSON operators for logical rule expressions are:

  • and

    Constructed as a JSON array (for example, "and":["{rule1}", "{rule2}"]). For this expression, all rules must be true to meet the condition.

  • or

    Constructed as a JSON array (for example, "or":["{rule1}", "{rule2}"]). For this expression, at least one rule must be true to meet the condition.

  • not

    Constructed as a JSON object (for example, "not":[{inner_rule}]). For this expression, the value must not be true to meet the condition.

The following sample shows a condition statement that uses the not logical operation:

"condition": {
   "not": {
        "ipRange": [
            "10.1.1.1/8",
            "10.0.0.0/8"
        ],
        "contains": "${flow.request.http.remoteIp}"
    }
}

In this case, the sign-on policy associated with this condition prevents sign-on from devices that contain the remote IP address value specified by the variable ${flow.request.http.remoteIp} in the specified IP address ranges.

The following sample shows a condition statement that uses the or logical operation to perform a data evaluation:

"condition": {
    "or": [
        {
            "value": "${user.population.id}",
            "equals": "ae2245b4-a942-47ad-9c9c-f6be13c2266b"
        },
        {
            "value": "${user.population.id}",
            "equals": "b0f1e4af-e0d1-4677-900c-fec8a354b332"
        }
    ]
}

The sign-on policy associated with this condition allows sign-on if the actor requesting access has a population ID value of ae2245b4-a942-47ad-9c9c-f6be13c2266b or b0f1e4af-e0d1-4677-900c-fec8a354b332 (or both).

Policy condition data rules

Data comparisons determine whether a given property value matches a second value or meets a specified threshold. A data comparison can be a one-to-one match using the equals operator:

{
    "value": "${user.population.id}",
    "equals": "b0f1e4af-e0d1-4677-900c-fec8a354b332"
}

A data comparison can also check whether a value has exceeded a specified maximum using the greater operator:

{
  "secondsSince" : "${session.lastSignOn.withAuthenticator.mfa.at}",
  "greater" : 50400
}

In this case, if the condition is met (the time since the last sign-on exceeds one hour), then the user can be directed to a specific authentication action, such as re-entering a password.

Condition variables

The following variables can be referenced in sign-on policy action conditions:

Property Description
${session.lastSignOn.at} Specifies the last time the user signed on using one or more authenticators.
${session.lastSignOn.withAuthenticator.pwd.at} Specifies the last successful time the password authenticator was used for sign on.
${session.lastSignOn.withAuthenticator.mfa.at} Specifies the last successful time an MFA authenticator was used for sign on. Options are: email, sms, and applications.id.
${flow.request.http.remoteIp} Specifies the remote IP address of the request that initiated the flow.
${user.*} Specifies the user attribute used in the condition. Only string core, standard, and custom attributes are supported. For complex attribute types, you must reference the sub-attribute (${user.name.firstName}).

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 associated with this sign-on policy assignment.
type A string that specifies the type of action. Options are: LOGIN and MULTI_FACTOR_AUTHENTICATION.

LOGIN action data model

Property Description
recovery Specifies the account recovery options.
recovery.enabled A boolean that specifies the enabled/disabled state of the account recovery action. The default is disabled when creating a new policy. When enabled, it allows the use of the forgot password flow.
registration Specifies the account registration options.
registration.enabled A boolean that specifies the enabled/disabled state of the policy action. The default is disabled when creating a new policy. When enabled, it allows the use of the new user registration flow. This attribute should be set to true when implementing the social login sign-on policy option.
registration.population.id A string that specifies the population ID associated with the newly registered user.
socialProviders.id An array of strings that specifies the IDs of the identity providers that can be used for the social login sign-on flow.

MULTI_FACTOR_AUTHENTICATION action data model

Property Description
email Specifies MFA through email options.
email.enabled A boolean that specifies the enabled/disabled state of the MFA through email action. The default is enabled when creating a new policy. When enabled, it allows users to receive the one-time password and authenticate through email.
sms Specifies MFA through SMS text messaging options.
sms.enabled A boolean that specifies the enabled/disabled state of the MFA through SMS action. The default is enabled when creating a new policy. When enabled, it allows users to receive the one-time password and authenticate through SMS text message.
applications The applications collection specifies all the native mobile applications that are allowed in the sign-on policy action.
Each item in the applications collection is an object with these properties:
  • id: <application-id>
    If the applications collection is empty, a push notification is not allowed for the action.
  • autoEnrollment.enabled
    A boolean that specifies the enabled/disabled state of automatic MFA enrollment for the application.
    The default is disabled when creating a new policy.
    When enabled, it allows automatic enrollment of the mobile application to MFA during the authentication flow.

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.

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/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/signOnPolicies/c8c9b0df-8325-491a-aac6-a37b115dd2be/actions"
    }
  },
  "_embedded": {
    "actions": [
      {
        "_links": {
          "self": {
            "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/signOnPolicies/c8c9b0df-8325-491a-aac6-a37b115dd2be/actions/36ba5e95-362a-42ad-806e-bd6207618fd0"
          },
          "environment": {
            "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7"
          },
          "signOnPolicy": {
            "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/signOnPolicies/c8c9b0df-8325-491a-aac6-a37b115dd2be"
          }
        },
        "id": "36ba5e95-362a-42ad-806e-bd6207618fd0",
        "environment": {
          "id": "9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7"
        },
        "type": "MULTI_FACTOR_AUTHENTICATION",
        "condition": {
          "secondsSince": "${session.lastSignOn.withAuthenticator.mfa.at}",
          "greater": 3600
        },
        "signOnPolicy": {
          "id": "c8c9b0df-8325-491a-aac6-a37b115dd2be"
        },
        "priority": 2,
        "sms": {
          "enabled": true
        },
        "email": {
          "enabled": true
        }
      },
      {
        "_links": {
          "self": {
            "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/signOnPolicies/c8c9b0df-8325-491a-aac6-a37b115dd2be/actions/a85bd6d9-55a9-4fb7-a70d-1630022cf63a"
          },
          "environment": {
            "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7"
          },
          "signOnPolicy": {
            "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/signOnPolicies/c8c9b0df-8325-491a-aac6-a37b115dd2be"
          }
        },
        "id": "a85bd6d9-55a9-4fb7-a70d-1630022cf63a",
        "environment": {
          "id": "9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7"
        },
        "type": "LOGIN",
        "condition": {
          "not": {
            "ipRange": [
              "10.1.1.1/8",
              "10.0.0.0/8"
            ],
            "contains": "${flow.request.http.remoteIp}"
          }
        },
        "signOnPolicy": {
          "id": "c8c9b0df-8325-491a-aac6-a37b115dd2be"
        },
        "priority": 1,
        "registration": {
          "enabled": true,
          "population": null
        },
        "recovery": {
          "enabled": true
        }
      }
    ]
  },
  "count": 2,
  "size": 2
}

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"

The response data looks like this:

{
  "_links" : {
    "self" : {
      "href" : "https://api.pingone.com/v1/environments/0eabfd1a-4655-4409-98d4-3d01092bc87d/signOnPolicies/708784f6-d51f-4ae3-b4b7-3f00354eb88b/actions/1ff6ead6-ff1f-45ea-9e67-b0e0b9206883"
    },
    "environment" : {
      "href" : "https://api.pingone.com/v1/environments/0eabfd1a-4655-4409-98d4-3d01092bc87d"
    },
    "signOnPolicy" : {
      "href" : "https://api.pingone.com/v1/environments/0eabfd1a-4655-4409-98d4-3d01092bc87d/signOnPolicies/708784f6-d51f-4ae3-b4b7-3f00354eb88b"
    }
  },
  "id" : "1ff6ead6-ff1f-45ea-9e67-b0e0b9206883",
  "environment" : {
    "id" : "0eabfd1a-4655-4409-98d4-3d01092bc87d"
  },
  "type" : "LOGIN",
  "condition" : {
    "secondsSince" : "${session.lastSignOn.withAuthenticator.pwd.at}",
    "greater" : 14400
  },
  "signOnPolicy" : {
    "id" : "708784f6-d51f-4ae3-b4b7-3f00354eb88b"
  },
  "priority" : 1,
  "registration" : {
    "enabled" : true,
    "population" : {
      "id" : "fb526776-dc9b-4c35-af89-d9c98d8d723b"
    }
  },
  "recovery" : {
    "enabled" : true
  }
}

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

A POST request for a sign-on policy action with the type attribute set to MULTI_FACTOR_AUTHENTICATION requires a value for at least one of the email, sms or applications authenticators. The following sample shows the request body for an MFA sign-on policy action:

curl -X "POST" "https://api.pingone.com/v1/environments/{environmentId}/signOnPolicies{policyId}/actions" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d $'{
    "priority": 30,
    "type": "MULTI_FACTOR_AUTHENTICATION",
    "recovery": {
    	"enabled": false
    },

    "sms": {
        "enabled": true
    },
    "email": {
        "enabled": true
    },
    "applications": [
        {
            "id": "5e81bba1-1234-457c-926a-aae0e9876543",
            "autoEnrollment":{"enabled":true}
        }
    ]
}'

Update sign-on policy actions

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,
    "condition" : {
      "or" : [ {
        "not" : {
          "ipRange" : [ "10.5.3.72/24" ],
          "contains" : "${flow.request.http.remoteIp}"
        }
      }, {
        "secondsSince" : "${session.lastSignOn.withAuthenticator.pwd.at}",
        "greater" : 50400
      }, {
        "value" : "${user.population.id}",
        "equals" : "3985fb03-df09-4b00-a01f-89fd529c9de2"
      }, {
        "value" : "${user.email}",
        "equals" : "joe@pingidentity.com"
      } ]
    }
  }'

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.