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:

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:

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, 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 tomaxScore 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.

Sign-on policy actions 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 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, IDENTITY_PROVIDER, AGREEMENT, PROGRESSIVE_PROFILING, PROGRESSIVE_PROFILING_FORM, EXPERIENCE and PINGID_AUTHENTICATION.

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.
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.flowDefinition.id A string that specifies the flow definition to use for user registration rather than the registration logic provided by the action. This property can be set only when registration.enabled is false, and it is mutually exclusive with registration.external.href.
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
authenticator Specifies MFA through a Time-based One-time Password (TOTP) option over a third-party authenticator application.
authenticator.enabled A boolean that specifies the enabled/disabled state of the MFA through a Time-based One-time Password (TOTP) action. The default is disabled when creating a new policy. When enabled, it allows users to authenticate using a TOTP authenticator application.
boundBiometrics Specifies MFA through a FIDO2 biometrics platform device.
boundBiometrics.enabled A boolean that specifies whether to permit users to authenticate with a FIDO2 biometrics platform device.
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 disbled when creating a new policy. When enabled, it allows users to receive the one-time password and authenticate through email.
securityKey Specifies MFA using a FIDO2 or U2F security key device.
securityKey.enabled A boolean that specifies whether to permit users to authenticate with a security key device.
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 disabled 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.
  • deviceAuthorization.enabled
    A boolean that specifies the enabled/disabled state of automatic MFA for mobile devices paired with the user for the specified application.
    The default is disabled when creating a new policy.
  • deviceAuthorization.extraVerification
    Specifies the level of further verification when deviceAuthorization is enabled. The PingOne platform performs an extra verification check by sending a “silent” push notification to the customer mobile application, and receives a confirmation in return.
    extraVerification can be one of the following levels:
    • disabled (default): The PingOne platform does not perform the extra verification check.
    • permissive: The PingOne platform performs the extra verification check. Upon timeout or failure to get a response from the mobile app, the MFA step is treated as successfully completed.
    • restrictive: The PingOne platform performs the extra verification check.The PingOne platform performs the extra verification check. Upon timeout or failure to get a response from the mobile app, the MFA step is treated as failed.
noDeviceMode 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, see Authorize (Browserless and MFA Only Flows).

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}”
}
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.flowDefinition.id A string that specifies the flow definition to use for user registration rather than the registration logic provided by the action. This property can be set only when registration.enabled is false, and it is mutually exclusive with registration.external.href.
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.

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 An object that specifies the form to prompt for this progressive profiling action. This property is required.
form.id A string that specifies the Id of the form resource. Only forms that are appropriate for progressive profiling are supported for this action. 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.

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.
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.
includeSubject A boolean that specifies whether to include a login hint on the authorize request for SAML identity providers. The login hint for the IDENTITY_PROVIDER action 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 a 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. SAML follows this workflow, but only if the includeSubject parameter is set to true.
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.

EXPERIENCE action data model

Property Description
flowDefinition.id A reference to a flow definition, which serves as a redirect. Only flow definitions associated with an experience trigger can be referenced in the experience action.
flowDefinition.id A string that specifies the flow definition ID.

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.