PingDS 7.5.1

HDAP and password policies

Examples in this documentation depend on features activated in the ds-evaluation setup profile. For details, refer to Learn about the evaluation setup profile.

The code samples demonstrate how to contact the server over HTTPS using the deployment CA certificate. Before trying the samples, generate the CA certificate in PEM format from the server deployment ID and password:

$ dskeymgr \
 export-ca-cert \
 --deploymentId $DEPLOYMENT_ID \
 --deploymentIdPassword password \
 --outputFile ca-cert.pem

This example demonstrates how to add a subentry password policy with HDAP. Subentry password policies are replicated.

This example uses Kirsten Vaughan as a password administrator. Kirsten is a member of the Directory Administrators group.

  1. Before trying this example, make sure the password administrator has the necessary access:

    1. Grant the subentry-write privilege to edit password policies:

      • Curl

      • JavaScript

      • Python

      • Ruby

      $ curl \
 --request PATCH \
 --cacert ca-cert.pem \
 --user uid=admin:password \
 --header 'Content-Type: application/json' \
 --data '[{
  "operation": "add",
  "field": "ds-privilege-name",
  "value": "subentry-write"
 }]' \
 'https://localhost:8443/hdap/dc=com/dc=example/ou=People/uid=kvaughan?_fields=_id,ds-privilege-name'
      (async () => {
    const { authenticate, doRequest, getOptions } = require('./utils')
    const options = getOptions({
        path: '/hdap/dc=com/dc=example/ou=People/uid=kvaughan?_fields=_id,ds-privilege-name',
        method: 'PATCH',
        credentials: 'uid=admin:password',
        body: [{
            "operation": "add",
            "field": "ds-privilege-name",
            "value": "subentry-write"
        }]
    })
    const jwt = await authenticate(options)
    options.headers['Authorization'] = 'Bearer ' + jwt
    const response = await doRequest('HDAP: assign the subentry-write privilege', options)
    console.log(response)
})().catch(error => { console.error(error) })

      Source files for this sample: pwp-subentry-write.js, utils.js

      #!/usr/bin/env python3

import requests
import utils

patch = [{
    'operation': 'add',
    'field': 'ds-privilege-name',
    'value': 'subentry-write'
}]
jwt = utils.authenticate('uid=admin', 'password')
headers = { 'Content-Type': 'application/json', 'Authorization': f'Bearer {jwt}' }
response = requests.patch(
    f'https://{utils.host}:{utils.port}/hdap/dc=com/dc=example/ou=People/uid=kvaughan',
    headers=headers,
    json=patch,
    verify=utils.ca_pem)
print('Status code: %d\nJSON: %s' % (response.status_code, response.json()))

      Source files for this sample: utils.py, pwp-subentry-write.py

      require_relative 'utils.rb'
require 'faraday'
require 'json'

utils = Utils.new('uid=admin', 'password')
options = { ca_file: utils.ca_pem }
jwt = utils.authenticate
query = { '_fields': '_id,ds-privilege-name' }
hdap = Faraday.new(url: "https://#{utils.host}:#{utils.port}/hdap/", params: query, ssl: options) do |f|
    f.headers['Content-Type'] = 'application/json'
    f.request :authorization, 'Bearer', jwt
end
body = [{
    "operation" => "add",
    "field" => "ds-privilege-name",
    "value" => "subentry-write"
}]
response = hdap.patch do |h|
    h.path = 'dc=com/dc=example/ou=People/uid=kvaughan'
    h.body = JSON.generate(body)
end

puts "Status code: #{response.status}\nJSON: #{response.body}"

      Source files for this sample: utils.rb, pwp-subentry-write.rb

      HDAP Ruby examples require Ruby 3.2 and the faraday and json gems.

    2. Grant access to manage password policies.

      • Curl

      • JavaScript

      • Python

      • Ruby

      $ curl \
 --request PATCH \
 --cacert ca-cert.pem \
 --user uid=admin:password \
 --header 'Content-Type: application/json' \
 --url 'https://localhost:8443/hdap/dc=com/dc=example?_fields=_id,aci' \
 --data @- << JSON
[{
  "operation": "add",
  "field": "aci",
  "value": "(targetattr = \"pwdPolicySubentry||ds-pwp-password-policy-dn||ds-pwp-password-validator||subtreeSpecification\")(version 3.0;acl \"Allow Administrators to manage user password policies\";allow (all) (groupdn = \"ldap:///cn=Directory Administrators,ou=Groups,dc=example,dc=com\");)"
}]
JSON
      (async () => {
    const { authenticate, doRequest, getOptions } = require('./utils')
    const options = getOptions({
        path: '/hdap/dc=com/dc=example?_fields=_id,aci',
        method: 'PATCH',
        credentials: 'uid=admin:password',
        body: [{
            "operation": "add",
            "field": "aci",
            "value": "(targetattr = \"pwdPolicySubentry||ds-pwp-password-policy-dn||ds-pwp-password-validator||subtreeSpecification\")(version 3.0;acl \"Allow Administrators to manage user password policies\";allow (all) (groupdn = \"ldap:///cn=Directory Administrators,ou=Groups,dc=example,dc=com\");)"
        }]
    })
    const jwt = await authenticate(options)
    options.headers['Authorization'] = 'Bearer ' + jwt
    const response = await doRequest('HDAP: grant access to manage password policies', options)
    console.log(response)
})().catch(error => { console.error(error) })

      Source files for this sample: pwp-admin-access.js, utils.js

      #!/usr/bin/env python3

import requests
import utils

patch = [{
    'operation': 'add',
    'field': 'aci',
    'value': '(targetattr = "pwdPolicySubentry||ds-pwp-password-policy-dn||ds-pwp-password-validator||subtreeSpecification")(version 3.0;acl "Allow Administrators to manage user password policies";allow (all) (groupdn = "ldap:///cn=Directory Administrators,ou=Groups,dc=example,dc=com");)'
}]
jwt = utils.authenticate('uid=admin', 'password')
headers = { 'Content-Type': 'application/json', 'Authorization': f'Bearer {jwt}' }
params = {'_fields': '_id,aci' }
response = requests.patch(
    f'https://{utils.host}:{utils.port}/hdap/dc=com/dc=example',
    headers=headers,
    json=patch,
    params=params,
    verify=utils.ca_pem)
print('Status code: %d\nJSON: %s' % (response.status_code, response.json()))

      Source files for this sample: utils.py, pwp-admin-access.py

      require_relative 'utils.rb'
require 'faraday'
require 'json'

utils = Utils.new('uid=admin', 'password')
options = { ca_file: utils.ca_pem }
jwt = utils.authenticate
query = { '_fields': '_id,aci' }
hdap = Faraday.new(url: "https://#{utils.host}:#{utils.port}/hdap/", params: query, ssl: options) do |f|
    f.headers['Content-Type'] = 'application/json'
    f.request :authorization, 'Bearer', jwt
end
body = [{
    "operation" => "add",
    "field" => "aci",
    "value" => "(targetattr = \"pwdPolicySubentry||ds-pwp-password-policy-dn||ds-pwp-password-validator||subtreeSpecification\")(version 3.0;acl \"Allow Administrators to manage user password policies\";allow (all) (groupdn = \"ldap:///cn=Directory Administrators,ou=Groups,dc=example,dc=com\");)"
}]
response = hdap.patch do |h|
    h.path = 'dc=com/dc=example'
    h.body = JSON.generate(body)
end

puts "Status code: #{response.status}\nJSON: #{response.body}"

      Source files for this sample: utils.rb, pwp-admin-access.rb

      HDAP Ruby examples require Ruby 3.2 and the faraday and json gems.

  2. Create and assign a subentry password policy as the password administrator:

    • Curl

    • JavaScript

    • Python

    • Ruby

    $ curl \
 --request POST \
 --cacert ca-cert.pem \
 --user dc=com/dc=example/ou=People/uid=kvaughan:bribery \
 --header 'Content-Type: application/json' \
 --url 'https://localhost:8443/hdap/dc=com/dc=example?_action=create&_fields=*,subtreeSpecification&_prettyPrint=true' \
 --data @- << JSON
{
  "_id" : "dc=com/dc=example/cn=Replicated%20password%20policy",
  "objectClass" : [ "top", "subentry", "ds-pwp-password-policy", "ds-pwp-validator", "ds-pwp-length-based-validator" ],
  "cn" : [ "Replicated password policy" ],
  "ds-pwp-default-password-storage-scheme" : [ "PBKDF2-HMAC-SHA512" ],
  "ds-pwp-length-based-min-password-length" : 8,
  "ds-pwp-password-attribute" : "userPassword",
  "subtreeSpecification": { "base": "ou=People", "filter": "/objectClass eq \"person\"" }
 }
JSON
    (async () => {
    const { authenticate, doRequest, getOptions } = require('./utils')
    const options = getOptions({
        path: '/hdap/dc=com/dc=example?_action=create&_fields=*,subtreeSpecification',
        method: 'POST',
        body: {
            "_id": "dc=com/dc=example/cn=Replicated%20password%20policy",
            "objectClass": ["top", "subentry", "ds-pwp-password-policy", "ds-pwp-validator", "ds-pwp-length-based-validator"],
            "cn": ["Replicated password policy"],
            "ds-pwp-default-password-storage-scheme": ["PBKDF2-HMAC-SHA512"],
            "ds-pwp-length-based-min-password-length": 8,
            "ds-pwp-password-attribute": "userPassword",
            "subtreeSpecification": { "base": "ou=People", "filter": "/objectClass eq \"person\"" }
        }
    })
    const jwt = await authenticate(options)
    options.headers['Authorization'] = 'Bearer ' + jwt
    const response = await doRequest('HDAP: create password policy', options)
    console.log(response)
})().catch(error => { console.error(error) })

    Source files for this sample: pwp-add-policy.js, utils.js

    #!/usr/bin/env python3

import requests
import utils

body = {
    '_id': 'dc=com/dc=example/cn=Replicated%20password%20policy',
    'objectClass': ['top', 'subentry', 'ds-pwp-password-policy', 'ds-pwp-validator', 'ds-pwp-length-based-validator'],
    'cn': ['Replicated password policy'],
    'ds-pwp-default-password-storage-scheme': ['PBKDF2-HMAC-SHA512'],
    'ds-pwp-length-based-min-password-length': 8,
    'ds-pwp-password-attribute': 'userPassword',
    'subtreeSpecification': { "base": "ou=people", "filter": "/objectClass eq \"person\"" }
}
jwt = utils.authenticate('dc=com/dc=example/ou=People/uid=kvaughan', 'bribery')
headers = { 'Content-Type': 'application/json', 'Authorization': f'Bearer {jwt}' }
params = { '_fields': '*,subtreeSpecification' }
response = requests.post(
    f'https://{utils.host}:{utils.port}/hdap/dc=com/dc=example',
    headers=headers,
    json=body,
    params=params,
    verify=utils.ca_pem)
print('Status code: %d\nJSON: %s' % (response.status_code, response.json()))

    Source files for this sample: utils.py, pwp-add-policy.py

    require_relative 'utils.rb'
require 'faraday'
require 'json'

utils = Utils.new('dc=com/dc=example/ou=People/uid=kvaughan', 'bribery')
options = { ca_file: utils.ca_pem }
jwt = utils.authenticate
query = { '_fields': '*,subtreeSpecification' }
hdap = Faraday.new(url: "https://#{utils.host}:#{utils.port}/hdap/", params: query, ssl: options) do |f|
    f.headers['Content-Type'] = 'application/json'
    f.request :authorization, 'Bearer', jwt
end
body = {
    "_id": "dc=com/dc=example/cn=Replicated%20password%20policy",
    "objectClass": ["top", "subentry", "ds-pwp-password-policy", "ds-pwp-validator", "ds-pwp-length-based-validator"],
    "cn": ["Replicated password policy"],
    "ds-pwp-default-password-storage-scheme": ["PBKDF2-HMAC-SHA512"],
    "ds-pwp-length-based-min-password-length": 8,
    "ds-pwp-password-attribute": "userPassword",
    "subtreeSpecification": { "base": "ou=People", "filter": "/objectClass eq \"person\"" }
}
response = hdap.post do |h|
    h.path = 'dc=com/dc=example'
    h.body = JSON.generate(body)
end

puts "Status code: #{response.status}\nJSON: #{response.body}"

    Source files for this sample: utils.rb, pwp-add-policy.rb

    HDAP Ruby examples require Ruby 3.2 and the faraday and json gems.

  3. Verify the password administrator can view which password policy applies:

    • Curl

    • JavaScript

    • Python

    • Ruby

    $ curl \
 --cacert ca-cert.pem \
 --user dc=com/dc=example/ou=People/uid=kvaughan:bribery \
 'https://localhost:8443/hdap/dc=com/dc=example/ou=People/uid=kvaughan?_fields=_id,pwdPolicySubentry&_prettyPrint=true'
{
  "_id" : "dc=com/dc=example/ou=People/uid=kvaughan",
  "_rev" : "<revision>",
  "pwdPolicySubentry" : "dc=com/dc=example/cn=Replicated%20password%20policy"
}
    (async () => {
    const { authenticate, doRequest, getOptions } = require('./utils')
    // Kirsten Vaughan is the password administrator in this example.
    const options = getOptions({
        path: '/hdap/dc=com/dc=example/ou=People/uid=kvaughan?_fields=_id,pwdPolicySubentry'
    })
    const jwt = await authenticate(options)
    options.headers['Authorization'] = 'Bearer ' + jwt
    const response = await doRequest('HDAP: read pwp as admin', options)
    console.log(response)
})().catch(error => { console.error(error) })

    Source files for this sample: pwp-read-pol-as-admin.js, utils.js

    #!/usr/bin/env python3

import requests
import utils

params = { '_fields': '_id,pwdPolicySubentry' }
# Kirsten Vaughan is the password administrator in this example.
jwt = utils.authenticate('dc=com/dc=example/ou=People/uid=kvaughan', 'bribery')
headers = { 'Content-Type': 'application/json', 'Authorization': f'Bearer {jwt}' }
response = requests.get(
    f'https://{utils.host}:{utils.port}/hdap/dc=com/dc=example/ou=People/uid=bjensen',
    headers=headers,
    params=params,
    verify=utils.ca_pem)
print('Status code: %d\nJSON: %s' % (response.status_code, response.json()))

    Source files for this sample: utils.py, pwp-read-pol-as-admin.py

    require_relative 'utils.rb'
require 'faraday'

# Kirsten Vaughan is the password administrator in this example.
utils = Utils.new('dc=com/dc=example/ou=People/uid=kvaughan', 'bribery')
options = { ca_file: utils.ca_pem }
jwt = utils.authenticate
fields = { "_fields": "_id,pwdPolicySubentry" }
hdap = Faraday.new(url: "https://#{utils.host}:#{utils.port}/hdap/", params: fields, ssl: options) do |f|
    f.headers['Content-Type'] = 'application/json'
    f.request :authorization, 'Bearer', jwt
end
response = hdap.get('dc=com/dc=example/ou=People/uid=bjensen')

puts "Status code: #{response.status}\nJSON: #{response.body}"

    Source files for this sample: utils.rb, pwp-read-pol-as-admin.rb

    HDAP Ruby examples require Ruby 3.2 and the faraday and json gems.

  4. Verify the field is not visible to regular users:

    • Curl

    • JavaScript

    • Python

    • Ruby

    $ curl \
 --cacert ca-cert.pem \
 --user dc=com/dc=example/ou=People/uid=bjensen:hifalutin \
 'https://localhost:8443/hdap/dc=com/dc=example/ou=People/uid=bjensen?_fields=_id,pwdPolicySubentry&_prettyPrint=true'
{
  "_id" : "dc=com/dc=example/ou=People/uid=bjensen",
  "_rev" : "<revision>"
}
    (async () => {
    const { authenticate, doRequest, getOptions } = require('./utils')
    const options = getOptions({
        path: '/hdap/dc=com/dc=example/ou=People/uid=bjensen?_fields=_id,pwdPolicySubentry',
        credentials: 'dc=com/dc=example/ou=People/uid=bjensen:hifalutin'
    })
    const jwt = await authenticate(options)
    options.headers['Authorization'] = 'Bearer ' + jwt
    const response = await doRequest('HDAP: read pwp as user', options)
    console.log(response)
})().catch(error => { console.error(error) })

    Source files for this sample: pwp-read-pol-as-user.js, utils.js

    #!/usr/bin/env python3

import requests
import utils

params = { '_fields': '_id,pwdPolicySubentry' }
jwt = utils.authenticate('dc=com/dc=example/ou=People/uid=bjensen', 'hifalutin')
headers = { 'Content-Type': 'application/json', 'Authorization': f'Bearer {jwt}' }
response = requests.get(
    f'https://{utils.host}:{utils.port}/hdap/dc=com/dc=example/ou=People/uid=bjensen',
    headers=headers,
    params=params,
    verify=utils.ca_pem)
print('Status code: %d\nJSON: %s' % (response.status_code, response.json()))

    Source files for this sample: utils.py, pwp-read-pol-as-user.py

    require_relative 'utils.rb'
require 'faraday'

utils = Utils.new('dc=com/dc=example/ou=People/uid=bjensen', 'hifalutin')
options = { ca_file: utils.ca_pem }
jwt = utils.authenticate
fields = { "_fields": "_id,pwdPolicySubentry" }
hdap = Faraday.new(url: "https://#{utils.host}:#{utils.port}/hdap/", params: fields, ssl: options) do |f|
    f.headers['Content-Type'] = 'application/json'
    f.request :authorization, 'Bearer', jwt
end
response = hdap.get('dc=com/dc=example/ou=People/uid=bjensen')

puts "Status code: #{response.status}\nJSON: #{response.body}"

    Source files for this sample: utils.rb, pwp-read-pol-as-user.rb

    HDAP Ruby examples require Ruby 3.2 and the faraday and json gems.

When listing subentry password policies, use the subentries=true parameter:

  • Curl

  • JavaScript

  • Python

  • Ruby

$ curl \
 --get \
 --cacert ca-cert.pem \
 --user uid=admin:password \
 --data "_queryFilter=/objectClass+eq+'ds-pwp-password-policy'" \
 --data '_fields=*,subtreeSpecification' \
 --data 'subentries=true' \
 --data '_prettyPrint=true' \
 'https://localhost:8443/hdap/dc=com/dc=example'
{
  "result" : [ {
    "_id" : "dc=com/dc=example/cn=Replicated%20password%20policy",
    "_rev" : "<revision>",
    "objectClass" : [ "top", "subentry", "ds-pwp-password-policy", "ds-pwp-validator", "ds-pwp-length-based-validator" ],
    "cn" : [ "Replicated password policy" ],
    "ds-pwp-default-password-storage-scheme" : [ "PBKDF2-HMAC-SHA512" ],
    "ds-pwp-length-based-min-password-length" : 8,
    "ds-pwp-password-attribute" : "userPassword",
    "subtreeSpecification" : {
      "filter" : "/objectClass eq \"person\"",
      "base" : "ou=People"
    }
  } ],
  "resultCount" : 1,
  "pagedResultsCookie" : null,
  "totalPagedResultsPolicy" : "NONE",
  "totalPagedResults" : -1,
  "remainingPagedResults" : -1
}
(async () => {
    const { authenticate, doRequest, getOptions } = require('./utils')
    const filter = "/objectClass+eq+'ds-pwp-password-policy'"
    const parameters = 'subentries=true&_fields=*,subtreeSpecification'
    const options = getOptions({
        path: `/hdap/dc=com/dc=example?_queryFilter=${filter}&${parameters}`,
        credentials: 'uid=admin:password'
    })
    const jwt = await authenticate(options)
    options.headers['Authorization'] = 'Bearer ' + jwt
    const response = await doRequest('HDAP: query subentry password policies', options)
    console.log(response)
})().catch(error => { console.error(error) })

Source files for this sample: pwp-query.js, utils.js

#!/usr/bin/env python3

import requests
import utils

params = {
    '_fields': '*,subtreeSpecification',
    '_queryFilter': '/objectClass eq "ds-pwp-password-policy"',
    'subentries': True
}
jwt = utils.authenticate('uid=admin', 'password')
headers = { 'Content-Type': 'application/json', 'Authorization': f'Bearer {jwt}' }
response = requests.get(
    f'https://{utils.host}:{utils.port}/hdap/dc=com/dc=example',
    headers=headers,
    params=params,
    verify=utils.ca_pem)
print('Status code: %d\nJSON: %s' % (response.status_code, response.json()))

Source files for this sample: utils.py, pwp-query.py

require_relative 'utils.rb'
require 'faraday'

utils = Utils.new('uid=admin', 'password')
options = { ca_file: utils.ca_pem }
jwt = utils.authenticate
query = {
    "_fields": "*,subtreeSpecification",
    "_queryFilter": "/objectClass eq 'ds-pwp-password-policy'",
    "subentries": true
}
hdap = Faraday.new(url: "https://#{utils.host}:#{utils.port}/hdap/", params: query, ssl: options) do |f|
    f.headers['Content-Type'] = 'application/json'
    f.request :authorization, 'Bearer', jwt
end
response = hdap.get('dc=com/dc=example')

puts "Status code: #{response.status}\nJSON: #{response.body}"

Source files for this sample: utils.rb, pwp-query.rb

HDAP Ruby examples require Ruby 3.2 and the faraday and json gems.

For details about policy settings, refer to DS subentry password policies.