Sign-on policies


Sign-on policies

Sign-on policies determine the account authentication flow users must complete to access applications secured by PingOne services. PingOne provides the following pre-defined sign-on policy configurations:

  • Single_Factor

    The configured single-factor sign-on policy is a basic authentication method that prompts users to enter a username and password to authenticate the account.

  • Multi_Factor

    The configured multi-factor sign-on policy is a two-step authentication method that prompts users to take the following actions:

    • Enter a username and password.
    • Enter a one-time password on a registered device.

Sign-on policies are defined by their associated actions. For example, the Single-Factor sign-on policy resource includes a defined LOGIN action that prompts users for a username and password. The actions associated with a sign-on policy resource can be modified using a PUT request.

The examples that follow show common operations to create and manage sign-on policies resources. You need the Environment Admin role to perform operations on sign-on policy resources.

Sign-on policies API operations

The sign-on policies 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 policies data model

Property Description
createdAt The time the resource was created.
description A string that specifies the description of the sign-on policy.
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 resource’s unique identifier.
name A string that specifies the resource name.
updatedAt The time the resource was last updated.

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 policies

The GET /environments/{environmentId}/signOnPolicies endpoint returns a list of all sign-on policy resources for the specified environment.

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

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

The response data looks like this:

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/signOnPolicies"
        }
    },
    "_embedded": {
        "signOnPolicies": [
            {
                "_links": {
                    "self": {
                        "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/signOnPolicies/1c006010-a765-448b-84bf-32199c4af3c3"
                    },
                    "environment": {
                        "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba"
                    },
                    "actions": {
                        "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/signOnPolicies/1c006010-a765-448b-84bf-32199c4af3c3/actions"
                    }
                },
                "id": "1c006010-a765-448b-84bf-32199c4af3c3",
                "environment": {
                    "id": "0bda42bc-d54f-449f-8d46-d5b8990c43ba"
                },
                "name": "Multi_Factor",
                "description": "A sign-on policy that requires primary username and password along with an out-of-band OTP"
            },
            {
                "_links": {
                    "self": {
                        "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/signOnPolicies/7bf52bba-ef9a-47ac-9163-4310f3208409"
                    },
                    "environment": {
                        "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba"
                    },
                    "actions": {
                        "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/signOnPolicies/7bf52bba-ef9a-47ac-9163-4310f3208409/actions"
                    }
                },
                "id": "7bf52bba-ef9a-47ac-9163-4310f3208409",
                "environment": {
                    "id": "0bda42bc-d54f-449f-8d46-d5b8990c43ba"
                },
                "name": "Single_Factor",
                "description": "A sign-on policy that requires username and password"
            }
        ]
    },
    "count": 2,
    "size": 2
}

Get one sign-on policy

To get data for a specific sign-on policy, the GET /environments/{environmentId}/signOnPolicies/{policyId} operation returns data for the sign-on policy resource with the specified ID.

curl -X GET "https://api.pingone.com/v1/environments/{environmentId}/signOnPolicies/{policyId}" \
-H "Authorization: Bearer jwtToken"

The response data looks like this:

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/signOnPolicies/7bf52bba-ef9a-47ac-9163-4310f3208409"
        },
        "environment": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba"
        },
        "actions": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/signOnPolicies/7bf52bba-ef9a-47ac-9163-4310f3208409/actions"
        }
    },
    "id": "7bf52bba-ef9a-47ac-9163-4310f3208409",
    "environment": {
        "id": "0bda42bc-d54f-449f-8d46-d5b8990c43ba"
    },
    "name": "Single_Factor",
    "description": "A sign-on policy that requires username and password"
}

Create sign-on policies

The POST /environments/{environmentId}/signOnPolicies operation creates a new sign-on policy resource. In the request body, the name property is required, and the sign-on policy name must be unique within the environment. All other properties are optional.

curl -X "POST" "https://api.pingone.com/v1/environments/{environmentId}/signOnPolicies" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d $'{
  "name": "Simple_Login",
  "default": "false",
  "description": "A new basic sign-on policy."
}'

The response data looks like this:

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/signOnPolicies/7bf52bba-ef9a-47ac-9163-4310f3208409"
        },
        "environment": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba"
        },
        "actions": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/signOnPolicies/7bf52bba-ef9a-47ac-9163-4310f3208409/actions"
        }
    },
    "id": "7bf52bba-ef9a-47ac-9163-4310f3208409",
    "environment": {
        "id": "0bda42bc-d54f-449f-8d46-d5b8990c43ba"
    },
    "default": "false",
    "description": "A new basic sign-on policy.",
    "name": "Simple_Login"
}

Update sign-on policies

The PUT /environments/{environmentId}/signOnPolicies/{policyId} operation updates the sign-on policy resource specified by its ID in the request URL.

curl -X "PUT" "https://api.pingone.com/v1/environments/{environmentId}/signOnPolicies/{policyId}" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d $'{
  "default": "true",
  "description": "A more complex sign-on policy.",
  "name": "Complex_Login"
}'

The response data looks like this:

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/signOnPolicies/7bf52bba-ef9a-47ac-9163-4310f3208409"
        },
        "environment": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba"
        },
        "actions": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/signOnPolicies/7bf52bba-ef9a-47ac-9163-4310f3208409/actions"
        }
    },
    "id": "7bf52bba-ef9a-47ac-9163-4310f3208409",
    "environment": {
        "id": "0bda42bc-d54f-449f-8d46-d5b8990c43ba"
    },
    "default": "true",
    "description": "A new basic sign-on policy.",
    "name": "Complex_Login"
}

Delete sign-on policies

The following sample shows the DELETE /environments/{environmentId}/signOnPolicies/{policyId} operation to delete the sign-on policy resource.

curl -X DELETE "https://api.pingone.com/v1/environments/{environmentId}/signOnPolicies/{policyId}" \
-H "Authorization: Bearer jwtToken"

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