Configuration examples

Examples in this documentation depend on features activated in the ds-evaluation setup profile.

For details, see Learn about the evaluation setup profile.

Per-server password policies

This example demonstrates how to add a per-server password policy over REST. Per-server password policies are set in the server configuration, and not replicated. You must create them on each replica.

The password policy in this example includes:

A password history setting to retain the last five password values.
The same password storage scheme as the default password policy.
The default random password generator.
The default length-based password validator.
The default dictionary password validator, which is available, but not enabled by default.

With the default password policy, a user can change their password to password. A password policy with the default dictionary validator would not allow this:

$ curl \
 --request POST \
 --cacert ca-cert.pem \
 --user bjensen:hifalutin \
 --header "Content-Type: application/json" \
 --data '{"oldPassword": "hifalutin", "newPassword": "password"}' \
 --silent \
 "https://localhost:8443/api/users/bjensen?_action=modifyPassword&dryRun=true&passwordQualityAdvice=true"

{}

Update the server configuration to enable the password policy for all Example.com users:

Enable the default dictionary password validator:

$ curl \
 --request PATCH \
 --user admin:password \
 --data '[{"operation": "replace", "field": "/enabled", "value": true}]' \
 --cacert ca-cert.pem \
 --header "Content-Type: application/json" \
 --silent \
 "https://localhost:8443/admin/config/password-validators/Dictionary"

Add the password policy:

$ curl \
 --request POST \
 --user admin:password \
 --data '{
  "_id": "Per-Server Password Policy",
  "_schema": "password-policy",
  "password-attribute": "userPassword",
  "default-password-storage-scheme": [{"_id": "PBKDF2-HMAC-SHA256"}],
  "password-generator": { "_id": "Random Password Generator" },
  "password-validator": [{"_id": "Dictionary"}, {"_id": "Length-Based Password Validator"}],
  "password-history-count": 5
 }' \
 --cacert ca-cert.pem \
 --header "Content-Type: application/json" \
 --silent \
 "https://localhost:8443/admin/config/password-policies/"

Assign the password policy to users:

The following command adds a virtual attribute that assigns the password policy to all Example.com users:

$ curl \
 --request POST \
 --user admin:password \
 --data '{
  "_id": "Password Policy Virtual Attribute",
  "_schema": "user-defined-virtual-attribute",
  "enabled": true,
  "base-dn": [ "ou=people,dc=example,dc=com" ],
  "filter": [ "(objectClass=person)" ],
  "attribute-type": "ds-pwp-password-policy-dn",
  "value": [ "cn=Per-Server Password Policy,cn=Password Policies,cn=config" ]
 }' \
 --cacert ca-cert.pem \
 --header "Content-Type: application/json" \
 --silent \
 "https://localhost:8443/admin/config/virtual-attributes/"

Check that the new policy does not let a user change their password to password:

$ curl \
 --request POST \
 --cacert ca-cert.pem \
 --user bjensen:hifalutin \
 --header "Content-Type: application/json" \
 --data '{"oldPassword": "hifalutin", "newPassword": "password"}' \
 --silent \
 "https://localhost:8443/api/users/bjensen?_action=modifyPassword&dryRun=true&passwordQualityAdvice=true"

{
  "code" : 400,
  "reason" : "Bad Request",
  "message" : "Constraint Violation: The provided new password failed the validation checks defined in the server: The provided password contained a word from the server's dictionary",
  "detail" : {
    "passwordQualityAdvice" : {
      "passingCriteria" : [ {
        "type" : "length-based",
        "parameters" : {
          "min-password-length" : 6,
          "max-password-length" : 0
        }
      } ],
      "failingCriteria" : [ {
        "type" : "dictionary",
        "parameters" : {
          "case-sensitive-validation" : false,
          "min-substring-length" : 5,
          "test-reversed-password" : true,
          "check-substrings" : true
        }
      } ]
    }
  }
}

For details on password policy settings, see Per-server password policies.

REST API documentation

API descriptors provide runtime documentation for REST APIs. Requests for API descriptors use the reserved query string parameters, _api and _crestapi. By default, DS servers do not return descriptors, but respond instead with HTTP status code 501 Not Implemented.

Although it is possible to serve the descriptors at runtime, do not use production servers for this purpose.

Instead, prepare the documentation by reading API descriptors from a server with the same API as production servers. Publish the documentation separately.

Preparing documentation for a Rest2ldap endpoint is an iterative process:

Enable API descriptors for the connection handler you use:

$ dsconfig \
 set-connection-handler-prop \
 --hostname localhost \
 --port 4444 \
 --bindDN uid=admin \
 --bindPassword password \
 --handler-name HTTPS \
 --set api-descriptor-enabled:true \
 --usePkcs12TrustStore /path/to/opendj/config/keystore \
 --trustStorePassword:file /path/to/opendj/config/keystore.pin \
 --no-prompt

Restart the connection handler to take the configuration change into account:

$ dsconfig \
 set-connection-handler-prop \
 --hostname localhost \
 --port 4444 \
 --bindDN uid=admin \
 --bindPassword password \
 --handler-name HTTPS \
 --set enabled:false \
 --usePkcs12TrustStore /path/to/opendj/config/keystore \
 --trustStorePassword:file /path/to/opendj/config/keystore.pin \
 --no-prompt

$ dsconfig \
 set-connection-handler-prop \
 --hostname localhost \
 --port 4444 \
 --bindDN uid=admin \
 --bindPassword password \
 --handler-name HTTPS \
 --set enabled:true \
 --usePkcs12TrustStore /path/to/opendj/config/keystore \
 --trustStorePassword:file /path/to/opendj/config/keystore.pin \
 --no-prompt

Configure the API.
Run a local copy of a tool for viewing OpenAPI documentation, such as Swagger UI.
View the generated documentation through the tool by reading the OpenAPI format descriptor.

For example, read the descriptor for the /api endpoint with a URL such as https://kvaughan:bribery@localhost:8443/api?_api for directory data, or https://admin:password@localhost:8443/admin?_api for the server configuration.

The following screenshot shows example documentation:

If your browser does not display the generated documentation, disable CORS settings. See your browser’s documentation or search the web for details.
Update the API configuration.

Force the Rest2ldap endpoint to reread the updated configuration file:

$ dsconfig \
 set-http-endpoint-prop \
 --hostname localhost \
 --port 4444 \
 --bindDN uid=admin \
 --bindPassword password \
 --endpoint-name "/api" \
 --set enabled:false \
 --usePkcs12TrustStore /path/to/opendj/config/keystore \
 --trustStorePassword:file /path/to/opendj/config/keystore.pin \
 --no-prompt

$ dsconfig \
 set-http-endpoint-prop \
 --hostname localhost \
 --port 4444 \
 --bindDN uid=admin \
 --bindPassword password \
 --endpoint-name "/api" \
 --set enabled:true \
 --usePkcs12TrustStore /path/to/opendj/config/keystore \
 --trustStorePassword:file /path/to/opendj/config/keystore.pin \
 --no-prompt

Edit the descriptor.
Publish the final descriptor alongside your production service.

PingDS

Configuration examples

Per-server password policies

REST API documentation