Configuration examples
Examples in this documentation depend on features activated in the 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"
bash -
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/"
bash -
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/"
bash
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
bash -
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
bash -
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 ashttps://kvaughan:bribery@localhost:8443/api?_api
for directory data, orhttps://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
bash -
Edit the descriptor.
-
Publish the final descriptor alongside your production service.