PingOne Platform APIs

Update Password (LDAP Gateway)

   

PUT {{apiPath}}/environments/{{envID}}/users/{{userID}}/password

Use the PUT {{apiPath}}/environments/{{envID}}/users/{{userID}}/password endpoint to configure a user to use the LDAP gateway as the password authority when the user already exists in PingOne. This operation uses the application/vnd.pingidentity.password.setGateway+json custom media type as the content type in the request header.

In the LDAP gateway configuration, the userTypes.passwordAuthority property specifies the password authority. If LDAP is the password authority, then PingOne does not migrate the password to the PingOne directory. The user’s password is removed from PingOne, and credential validation requests are sent to the LDAP directory through the LDAP gateway. The user’s password state is set as EXTERNAL. If PING_ONE is the password authority, and the user’s password is not set, then the user’s password is migrated from the LDAP directory to PingOne the next time the user signs on.

If PING_ONE is the password authority, follow this process to migrate a user password from the LDAP gateway to PingOne:

  1. Set up the password gateway configuration for the user. For more information, refer to Gateway Management and the password.external properties in User Operations.

  2. If the user already has a password set in PingOne, call this operation with an empty string ({}) in the request body to unset the user password. If the user’s password is not set, this step can be skipped.

  3. If PingOne is the password authority, on the user’s next sign on, the user’s password is migrated from the LDAP directory to PingOne.

Prerequisites

Request Model
Property Type Required?

value

String

Required

forceChange

Boolean

Required

password.external.gateway.id

String

Optional

password.external.gateway.correlationAttributes

Object

Optional

password.external.gateway.correlationAttributes.uid

String

Optional

password.external.gateway.correlationAttributes.mail

String

Optional

password.external.gateway.userType.id

String

Optional

Refer to the User operations data model for full property descriptions.

Headers

Authorization      Bearer {{accessToken}}

Content-Type      application/vnd.pingidentity.password.setGateway+json

Body

raw ( application/vnd.pingidentity.password.setGateway+json )

{
    "id": "{{gatewayID}}",
    "userType": {
        "id": "{{userTypeID}}"
    },
    "correlationAttributes": {
        "uid": "eFudd",
        "mail": "eFudd@example.com"
    }
}

Example Request

  • cURL

  • C#

  • Go

  • HTTP

  • Java

  • jQuery

  • NodeJS

  • Python

  • PHP

  • Ruby

  • Swift

curl --location --globoff --request PUT '{{apiPath}}/environments/{{envID}}/users/{{userID}}/password' \
--header 'Content-Type: application/vnd.pingidentity.password.setGateway+json' \
--header 'Authorization: Bearer {{accessToken}}' \
--data-raw '{
    "id": "{{gatewayID}}",
    "userType": {
        "id": "{{userTypeID}}"
    },
    "correlationAttributes": {
        "uid": "eFudd",
        "mail": "eFudd@example.com"
    }
}'
var options = new RestClientOptions("{{apiPath}}/environments/{{envID}}/users/{{userID}}/password")
{
  MaxTimeout = -1,
};
var client = new RestClient(options);
var request = new RestRequest("", Method.Put);
request.AddHeader("Content-Type", "application/vnd.pingidentity.password.setGateway+json");
request.AddHeader("Authorization", "Bearer {{accessToken}}");
var body = @"{" + "\n" +
@"    ""id"": ""{{gatewayID}}""," + "\n" +
@"    ""userType"": {" + "\n" +
@"        ""id"": ""{{userTypeID}}""" + "\n" +
@"    }," + "\n" +
@"    ""correlationAttributes"": {" + "\n" +
@"        ""uid"": ""eFudd""," + "\n" +
@"        ""mail"": ""eFudd@example.com""" + "\n" +
@"    }" + "\n" +
@"}";
request.AddStringBody(body, DataFormat.Json);
RestResponse response = await client.ExecuteAsync(request);
Console.WriteLine(response.Content);
package main

import (
  "fmt"
  "strings"
  "net/http"
  "io"
)

func main() {

  url := "{{apiPath}}/environments/{{envID}}/users/{{userID}}/password"
  method := "PUT"

  payload := strings.NewReader(`{
    "id": "{{gatewayID}}",
    "userType": {
        "id": "{{userTypeID}}"
    },
    "correlationAttributes": {
        "uid": "eFudd",
        "mail": "eFudd@example.com"
    }
}`)

  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, payload)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("Content-Type", "application/vnd.pingidentity.password.setGateway+json")
  req.Header.Add("Authorization", "Bearer {{accessToken}}")

  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := io.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}
PUT /environments/{{envID}}/users/{{userID}}/password HTTP/1.1
Host: {{apiPath}}
Content-Type: application/vnd.pingidentity.password.setGateway+json
Authorization: Bearer {{accessToken}}

{
    "id": "{{gatewayID}}",
    "userType": {
        "id": "{{userTypeID}}"
    },
    "correlationAttributes": {
        "uid": "eFudd",
        "mail": "eFudd@example.com"
    }
}
OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/vnd.pingidentity.password.setGateway+json");
RequestBody body = RequestBody.create(mediaType, "{\n    \"id\": \"{{gatewayID}}\",\n    \"userType\": {\n        \"id\": \"{{userTypeID}}\"\n    },\n    \"correlationAttributes\": {\n        \"uid\": \"eFudd\",\n        \"mail\": \"eFudd@example.com\"\n    }\n}");
Request request = new Request.Builder()
  .url("{{apiPath}}/environments/{{envID}}/users/{{userID}}/password")
  .method("PUT", body)
  .addHeader("Content-Type", "application/vnd.pingidentity.password.setGateway+json")
  .addHeader("Authorization", "Bearer {{accessToken}}")
  .build();
Response response = client.newCall(request).execute();
var settings = {
  "url": "{{apiPath}}/environments/{{envID}}/users/{{userID}}/password",
  "method": "PUT",
  "timeout": 0,
  "headers": {
    "Content-Type": "application/vnd.pingidentity.password.setGateway+json",
    "Authorization": "Bearer {{accessToken}}"
  },
  "data": JSON.stringify({
    "id": "{{gatewayID}}",
    "userType": {
      "id": "{{userTypeID}}"
    },
    "correlationAttributes": {
      "uid": "eFudd",
      "mail": "eFudd@example.com"
    }
  }),
};

$.ajax(settings).done(function (response) {
  console.log(response);
});
var request = require('request');
var options = {
  'method': 'PUT',
  'url': '{{apiPath}}/environments/{{envID}}/users/{{userID}}/password',
  'headers': {
    'Content-Type': 'application/vnd.pingidentity.password.setGateway+json',
    'Authorization': 'Bearer {{accessToken}}'
  },
  body: JSON.stringify({
    "id": "{{gatewayID}}",
    "userType": {
      "id": "{{userTypeID}}"
    },
    "correlationAttributes": {
      "uid": "eFudd",
      "mail": "eFudd@example.com"
    }
  })

};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});
import requests
import json

url = "{{apiPath}}/environments/{{envID}}/users/{{userID}}/password"

payload = json.dumps({
  "id": "{{gatewayID}}",
  "userType": {
    "id": "{{userTypeID}}"
  },
  "correlationAttributes": {
    "uid": "eFudd",
    "mail": "eFudd@example.com"
  }
})
headers = {
  'Content-Type': 'application/vnd.pingidentity.password.setGateway+json',
  'Authorization': 'Bearer {{accessToken}}'
}

response = requests.request("PUT", url, headers=headers, data=payload)

print(response.text)
<?php
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('{{apiPath}}/environments/{{envID}}/users/{{userID}}/password');
$request->setMethod(HTTP_Request2::METHOD_PUT);
$request->setConfig(array(
  'follow_redirects' => TRUE
));
$request->setHeader(array(
  'Content-Type' => 'application/vnd.pingidentity.password.setGateway+json',
  'Authorization' => 'Bearer {{accessToken}}'
));
$request->setBody('{\n    "id": "{{gatewayID}}",\n    "userType": {\n        "id": "{{userTypeID}}"\n    },\n    "correlationAttributes": {\n        "uid": "eFudd",\n        "mail": "eFudd@example.com"\n    }\n}');
try {
  $response = $request->send();
  if ($response->getStatus() == 200) {
    echo $response->getBody();
  }
  else {
    echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
    $response->getReasonPhrase();
  }
}
catch(HTTP_Request2_Exception $e) {
  echo 'Error: ' . $e->getMessage();
}
require "uri"
require "json"
require "net/http"

url = URI("{{apiPath}}/environments/{{envID}}/users/{{userID}}/password")

http = Net::HTTP.new(url.host, url.port);
request = Net::HTTP::Put.new(url)
request["Content-Type"] = "application/vnd.pingidentity.password.setGateway+json"
request["Authorization"] = "Bearer {{accessToken}}"
request.body = JSON.dump({
  "id": "{{gatewayID}}",
  "userType": {
    "id": "{{userTypeID}}"
  },
  "correlationAttributes": {
    "uid": "eFudd",
    "mail": "eFudd@example.com"
  }
})

response = http.request(request)
puts response.read_body
let parameters = "{\n    \"id\": \"{{gatewayID}}\",\n    \"userType\": {\n        \"id\": \"{{userTypeID}}\"\n    },\n    \"correlationAttributes\": {\n        \"uid\": \"eFudd\",\n        \"mail\": \"eFudd@example.com\"\n    }\n}"
let postData = parameters.data(using: .utf8)

var request = URLRequest(url: URL(string: "{{apiPath}}/environments/{{envID}}/users/{{userID}}/password")!,timeoutInterval: Double.infinity)
request.addValue("application/vnd.pingidentity.password.setGateway+json", forHTTPHeaderField: "Content-Type")
request.addValue("Bearer {{accessToken}}", forHTTPHeaderField: "Authorization")

request.httpMethod = "PUT"
request.httpBody = postData

let task = URLSession.shared.dataTask(with: request) { data, response, error in
  guard let data = data else {
    print(String(describing: error))
    return
  }
  print(String(data: data, encoding: .utf8)!)
}

task.resume()

Example Response

200 OK

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/users/a1dad115-5d2f-469d-9c02-de0523402995/password"
        },
        "environment": {
            "href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6"
        },
        "user": {
            "href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/users/a1dad115-5d2f-469d-9c02-de0523402995"
        },
        "passwordPolicy": {
            "href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/passwordPolicies/cd502ee4-176a-438a-a947-a4d8cffb0fdb"
        },
        "password.check": {
            "href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/users/a1dad115-5d2f-469d-9c02-de0523402995/password"
        },
        "password.reset": {
            "href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/users/a1dad115-5d2f-469d-9c02-de0523402995/password"
        },
        "password.set": {
            "href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/users/a1dad115-5d2f-469d-9c02-de0523402995/password"
        },
        "password.recover": {
            "href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/users/a1dad115-5d2f-469d-9c02-de0523402995/password"
        }
    },
    "environment": {
        "id": "abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6"
    },
    "user": {
        "id": "a1dad115-5d2f-469d-9c02-de0523402995"
    },
    "passwordPolicy": {
        "id": "cd502ee4-176a-438a-a947-a4d8cffb0fdb"
    },
    "status": "OK",
    "lastChangedAt": "2023-01-24T15:56:49.360Z",
    "warnings": {
        "expires": "2023-07-25T15:56:49.360Z"
    }
}