Administrative Roles

The server setup process creates one directory superuser account. The directory superuser has unrestricted access to manage the directory service and data.

For any directory service with more than one administrator, one account is not enough. Instead, grant appropriate access to each administrator, based on their duties.

Administrative Access

Only the directory superuser should have all the default access and privileges of that account. Directory service administrators should have limited access, as outlined in the following table:

Tasks Required Access(1) and Privileges(2)

Install and upgrade servers

Access to file system.

Access to run server commands.

Delegate administration

Access to write administration-related attributes on others' entries.

DS server privileges: config-read, config-write, modify-acl, privilege-change.

Manage server processes (start, restart, stop)

Access to run the start-ds and stop-ds commands.

DS server privileges: server-restart, server-shutdown.

Manage changes to server configuration, including global and default settings

Access to read and write to cn=config, cn=schema, and potentially other administrative DNs, such as cn=tasks.

DS server privileges: config-read, config-write, modify-acl (for global ACIs), update-schema.

Manage containers for user data, including backends and indexes

File system access for backup data and exported LDIF.

Access to create entries under cn=tasks.

DS server privileges: backend-backup, backend-restore, config-read, config-write, ldif-export, ldif-import, modify-acl (for ACIs in user data), subentry-write.

Manage changes to server schemas

Access to write to cn=schema.

File system access to add schema files.

DS server privilege: update-schema.

Manage directory server data replication

File system access to read logs/replication.

Access to read and write to cn=admin data, if any password policies configure a reversible password storage scheme.

Access to run the dsrepl command.

DS server privileges: changelog-read, config-read, data-sync.

Monitor the directory service

Access to read cn=monitor.

DS server privileges: monitor-read, jmx-notify, jmx-read, jmx-write (the last three being useful when using JMX for monitoring).

Back up and restore directory data

File system access for backup data and exported LDIF.

Access to create entries under cn=tasks.

DS server privileges: backend-backup, backend-restore, ldif-export, ldif-import.

Troubleshoot problems with the directory service

File system access to read log messages.

Write access to create entries under cn=tasks.

Access to read cn=monitor.

DS server privileges: bypass-lockdown, cancel-request, config-read, config-write (to enable debug logging, for example), disconnect-client, monitor-read, server-lockdown.

(1) Access control is covered in Access Control.

(2) Privileges are covered in Administrative Privileges.

Directory data administrators should have limited access, as outlined in the following table:

Tasks Required Access(1) and Privileges(2)

Manage changes to users, groups, and other accounts for their organizations

Access to read and write to others' entries.

Delegate administration within their organizations

Access to write administration-related attributes on others' entries.

DS server privileges: modify-acl, privilege-change.

Update administrative user data, such as subentry password policies and access controls

Access to write administration-related attributes on others' entries.

DS server privileges: modify-acl, subentry-write.

Help users who are locked out, or have forgotten or lost their password

Access to use the manage-account command.

Access to request a password modify extended operation.

Access to update passwords on user entries.

DS server privilege: password-reset.

Assist users and application developers who access the directory service

Access to read (and potentially write to) others' entries.

If performing operations on behalf of other users, access to request proxied authorization.

DS server privilege: proxied-auth.

(1) Access control is covered in Access Control.

(2) Privileges are covered in Administrative Privileges.

Administrative Accounts

Limit use of the uid=admin superuser account.

To bootstrap the system, the default directory superuser account is not subject to access control. It has privileges to perform almost every administrative operation, including increasing its own privileges.

Treat this account as you would the UNIX root account, or the Windows Administrator account. Use it only when you must.

Use a Non-Default Superuser Account

The following steps replace the directory superuser account:

  1. Create an administrator account that duplicates the default directory superuser account.

    Show details

    The default administrator account is uid=admin. It is stored in its own backend, rootUser. The rootUser LDIF backend holds the file db/rootUser.ldif.

    The following example shows the LDIF for an alternative directory superuser:

    dn: uid=altadmin
    objectClass: top
    objectClass: person
    objectClass: organizationalPerson
    objectClass: inetOrgPerson
    cn: Alternative Superuser
    givenName: Alternative
    sn: Superuser
    ds-rlim-size-limit: 0
    ds-rlim-time-limit: 0
    ds-rlim-idle-time-limit: 0
    ds-rlim-lookthrough-limit: 0
    ds-rlim-cursor-entry-limit: 100000
    ds-pwp-password-policy-dn: cn=Root Password Policy,cn=Password Policies,cn=config
    ds-privilege-name: bypass-lockdown
    ds-privilege-name: bypass-acl
    ds-privilege-name: modify-acl
    ds-privilege-name: config-read
    ds-privilege-name: config-write
    ds-privilege-name: ldif-import
    ds-privilege-name: ldif-export
    ds-privilege-name: backend-backup
    ds-privilege-name: backend-restore
    ds-privilege-name: server-lockdown
    ds-privilege-name: server-shutdown
    ds-privilege-name: server-restart
    ds-privilege-name: disconnect-client
    ds-privilege-name: cancel-request
    ds-privilege-name: password-reset
    ds-privilege-name: update-schema
    ds-privilege-name: privilege-change
    ds-privilege-name: unindexed-search
    ds-privilege-name: subentry-write
    ds-privilege-name: changelog-read
    ds-privilege-name: monitor-read
    uid: altadmin
    userPassword: password

    Do not use altadmin, since it shows up here in the documentation.

  2. Create a private backend to store the new directory superuser account.

    Show details

    The following example creates an LDIF backend to store the entry. Before creating the backend, create a separate directory to hold the backend files:

    $ mkdir /path/to/opendj/db/altRootUser
    
    $ dsconfig \
     create-backend \
     --hostname localhost \
     --port 4444 \
     --bindDN uid=admin \
     --bindPassword password \
     --backend-name altRootUser \
     --type ldif \
     --set enabled:true \
     --set base-dn:uid=altadmin \
     --set ldif-file:db/altRootUser/altRootUser.ldif \
     --set is-private-backend:true \
     --usePkcs12TrustStore /path/to/opendj/config/keystore \
     --trustStorePassword:file /path/to/opendj/config/keystore.pin \
     --no-prompt
  3. Import the new directory superuser entry into the new backend:

    Show details
    $ import-ldif \
     --hostname localhost \
     --port 4444 \
     --bindDN uid=admin \
     --bindPassword password \
     --backendID altRootUser \
     --ldifFile /tmp/alt-root.ldif \
     --usePkcs12TrustStore /path/to/opendj/config/keystore \
     --trustStorePassword:file /path/to/opendj/config/keystore.pin
  4. Remove the backend database and the unused LDIF files for the default superuser account:

    Show details
    $ dsconfig \
     delete-backend \
     --hostname localhost \
     --port 4444 \
     --bindDN uid=admin \
     --bindPassword password \
     --backend-name rootUser \
     --usePkcs12TrustStore /path/to/opendj/config/keystore \
     --trustStorePassword:file /path/to/opendj/config/keystore.pin \
     --no-prompt
    
    $ rm -rf /path/to/opendj/db/rootUser

    In this example, uid=altadmin now has the same rights as the original superuser.

  5. Repeat these steps for other DS servers.

    The account is not replicated by default.

Make Users Administrators

You can assign access and privileges to any directory account:

  1. Adjust the resource limits to as needed.

    For details, see Resource Limits.

  2. Assign any necessary administrative privileges.

    For details, see Administrative Privileges.

  3. Add any necessary ACIs.

    For details, see Access Control.

Administrative Privileges

Privileges provide access control for server administration independently from ACIs. The default directory superuser, uid=admin, is granted the privileges marked with an asterisk (*):

Privilege Description

backend-backup*

Request a task to back up data, or to purge backup files.

backend-restore*

Request a task to restore data from backup.

bypass-acl*

Perform operations without regard to ACIs.

bypass-lockdown*

Perform operations without regard to lockdown mode.

cancel-request*

Cancel any client request.

changelog-read*

Read the changelog (under cn=changelog).

config-read*

Read the server configuration.

config-write*

Change the server configuration.

data-sync

Perform data synchronization.

disconnect-client*

Close any client connection.

jmx-notify

Subscribe to JMX notifications.

jmx-read

Read JMX attribute values.

jmx-write

Write JMX attribute values.

ldif-export*

Export data to LDIF.

ldif-import*

Import data from LDIF.

modify-acl*

Change ACIs.

monitor-read*

Read metrics under cn=monitor, /metrics/api, /metrics/prometheus, and over JMX.

password-reset*

Reset other users' passwords.

privilege-change*

Change the privileges assigned to users, including their own privileges.

proxied-auth

Use the LDAP proxied authorization control.

server-lockdown*

Put the server into and take the server out of lockdown mode.

server-restart*

Request a task to restart the server.

server-shutdown*

Request a task to stop the server.

subentry-write*

Perform LDAP subentry write operations.

unindexed-search*

Search using a filter with no corresponding index.

update-schema*

Change LDAP schema definitions.

Assign Individual Account Privileges

Specify privileges as values of the ds-privilege-name operational attribute:

  1. Determine the privileges to add.

    Kirsten Vaughan has access to modify user entries. Kirsten lacks privileges to read the server configuration, and reset user passwords:

    $ ldapsearch \
     --hostname localhost \
     --port 1636 \
     --useSsl \
     --usePkcs12TrustStore /path/to/opendj/config/keystore \
     --trustStorePassword:file /path/to/opendj/config/keystore.pin \
     --bindDN "uid=kvaughan,ou=people,dc=example,dc=com" \
     --bindPassword bribery \
     --baseDN cn=config \
     "(objectclass=*)"
    
    # The LDAP search request failed: 50 (Insufficient Access Rights)
    # Additional Information:  You do not have sufficient privileges to perform search operations in the Directory Server configuration
    
    $ ldappasswordmodify \
     --hostname localhost \
     --port 1636 \
     --useSsl \
     --usePkcs12TrustStore /path/to/opendj/config/keystore \
     --trustStorePassword:file /path/to/opendj/config/keystore.pin \
     --bindDN "uid=kvaughan,ou=people,dc=example,dc=com" \
     --bindPassword bribery \
     --authzID "dn:uid=scarter,ou=People,dc=example,dc=com" \
     --newPassword chngthspwd
    
    The LDAP password modify operation failed: 50 (Insufficient Access Rights)
    Additional Information:  You do not have sufficient privileges to perform
    password reset operations
  2. Apply the change as a user with the privilege-change privilege, and give Kirsten access to read cn=config:

    $ ldapmodify \
     --hostname localhost \
     --port 1636 \
     --useSsl \
     --usePkcs12TrustStore /path/to/opendj/config/keystore \
     --trustStorePassword:file /path/to/opendj/config/keystore.pin \
     --bindDN uid=admin \
     --bindPassword password << EOF
    dn: uid=kvaughan,ou=People,dc=example,dc=com
    changetype: modify
    add: ds-privilege-name
    ds-privilege-name: config-read
    ds-privilege-name: password-reset
    EOF
    
    $ dsconfig \
     set-access-control-handler-prop \
     --hostname localhost \
     --port 4444 \
     --bindDN uid=admin \
     --bindPassword password \
     --add "global-aci:(target=\"ldap:///cn=config\")(targetattr=\"*||+\")\
    (version 3.0; acl \"Config read for Kirsten Vaughan\"; allow (read,search,compare)\
    userdn=\"ldap:///uid=kvaughan,ou=People,dc=example,dc=com\";)" \
     --usePkcs12TrustStore /path/to/opendj/config/keystore \
     --trustStorePassword:file /path/to/opendj/config/keystore.pin \
     --no-prompt

    Kirsten can perform the operations now:

    Show details
    $ ldapsearch \
     --hostname localhost \
     --port 1636 \
     --useSsl \
     --usePkcs12TrustStore /path/to/opendj/config/keystore \
     --trustStorePassword:file /path/to/opendj/config/keystore.pin \
     --bindDN "uid=kvaughan,ou=people,dc=example,dc=com" \
     --bindPassword bribery \
     --baseDN cn=config \
     "(objectclass=*)"
    
    dn: cn=config
    
    $ ldappasswordmodify \
     --hostname localhost \
     --port 1636 \
     --useSsl \
     --usePkcs12TrustStore /path/to/opendj/config/keystore \
     --trustStorePassword:file /path/to/opendj/config/keystore.pin \
     --bindDN "uid=kvaughan,ou=people,dc=example,dc=com" \
     --bindPassword bribery \
     --authzID "dn:uid=scarter,ou=People,dc=example,dc=com" \
     --newPassword chngthspwd
    
    The LDAP password modify operation was successful

Assign Group Privileges

Use a collective attribute subentry to assign privileges to a group:

  1. Create an LDAP subentry that specifies the collective attributes:

    $ ldapmodify \
     --hostname localhost \
     --port 1636 \
     --useSsl \
     --usePkcs12TrustStore /path/to/opendj/config/keystore \
     --trustStorePassword:file /path/to/opendj/config/keystore.pin \
     --bindDN uid=admin \
     --bindPassword password << EOF
    dn: cn=Administrator Privileges,dc=example,dc=com
    objectClass: collectiveAttributeSubentry
    objectClass: extensibleObject
    objectClass: subentry
    objectClass: top
    cn: Administrator Privileges
    ds-privilege-name;collective: config-read
    ds-privilege-name;collective: config-write
    ds-privilege-name;collective: ldif-export
    ds-privilege-name;collective: modify-acl
    ds-privilege-name;collective: password-reset
    ds-privilege-name;collective: proxied-auth
    subtreeSpecification: {base "ou=people", specificationFilter
      "(isMemberOf=cn=Directory Administrators,ou=Groups,dc=example,dc=com)" }
    EOF
  2. The change takes effect immediately:

    Show details
    $ ldappasswordmodify \
     --hostname localhost \
     --port 1636 \
     --useSsl \
     --usePkcs12TrustStore /path/to/opendj/config/keystore \
     --trustStorePassword:file /path/to/opendj/config/keystore.pin \
     --bindDN "uid=hmiller,ou=people,dc=example,dc=com" \
     --bindPassword hillock \
     --authzID "dn:uid=scarter,ou=People,dc=example,dc=com"
    
    The LDAP password modify operation was successful
    Generated Password:  <password>

Limit Inherited Privileges

Privileges assigned by collective attributes are inherited by every target account. To limit effective privileges, override the privilege in the account by preceding the privilege attribute value with a -.

This examples shows how to prevent Kirsten Vaughan from using the privilege to reset passwords:

  1. Check the privilege settings for the account:

    $ ldapsearch \
     --hostname localhost \
     --port 1636 \
     --useSsl \
     --usePkcs12TrustStore /path/to/opendj/config/keystore \
     --trustStorePassword:file /path/to/opendj/config/keystore.pin \
     --bindDN uid=admin \
     --bindPassword password \
     --baseDN dc=example,dc=com \
     "(uid=kvaughan)" \
     ds-privilege-name
    
    dn: uid=kvaughan,ou=People,dc=example,dc=com
    ds-privilege-name: config-read
    ds-privilege-name: password-reset
  2. Use the override to deny the privilege:

    $ ldapmodify \
     --hostname localhost \
     --port 1636 \
     --useSsl \
     --usePkcs12TrustStore /path/to/opendj/config/keystore \
     --trustStorePassword:file /path/to/opendj/config/keystore.pin \
     --bindDN uid=admin \
     --bindPassword password << EOF
    dn: uid=kvaughan,ou=people,dc=example,dc=com
    changetype: modify
    add: ds-privilege-name
    ds-privilege-name: -password-reset
    EOF
  3. The change takes effect immediately:

    Show details
    $ ldappasswordmodify \
     --hostname localhost \
     --port 1636 \
     --useSsl \
     --usePkcs12TrustStore /path/to/opendj/config/keystore \
     --trustStorePassword:file /path/to/opendj/config/keystore.pin \
     --bindDN "uid=kvaughan,ou=people,dc=example,dc=com" \
     --bindPassword bribery \
     --authzID "dn:uid=scarter,ou=People,dc=example,dc=com"
    
    The LDAP password modify operation failed: 50 (Insufficient Access Rights)
    Additional Information:  You do not have sufficient privileges to perform
    password reset operations

Identity Management

DS software lets you manage user and administrator accounts individually or in groups. If the deployment calls for provisioning and workflow capabilities, or custom tools, then consider using identity management software, such as ForgeRock Identity Management. For details, see the IDM documentation.

Simple or local deployments might require a GUI for generic or system-specific administrative operations. DS software’s support for standards like LDAP v3 makes it interoperable with many third-party tools.