Activity - Configure a passwordless sign-on policy


Introduction and workflow tasks

PingOne supports a sign-on flow that uses only a username and a multi-factor authentication sign-on action to authenticate the user. This activity shows you how to create a sign-on policy that does not require a password at login.

Note: To create a new sign-on policy and its associated sign-on policy action, you must have the Environment Admin role.

This scenario illustrates the following common operations supported by the PingOne for Customers APIs:

  • Create a sign-on policy
  • Create a sign-on policy action
  • Assign the sign-on policy to an application

Workflow order of operations

To create a sign-on policy that does not prompt for a password at login, the following tasks must be completed successfully:

  1. Make a POST request to /environments/{environmentId}/signOnPolicies to create a new sign-on policy.

  2. Make a POST request to /environments/{environmentId}/signOnPolicies/{policyId}/actions to create a new MFA sign-on policy action, which is associated with the new (no password) sign-on policy.

  3. Make a POST request to /environments/{environmentId}/applications/{applicationId}/signOnPolicyAssignments to associate this sign-on policy with the specified application.

Step 1: Create the new sign-on policy

You can use the POST /environments/{environmentId}/signOnPolicies endpoint to create the new sign-on policy.

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

In the request, the name property is required and must be unique within the environment. The description property is optional, but recommended.

The response shows the property data for the new sign-on policy.

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/signOnPolicies/5edef002-3f1f-4e00-a4db-130807f41234"
        },
        "environment": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006"
        },
        "actions": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/signOnPolicies/5edef002-3f1f-4e00-a4db-130807f41234/actions"
        }
    },
    "id": "5edef002-3f1f-4e00-a4db-130807f41234",
    "environment": {
        "id": "88c23def-39c9-4646-8d41-aa91a14a1006"
    },
    "name": "Passwordless",
    "description": "A no password sign-on policy",
    "default": false,
}

Note: The response includes an actions HAL link to the sign-on policy actions endpoint, which is used to assign an action to the new sign-on policy. The policy must have at least one associated action before it can be assigned to an application.

Step 2: Create the sign-on policy action

The POST /environments/{environmentId}/signOnPolicies/{policyId}/actions operation creates the new sign-on policy action resource, which is associated with the sign-on policy ({policyId}) specified in the request URL.

PingOne supports the following two sign-on policy action types:

  • LOGIN

    Basic authentication that prompts for a username and password.

  • MULTI_FACTOR_AUTHENTICATION

    A multi-factor action that can return multiple status conditions, which result in more than one operation to complete.

To initiate a “passwordless” login flow, the type property for the action resource associated with the sign-on policy must be set to MULTI_FACTOR_AUTHENTICATION. You are creating a multi-factor action in which the first operation validates the username, and the second operation issues and validates the one-time password.

curl -X "POST" "https://api.pingone.com/v1/environments/{environmentID}/signOnPolicies/{policyID}/actions" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d '{
    "priority": 1,
    "type": "MULTI_FACTOR_AUTHENTICATION",
    "recovery": {
    	"enabled": false
    },
	  "sms": {
        "enabled": true
    },
    "email": {
        "enabled": true
    }
}'

This sign-on policy specifies the sms and email MFA authenticators. Note that it does not specify the pwd (password) authenticator.

The response data looks like this:

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/signOnPolicies/5edef002-3f1f-4e00-a4db-130807f41234/actions/a256b35d-4b14-4ee5-85da-d8450c1aefd2"
        },
        "environment": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006"
        },
        "signOnPolicy": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/signOnPolicies/5edef002-3f1f-4e00-a4db-130807f41234"
        }
    },
    "id": "a256b35d-4b14-4ee5-85da-d8450c1aefd2",
    "environment": {
        "id": "88c23def-39c9-4646-8d41-aa91a14a1006"
    },
    "signOnPolicy": {
        "id": "5edef002-3f1f-4e00-a4db-130807f41234"
    },
    "priority": 1,
    "type": "MULTI_FACTOR_AUTHENTICATION",
    "sms": {
        "enabled": true
    },
    "email": {
        "enabled": true
    }
}

Step 3: Assign the sign-on policy to an application

To use the new sign-on policy, the POST /environments/{environmentId}/applications/{applicationId}/signOnPolicyAssignments operation assigns the new “passwordless” sign-on policy to the application specified by its ID in the request URL. The request body requires the sign-on policy property id and an integer value for the priority property.

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": "5edef002-3f1f-4e00-a4db-130807f41234"
    },
    "priority": 1
}'

Note: If an application’s sign-on policy assignments include only one policy, such as the Passwordless sign-on policy, then the application uses only that sign-on policy. If the application has multiple assigned sign-on policies, it uses the sign-on priority with the highest priority (priority 1). If an authorization request specifies the Passwordless sign-on policy in the acr_values property, then the application uses only the Passwordless sign-on policy. When acr_values are specified in the authorization request, the sign-on policy (or policies) specified must be assigned to the application.