PingOne Platform APIs

Sign-On Policy Actions

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.

    If you’re provisioning users from an external LDAP directory, refer to the userTypes parameter for the Gateway LDAP data model. For flow details, refer to Login action.

  • MULTI_FACTOR_AUTHENTICATION

    A two-step authentication method that prompts users to enter a one-time password received on a registered device or accept a push confirmation on a registered native device. For flow details, refer to Multi-factor (MFA) action.

  • IDENTIFIER_FIRST

    An action used to identify the user by username and determine the applicable authentication methods for this user. Identifier first flows do not result in a failed state. Any user that does not match a discovery rule will authenticate against PingOne. For flow details, refer to Identifier first action.

  • PROGRESSIVE_PROFILING

    An action to prompt users to provide additional data at sign on. This action type does not authenticate users. It is used only to obtain additional profile data. For flow details, refer to Progressive profiling action.

  • PROGRESSIVE_PROFILING_FORM

    An action to prompt users to provide additional data at sign on. This action is similar to PROGRESSIVE_PROFILING but uses a form configured by form builder to prompt for additional profile data. For flow details, refer to Progressive profiling action.

  • IDENTITY_PROVIDER

    An action that bypasses the PingOne sign-on prompt and immediately redirects the user to an external identity provider’s sign-on workflow to authenticate. For flow details, refer to Identity provider account confirmation.

  • AGREEMENT

    An action that enforces consent to an agreement.

  • PINGID_AUTHENTICATION

    An action that uses PingID as the MFA solution.

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.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, voice, authenticator, user, 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}).

${conditions.geovelocity}

Specifies that an authentication request requires MFA when a geovelocity anomaly is detected. The PingIntelligence platform analyzes location data and determines whether travel time between a user’s current login location and their previous login location is possible in the time frame that has elapsed since the previous login.

${conditions.ipRisk}

Specifies that an authentication request requires MFA when the request comes from an IP address with a high risk score. The PingIntelligence platform collects and analyzes IP address data of authentication requests. An IP address is considered high risk if it may have recently been involved in malicious activities, such as DDos attacks, or spam activity. When the ipRisk condition is applied, the minScore and maxScore parameters defining the high risk score range must be supplied. Authentication requests with a risk score greater than minScore, and less than or equal to`maxScore` require MFA.
For example, if minScore is 80 and maxScore is 90:

* An authentication request with risk score of 80 and below does not require MFA.

* An authentication request with risk score in the range of 81 to 90 (inclusive) requires MFA.

* An authentication request with risk score of 91 and above does not require MFA.

The value set by the admin UI for minScore is 80, and for maxScore is 100. These are also the recommended values.

${conditions.anonymousNetwork}

Specifies that an authentication request requires MFA when the request comes from an IP address detected as an anonymous network. The PingIntelligence platform analyzes IP address data of authentication requests. When the platform identifies an IP address as originating from an anonymous network such as an unknown VPN, proxy or anonymity communication tool such as Tor, it will invoke the MFA flow, with the exception of authentication requests originating from whitelisted IP addresses.

Note: The conditions related to IP address require a PingOne Protect license.

Sign-on policy actions base data model

Property Description

conditions.ipRange

A string that specifies the supported network IP addresses expressed as classless inter-domain routing (CIDR) strings.

conditions.secondsSince

An integer that specifies the maximum number of minutes to wait since the last sign on before prompting for a new sign-on action.

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 associated sign-on policy resource’s unique identifier.

type

A string that specifies the type of action. Options are: LOGIN, MULTI_FACTOR_AUTHENTICATION, IDENTIFIER_FIRST, and PROGRESSIVE_PROFILING.

A sign-on policy supports a maximum of twenty (20) associated sign-on policy actions. If you try to create a sign-on policy action, and this action represents the twenty-first action associated with the policy ID in the signOnPolicy property, the request returns a REQUEST_FAILED exception.

LOGIN action data model

Property Description

confirmIdentityProviderAttributes

A boolean that specifies whether users must confirm data returned from an identity provider prior to registration. Users can modify the data and omit non-required attributes. Modified attributes are added to the user’s profile during account creation. This is an optional property. If omitted, the default value is set to false.

enforceLockoutForIdentityProviders

A boolean that if set to true and if the user’s account is locked (the account.canAuthenticate attribute is set to false), then social sign on with an external identity provider is prevented.

newUserProvisioning

Enables user entries existing outside of PingOne to be provisioned in PingDirectory during login, using an external integration solution (such as a Gateway).

newUserProvisioning.gateways

Allows a set of preconfigured gateways or userType pairs that are specified in the Gateway Management schema to determine how to find and migrate user entries existing in an external directory.

newUserProvisioning.gateways.id

A string referencing the UUID for the gateway.

newUserProvisioning.gateways.type

A string identifying the type of gateway. Currently, only LDAP is supported.

newUserProvisioning.gateways.userType

A reference to the ID of the userTypes configuration set on the gateway for user account migration.

newUserProvisioning.gateways.userType.id

A string referencing the UUID of userType.

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

A string that specifies the link to the external identity provider’s identity store. This property is set when the administrator chooses to have users register in an external identity store. This can be set only when the registration.enabled property is false. This cannot be used when registration.flowDefinition is enabled.

registration.population.id

A string that specifies the population ID associated with the newly registered user.

registration.flowDefinition

A reference to a flow definition to use for user registration rather than the registration logic provided by the action. This can only be set when registration.enabled is false. This cannot be used when registration.external is enabled.

socialProviders[0].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

deviceAuthenticationPolicy.id

The ID of the MFA policy that should be used. This parameter is optional. If it is omitted, the default MFA policy is used.

noDeviceMode

Optional parameter. A string that specifies the device mode for the MFA flow. Options are BYPASS to allow MFA without a specified device, or BLOCK to block the MFA flow if no device is specified. To use this configuration option, the authorize request must include a signed login_hint_token property. For more information, refer to Authorize (Non-redirect and MFA Only Flows). If the parameter is not provided, the default value is BLOCK.

IDENTIFIER_FIRST action data model

Property Description

confirmIdentityProviderAttributes

A boolean that specifies whether users must confirm data returned from an identity provider prior to registration. Users can modify the data and omit non-required attributes. Modified attributes are added to the user’s profile during account creation. This is an optional property. If omitted, the default value is set to false.

discoveryRules.condition

The list of IDP discovery rules that are evaluated in order when no user is associated with the user identifier. The maximum number of rules is 100. The condition on which this identity provider is used to authenticate the user is expressed using the PingOne policy condition language, Constrained to the following format:
{
"value": "${user.username}",
"contains": "{someValue}"
}

enforceLockoutForIdentityProviders

A boolean that if set to true and if the user’s account is locked (the account.canAuthenticate attribute is set to false), then social sign on with an external identity provider is prevented.

identityProvider.id

A string that specifies the identity provider that will be used to authenticate the user if the condition is matched.

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

A string that specifies the link to the external identity provider’s identity store. This property is set when the administrator chooses to have users register in an external identity store. This attribute can be set only when the registration.enabled property is set to false.

registration.population.id

A string that specifies the population ID associated with the newly registered user.

socialProviders[0].id

An array of strings that specifies the IDs of the identity providers that can be used for the social login sign-on flow.

PROGRESSIVE_PROFILING action data model

Property Description

attributes.name

A string that specifies the name and path of the user profile attribute as defined in the user schema (for example, email or address.postalCode). This property is required.

attributes.required

A boolean that specifies whether the user is required to provide a value for the attribute. This property is required.

preventMultiplePromptsPerFlow

A boolean that specifies whether the progressive profiling action will not be executed if another progressive profiling action has already been executed during the flow. This property is required.

promptIntervalSeconds

An integer that specifies how often to prompt the user to provide profile data for the configured attributes for which they do not have values. This property is required.

promptText

A string that specifies text to display to the user when prompting for attribute values. This property is required.

PROGRESSIVE_PROFILING_FORM action data model

Property Description

form.id

An object that specifies the form ID. The form’s category property must be set to PROGRESSIVE_PROFILING. This property is required.

preventMultiplePromptsPerFlow

A boolean that specifies whether the progressive profiling action will not be executed if another progressive profiling action has already been executed during the flow. This property is required.

promptIntervalSeconds

An integer that specifies how often to prompt the user to provide profile data for the configured attributes for which they do not have values. This property is required.

AGREEMENT action data model

Property Description

agreement

The relationship to the agreement to which the user must consent. The agreement must exist and be enabled. An agreement cannot be disabed if an action uses it. An enabled agreement must always support the default language. This property is required.

agreement.id

A string that specifies the ID of the agreement to which the user must consent. This property is required.

IDENTITY_PROVIDER action data model

Property Description

acrValues

A string that designates the sign-on policies included in the authorization flow request. Options can include the PingOne predefined sign-on policies, Single_Factor and Multi_Factor, or any custom defined sign-on policy names. Sign-on policy names should be listed in order of preference, and they must be assigned to the application. This property can be configured on the identity provider action and is passed to the identity provider if the identity provider is of type SAML or OPENID_CONNECT.

entraIdEnabled

An optional boolean used to specify the policy purpose. Applicable only when identityProvider.id relates to a Microsoft Identity Provider, where the Identity provider’s type property value is set to MICROSOFT.

identityProvider

A reference to the external identity provider that is used to authenticate the user. This property is required.

identityProvider.id

A string that specifies the ID of the external identity provider to which the user is redirected for sign-on. This property is required.

passUserContext

A boolean that specifies whether to pass in a login hint to the identity provider on the authentication request. Based on user context, the login hint is set if (1) the user is set on the flow, and (2) the user already has an account link for the identity provider. If both of these conditions are true, then the user is sent to the identity provider with a login hint equal to their externalId for the identity provider (saved on the account link). If these conditions are not true, then the API checks see if there is an OIDC login hint on the flow. If so, that login hint is used. If none of these conditions are true, the login hint parameter is not included on the authorization request to the identity provider.

registration

Specifies the account registration options.

registration.confirmIdentityProviderAttributes

A boolean that specifies whether users must confirm data returned from an identity provider prior to registration. Users can modify the data and omit non-required attributes. Modified attributes are added to the user’s profile during account creation. This is an optional property. If omitted, the default value is set to false.

registration.enabled

A boolean that specifies the enabled/disabled state of the policy action. The property is disabled by default 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.

Sign-on policy actions events generated

Refer to Audit Reporting Events for the events generated.

Response codes

Code Message

200

Successful operation.

201

Successfully created.

204

Successfully removed. No content.

400

The request could not be completed.

403

You do not have permissions or are not licensed to make this request, or your license is exceeded.

404

The requested resource was not found.

Sign-on policy action errors

In addition to the general error codes, sign-on policy action operations can return the following errors:

HTTP status Top‑level code Detail code When it happens and what the response contains

400

INVALID_DATA

EMPTY_VALUE, INVALID_VALUE, or OUT_OF_RANGE

Message: Validation Error : [<property> <message>]

When and details

When: A POST or PUT sign-on policy action request omits the required priority property, omits a required property of the selected action type, or supplies an action property value or registration setting that fails the type’s validation rules

Details: Describes the failing property, such as must not be null for an omitted priority, must be greater than or equal to 1 for a priority less than 1, must be disabled to configure external or flowDefinition when a LOGIN or IDENTIFIER_FIRST action sets registration.external or registration.flowDefinition while registration.enabled is true, or external and flowDefinition are mutually exclusive when a LOGIN or IDENTIFIER_FIRST action sets both. A property value outside its allowed range, such as a negative promptIntervalSeconds, returns OUT_OF_RANGE with rangeMinimumValue and rangeMaximumValue inner errors, for example Validation Error : [promptIntervalSeconds must be between 0 and 2147483647]

400

INVALID_DATA

INVALID_VALUE or EMPTY_VALUE

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A POST or PUT sign-on policy action request supplies a type value that is not one of the supported action types, omits the type property, or an IDENTITY_PROVIDER action that sets passUserContext or entraIdEnabled for an identity provider of a type that does not support the property

Details: Describes the rejected value, such as <value> is not a known action type. for an unrecognized type (with target type), Must not be empty. when type is omitted or empty, Only SAML or OIDC type IDP can be configured with 'passUserContext' property. (with target passUserContext), or Only MICROSOFT type IDP can be configured with 'entraIdEnabled' property. (with target entraIdEnabled)

400

INVALID_DATA

INVALID_VALUE

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: An IDENTIFIER_FIRST action request has more than 200 discoveryRules entries (raised to 500 for environments with the increased-limit feature enabled), a discovery rule condition that is not a data rule, a comparison operation that is not contains, a comparing value that is not ${identifier}, an empty contains value, or discovery-rule identity providers that do not exist in the environment

Details: One detail per failing rule, such as exceeds the maximum limit of 200, rule is not a data rule, operation is not contains, value is not ${identifier}, contains is empty, or All identity providers must exist within the environment.

400

INVALID_DATA

UNIQUENESS_VIOLATION

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A PROGRESSIVE_PROFILING action request repeats an attribute in the attributes array, or a LOGIN action’s newUserProvisioning.gateways array repeats a gateway and user type combination

Details: All attributes must be unique or All gateway and user type combinations must be unique.

400

INVALID_DATA

INVALID_VALUE

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: An AGREEMENT action references an agreement that does not exist, a PROGRESSIVE_PROFILING_FORM action references a form that does not exist or whose category property is not PROGRESSIVE_PROFILING, a LOGIN, IDENTIFIER_FIRST, or IDENTITY_PROVIDER action references a population that does not exist, a LOGIN action references a nonexistent or non-LDAP gateway, a user type that does not exist on its referenced gateway, or a user type without newUserLookup configuration, a LOGIN or IDENTIFIER_FIRST action references an identity provider in its socialProviders array that does not exist in the environment, or an IDENTITY_PROVIDER action references an identity provider that does not exist in the environment, or a LOGIN or IDENTIFIER_FIRST action with registration.enabled set to false references a registration.flowDefinition that does not exist or whose trigger type is not SIGN_ON_POLICY

Details: The agreement does not exist., Progressive profiling form does not exist., Category must be PROGRESSIVE_PROFILING, Population does not exist, All gateways must exist within the environment., Only 'LDAP' type gateways are supported for newUserProvisioning., All user types must exist on their referenced gateway., All user types must have newUserLookup configuration to support provisioning., All identity providers must exist within the environment. (target socialProviders), The identity provider must exist within the environment. (target identityProvider.id), Flow definition does not exist (target registration.flowDefinition.id), or Flow definition trigger type must be SIGN_ON_POLICY (target registration.flowDefinition.id)

400

INVALID_REQUEST

None

Message: The request could not be completed. One or more validation errors were in the request. (the top‑level code is INVALID_REQUEST even though the message text is the INVALID_DATA default message)

When and details

When: A path identifier cannot be parsed as a UUID

Details: None.

400

INVALID_REQUEST

INVALID_VALUE or None

Message: The request could not be completed. The request was malformed or invalid.

When and details

When: The request body is not well-formed JSON or contains a property whose value cannot be converted to the type the selected action expects. An unrecognized or missing type property returns INVALID_DATA instead (see the action-type row above)

Details: For a JSON field conversion error, the detail is Invalid value for attribute. with the field path as the target. Otherwise no detail is returned.

400

INVALID_DATA

INVALID_VALUE

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: The condition property cannot be deserialized as a policy condition

Details: condition language is malformed, with the parser message in innerError.malformedCondition

400

REQUEST_FAILED

CONSTRAINT_VIOLATION

Message: The request could not be completed. There was an issue processing the request.

When and details

When: A POST /signOnPolicies/{policyID}/actions request would create the twenty‑first action associated with the sign-on policy (a policy supports a maximum of twenty associated actions), a DELETE /signOnPolicies/{policyID}/actions/{actionID} request would remove the policy’s last remaining action, a LOGIN action’s newUserProvisioning array assigns more than the allowed number of gateways, or an actor without valid MFA settings would lock themselves out by creating or updating an action on a sign-on policy assigned to the platform’s self-service application or on the environment’s default policy

Details: Cannot create more than 20 actions per policy for the action limit, Cannot delete last action from the policy: <policyId> for the delete limit, Cannot assign more than <maximum> gateways for new user provisioning for the gateway limit, or Cannot update the sign on policy to include MFA when you have MFA disabled or no valid registered device. for the MFA lockout

400

INVALID_DATA

INVALID_VALUE

Message: The request violates a constraint imposed by the service. (the top‑level code is INVALID_DATA even though the message text is the constraint‑violation message)

When and details

When: A PUT /signOnPolicies/{policyID}/actions/{actionID} request changes the action’s type from the existing type

Details: Expecting <existingType> action type.

400

REQUEST_FAILED

CONSTRAINT_VIOLATION

Message: The request could not be completed. There was an issue processing the request.

When and details

When: An action’s condition contains more than one data rule of the same PingIntelligence type (Intelligence Risk, Intelligence GeoVelocity, Intelligence Reputation, or Intelligence AnonymousNetwork)

Details: Only one rule of type <rule name>: can be created for action

403

ACCESS_FAILED

LICENSE_EXCEEDED

Message: The request could not be completed. You do not have access to this resource.

When and details

When: A POST or PUT request creates or updates a PINGID_AUTHENTICATION or PINGID_WINLOGIN_PASSWORDLESS_AUTHENTICATION action for an environment that has no PingID deployment, or a POST request (or a PUT request that changes the condition) for an action whose condition uses a PingIntelligence rule (Intelligence Risk, Intelligence GeoVelocity, Intelligence Reputation, or Intelligence AnonymousNetwork) for an environment that is not enabled for that capability

Details: PingID is disabled for environment: <environmentId> or Environment is disabled for <rule name>: <environmentId>

403

ACCESS_FAILED

None

Message: The actor attempting to perform the request is not authorized.

When and details

When: The actor lacks the authn:update:signOnPolicy permission (POST creating an action, PUT, or DELETE), the authn:read:signOnPolicy permission (GET operations), or the authn:delete:signOnPolicy permission (DELETE on the sign-on policy itself)

Details: None.

404

NOT_FOUND

None

Message: The request could not be completed. The requested resource was not found.

When and details

When: GET or POST /signOnPolicies/{policyID}/actions references a sign-on policy that does not exist in the environment, or GET, PUT, or DELETE /signOnPolicies/{policyID}/actions/{actionID} references a sign-on policy or action that does not exist

Details: None.
Related topics