Application Sign-On Policy Assignments

Sign-on policy assignment endpoints manage the sign-on policies associated with the specified application. An application can have zero or more sign-on policies assigned to it that determine how users are authenticated. The number of sign-on policies assigned to an application also controls how the authentication flow progresses.

No sign-on policy assignments

Applications that have no sign-on policy assignments use the environment resource’s default sign-on policy to authenticate users. Every environment has one designated sign-on policy as its default policy. If the environment’s default sign-on policy changes, then the application’s sign-on policy changes to use the updated default policy.

One sign-on policy assignment

Applications that have one sign-on policy assignment always use that sign-on policy to authenticate users. For example, if the application has the Single_Factor sign-on policy assigned, the application will always use this basic authentication method that prompts users to enter a username and password to authenticate the account.

Two or more sign-on policy assignments

If an application has two or more assigned sign-on policies, the authentication flow uses the sign-on policy with the highest priority (priority 1) first. If authentication is successful, the sign-on flow is complete. If authentication fails, the flow initiates the sign-on policy with the next highest priority. If authentication fails again, the sign-on flow initiates the next sign-on policy. The sign-on flow continues until one of the assigned sign-on policies completes successfully or all policies have been tried and failed.

Sign-on policy priority when `acr_values` is set

For applications with the protocol property set to OPENID_CONNECT, the acr_values property (set on the authorize request) identifies the exact list of sign-on policies that can execute at sign on. At sign-on, only the sign-on policies listed in the acr_values property are evaluated, and they are evaluated based on the order of the policies listed in this property. In addition, if there are numerous sign-on policies assigned to an application, setting the acr_values property limits the number of sign-on policies evaluated to only those listed in this property.

For example, if the authorize request includes acr_values=Multi_Factor Single_Factor, the authentication flow executes the Multi_Factor policy first. If the multi-factor sign-on flow completes all conditions for the policy, the flow completes and the user is issued a token. If the multi-factor policy fails, the Single_Factor policy executes. If that policy completes all conditions, the flow completes and the user is issued a token. If the single-factor policy is the last policy in the acr_values list, and it fails, then the sign-on flow fails. No other sign-on policies are tried, even if the application has additional sign-on policy assignments.

Applications sign-on policy assignments data model

Property Type Required Mutable Description

Property	Type	Required	Mutable	Description
`application.id`	String	Required	Read-only	The application resource ID associated with the sign-on policy assignment.
`environment.id`	String	Required	Read-only	The environment associated with the application sign-on policy assignment.
`id`	String	Required	Read-only	The sign-on policy assignment resource’s unique identifier.
`priority`	Integer	Required	Mutable	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.
`signOnPolicy.id`	String	Required	Mutable	The sign-on policy resource’s unique identifier associated with this sign-on policy assignment.

application.id

String

Required

Read-only

The application resource ID associated with the sign-on policy assignment.

environment.id

String

Required

Read-only

The environment associated with the application sign-on policy assignment.

id

String

Required

Read-only

The sign-on policy assignment resource’s unique identifier.

priority

Integer

Required

Mutable

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.

signOnPolicy.id

String

Required

Mutable

The sign-on policy resource’s unique identifier associated with this sign-on policy assignment.

Application Sign-on Policy 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.
401	You do not have access to this resource.
403	You do not have permissions or are not licensed to make this request.
404	The requested resource was not found.
500	An unexpected error occurred.

Application sign-on policy assignment errors

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

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

HTTP status	Top‑level code	Detail code	When it happens and what the response contains
400	`INVALID_DATA`	`EMPTY_VALUE` or `OUT_OF_RANGE` or `INVALID_VALUE`	Message: `Validation Error : [<property> <message>]` When and details When: A `POST` or `PUT` request omits a required request body property (the `signOnPolicy` relationship with an `id`, or `priority`) or supplies a `priority` value less than 1 Details: Describes the failing property, such as `must not be null` for an omitted `priority` property, `must have an id` for a `signOnPolicy` relationship without an `id`, or `must be greater than or equal to 1` for a `priority` less than 1, for example `Validation Error : [priority must be greater than or equal to 1]`
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: A `POST` request references a sign-on policy that does not exist in the environment, or a `PUT` request sets `signOnPolicy.id` to a value that does not match the assignment’s current sign-on policy Details: `The sign-on policy does not exist` for a `POST` referencing a nonexistent policy, or `The attribute is immutable and cannot be updated` for a `PUT` that changes the sign-on policy.
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 `POST` request assigns a sign-on policy that is already assigned to the application Details: `The sign-on policy is already assigned to the application.`
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` request creates the twenty‑first sign-on policy assignment for the application (a maximum of twenty assignments per application is enforced), or a `POST` or `DELETE` request changes the sign-on policies of the PingOne self-service application in a way that would lock the actor out of the application (the actor has MFA disabled or no valid registered devices) Details: `Cannot create more than 20 policy assignments per application` for the assignment limit, `Cannot assign a MFA sign on policy to an application when you have MFA disabled or no valid registered devices.` for a self-service `POST`, or `Cannot delete policy assignment because your MFA settings are incompatible with the proposed assignments.` for a self-service `DELETE`
400	`INVALID_REQUEST`	None	Message: `The request could not be completed. One or more validation errors were in the request.` When and details When: A path identifier cannot be parsed as a UUID Details: None. The top-level code is `INVALID_REQUEST` even though the message text is the `INVALID_DATA` default message.
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 cannot be deserialized Details: For a JSON field conversion error, the target is the field path. Otherwise no detail is returned.
403	`ACCESS_FAILED`	None	Message: `The actor attempting to perform the request is not authorized.` When and details When: The actor lacks the `applications:read:signOnPolicyAssignment` permission (`GET` operations), `applications:create:signOnPolicyAssignment` (`POST`), `applications:update:signOnPolicyAssignment` (`PUT`), or `applications:delete:signOnPolicyAssignment` (`DELETE`) Details: None.
404	`NOT_FOUND`	None	Message: `The request could not be completed. The requested resource was not found.` When and details When: A `GET`, `PUT`, or `DELETE` request specifies an assignment ID that does not exist for the application, or the application does not exist in the environment (including requests that target the PingOne admin console application, to which sign-on policies cannot be assigned) Details: None.
500	`UNEXPECTED_ERROR`	None	Message: `There was an unexpected error with the service. Please try again later.` When and details When: The service encounters an internal error while processing the request Details: None.

400

INVALID_DATA

EMPTY_VALUE or OUT_OF_RANGE or INVALID_VALUE

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

When and details

When: A POST or PUT request omits a required request body property (the signOnPolicy relationship with an id, or priority) or supplies a priority value less than 1

Details: Describes the failing property, such as must not be null for an omitted priority property, must have an id for a signOnPolicy relationship without an id, or must be greater than or equal to 1 for a priority less than 1, for example Validation Error : [priority must be greater than or equal to 1]

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: A POST request references a sign-on policy that does not exist in the environment, or a PUT request sets signOnPolicy.id to a value that does not match the assignment’s current sign-on policy

Details: The sign-on policy does not exist for a POST referencing a nonexistent policy, or The attribute is immutable and cannot be updated for a PUT that changes the sign-on policy.

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 POST request assigns a sign-on policy that is already assigned to the application

Details: The sign-on policy is already assigned to the application.

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 request creates the twenty‑first sign-on policy assignment for the application (a maximum of twenty assignments per application is enforced), or a POST or DELETE request changes the sign-on policies of the PingOne self-service application in a way that would lock the actor out of the application (the actor has MFA disabled or no valid registered devices)

Details: Cannot create more than 20 policy assignments per application for the assignment limit, Cannot assign a MFA sign on policy to an application when you have MFA disabled or no valid registered devices. for a self-service POST, or Cannot delete policy assignment because your MFA settings are incompatible with the proposed assignments. for a self-service DELETE

400

INVALID_REQUEST

None

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

When and details

When: A path identifier cannot be parsed as a UUID

Details: None. The top-level code is INVALID_REQUEST even though the message text is the INVALID_DATA default message.

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 cannot be deserialized

Details: For a JSON field conversion error, the target is the field path. Otherwise no detail is returned.

403

ACCESS_FAILED

None

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

When and details

When: The actor lacks the applications:read:signOnPolicyAssignment permission (GET operations), applications:create:signOnPolicyAssignment (POST), applications:update:signOnPolicyAssignment (PUT), or applications:delete:signOnPolicyAssignment (DELETE)

Details: None.

404

NOT_FOUND

None

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

When and details

When: A GET, PUT, or DELETE request specifies an assignment ID that does not exist for the application, or the application does not exist in the environment (including requests that target the PingOne admin console application, to which sign-on policies cannot be assigned)

Details: None.

500

UNEXPECTED_ERROR

None

Message: There was an unexpected error with the service. Please try again later.

When and details

When: The service encounters an internal error while processing the request

Details: None.

PingOne Platform APIs

Application Sign-On Policy Assignments

No sign-on policy assignments

One sign-on policy assignment

Two or more sign-on policy assignments

Sign-on policy priority when acr_values is set

Applications sign-on policy assignments data model

Application Sign-on Policy events generated

Response codes

Application sign-on policy assignment errors

Sign-on policy priority when `acr_values` is set