Sign-on policy assignments


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.

Applications sign-on policy assignments API operations

The Applications sign-on policy assignments endpoints support the following operations:

For hands-on experience with the Applications 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.

Applications sign-on policy assignments data model

Property Description
application.id The identifier of the resource referenced by this relationship
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 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 A string that specifies the sign-on policy resource’s unique identifier associate with this sign-on policy assignment.

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.

Note: You need the Client Application Developer role to perform operations on application resources.

Endpoint examples

Get sign-on policy assignments

The GET /environments/{environmentId}/applications/{applicationId}/signOnPolicyAssignments endpoint returns a list of all sign-on policy resources assigned to an application.

The following sample returns the list of sign-on policy resources associated with the application ID specified in the request URL:

curl -X "GET" "https://api.pingone.com/v1/environments/{environmentId}/applications/{applicationId}/signOnPolicyAssignments" \
-H 'Authorization: Bearer jwtToken'

The response data looks like this:

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/e4d7bcd3-7a00-4c4d-9ce0-88f4b1954474/applications/d64f66de-1502-4398-96a1-02f0d2a86f9c/signOnPolicyAssignments
        }
    },
    "_embedded": {
        "signOnPolicyAssignments": [
        {
              "_links": {
                  "self": {
                     "href": "https://api.pingone.com/v1/environments/e4d7bcd3-7a00-4c4d-9ce0-88f4b1954474/applications/d64f66de-1502-4398-96a1-02f0d2a86f9c/signOnPolicyAssignments/ede42c6c-a97a-4c2c-aaeb-9cb38f13bb13"
              },
              "environment": {
                 "href": "https://api.pingone.com/v1/environments/e4d7bcd3-7a00-4c4d-9ce0-88f4b1954474"
              },
              "application": {
                 "href": "https://api.pingone.com/v1/environments/e4d7bcd3-7a00-4c4d-9ce0-88f4b1954474/applications/d64f66de-1502-4398-96a1-02f0d2a86f9c"
              },
              "signOnPolicy": {
                 "href": "https://api.pingone.com/v1/environments/e4d7bcd3-7a00-4c4d-9ce0-88f4b1954474/signOnPolicies/54f11a8b-0e09-4f76-8cdc-2efa2c9c499e"
              }
          },
        "id": "ede42c6c-a97a-4c2c-aaeb-9cb38f13bb13",
        "environment": {
            "id": "e4d7bcd3-7a00-4c4d-9ce0-88f4b1954474"
         },
        "application": {
            "id": "d64f66de-1502-4398-96a1-02f0d2a86f9c"
        },
        "signOnPolicy": {
            "id": "54f11a8b-0e09-4f76-8cdc-2efa2c9c499e"
        },
        "priority": 1
       }
     }
   ]
},
"count": 1,
"size": 1
}

Get one sign-on policy assignment

To get data for a specific sign-on policy assignment, the GET /environments/{environmentId}/applications/{applicationId}/signOnPolicyAssignments/{assignmentId} operation returns data for the sign-on policy assignment resource with the specified ID.

curl -X GET "https://api.pingone.com/v1/environments/environments/{environmentId}/applications/{applicationId}/signOnPolicyAssignments/{assignmentId}" \
-H "Authorization: Bearer jwtToken"

Create sign-on policy assignments

The POST /environments/{environmentId}/applications/{applicationId}/signOnPolicyAssignments operation creates a new sign-on policy assignment resource. The id for the signOnPolicy property and the priority property are required in the request body.

curl -X "POST" "https://api.pingone.com/v1/environments/{environmentId}/applications/{applicationId}/signOnPolicyAssignments" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d '{
    "signOnPolicy": {
      "id": "54f11a8b-0e09-4f76-8cdc-2efa2c9c499e"
    },
    "priority": 1
}'

The response data looks like this:

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/e4d7bcd3-7a00-4c4d-9ce0-88f4b1954474/applications/d64f66de-1502-4398-96a1-02f0d2a86f9c/signOnPolicyAssignments/ede42c6c-a97a-4c2c-aaeb-9cb38f13bb13"
        },
        "environment": {
            "href": "https://api.pingone.com/v1/environments/e4d7bcd3-7a00-4c4d-9ce0-88f4b1954474"
        },
        "application": {
            "href": "https://api.pingone.com/v1/environments/e4d7bcd3-7a00-4c4d-9ce0-88f4b1954474/applications/d64f66de-1502-4398-96a1-02f0d2a86f9c"
        },
        "signOnPolicy": {
            "href": "https://api.pingone.com/v1/environments/e4d7bcd3-7a00-4c4d-9ce0-88f4b1954474/signOnPolicies/54f11a8b-0e09-4f76-8cdc-2efa2c9c499e"
        }
    },
    "id": "ede42c6c-a97a-4c2c-aaeb-9cb38f13bb13",
    "environment": {
        "id": "e4d7bcd3-7a00-4c4d-9ce0-88f4b1954474"
    },
    "application": {
        "id": "d64f66de-1502-4398-96a1-02f0d2a86f9c"
    },
    "signOnPolicy": {
        "id": "54f11a8b-0e09-4f76-8cdc-2efa2c9c499e"
    },
    "priority": 1
}

Update sign-on policy assignments

The PUT /environments/environments/{environmentId}/applications/{applicationId}/signOnPolicyAssignments/{assignmentId} operation modifies the sign-on policy assignment resource specified by its ID in the request URL.

curl -X "PUT" "https://api.pingone.com/v1/environments/environments/environments/{environmentId}/applications/{applicationId}/signOnPolicyAssignments/{assignmentId}" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d '{
    "signOnPolicy": {
      "id": "54f11a8b-0e09-4f76-8cdc-2efa2c9c499e"
    },
    "priority": 2
}'

Delete sign-on policy assignments

The following sample shows the DELETE /environments/environments/{environmentId}/applications/{applicationId}/signOnPolicyAssignments/{assignmentId} operation to delete the sign-on policy assignment.

curl -X DELETE "https://api.pingone.com/v1//environments/environments/{environmentId}/applications/{applicationId}/signOnPolicyAssignments/{assignmentId}" \
-H "Authorization: Bearer jwtToken" \

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