HDAP and password policies

Examples in this documentation depend on features activated in the ds-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.

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

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) })

javascript

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()))

python

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}"

ruby

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

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

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) })

javascript

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()))

python

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}"

ruby

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

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

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) })

javascript

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()))

python

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}"

ruby

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

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

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'

Show output

{
  "_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) })

javascript

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()))

python

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}"

ruby

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.

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'

Show output

{
  "_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) })

javascript

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()))

python

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}"

ruby

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'

Show output

{
  "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) })

javascript

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()))

python

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}"

ruby

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.

PingDS 8.0.0

HDAP and password policies