Work with users


Users

A user resource is a unique identity within PingOne that interacts with the applications and services in the environment to which the user is assigned. The users service implements directory functions to create, read, update, delete, and search for user resources. Users are associated with an environment and a population. The following diagram shows how users are organized in the directory.

Users

The examples below show common actions to find and manage users. You need the Identity Data Admin role to perform operations on users resources. For more information, see Work with user roles.

Filtering result data

You can filter result data by applying a SCIM filtering expression to the GET request URL. For large collections, a filtering expression appended to the query returns a targeted, more useful data set. For example, this URL-encoded SCIM filter returns users with a last name of “Smith” and a first name that starts with the letter “W”:

https://api.pingone.com/v1/environments/b7372995-824b-44ff-99f8-ab151dac3263/users?filter=name.family%20eq%20%Smith%22%20and%20name.given%20sw%20%22W%22"

These SCIM operators can be applied to the following attributes:

  • eq (equals)

    Supported attributes: username, name.family, name.given, email, mobilePhone, population.id

  • sw (starts with)

    Supported attributes: username, name.family, name.given, email, mobilePhone

  • and (logical AND)

    Logical AND for building compound expressions in which both expressions are true.

  • or (logical OR)

    Logical OR for building compound expressions if either expression is true.

Note: These SCIM operators are not supported: ne (not equal), co (contains), ew (ends with), pr (present, is a non-empty or non-null value), gt (greater than), ge (greater than or equal to), lt (less than), le (less than or equal to), not (logical NOT).

For more information about SCIM syntax and operators, see Conventions.

Get users

The following sample shows the GET /environments/{environmentId}/users operation to return a list of all user resources for the specified environment.

curl -X "GET" "https://api.pingone.com/v1/environments/b7372995-824b-44ff-99f8-ab151dac3263/users" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken'

The response data looks like this:

{
  "_links" : {
    "self" : {
      "href" : "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/users"
    }
  },
  "_embedded" : {
    "users" : [ {
      "_links" : {
        "self" : {
          "href" : "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/users/9a774ad6-b6b6-4179-af87-226cd68955f0"
        },
        "password" : {
          "href" : "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/users/9a774ad6-b6b6-4179-af87-226cd68955f0/password"
        },
        "password.set" : {
          "href" : "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/users/9a774ad6-b6b6-4179-af87-226cd68955f0/password"
        },
        "password.reset" : {
          "href" : "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/users/9a774ad6-b6b6-4179-af87-226cd68955f0/password"
        }
      },
      "id" : "9a774ad6-b6b6-4179-af87-226cd68955f0",
      "environment" : {
        "id" : "02d37832-476a-431b-8a60-d77cecd7005c"
      },
      "population" : {
        "id" : "7c686ee8-a0cc-4c6f-8336-a37bb0384acd"
      },
      "username" : "Joe",
      "email" : "joe@ping.com",
      "createdAt" : "2018-05-15T19:23:25.089Z",
      "updatedAt" : "2018-05-15T19:23:25.089Z"
    }, {
      "_links" : {
        "self" : {
          "href" : "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/users/3987b40b-c4f9-4c3a-9c23-8b957c8cfced"
        },
        "password" : {
          "href" : "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/users/3987b40b-c4f9-4c3a-9c23-8b957c8cfced/password"
        },
        "password.set" : {
          "href" : "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/users/3987b40b-c4f9-4c3a-9c23-8b957c8cfced/password"
        },
        "password.reset" : {
          "href" : "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/users/3987b40b-c4f9-4c3a-9c23-8b957c8cfced/password"
        }
      },
      "id" : "3987b40b-c4f9-4c3a-9c23-8b957c8cfced",
      "environment" : {
        "id" : "02d37832-476a-431b-8a60-d77cecd7005c"
      },
      "population" : {
        "id" : "c47e0d4e-10c9-4589-9046-6652e014a786"
      },
      "username" : "ashley_graham",
      "name" : {
        "family" : "graham",
        "given" : "ashley"
      },
      "email" : "do-not-send@pingidentity.com",
      "createdAt" : "2018-06-01T19:44:21.780Z",
      "updatedAt" : "2018-06-01T19:44:21.780Z"
    } ]
  },
  "count" : 2,
  "size" : 2
}

To get data for a single user resource, the GET /environments/{environmentId}/users/{userId} operation returns data only for the user resource with the ID specified in the request URL.

curl -X GET "https://api.pingone.com/v1/environments/58f92121-b753-4e7e-8d82-23b5bf80efe5/users/2c820676-3f02-49fe-b3c6-0fd854e53d4e" \
-H "Content-type: application/json" \
-H "Authorization: Bearer jwtToken"

Add users

The following sample shows the POST /environments/{environmentId}/users operation to add a new user resource to the specified environment. This operation creates a new user but does not support an attribute to set the new user’s password. To create a user and set the password, see Import user.

curl -X "POST" "https://api.pingone.com/v1/environments/b7372995-824b-44ff-99f8-ab151dac3263/users" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d $'{
  "username": "lindajones",
  "email": "ljones@company.com",
  "population" : {
    "id" : "21731b50-6b54-41b0-8454-9cd9de62a7a1"
    }
}'

New users must be assigned to a population resource identified by its ID, and the request must set values for the username and email attributes. If successful, the response returns a 201 Successfully created message and shows the new user resource’s property data.

Note: For information about setting a user’s password after creating the new user, see Set password.

Import users

The import users operation gives privileged applications the ability to create a new user and set the user’s password. The password attribute in this operation uses the same format for specifying passwords as the set password request, allowing both cleartext and pre-encoded password values. This endpoint requires the dir:import:user permission, which is not included in the Identity Data Admin role (or any other administrator role).

The following sample shows the POST /environments/{environmentId}/users operation to import a new user resource to the specified environment. This operation uses the application/vnd.pingidentity.user.import+json custom content type in the request header.

curl -X "POST" "https://api.pingone.com/v1/environments/b7372995-824b-44ff-99f8-ab151dac3263/users" \
-H 'Content-type: application/vnd.pingidentity.user.import+json' \
-H 'Authorization: Bearer jwtToken' \
-d $'{
  "email":"angelamontero@pingidentity.com",
  "name":{  
     "given":"angela",
     "family":"montero"
  },
  "population":{  
     "id":"87972995-664b-11ff-99f8-qw341dac3667"
  },
  "username":"angelamontero",
  "password":{
     "value": "{SSHA512}UkGWfORubNKFpFBWh+Lgy4FrciclzUXneuryV+B+zBDR4Gqd5wvMqAvKRixgQWoZlZUgq8Wh40uMK3s6bWpzWt1/TqQH02hX",
     "forceChange": false
  }
 }'

New users must be assigned to a population resource identified by its ID, and the request must set values for the username and email attributes. In addition, this operation supports the password attribute, which can accept a pre-encoded password value and a forceChange value of false. If successful, the response returns a 201 Successfully created message and shows the new user resource’s property data.

Note: Pre-encoded passwords are specified by the name of the encoding scheme followed by an encoded representation of the password (as shown in the example above). Supported encoding schemes are bcrypt, scrypt, salted SHA1, salted SHA256, salted SHA384, and salted SHA512.

For more information about pre-encoded passwords, see Set password. For import operations, if a pre-encoded password is not accepted by PingOne, then it does not conform to the supported encoding schemes described in the Set password topic.

Change a user’s population

To move a user from one population to another, you need to know the user’s ID and the ID of the new population resource to associate with the user. To retrieve the list of all population IDs in a specified environment, you can call the GET /environments/{environmentId}/populations method.

The following sample shows the PUT /environments/{environmentId}/users/{userId}/population operation to associate the user with the specified population.

curl -X "PUT" "https://api.pingone.com/v1/environments/b7372995-824b-44ff-99f8-ab151dac3263/users/05ad3cc6-8723-4f85-9711-05ad549717f6/population" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d $'{
  "id": "21731b50-6b54-41b0-8454-9cd9de62a7a1"
}'

In the request body, the id attribute value is the population ID for the new population associated with the user.

Change a user’s multi-factor authentication state

When a new user resource is created, the mfaEnabled attribute that controls the user’s ability to use multi-factor authentication is set to false by default. This is a read-only attribute that cannot be changed through calls to PUT /environments/{environmentId}/users/{userId} or PATCH /environments/{environmentId}/users/{userId}. However, you can update the mfaEnabled value by calling the PUT /environments/{environmentId}/users/{userId}/mfaEnabled endpoint.

The following sample shows the PUT /environments/{environmentId}/users/{userId}/mfaEnabled operation to enable the user resource’s ability to use multi-factor authentication.

curl -X "PUT" "https://api.pingone.com/v1/environments/b7372995-824b-44ff-99f8-ab151dac3263/users/05ad3cc6-8723-4f85-9711-05ad549717f6/mfaEnabled" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d $'{
   "mfaEnabled": "true"
}'

The response returns a 200 OK message. The response data looks like this:

{
  "_links": {
    "self": {
      "href": "https://api.pingone.com/v1/environments/b7372995-824b-44ff-99f8-ab151dac3263/users/05ad3cc6-8723-4f85-9711-05ad549717f6/mfaEnabled"
    },
    "user": {
      "href": "https://api.pingone.com/v1/environments/b7372995-824b-44ff-99f8-ab151dac3263/users/05ad3cc6-8723-4f85-9711-05ad549717f6"
    }
  },
  "mfaEnabled": true
}

Enable or disable users

When a new user resource is created, the value specified for the enabled attribute determines the user’s ability to authenticate. If the enabled attribute is omitted from the POST request, the value is set to true by default.

For existing users, you can use the GET environments/{environmentId}/users/{userId}/enabled operation to check whether the specified user is enabled or disabled.

curl -X "GET" "https://api.pingone.com/v1/environments/b7372995-824b-44ff-99f8-ab151dac3263/users/05ad3cc6-8723-4f85-9711-05ad549717f6/enabled" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken'

The response data for an enabled user looks like this:

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/users/9a774ad6-b6b6-4179-af87-226cd68955f0/enabled"
        },
        "user": {
            "href": "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/users/9a774ad6-b6b6-4179-af87-226cd68955f0"
        }
    },
    "enabled": true
}

You can modify the user’s enabled attribute value by calling the PUT /environments/{environmentId}/users/{userId}/enabled endpoint.

The following sample shows the PUT environments/{environmentId}/users/{userId}/enabled operation to disable the user resource’s ability to authenticate.

curl -X "PUT" "https://api.pingone.com/v1/environments/b7372995-824b-44ff-99f8-ab151dac3263/users/05ad3cc6-8723-4f85-9711-05ad549717f6/enabled" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d $'{
  "enabled": "false"
}'

The response data with the updated setting looks like this:

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/users/9a774ad6-b6b6-4179-af87-226cd68955f0/enabled"
        },
        "user": {
            "href": "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/users/9a774ad6-b6b6-4179-af87-226cd68955f0"
        }
    },
    "enabled": false
}

Delete a user

To delete a user resource from the directory, you need to specify the environment and user IDs.

The following sample shows the DELETE /environments/{environmentId}/users/{userId} operation to remove the specified user resource from the directory.

curl -X "DELETE" "https://api.pingone.com/v1/environments/b7372995-824b-44ff-99f8-ab151dac3263/users/05ad3cc6-8723-4f85-9711-05ad549717f6" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken'

For successful delete operations, a 204 NO CONTENT message is returned by the request.