Validate and simplify OpenDJ guides (#1313)
## Summary
- Validate and simplify the AsciiDoc Getting Started, Installation,
Administration, and Server Developer guides against the OpenDJ tools and
code.
- Add hands-on examples for LDAP SDK clients, REST over HTTPS, access
delegation, replication, and LDAP performance measurements.
- Correct upgrade, backend migration, plugin packaging, certificate
verification, and monitoring instructions.
## Review follow-up
- After an interrupted Docker upgrade, identify all affected DN equality
indexes using the backend configuration and effective instance schema,
including inherited matching rules. Require a valid index status and
successful offline verification for every affected index before clearing
`.upgrade-pending`. Align the Docker README and upgrade startup message
with the recovery guide, including when to restore the backup.
- Explain when Docker retries bootstrap and how to recover running and
stopped containers. Mount a named data volume in the Docker README
examples. Document how to copy an instance from a stopped container's
writable layer into a volume. If OpenDJ starts in the recovery shell,
require a successful local stop before clearing `.bootstrap-pending`.
- In the ZIP upgrade example, use `stop-ds --noPropertiesFile` and
require a successful local stop, backup, and extraction before replacing
files.
- Require a restart when changing the listen address of an active JMX
handler and use `jmx-read` in the monitoring example.
- Specify the DSML and REST to LDAP WAR context paths. For Tomcat with
`unpackWARs=false`, deploy the exploded REST gateway directory and keep
the archive outside `appBase`. Identify the SASL sample's test-only TLS
settings and document `_id` for users (`uid`) and groups (`cn`).
## Verification
- The documentation module passed `mvn verify` with the `man-pages`
profile, including 36 tests, the AsciiDoc attribute check, and 644 file
cross-references across 77 pages.
- On OpenDJ 5.2.0, exercised stopped-container recovery with its
existing volume and with data copied from the writable layer. Verified
that `stop-ds --noPropertiesFile` shut down the server in the recovery
shell before the repaired volume was attached to a replacement
container. Checked index validity and offline verification before and
after rebuilding the `owner` and inherited `myManager` DN equality
indexes.
- Exercised the ZIP failure paths and confirmed that the successful
backup archived the installation and instance data with restricted
permissions.
- On Tomcat 10.1.59 with `unpackWARs=false`, confirmed that Tomcat
selects the WAR when both artifacts are present and that deploying the
exploded directory alone exposes `config.json` as a file on disk.
- In the initial pass, checked 1,007 local links across 47 rendered
pages. Exercised the HTTPS REST and password delegation recipes with
OpenDJ 5.2.0 and 5.2.1-SNAPSHOT ZIP distributions.
- Verified both directions of the replication exercise and packaged
resources in both plugin examples.
39 files modified
1 files added
| | |
| | | a|[none] |
| | | * `backendstat` |
| | | * `create-rc-script` |
| | | * `dsjavaproperties` |
| | | * `encode-password` |
| | | * `list-backends` |
| | | * `setup` |
| | |
| | | This commands is not useful with other types of directory servers. |
| | | |
| | | a|[none] |
| | | * `make-ldif` |
| | | * `makeldif` |
| | | a|This command depends on template files. The template files can make use of configuration files installed with OpenDJ directory server under `config/MakeLDIF/`. |
| | | |
| | | The LDIF output can be used with OpenDJ and other directory servers. |
| | |
| | | * `ldapmodify` |
| | | * `ldappasswordmodify` |
| | | * `ldapsearch` |
| | | * `ldif-diff` |
| | | * `ldifdiff` |
| | | * `ldifmodify` |
| | | * `ldifsearch` |
| | | a|These commands can be used independently of OpenDJ directory server, and so are not tied to a specific version. |
| | |
| | | + |
| | | For details see xref:../reference/admin-tools-ref.adoc#dsconfig-1[dsconfig(1)] in the __Reference__. |
| | | |
| | | `dsjavaproperties`:: |
| | | Apply changes you make to `opendj/config/java.properties`, which sets Java runtime options. |
| | | |
| | | + |
| | | For details see xref:../reference/admin-tools-ref.adoc#dsjavaproperties-1[dsjavaproperties(1)] in the __Reference__. |
| | | |
| | | `dsreplication`:: |
| | | Configure data replication between directory servers to keep their contents in sync. |
| | | |
| | |
| | | + |
| | | For details see xref:../reference/admin-tools-ref.adoc#ldapsearch-1[ldapsearch(1)] in the __Reference__. |
| | | |
| | | `ldif-diff`:: |
| | | `ldifdiff`:: |
| | | Display differences between two LDIF files, with the resulting output having LDIF format. |
| | | |
| | | + |
| | | For details see xref:../reference/admin-tools-ref.adoc#ldifdiff-1[ldif-diff(1)] in the __Reference__. |
| | | For details see xref:../reference/admin-tools-ref.adoc#ldifdiff-1[ldifdiff(1)] in the __Reference__. |
| | | |
| | | `ldifmodify`:: |
| | | Similar to the `ldapmodify` command, modify specified attribute values for specified entries in an LDIF file. |
| | |
| | | + |
| | | For details see xref:../reference/admin-tools-ref.adoc#list-backends-1[list-backends(1)] in the __Reference__. |
| | | |
| | | `make-ldif`:: |
| | | `makeldif`:: |
| | | Generate directory data in LDIF based on templates that define how the data should appear. |
| | | |
| | | + |
| | | The `make-ldif` command is designed to help generate test data that mimics data expected in production, but without compromising real, potentially private information. |
| | | The `makeldif` command is designed to help generate test data that mimics data expected in production, but without compromising real, potentially private information. |
| | | |
| | | + |
| | | For details see xref:../reference/admin-tools-ref.adoc#makeldif-1[makeldif(1)] in the __Reference__. |
| | |
| | | information: "Portions copyright [year] [name of copyright owner]". |
| | | |
| | | Copyright 2017 ForgeRock AS. |
| | | Portions Copyright 2024 3A Systems LLC. |
| | | Portions Copyright 2024-2026 3A Systems, LLC. |
| | | //// |
| | | |
| | | :figure-caption!: |
| | |
| | | :table-caption!: |
| | | |
| | | |
| | | ifndef::env-site[] |
| | | [#chap-backup-restore] |
| | | endif::[] |
| | | == Backing Up and Restoring Data |
| | | |
| | | ifdef::env-site[] |
| | | anchor:chap-backup-restore[] |
| | | endif::[] |
| | | |
| | | This chapter covers management of directory data backup archives. For information on managing directory data in an interoperable format that is portable between directory server products, see xref:chap-import-export.adoc#chap-import-export["Managing Directory Data"] instead. In this chapter you will learn to: |
| | | |
| | | * Create backup archives |
| | |
| | | :table-caption!: |
| | | |
| | | |
| | | ifndef::env-site[] |
| | | [#chap-change-certs] |
| | | endif::[] |
| | | == Changing Server Certificates |
| | | |
| | | ifdef::env-site[] |
| | | anchor:chap-change-certs[] |
| | | endif::[] |
| | | |
| | | This chapter covers how to replace OpenDJ key pairs and public key certificates. In this chapter you will learn to: |
| | | |
| | | * Replace a key pair for securing a connection handler |
| | |
| | | [source, console] |
| | | ---- |
| | | $ keytool \ |
| | | -genkey \ |
| | | -genkeypair \ |
| | | -alias admin-cert \ |
| | | -keyalg RSA \ |
| | | -validity 7300 \ |
| | |
| | | -keypass `cat admin-keystore.pin` |
| | | ---- |
| | | + |
| | | Notice that the `-alias` option takes the same alias as before. This is because the `ssl-cert-nickname` for the Administration Connector is configured as `admin-cert`. Also, the `-dname` option has a CN value corresponding to the fully qualified domain name of the host where OpenDJ directory server is running. |
| | | |
| | | . Get the new key pair's certificate signed, using one of the following alternatives: |
| | | + |
| | | |
| | | * Self-sign the certificate: |
| | | + |
| | | |
| | | [source, console] |
| | | ---- |
| | | $ keytool \ |
| | | -selfcert \ |
| | | -alias admin-cert \ |
| | | -validity 7300 \ |
| | | -keystore admin-keystore \ |
| | | -storepass `cat admin-keystore.pin` |
| | | ---- |
| | | |
| | | * Create a certificate signing request, have it signed by a CA, and import the signed certificate from the CA reply. |
| | | + |
| | | For examples of the `keytool` commands to use, see xref:chap-connection-handlers.adoc#new-ca-signed-cert["To Request and Install a CA-Signed Certificate"]. |
| | | |
| | | Keep the configured alias, `admin-cert`, and set the server DNS name in `-ext`. The generated certificate is self-signed. To use a CA-signed certificate, follow the signing and import steps in xref:chap-connection-handlers.adoc#new-ca-signed-cert[Request and Install a CA-Signed Certificate] with the same alias and DNS name. |
| | | |
| | | . Export a copy of the certificate from the keystore: |
| | | + |
| | |
| | | :table-caption!: |
| | | |
| | | |
| | | ifndef::env-site[] |
| | | [#chap-connection-handlers] |
| | | endif::[] |
| | | == Configuring Connection Handlers |
| | | |
| | | ifdef::env-site[] |
| | | anchor:chap-connection-handlers[] |
| | | endif::[] |
| | | |
| | | This chapter shows you how to configure OpenDJ directory server to listen for directory client requests using connection handlers. You can view information about connection handlers in the OpenDJ control panel, and update the configuration using the `dsconfig` command, described in xref:../reference/admin-tools-ref.adoc#dsconfig-1[dsconfig(1)] in the __Reference__. |
| | | In this chapter you will learn to: |
| | | |
| | |
| | | |
| | | . Generate the server private key and public key certificate by using the Java `keytool` command. |
| | | + |
| | | The FQDN for OpenDJ directory server, which you can see under Server Details in the OpenDJ control panel, is set both as a `DNSName` in the certificate's `SubjectAlternativeName` list, and also in the CN of the certificate's subject name DN for backwards compatibility: |
| | | Set the server DNS name in the Subject Alternative Name extension and in the subject CN. |
| | | + |
| | | |
| | | [source, console] |
| | | ---- |
| | | $ keytool \ |
| | | -genkey \ |
| | | -genkeypair \ |
| | | -alias server-cert \ |
| | | -keyalg rsa \ |
| | | -ext "san=dns:opendj.example.com" \ |
| | | -dname "CN=opendj.example.com,O=Example Corp,C=FR" \ |
| | | -keystore /path/to/opendj/config/keystore \ |
| | | -storetype JKS \ |
| | | -storepass changeit \ |
| | | -keypass changeit |
| | | ---- |
| | |
| | | Notice that the `-storepass` and `-keypass` options take identical password arguments. OpenDJ requires that you use the same password to protect both the keystore and the private key. |
| | | ====== |
| | | + |
| | | If the server can respond on multiple FQDNs, then specify multiple subject alternative names when using the `keytool` command's `-ext` option. In the following example the primary FQDN is `opendj.example.com` and the alternative is `ldap.example.com`: |
| | | + |
| | | For multiple names, use a comma-separated list such as `-ext "san=dns:opendj.example.com,dns:ldap.example.com"`. |
| | | |
| | | [source, console] |
| | | ---- |
| | | $ keytool \ |
| | | -genkey \ |
| | | -alias server-cert \ |
| | | -keyalg rsa \ |
| | | -ext "san=dns:opendj.example.com,dns:ldap.example.com" \ |
| | | -dname "CN=opendj.example.com,O=Example Corp,C=FR" \ |
| | | -keystore /path/to/opendj/config/keystore \ |
| | | -storepass changeit \ |
| | | -keypass changeit |
| | | ---- |
| | | |
| | | . Create a certificate signing request file for the certificate you generated: |
| | | . Create a certificate signing request with the same DNS names you used when generating the key pair: |
| | | + |
| | | |
| | | [source, console] |
| | |
| | | $ keytool \ |
| | | -certreq \ |
| | | -alias server-cert \ |
| | | -ext "san=dns:opendj.example.com" \ |
| | | -keystore /path/to/opendj/config/keystore \ |
| | | -storepass changeit \ |
| | | -file server-cert.csr |
| | | ---- |
| | | |
| | | . Have the CA sign the request (`server-cert.csr`). |
| | | + |
| | | See the instructions from your CA on how to provide the request. |
| | | + |
| | | The CA returns the signed certificate. |
| | | . Submit `server-cert.csr` to your CA. Check that the signed certificate includes the requested DNS names. |
| | | |
| | | . If you have set up your own CA and signed the certificate, or are using a CA whose signing certificate is not included in the Java runtime environment, import the CA certificate into the keystore so that it can be trusted. |
| | | + |
| | |
| | | [#tls-protocols-cipher-suites] |
| | | === TLS Protocols and Cipher Suites |
| | | |
| | | By default OpenDJ supports the SSL and TLS protocols and the cipher suites supported by the underlying Java virtual machine. For details see the documentation for the Java virtual machine (JVM) in which you run OpenDJ. For Oracle Java, see the __Java Cryptography Architecture Oracle Providers Documentation__ for the link:http://docs.oracle.com/javase/7/docs/technotes/guides/security/SunProviders.html#SunJSSEProvider[The SunJSSE Provider, window=\_blank]. |
| | | |
| | | To list the available protocols and cipher suites, read the `supportedTLSProtocols` and `supportedTLSCiphers` attributes of the root DSE. Install unlimited strength Java cryptography extensions for stronger ciphers: |
| | | OpenDJ uses the TLS protocols and cipher suites enabled by the Java runtime. Query the listener's root DSE to see its current settings. Use a client that xref:#setup-server-cert[trusts the server certificate]. |
| | | |
| | | [source, console] |
| | | ---- |
| | | $ ldapsearch --port 1389 --baseDN "" --searchScope base "(objectclass=*)" \ |
| | | $ ldapsearch --hostname opendj.example.com --port 1636 --useSSL \ |
| | | --baseDN "" --searchScope base "(objectclass=*)" \ |
| | | supportedTLSCiphers supportedTLSProtocols |
| | | dn: |
| | | supportedTLSCiphers: TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 |
| | | supportedTLSCiphers: TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 |
| | | supportedTLSCiphers: TLS_RSA_WITH_AES_128_CBC_SHA256 |
| | | supportedTLSCiphers: TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256 |
| | | supportedTLSCiphers: TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256 |
| | | supportedTLSCiphers: TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 |
| | | supportedTLSCiphers: TLS_DHE_DSS_WITH_AES_128_CBC_SHA256 |
| | | supportedTLSCiphers: TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA |
| | | supportedTLSCiphers: TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA |
| | | supportedTLSCiphers: TLS_RSA_WITH_AES_128_CBC_SHA |
| | | supportedTLSCiphers: TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA |
| | | supportedTLSCiphers: TLS_ECDH_RSA_WITH_AES_128_CBC_SHA |
| | | supportedTLSCiphers: TLS_DHE_RSA_WITH_AES_128_CBC_SHA |
| | | supportedTLSCiphers: TLS_DHE_DSS_WITH_AES_128_CBC_SHA |
| | | supportedTLSCiphers: TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 |
| | | supportedTLSCiphers: TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 |
| | | supportedTLSCiphers: TLS_RSA_WITH_AES_128_GCM_SHA256 |
| | | supportedTLSCiphers: TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256 |
| | | supportedTLSCiphers: TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256 |
| | | supportedTLSCiphers: TLS_DHE_RSA_WITH_AES_128_GCM_SHA256 |
| | | supportedTLSCiphers: TLS_DHE_DSS_WITH_AES_128_GCM_SHA256 |
| | | supportedTLSCiphers: TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA |
| | | supportedTLSCiphers: TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA |
| | | supportedTLSCiphers: SSL_RSA_WITH_3DES_EDE_CBC_SHA |
| | | supportedTLSCiphers: TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA |
| | | supportedTLSCiphers: TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA |
| | | supportedTLSCiphers: SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA |
| | | supportedTLSCiphers: SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA |
| | | supportedTLSCiphers: TLS_EMPTY_RENEGOTIATION_INFO_SCSV |
| | | supportedTLSProtocols: SSLv2Hello |
| | | supportedTLSProtocols: TLSv1 |
| | | supportedTLSProtocols: TLSv1.1 |
| | | supportedTLSCiphers: TLS_AES_128_GCM_SHA256 |
| | | supportedTLSCiphers: TLS_AES_256_GCM_SHA384 |
| | | ... |
| | | supportedTLSProtocols: TLSv1.2 |
| | | supportedTLSProtocols: TLSv1.3 |
| | | ---- |
| | | You can restrict the list of protocols and cipher suites used by setting the `ssl-protocol` and `ssl-cipher-suite` connection handler properties to include only the protocols or cipher suites you want. |
| | | |
| | | For example, to restrict the cipher suites to `TLS_EMPTY_RENEGOTIATION_INFO_SCSV` and `TLS_RSA_WITH_AES_256_CBC_SHA` use the `dsconfig set-connection-handler-prop` command as shown in the following example: |
| | | To limit the LDAPS listener to TLS 1.2 and 1.3, set both values in one command. |
| | | |
| | | [source, console] |
| | | ---- |
| | |
| | | --bindDN "cn=Directory Manager" \ |
| | | --bindPassword password \ |
| | | --handler-name "LDAPS Connection Handler" \ |
| | | --add ssl-cipher-suite:TLS_EMPTY_RENEGOTIATION_INFO_SCSV \ |
| | | --add ssl-cipher-suite:TLS_RSA_WITH_AES_256_CBC_SHA \ |
| | | --set ssl-protocol:TLSv1.2 \ |
| | | --set ssl-protocol:TLSv1.3 \ |
| | | --no-prompt \ |
| | | --trustAll |
| | | ---- |
| | | To restrict cipher suites, use one `--set ssl-cipher-suite:<suite>` per suite. Repeat the root DSE search to verify the settings. |
| | | |
| | | |
| | | [#client-cert-validation] |
| | |
| | | [#ldif-access] |
| | | === LDIF File Access |
| | | |
| | | The LDIF connection handler lets you make changes to directory data by placing LDIF in a file system directory that OpenDJ server regularly polls for changes. The LDIF, once consumed, is deleted. |
| | | |
| | | You configure LDIF file access by using the command-line tool `dsconfig`. |
| | | The LDIF connection handler runs change records from `.ldif` files as internal operations. Give write access to the server account and trusted data loaders. Check the `.applied.*` file for results. The handler removes processed input files or renames them with `.errors-encountered.*` after a parsing or I/O error. |
| | | |
| | | [#setup-ldif-access] |
| | | .To Set Up LDIF File Access |
| | | ==== |
| | | |
| | | . Create the default input directory under the server instance. |
| | | + |
| | | |
| | | [source, console] |
| | | ---- |
| | | $ mkdir /path/to/opendj/config/auto-process-ldif |
| | | ---- |
| | | |
| | | . Activate LDIF file access: |
| | | + |
| | | |
| | |
| | | + |
| | | The change takes effect immediately. |
| | | |
| | | . Add the directory where you put LDIF to be processed: |
| | | + |
| | | |
| | | [source, console] |
| | | ---- |
| | | $ mkdir /path/to/opendj/config/auto-process-ldif |
| | | ---- |
| | | + |
| | | This example uses the default value of the `ldif-directory` property for the LDIF connection handler. |
| | | |
| | | ==== |
| | | |
| | | |
| | |
| | | :table-caption!: |
| | | |
| | | |
| | | ifndef::env-site[] |
| | | [#chap-import-export] |
| | | endif::[] |
| | | == Managing Directory Data |
| | | |
| | | ifdef::env-site[] |
| | | anchor:chap-import-export[] |
| | | endif::[] |
| | | |
| | | This chapter covers management of LDAP Data Interchange Format (LDIF) data. In this chapter you will learn to: |
| | | |
| | | * Generate test LDIF data |
| | |
| | | [#generating-ldif] |
| | | === Generating Test Data |
| | | |
| | | When you install OpenDJ, you have the option of importing sample data that is generated during the installation. This procedure demonstrates how to generate LDIF by using the `make-ldif` command, described in xref:../reference/admin-tools-ref.adoc#makeldif-1[makeldif(1)] in the __Reference__. |
| | | |
| | | [#generate-ldif] |
| | | .To Generate Test LDIF Data |
| | | ==== |
| | | The `make-ldif` command uses templates to provide sample data. Default templates are located in the `/path/to/opendj/config/MakeLDIF/` directory. The `example.template` file can be used to create a suffix with entries of the type `inetOrgPerson`. You can do the equivalent in OpenDJ control panel (Directory Data > New Base DN... > Import Automatically Generated Example Data). |
| | | |
| | | . Write a file to act as the template for your generated LDIF. |
| | | + |
| | | The resulting test data template depends on what data you expect to encounter in production. Base your work on your knowledge of the production data, and on the sample template, `/path/to/opendj/config/MakeLDIF/example.template`, and associated data. |
| | | + |
| | | See xref:../reference/admin-tools-ref.adoc#makeldif-template-5[make-ldif.template(5)] in the __Reference__ for reference information about template files. |
| | | |
| | | . Create additional data files for the content in your template to be selected randomly from a file, rather than generated by an expression. |
| | | + |
| | | Additional data files are located in the same directory as your template file. |
| | | |
| | | . Decide whether you want to generate the same test data each time you run the `make-ldif` command with your template. |
| | | + |
| | | If so, provide the same `randomSeed` integer each time you run the command. |
| | | |
| | | . Before generating a very large LDIF file, make sure you have enough space on disk. |
| | | |
| | | . Run the `make-ldif` command to generate your LDIF file: |
| | | + |
| | | Use the bundled template to generate 10,002 entries under `dc=example,dc=org`. Keep the same `--randomSeed` to reproduce the data. |
| | | |
| | | [source, console] |
| | | ---- |
| | | $ make-ldif \ |
| | | $ makeldif \ |
| | | --randomSeed 0 \ |
| | | --templateFile /path/to/my.template \ |
| | | --ldifFile /path/to/generated.ldif |
| | | Processed 1000 entries |
| | | Processed 2000 entries |
| | | ... |
| | | Processed 10000 entries |
| | | LDIF processing complete. 10003 entries written |
| | | --constant suffix=dc=example,dc=org \ |
| | | --outputLDIF generated.ldif \ |
| | | /path/to/opendj/config/MakeLDIF/example.template |
| | | ---- |
| | | |
| | | To generate other data, pass a custom template. See xref:../reference/admin-tools-ref.adoc#makeldif-template-5[makeldif-template(5)] for template syntax and xref:../reference/admin-tools-ref.adoc#makeldif-1[makeldif(1)] for command options. |
| | | |
| | | In OpenDJ Control Panel, use Directory Data > New Base DN > Import Automatically Generated Example Data to generate and import sample data. |
| | | ==== |
| | | |
| | | |
| | |
| | | ---- |
| | | $ stop-ds |
| | | $ export-ldif \ |
| | | --offline |
| | | --offline \ |
| | | --includeBranch dc=example,dc=org \ |
| | | --backendID userRoot \ |
| | | --ldifFile /path/to/backup.ldif |
| | |
| | | --includeBranch dc=example,dc=org \ |
| | | --backendID userRoot \ |
| | | --ldifFile /path/to/backup.ldif \ |
| | | --start 20111221230000 \ |
| | | --trustAll |
| | | ---- |
| | | + |
| | | The `--start 20111221230000` option tells OpenDJ to start the export at 11 PM on December 21, 2012. |
| | | To schedule the export for later, add `--start` followed by a future date and time in `yyyyMMddHHmmss` format. |
| | | + |
| | | If OpenDJ is stopped at this time, then when you start OpenDJ again, the server attempts to perform the task after starting up. |
| | | |
| | |
| | | [#ldif-tools] |
| | | === Other Tools For Working With LDIF Data |
| | | |
| | | This section demonstrates the `ldifsearch`, `ldifmodify` and `ldif-diff` commands, described in xref:../reference/admin-tools-ref.adoc#ldifsearch-1[ldifsearch(1)] in the __Reference__, xref:../reference/admin-tools-ref.adoc#ldifmodify-1[ldifmodify(1)] in the __Reference__, and xref:../reference/admin-tools-ref.adoc#ldifdiff-1[ldif-diff(1)] in the __Reference__. |
| | | This section demonstrates the `ldifsearch`, `ldifmodify` and `ldifdiff` commands, described in xref:../reference/admin-tools-ref.adoc#ldifsearch-1[ldifsearch(1)] in the __Reference__, xref:../reference/admin-tools-ref.adoc#ldifmodify-1[ldifmodify(1)] in the __Reference__, and xref:../reference/admin-tools-ref.adoc#ldifdiff-1[ldifdiff(1)] in the __Reference__. |
| | | |
| | | [#ldifsearch-example] |
| | | ==== Searching in LDIF With ldifsearch |
| | |
| | | ---- |
| | | $ ldifsearch \ |
| | | --baseDN dc=example,dc=org \ |
| | | --ldifFile generated.ldif \ |
| | | generated.ldif \ |
| | | "(sn=Grenier)" \ |
| | | mobile |
| | | dn: uid=user.4630,ou=People,dc=example,dc=org |
| | | mobile: +1 728 983 6669 |
| | | ---- |
| | | The `--ldifFile ldif-file` option replaces the `--hostname` and `--port` options used to connect to an LDAP directory. Otherwise, the command syntax and LDIF output is familiar to `ldapsearch` users. |
| | | Pass the LDIF file as the first positional argument, followed by the search filter and any attributes to return. |
| | | |
| | | |
| | | [#ldifmodify-example] |
| | |
| | | |
| | | |
| | | [#ldif-diff-example] |
| | | ==== Comparing LDIF With ldif-diff |
| | | ==== Comparing LDIF With ldifdiff |
| | | |
| | | The `ldif-diff` command reports differences between two LDIF files in LDIF format: |
| | | The `ldifdiff` command reports differences between two LDIF files in LDIF format: |
| | | |
| | | [source, console] |
| | | ---- |
| | | $ ldif-diff --sourceLDIF old.ldif --targetLDIF new.ldif |
| | | $ ldifdiff generated.ldif new.ldif |
| | | dn: uid=user.0,ou=People,dc=example,dc=org |
| | | changetype: modify |
| | | add: initials |
| | | initials: AAA |
| | | - |
| | | delete: initials |
| | | initials: ASA |
| | | delete: description |
| | | description: This is the description for Aaccf Amar. |
| | | - |
| | | add: description |
| | | description: This is the new description for Aaccf Amar. |
| | | - |
| | | delete: description |
| | | description: This is the description for Aaccf Amar. |
| | | delete: initials |
| | | initials: ASA |
| | | - |
| | | add: initials |
| | | initials: AAA |
| | | - |
| | | ---- |
| | | The `ldif-diff` command reads both files into memory, and constructs tree maps to perform the comparison. The command is designed to work with small files and fragments, and can quickly run out of memory when calculating differences between large files. |
| | | `ldifdiff` exits with status 1 when entries differ and 0 when they match. It loads both files into memory, so use it for small datasets. |
| | | |
| | | |
| | | |
| | |
| | | OpenDJ directory server stores data in a __backend__. A backend is a private server repository that can be implemented in memory, as a file, or as an embedded database. |
| | | |
| | | Database backends are designed to hold large amounts of user data. OpenDJ directory server has tools for backing up and restoring database backends, as described in xref:chap-backup-restore.adoc#chap-backup-restore["Backing Up and Restoring Data"]. By default, OpenDJ directory server stores user data in a database backend named `userRoot`. |
| | | When installing the server and importing user data, and when creating a database backend, you choose the backend type. OpenDJ directory server offers a choice of JE and PDB types. |
| | | JE and PDB are embedded databases that store key-value pairs in B-trees. OpenDJ also supports xref:../how-to/jdbc-backend.adoc[JDBC], xref:../how-to/cassandra-backend.adoc[Cassandra], xref:chap-ldif-backend.adoc#chap-ldif-backend[LDIF files], and xref:chap-memory-backend.adoc#chap-memory-backend[in-memory storage]. |
| | | |
| | | These backend types are implemented using B-tree data structures. They store data as key-value pairs, which is different from the relational model exposed to clients of relational databases. JE and PDB backends differ in how they manage data on disk: |
| | | JE and PDB manage data on disk differently. |
| | | |
| | | * A JE backend stores data on disk using append-only log files with names like `number.jdb`. The JE backend writes updates to the highest-numbered log file. The log files grow until they reach a specified size (default: 100 MB). When the current log file reaches the specified size, the JE backend creates a new log file. |
| | | + |
| | |
| | | |
| | | You can create new backends using the `dsconfig create-backend` command, described in xref:../reference/dsconfig-subcommands-ref.adoc#dsconfig-create-backend[dsconfig create-backend(1)] in the __Reference__. OpenDJ directory server supports a variety of backend types, including in-memory backends, backends that store data in LDIF files, and backends that store data in key-value databases with indexes to improve performance with large data sets. When you create a backend, choose the type of backend that fits your purpose. |
| | | |
| | | The following example creates a backend named `myData`. The backend is of type `pdb`, which relies on a PDB database for data storage and indexing. Alternatively, you can choose a different backend type with a different argument to the `--type` option, as in `--type je`: |
| | | Create a PDB backend named `myData` with an unused base DN. For a JE backend, use `--type je`. |
| | | |
| | | [source, console] |
| | | ---- |
| | |
| | | branch: dc=example,dc=com |
| | | ---- |
| | | |
| | | And then use the `import-ldif` tool to import a template file as shown in the following example: |
| | | Place the template file on the server and import it into the new backend. Configure the client to xref:chap-connection-handlers.adoc#setup-server-cert[trust the administration connector's certificate] before connecting. |
| | | |
| | | [source, console] |
| | | ---- |
| | | $ /opt/opendj/bin/import-ldif \ |
| | | --templateFile base.template \ |
| | | $ import-ldif \ |
| | | --templateFile /path/to/base.template \ |
| | | --backendID myData \ |
| | | --hostname opendj.example.com \ |
| | | --port 4444 \ |
| | | --bindDN "cn=Directory Manager" \ |
| | | --bindPassword password |
| | | ---- |
| | |
| | | :table-caption!: |
| | | |
| | | |
| | | ifndef::env-site[] |
| | | [#chap-indexing] |
| | | endif::[] |
| | | == Indexing Attribute Values |
| | | |
| | | ifdef::env-site[] |
| | | anchor:chap-indexing[] |
| | | endif::[] |
| | | |
| | | This chapter covers OpenDJ indexing features used to speed up searches, and to limit the impact of searches on directory server resources. In this chapter you will learn to: |
| | | |
| | | * Define indexes and explain why they are useful |
| | |
| | | :example-caption!: |
| | | :table-caption!: |
| | | |
| | | ifndef::env-site[] |
| | | [#chap-memory-backend] |
| | | endif::[] |
| | | == Using the Memory Backend |
| | | |
| | | ifdef::env-site[] |
| | | anchor:chap-memory-backend[] |
| | | endif::[] |
| | | |
| | | The Memory backend stores directory entries only in the OpenDJ server process memory. Use it for small development datasets, isolated tests, disposable demonstrations, or temporary data that can be recreated. |
| | | |
| | | [WARNING] |
| | |
| | | information: "Portions copyright [year] [name of copyright owner]". |
| | | |
| | | Copyright 2017 ForgeRock AS. |
| | | Portions Copyright 2024-2026 3A Systems LLC. |
| | | Portions Copyright 2024-2026 3A Systems, LLC. |
| | | //// |
| | | |
| | | :figure-caption!: |
| | |
| | | |
| | | OpenDJ lets you monitor the server over SNMP with support for the Management Information Base described in link:http://tools.ietf.org/html/rfc2605[RFC 2605: Directory Server Monitoring MIB, window=\_top]. |
| | | |
| | | SNMP is not enabled by default. SNMP-based monitoring depends on OpenDMK, which you must link:https://github.com/OpenIdentityPlatform/OpenDJ/raw/master/opendj-server-legacy/opendmk/jdmkrt.jar[download separately, window=\_blank]. OpenDJ directory server that you download from GitHub is built with OpenDMK, but due to licensing OpenDMK is not part of OpenDJ. SNMP is therefore not enabled by default. |
| | | |
| | | To run the OpenDMK installer, use the self-extracting .jar: |
| | | |
| | | [source, console, subs="+attributes"] |
| | | ---- |
| | | $ java -jar ~/Downloads/opendmk-1.0-b02-*.jar |
| | | $ cd ~/Downloads/ |
| | | $ unzip opendj-{opendj-version}.zip |
| | | $ java -jar opendj/snmp/opendmk.jar |
| | | ---- |
| | | If you install under `/path/to`, then the runtime library needed for SNMP is `/path/to/OpenDMK-bin/lib/jdmkrt.jar`. |
| | | |
| | | Once you have installed OpenDMK, you can set up a connection handler for SNMP by enabling the connection handler, and pointing OpenDJ to your installation of the OpenDMK `jdmkrt.jar` library: |
| | | |
| | | [source, console] |
| | | ---- |
| | | $ dsconfig \ |
| | | set-connection-handler-prop \ |
| | | --port 4444 \ |
| | | --hostname opendj.example.com \ |
| | | --bindDN "cn=Directory Manager" \ |
| | | --bindPassword password \ |
| | | --handler-name "SNMP Connection Handler" \ |
| | | --set enabled:true \ |
| | | --set opendmk-jarfile:/path/to/OpenDMK-bin/lib/jdmkrt.jar \ |
| | | --trustAll \ |
| | | --no-prompt |
| | | ---- |
| | | By default, the SNMP connection handler listens on port 161 and uses port 162 for traps. On UNIX and Linux systems, only root can normally open these ports. Therefore if you install as a normal user, you might want to change the listen and trap ports: |
| | | The SNMP extension in the server ZIP needs the link:https://github.com/OpenIdentityPlatform/OpenDJ/raw/master/opendj-server-legacy/opendmk/jdmkrt.jar[OpenDMK runtime JAR]. Download it to a location the OpenDJ account can read, then enable SNMP on an unprivileged port. |
| | | |
| | | [source, console] |
| | | ---- |
| | |
| | | --bindPassword password \ |
| | | --handler-name "SNMP Connection Handler" \ |
| | | --set listen-port:11161 \ |
| | | --set trap-port:11162 \ |
| | | --trustAll \ |
| | | --no-prompt |
| | | ---- |
| | | Restart the SNMP connection handler to take the port number changes into account. |
| | | |
| | | To restart the connection handler, you disable it, then enable it again: |
| | | |
| | | [source, console] |
| | | ---- |
| | | $ dsconfig \ |
| | | set-connection-handler-prop \ |
| | | --port 4444 \ |
| | | --hostname opendj.example.com \ |
| | | --bindDN "cn=Directory Manager" \ |
| | | --bindPassword password \ |
| | | --handler-name "SNMP Connection Handler" \ |
| | | --set enabled:false \ |
| | | --trustAll \ |
| | | --no-prompt |
| | | |
| | | $ dsconfig \ |
| | | set-connection-handler-prop \ |
| | | --port 4444 \ |
| | | --hostname opendj.example.com \ |
| | | --bindDN "cn=Directory Manager" \ |
| | | --bindPassword password \ |
| | | --handler-name "SNMP Connection Handler" \ |
| | | --set opendmk-jarfile:/path/to/jdmkrt.jar \ |
| | | --set enabled:true \ |
| | | --trustAll \ |
| | | --no-prompt |
| | | ---- |
| | | The default listen port is 161 and the default trap destination port is 162. If you change the listen port after enabling SNMP, disable and re-enable the handler. |
| | | |
| | | Use a command such as `snmpwalk` to check that the SNMP listen port works: |
| | | |
| | | [source, console, subs="+attributes"] |
| | |
| | | [#jmx-monitoring] |
| | | === JMX-Based Monitoring |
| | | |
| | | OpenDJ provides JMX-based monitoring. A number of tools support JMX, including `jconsole` and `jvisualvm`, which are bundled with the Sun/Oracle Java platform. JMX is not configured by default. Use the `dsconfig` command to configure the JMX connection handler: |
| | | |
| | | Interface stability: Evolving (See xref:../reference/appendix-interface-stability.adoc#interface-stability["Product Interface Stability"] in the __Reference__) |
| | | |
| | | Configure the server to activate JMX access. The following example uses the reserved port number, 1689: |
| | | Enable the JMX listener on the loopback interface for local monitoring. See xref:chap-connection-handlers.adoc#jmx-access[JMX Client Access] for other connection settings. |
| | | |
| | | [source, console] |
| | | ---- |
| | | $ dsconfig \ |
| | | set-connection-handler-prop \ |
| | | --port 4444 \ |
| | | --hostname opendj.example.com \ |
| | | --hostname localhost \ |
| | | --bindDN "cn=Directory Manager" \ |
| | | --bindPassword password \ |
| | | --handler-name "JMX Connection Handler" \ |
| | | --set listen-address:127.0.0.1 \ |
| | | --set enabled:true \ |
| | | --trustAll \ |
| | | --no-prompt |
| | | ---- |
| | | Add appropriate privileges to access JMX monitoring information. By default, no users have privileges to access the JMX connection. The following commands create a user with JMX privileges, who can authenticate over an insecure connection: |
| | | |
| | | [source, console] |
| | | ---- |
| | | $ bin/dsconfig |
| | | create-password-policy |
| | | --policy-name "Allow insecure authentication" |
| | | --type password-policy |
| | | --set default-password-storage-scheme:PBKDF2-HMAC-SHA256 |
| | | --set password-attribute:userPassword |
| | | --trustAll --no-prompt |
| | | --hostname opendj.example.com |
| | | --port 4444 |
| | | --bindDN "cn=Directory Manager" |
| | | --bindPassword passwordt |
| | | ---- |
| | | If the JMX handler was already enabled when you changed its listen address, run `stop-ds --restart` before connecting. Until then, both RMI listeners keep their previous address. |
| | | |
| | | [source, console] |
| | | Create an account with the `jmx-read` privilege. This example uses a local test server with StartTLS and a self-signed certificate. |
| | | |
| | | [source,bash] |
| | | ---- |
| | | $ bin/ldapmodify --port 1389 --bindDN "cn=Directory Manager" --bindPassword password |
| | | dn: uid=JMX Monitor,dc=example,dc=com |
| | | objectClass: top |
| | | objectClass: person |
| | | objectClass: organizationalPerson |
| | | ldapmodify --hostname localhost --port 1389 --useStartTLS --trustAll \ |
| | | --bindDN "cn=Directory Manager" --bindPassword password <<'LDIF' |
| | | dn: uid=jmx-monitor,dc=example,dc=com |
| | | changetype: add |
| | | objectClass: inetOrgPerson |
| | | cn: JMX Monitor |
| | | sn: User |
| | | uid: JMX Monitor |
| | | userPassword: password |
| | | ds-privilege-name: monitor-read |
| | | ds-privilege-name: jmx-notify |
| | | sn: Monitor |
| | | uid: jmx-monitor |
| | | userPassword: sample-monitor-password |
| | | ds-privilege-name: jmx-read |
| | | ds-privilege-name: jmx-write |
| | | ds-pwp-password-policy-dn: cn=Allow insecure authentication,cn=Password Policies,cn=config |
| | | |
| | | Processing ADD request for uid=JMX Monitor,dc=example,dc=com |
| | | ADD operation successful for DN uid=JMX Monitor,dc=example,dc=com |
| | | ^C |
| | | ---- |
| | | Connect remotely. |
| | | |
| | | [source, console] |
| | | ---- |
| | | $ jconsole & |
| | | LDIF |
| | | ---- |
| | | |
| | | Remote process:: |
| | | `service:jmx:rmi:///jndi/rmi://localhost:1689/org.opends.server.protocols.jmx.client-unknown` |
| | | If your default password policy requires secure authentication, xref:chap-pwd-policy.adoc#assign-pwp[assign the monitoring account a policy] with `require-secure-authentication:false` for this loopback setup. |
| | | |
| | | Username:: |
| | | `uid=JMX Monitor,dc=example,dc=com` |
| | | On the server host, start `jconsole` and select *Remote Process*. Use `uid=jmx-monitor,dc=example,dc=com` and `sample-monitor-password` to connect to this service. |
| | | |
| | | Password:: |
| | | `password` |
| | | [source,text] |
| | | ---- |
| | | service:jmx:rmi:///jndi/rmi://127.0.0.1:1689/org.opends.server.protocols.jmx.client-unknown |
| | | ---- |
| | | |
| | | Connect:: |
| | | Insecure connection |
| | | |
| | | If prompted, allow the unencrypted loopback connection. The *MBeans* tab requires a query that the server's RMI filter rejects. To read the monitoring data, xref:#ldap-monitoring[query `cn=monitor` over LDAP]. |
| | | |
| | | |
| | | [#monitoring-status-and-tasks] |
| | |
| | | --port 4444 \ |
| | | --hostname opendj.example.com \ |
| | | --bindDN "cn=Directory Manager" \ |
| | | --bindPassword password |
| | | --bindPassword password \ |
| | | --publisher-name "Common Audit Csv File Access Logger" \ |
| | | --set tamper-evident:true \ |
| | | --set key-store-file:config/audit-keystore \ |
| | |
| | | --port 4444 \ |
| | | --hostname opendj.example.com \ |
| | | --bindDN "cn=Directory Manager" \ |
| | | --bindPassword password |
| | | --bindPassword password \ |
| | | --publisher-name "Common Audit Csv File HTTP Access Logger" \ |
| | | --set tamper-evident:true \ |
| | | --set key-store-file:config/audit-keystore \ |
| | |
| | | [#log-http-access] |
| | | ==== HTTP Access Logs |
| | | |
| | | For the HTTP Connection Handler, OpenDJ maintains a separate access log in `logs/http-access`. This access log, by default configured as the File Based HTTP Access Log Publisher, uses a different format than the LDAP access log. This HTTP access log uses link:http://www.w3.org/TR/WD-logfile.html[Extended Log File Format, window=\_blank] with fields described in link:http://www.microsoft.com/technet/prodtechnol/WindowsServer2003/Library/IIS/676400bc-8969-4aa7-851a-9319490a9bbb.mspx?mfr=true[Microsoft's implementation, window=\_blank] as well. |
| | | For the HTTP Connection Handler, OpenDJ maintains a separate access log in `logs/http-access`. This access log, by default configured as the File Based HTTP Access Log Publisher, uses a different format than the LDAP access log. This HTTP access log uses link:https://www.w3.org/TR/WD-logfile.html[Extended Log File Format, window=\_blank] with fields described in link:https://learn.microsoft.com/en-us/iis/configuration/system.applicationhost/sites/sitedefaults/logfile#attributes[Microsoft's implementation, window=\_blank] as well. |
| | | |
| | | Interface stability: Evolving (See xref:../reference/appendix-interface-stability.adoc#interface-stability["Product Interface Stability"] in the __Reference__) |
| | | -- |
| | |
| | | information: "Portions copyright [year] [name of copyright owner]". |
| | | |
| | | Copyright 2017 ForgeRock AS. |
| | | Portions Copyright 2024 3A Systems LLC. |
| | | Portions Copyright 2024-2026 3A Systems, LLC. |
| | | //// |
| | | |
| | | :figure-caption!: |
| | |
| | | --no-prompt |
| | | ---- |
| | | |
| | | . Check replication with `dsreplication status`. Before disabling replication, wait for the replica that will supply the data after the move to receive all changes from the server you are moving. If you cannot confirm convergence, resolve the replication issue before continuing. |
| | | |
| | | . Disable replication for the server: |
| | | + |
| | | |
| | |
| | | ... The Directory Server has started successfully |
| | | ---- |
| | | |
| | | . Enable and initialize replication: |
| | | . Enable replication between the existing replica (`opendj.example.com`) and the moved server (`opendj2.example.com`). |
| | | + |
| | | |
| | | [source, console] |
| | |
| | | $ dsreplication \ |
| | | enable \ |
| | | --adminUID admin \ |
| | | --bindPassword password \ |
| | | --adminPassword password \ |
| | | --baseDN dc=example,dc=com \ |
| | | --host1 opendj.example.com \ |
| | | --port1 4444 \ |
| | |
| | | --trustAll \ |
| | | --no-prompt |
| | | |
| | | Establishing connections ..... Done. |
| | | Checking registration information ..... Done. |
| | | Configuring Replication port on server opendj.example.com:4444 ..... Done. |
| | | Updating remote references on server opendj2.example.com:4444 ..... Done. |
| | | Updating replication configuration for baseDN dc=example,dc=com on server |
| | | opendj.example.com:4444 ..... Done. |
| | | Updating replication configuration for baseDN dc=example,dc=com on server |
| | | opendj2.example.com:4444 ..... Done. |
| | | Updating registration configuration on server |
| | | opendj.example.com:4444 ..... Done. |
| | | Updating registration configuration on server |
| | | opendj2.example.com:4444 ..... Done. |
| | | Updating replication configuration for baseDN cn=schema on server |
| | | opendj.example.com:4444 ..... Done. |
| | | Updating replication configuration for baseDN cn=schema on server |
| | | opendj2.example.com:4444 ..... Done. |
| | | Initializing registration information on server opendj.example.com:4444 with |
| | | the contents of server opendj2.example.com:4444 ..... Done. |
| | | Initializing schema on server opendj2.example.com:4444 with the contents of |
| | | server opendj.example.com:4444 ..... Done. |
| | | Replication has been successfully enabled. |
| | | |
| | | Replication has been successfully enabled. Note that for replication to work |
| | | you must initialize the contents of the base DN's that are being replicated |
| | | (use dsreplication initialize to do so). |
| | | |
| | | See /tmp/opends-replication-1476402020764482023.log for a detailed log of this |
| | | operation. |
| | | |
| | | $ dsreplication \ |
| | | pre-external-initialization \ |
| | | --adminUID admin \ |
| | | --bindPassword password \ |
| | | --port 4444 \ |
| | | --baseDN dc=example,dc=com \ |
| | | --trustAll \ |
| | | --no-prompt |
| | | |
| | | Preparing base DN dc=example,dc=com to be initialized externally ..... Done. |
| | | |
| | | Now you can proceed to the initialization of the contents of the base DN's on |
| | | all the replicated servers. You can use the command import-ldif or the binary |
| | | copy to do so. You must use the same LDIF file or binary copy on each server. |
| | | |
| | | When the initialization is completed you must use the subcommand |
| | | 'post-external-initialization' for replication to work with the new base DN's |
| | | contents. |
| | | |
| | | $ dsreplication \ |
| | | post-external-initialization \ |
| | | --adminUID admin \ |
| | | --bindPassword password \ |
| | | --port 4444 \ |
| | | --baseDN dc=example,dc=com \ |
| | | --trustAll \ |
| | | --no-prompt |
| | | |
| | | Updating replication information on base DN dc=example,dc=com ..... Done. |
| | | |
| | | Post initialization procedure completed successfully. |
| | | ---- |
| | | |
| | | . Accept updates from client applications: |
| | | . Initialize the moved server from the existing replica. This replaces the moved server's data. |
| | | + |
| | | |
| | | [source, console] |
| | | ---- |
| | | $ dsreplication \ |
| | | initialize \ |
| | | --adminUID admin \ |
| | | --adminPassword password \ |
| | | --baseDN dc=example,dc=com \ |
| | | --hostSource opendj.example.com \ |
| | | --portSource 4444 \ |
| | | --hostDestination opendj2.example.com \ |
| | | --portDestination 4444 \ |
| | | --trustAll \ |
| | | --no-prompt |
| | | ---- |
| | | + |
| | | Check both replicas with `dsreplication status`. |
| | | |
| | | . Allow the moved server to accept updates from client applications: |
| | | + |
| | | |
| | | [source, console] |
| | |
| | | $ dsconfig \ |
| | | set-global-configuration-prop \ |
| | | --port 4444 \ |
| | | --hostname opendj.example.com \ |
| | | --hostname opendj2.example.com \ |
| | | --bindDN "cn=Directory Manager" \ |
| | | --bindPassword password \ |
| | | --set writability-mode:enabled \ |
| | |
| | | information: "Portions copyright [year] [name of copyright owner]". |
| | | |
| | | Copyright 2017 ForgeRock AS. |
| | | Portions Copyright 2024 3A Systems LLC. |
| | | Portions Copyright 2024-2026 3A Systems, LLC. |
| | | //// |
| | | |
| | | :figure-caption!: |
| | |
| | | :table-caption!: |
| | | |
| | | |
| | | ifndef::env-site[] |
| | | [#chap-privileges-acis] |
| | | endif::[] |
| | | == Configuring Privileges and Access Control |
| | | |
| | | ifdef::env-site[] |
| | | anchor:chap-privileges-acis[] |
| | | endif::[] |
| | | |
| | | OpenDJ supports two mechanisms to protect access to the directory, __access control instructions__ and administrative __privileges__. Access control instructions apply to directory data, providing fine-grained control over what a user or group member is authorized to do in terms of LDAP operations. Most access control instructions specify scopes (targets) to which they apply such that an administrative user who has all access to `dc=example,dc=com` need not have any access to `dc=example,dc=org`. Privileges control the administrative tasks that users can perform, such as bypassing the access control mechanism, performing backup and restore operations, making changes to the configuration, and other tasks. |
| | | |
| | | Privileges are implemented independently from access control. By default, privileges restrict administrative access to directory root users, though any user can be assigned a privilege. Privileges apply to a directory server, and do not have a scope. This chapter covers both access control and privileges. In this chapter you will learn to: |
| | |
| | | [#configure-acis] |
| | | === Configuring Access Control |
| | | |
| | | Access control instructions are defined in the data as values for `aci` attributes. They can be imported in LDIF and modified over LDAP. Yet in order to make changes to ACIs users first need the `modify-acl` privilege described previously. By default, only the root DN user has the `modify-acl` privilege. |
| | | Access control instructions are defined in the data as values for `aci` attributes. They can be imported in LDIF and modified over LDAP. To change an ACI on a directory entry, an account needs both the `modify-acl` privilege and permission to write that entry's `aci` attribute. By default, the root DN user has the privilege and can bypass access checks. |
| | | |
| | | Global ACIs on `cn=Access Control Handler,cn=config` can be set using the `dsconfig` command. Global ACIs have attribute type `ds-cfg-global-aci`. For a list, see xref:#table-global-acis["Default Global ACIs"]. |
| | | You can modify global ACIs from the Access Control Handler menu in `dsconfig`. Modifying and removing global ACIs can have deleterious effects. Generally the impact depends on your deployment requirements. |
| | |
| | | a|Anonymous and authenticated users can read LDAP schema definitions. Modification or removal may affect applications. |
| | | a|`(target="ldap:///cn=schema")(targetscope="base")(targetattr="objectClass\|\|attributeTypes\|\|dITContentRules\|\|dITStructureRules\|\|ldapSyntaxes\|\|matchingRules\|\|matchingRuleUse\|\|nameForms\|\|objectClasses")(version 3.0; acl "User-Visible Schema Operational Attributes"; allow (read,search,compare) userdn="ldap:///anyone";)` |
| | | |=== |
| | | Users with write access to add ACIs and with the `modify-acl` privilege can use the `ldapmodify` command to change ACIs located in user data. |
| | | The default `User-Visible Operational Attributes` ACI lets clients read `subschemaSubentry` on entries they can read. That attribute points to the entry that publishes their schema. See xref:chap-schema.adoc#about-schema[About Directory Schema]. |
| | | |
| | | This section therefore focuses on ACI examples, rather than demonstrating how to update the directory for each example. To update ACIs, either change them using the `ldapmodify` command, or using OpenDJ control panel. |
| | | |
| | |
| | | [#access-control-anonymous-reads] |
| | | .ACI: Anonymous Reads and Searches |
| | | ==== |
| | | This works when the only attributes you do not want world-readable are password attributes: |
| | | This example exposes user attributes other than passwords. The global `reject-unauthenticated-requests` setting must be `false`, the default. |
| | | |
| | | [source, ldif] |
| | | ---- |
| | |
| | | ==== |
| | | |
| | | |
| | | [#aci-local-exercise] |
| | | === Try Delegating Access Control |
| | | |
| | | Use a disposable server with base entry `dc=example,dc=com` and LDAPS on port 1636. Run the commands in Bash from the OpenDJ installation directory. Replace the example administrator password with the password you chose at setup. The `--trustAll` option is for the local test certificate. |
| | | |
| | | Create a test branch and two accounts. The editor can change ACIs in this branch because the account has `modify-acl` and the branch ACI permits writes to `aci`. This lets the editor grant access to data in the branch. |
| | | |
| | | [source,bash] |
| | | ---- |
| | | bin/ldapmodify --hostname localhost --port 1636 --useSSL --trustAll \ |
| | | --bindDN 'cn=Directory Manager' --bindPassword password <<'LDIF' |
| | | dn: ou=Workshop,dc=example,dc=com |
| | | changetype: add |
| | | objectClass: organizationalUnit |
| | | ou: Workshop |
| | | aci: (targetattr="aci")(version 3.0; acl "Workshop access editor"; |
| | | allow (write) userdn="ldap:///uid=access-editor,ou=Workshop,dc=example,dc=com";) |
| | | |
| | | dn: uid=access-editor,ou=Workshop,dc=example,dc=com |
| | | changetype: add |
| | | objectClass: inetOrgPerson |
| | | uid: access-editor |
| | | cn: Workshop Editor |
| | | sn: Editor |
| | | userPassword: workshop-editor-password |
| | | ds-privilege-name: modify-acl |
| | | |
| | | dn: uid=member,ou=Workshop,dc=example,dc=com |
| | | changetype: add |
| | | objectClass: inetOrgPerson |
| | | uid: member |
| | | cn: Workshop Member |
| | | sn: Member |
| | | userPassword: workshop-member-password |
| | | LDIF |
| | | ---- |
| | | |
| | | Try adding a title as the member. On a fresh OpenDJ configuration, this operation fails with `Insufficient Access Rights`. |
| | | |
| | | [source,bash] |
| | | ---- |
| | | bin/ldapmodify --hostname localhost --port 1636 --useSSL --trustAll \ |
| | | --bindDN 'uid=member,ou=Workshop,dc=example,dc=com' \ |
| | | --bindPassword workshop-member-password <<'LDIF' |
| | | dn: uid=member,ou=Workshop,dc=example,dc=com |
| | | changetype: modify |
| | | replace: title |
| | | title: Workshop participant |
| | | LDIF |
| | | ---- |
| | | |
| | | Now bind as the editor and add a rule that lets users change their own title within the branch. |
| | | |
| | | [source,bash] |
| | | ---- |
| | | bin/ldapmodify --hostname localhost --port 1636 --useSSL --trustAll \ |
| | | --bindDN 'uid=access-editor,ou=Workshop,dc=example,dc=com' \ |
| | | --bindPassword workshop-editor-password <<'LDIF' |
| | | dn: ou=Workshop,dc=example,dc=com |
| | | changetype: modify |
| | | add: aci |
| | | aci: (targetattr="title")(version 3.0; acl "Edit your workshop title"; |
| | | allow (write) userdn="ldap:///self";) |
| | | LDIF |
| | | ---- |
| | | |
| | | Repeat the member's title change. It should succeed. Use xref:#get-effective-rights[Viewing Effective Rights] to inspect the permissions for a specific user. |
| | | |
| | | |
| | | [#get-effective-rights] |
| | | === Viewing Effective Rights |
| | | |
| | |
| | | |
| | | Make sure that your operational plans provide for deploying Java security updates to systems where you run OpenDJ software. |
| | | |
| | | After you update the Java runtime environment, edit the `default.java-home` setting in the file `/path/to/opendj/config/java.properties` to use the path to the update release, and then use the `dsjavaproperties` command for the changes to be taken into account. Then restart OpenDJ directory server. For details see xref:../reference/admin-tools-ref.adoc#dsjavaproperties-1[dsjavaproperties(1)] in the __Reference__. |
| | | After updating Java, change the setting the server uses to find Java and restart it. Update `default.java-home` or `start-ds.java-home` in `config/java.properties`, or update `OPENDJ_JAVA_HOME` or `OPENDJ_JAVA_BIN` if your startup environment sets it. |
| | | |
| | | |
| | | [#production-services] |
| | |
| | | --port 4444 \ |
| | | --bindDN "cn=Directory Manager" \ |
| | | --bindPassword - \ |
| | | --backupAll \ |
| | | --backUpAll \ |
| | | --backupDirectory /path/to/opendj/bak \ |
| | | --encrypt \ |
| | | --start 0 |
| | |
| | | :table-caption!: |
| | | |
| | | |
| | | ifndef::env-site[] |
| | | [#chap-pwd-policy] |
| | | endif::[] |
| | | == Configuring Password Policy |
| | | |
| | | ifdef::env-site[] |
| | | anchor:chap-pwd-policy[] |
| | | endif::[] |
| | | |
| | | This chapter covers password policy including examples for common use cases. In this chapter you will learn to: |
| | | |
| | | * Decide what type of password policy is needed |
| | |
| | | :table-caption!: |
| | | |
| | | |
| | | ifndef::env-site[] |
| | | [#chap-replication] |
| | | endif::[] |
| | | == Managing Data Replication |
| | | |
| | | ifdef::env-site[] |
| | | anchor:chap-replication[] |
| | | endif::[] |
| | | |
| | | OpenDJ uses advanced data replication with automated conflict resolution to help ensure your directory services remain available during administrative operations that take an individual server offline, or in the event a server crashes or a network goes down. This chapter explains how to manage OpenDJ directory data replication. In this chapter you will learn to: |
| | | |
| | | * Set up replication as part of initial installation using OpenDJ control panel, or at any time using command-line tools |
| | |
| | | |
| | | * In the Data Replication screen, select the user and application data base DN(s) to replicate. |
| | | + |
| | | OpenDJ directory server automatically replicates configuration data and directory schema. |
| | | OpenDJ also replicates administrative data under `cn=admin data` and directory schema under `cn=schema`. The server configuration under `cn=config` stays local. |
| | | |
| | | Once replication is set up, it works for all the replicas. You can monitor replication status through OpenDJ control panel. |
| | | |
| | | |
| | | [#repl-local-exercise] |
| | | === Try Replication on Two Local Servers |
| | | |
| | | Use Bash on an isolated test host. Start with the OpenDJ server ZIP saved as `opendj.zip` in an empty working directory. Read the license before using `--acceptLicense`. The ports below must be available. |
| | | |
| | | Create two instances with the same base DN. These commands use separate directories, ports, and self-signed certificates. |
| | | |
| | | [source,bash] |
| | | ---- |
| | | unzip -q opendj.zip -d first |
| | | unzip -q opendj.zip -d second |
| | | |
| | | first/opendj/setup --cli --no-prompt --acceptLicense --hostname localhost \ |
| | | --ldapPort 2389 --ldapsPort 2636 --adminConnectorPort 5444 \ |
| | | --rootUserDN 'cn=Directory Manager' --rootUserPassword password \ |
| | | --baseDN dc=example,dc=com --addBaseEntry --generateSelfSignedCertificate |
| | | |
| | | second/opendj/setup --cli --no-prompt --acceptLicense --hostname localhost \ |
| | | --ldapPort 3389 --ldapsPort 3636 --adminConnectorPort 6444 \ |
| | | --rootUserDN 'cn=Directory Manager' --rootUserPassword password \ |
| | | --baseDN dc=example,dc=com --addBaseEntry --generateSelfSignedCertificate |
| | | ---- |
| | | |
| | | Connect the two instances and initialize the second from the first. Initialization replaces the destination's data. Use `--trustAll` only with these local test certificates. |
| | | |
| | | [source,bash] |
| | | ---- |
| | | first/opendj/bin/dsreplication enable --baseDN dc=example,dc=com \ |
| | | --adminUID admin --adminPassword password \ |
| | | --host1 localhost --port1 5444 --replicationPort1 9989 \ |
| | | --bindDN1 'cn=Directory Manager' --bindPassword1 password \ |
| | | --host2 localhost --port2 6444 --replicationPort2 10989 \ |
| | | --bindDN2 'cn=Directory Manager' --bindPassword2 password \ |
| | | --trustAll --no-prompt |
| | | |
| | | first/opendj/bin/dsreplication initialize --baseDN dc=example,dc=com \ |
| | | --adminUID admin --adminPassword password \ |
| | | --hostSource localhost --portSource 5444 \ |
| | | --hostDestination localhost --portDestination 6444 \ |
| | | --trustAll --no-prompt |
| | | ---- |
| | | |
| | | OpenDJ accepts writes on either replica. To check that a replica catches up after an interruption, stop the second, write to the first, then start the second again. |
| | | |
| | | [source,bash] |
| | | ---- |
| | | second/opendj/bin/stop-ds |
| | | first/opendj/bin/ldapmodify --hostname localhost --port 2636 --useSSL --trustAll \ |
| | | --bindDN 'cn=Directory Manager' --bindPassword password <<'LDIF' |
| | | dn: dc=example,dc=com |
| | | changetype: modify |
| | | replace: description |
| | | description: Updated while the second replica was stopped |
| | | LDIF |
| | | second/opendj/bin/start-ds |
| | | ---- |
| | | |
| | | Read the entry on the second server. If the update has yet to arrive, repeat the search after replication catches up. |
| | | |
| | | [source,bash] |
| | | ---- |
| | | second/opendj/bin/ldapsearch --hostname localhost --port 3636 --useSSL --trustAll \ |
| | | --bindDN 'cn=Directory Manager' --bindPassword password \ |
| | | --baseDN dc=example,dc=com --searchScope base '(objectClass=*)' description |
| | | ---- |
| | | |
| | | The result should include `description: Updated while the second replica was stopped`. To check the opposite direction, stop the first replica, write a different `description` on the second, and verify that the first returns the new value after it restarts. |
| | | |
| | | [#repl-local-backlog] |
| | | ==== Check for Missing Changes |
| | | |
| | | [source,bash] |
| | | ---- |
| | | first/opendj/bin/dsreplication status --hostname localhost --port 5444 \ |
| | | --adminUID admin --adminPassword password --baseDN dc=example,dc=com \ |
| | | --trustAll --no-prompt |
| | | ---- |
| | | |
| | | Check `M.C.` for the number of missing changes on each replica. After both replicas catch up, the column should show `0` for both. `A.O.M.C.` shows when the oldest missing change was generated. To read updates from an application, see xref:#use-ecl[Using the External Change Log]. |
| | | |
| | | Stop both instances with their `bin/stop-ds` commands when finished. |
| | | |
| | | |
| | | [#about-repl] |
| | | === About Replication |
| | | |
| | |
| | | --bindDN "cn=Directory Manager" \ |
| | | --bindPassword password \ |
| | | --provider-name "Multimaster Synchronization" \ |
| | | --domain-name dc=example,dc=com |
| | | --set enabled:false |
| | | --domain-name dc=example,dc=com \ |
| | | --set enabled:false \ |
| | | --trustAll \ |
| | | --no-prompt |
| | | |
| | |
| | | :table-caption!: |
| | | |
| | | |
| | | ifndef::env-site[] |
| | | [#chap-resource-limits] |
| | | endif::[] |
| | | == Setting Resource Limits |
| | | |
| | | ifdef::env-site[] |
| | | anchor:chap-resource-limits[] |
| | | endif::[] |
| | | |
| | | This chapter shows you how to set resource limits that prevent directory clients from using an unfair share of system resources. In this chapter you will learn to: |
| | | |
| | | * Limit the resources used when a user searches the directory |
| | |
| | | information: "Portions copyright [year] [name of copyright owner]". |
| | | |
| | | Copyright 2017 ForgeRock AS. |
| | | Portions Copyright 2024 3A Systems LLC. |
| | | Portions Copyright 2024-2026 3A Systems, LLC. |
| | | //// |
| | | |
| | | :figure-caption!: |
| | |
| | | :table-caption!: |
| | | |
| | | |
| | | ifndef::env-site[] |
| | | [#chap-schema] |
| | | endif::[] |
| | | == Managing Schema |
| | | |
| | | ifdef::env-site[] |
| | | anchor:chap-schema[] |
| | | endif::[] |
| | | |
| | | This chapter describes how to manage Lightweight Directory Access Protocol (LDAP) schema definitions for directory data. In this chapter you will learn to: |
| | | |
| | | * Understand LDAP schemas including the schema definitions delivered with OpenDJ directory server |
| | |
| | | This file contains a core set of attribute type and object class definitions from the following Internet-Drafts, RFCs, and standards: |
| | | + |
| | | [none] |
| | | * link:https://tools.ietf.org/html/draft-ietf-boreham-numsubordinates[draft-ietf-boreham-numsubordinates, window=\_blank] |
| | | * link:https://datatracker.ietf.org/doc/html/draft-boreham-numsubordinates-01[numSubordinates draft, window=\_blank] |
| | | * link:https://tools.ietf.org/html/draft-findlay-ldap-groupofentries[draft-findlay-ldap-groupofentries, window=\_blank] |
| | | * link:https://tools.ietf.org/html/draft-furuseth-ldap-untypedobject[draft-furuseth-ldap-untypedobject, window=\_blank] |
| | | * link:https://tools.ietf.org/html/draft-good-ldap-changelog[draft-good-ldap-changelog, window=\_blank] |
| | |
| | | [#troubleshoot-simple-paged-results] |
| | | ==== Clients Need Simple Paged Results Control |
| | | |
| | | For Solaris and some versions of Linux you might see a message in the OpenDJ access logs such as the following: |
| | | A client requesting the link:https://www.rfc-editor.org/rfc/rfc2696[simple paged results control] anonymously can encounter this error: |
| | | |
| | | [source] |
| | | ---- |
| | | The request control with Object Identifier (OID) "1.2.840.113556.1.4.319" |
| | | cannot be used due to insufficient access rights |
| | | ---- |
| | | This message means clients are trying to use the link:http://tools.ietf.org/html/rfc2696[simple paged results control, window=\_blank] without authenticating. By default, OpenDJ includes a global ACI to allow only authenticated users to use the control: |
| | | By default, clients must bind before requesting paged results. If your clients require anonymous paging, grant access to the control while keeping the existing entry and attribute ACIs. |
| | | |
| | | Configure the client to xref:chap-connection-handlers.adoc#setup-server-cert[trust the administration connector's certificate] before connecting. |
| | | |
| | | [source, console] |
| | | ---- |
| | | $ dsconfig \ |
| | | --port 4444 \ |
| | | --hostname opendj.example.com \ |
| | | --bindDN "cn=Directory Manager" \ |
| | | --bindPassword "password" \ |
| | | get-access-control-handler-prop |
| | | |
| | | Property : Value(s) |
| | | -----------:------------------------------------------------------------------- |
| | | enabled : true |
| | | global-aci : (extop="1.3.6.1.4.1.26027.1.6.1 || 1.3.6.1.4.1.26027.1.6.3 || |
| | | ... |
| | | : (targetcontrol="1.3.6.1.1.12 || 1.3.6.1.1.13.1 || 1.3.6.1.1.13.2 |
| | | : || 1.2.840.113556.1.4.319 || 1.2.826.0.1.3344810.2.3 || |
| | | : 2.16.840.1.113730.3.4.18 || 2.16.840.1.113730.3.4.9 || |
| | | : 1.2.840.113556.1.4.473 || 1.3.6.1.4.1.42.2.27.9.5.9") (version |
| | | : 3.0; acl "Authenticated users control access"; allow(read) |
| | | : userdn="ldap:///all";), (targetcontrol="2.16.840.1.113730.3.4.2 || |
| | | : 2.16.840.1.113730.3.4.17 || 2.16.840.1.113730.3.4.19 || |
| | | : 1.3.6.1.4.1.4203.1.10.2 || 1.3.6.1.4.1.42.2.27.8.5.1 || |
| | | : 2.16.840.1.113730.3.4.16") (version 3.0; acl "Anonymous control |
| | | : access"; allow(read) userdn="ldap:///anyone";) |
| | | ---- |
| | | To grant anonymous (unauthenticated) user access to the control, add the OID for the simple paged results control to the list of those in the `Anonymous control access` global ACI: |
| | | |
| | | [source, console] |
| | | ---- |
| | | $ dsconfig \ |
| | | --port 4444 \ |
| | | --hostname opendj.example.com \ |
| | | --bindDN "cn=Directory Manager" \ |
| | | --bindPassword "password" \ |
| | | set-access-control-handler-prop \ |
| | | --remove global-aci:"(targetcontrol=\"2.16.840.1.113730.3.4.2 || \ |
| | | 2.16.840.1.113730.3.4.17 || 2.16.840.1.113730.3.4.19 || \ |
| | | 1.3.6.1.4.1.4203.1.10.2 || 1.3.6.1.4.1.42.2.27.8.5.1 || \ |
| | | 2.16.840.1.113730.3.4.16\") (version 3.0; acl \"Anonymous control access\"; \ |
| | | allow(read) userdn=\"ldap:///anyone\";)" \ |
| | | --add global-aci:"(targetcontrol=\"2.16.840.1.113730.3.4.2 || \ |
| | | 2.16.840.1.113730.3.4.17 || 2.16.840.1.113730.3.4.19 || \ |
| | | 1.3.6.1.4.1.4203.1.10.2 || 1.3.6.1.4.1.42.2.27.8.5.1 || \ |
| | | 2.16.840.1.113730.3.4.16 || 1.2.840.113556.1.4.319\") \ |
| | | (version 3.0; acl \"Anonymous control access\"; allow(read) \ |
| | | userdn=\"ldap:///anyone\";)" \ |
| | | --port 4444 \ |
| | | --hostname opendj.example.com \ |
| | | --bindDN "cn=Directory Manager" \ |
| | | --bindPassword password \ |
| | | --add 'global-aci:(targetcontrol="1.2.840.113556.1.4.319")(version 3.0; acl "Anonymous paged results control access"; allow(read) userdn="ldap:///anyone";)' \ |
| | | --no-prompt |
| | | ---- |
| | | Alternatively, stop OpenDJ, edit the corresponding ACI carefully in `/path/to/opendj/config/config.ldif`, and restart OpenDJ. footnote:d67723e18754[Unlike the`dsconfig`command, the`config.ldif`file is not a public interface, so this alternative should not be used in production.] |
| | | |
| | | |
| | | |
| | | [#troubleshoot-repl] |
| | |
| | | :table-caption!: |
| | | |
| | | |
| | | ifndef::env-site[] |
| | | [#chap-tuning] |
| | | endif::[] |
| | | == Tuning Servers For Performance |
| | | |
| | | ifdef::env-site[] |
| | | anchor:chap-tuning[] |
| | | endif::[] |
| | | |
| | | This chapter suggests ways to measure and improve directory service performance. In this chapter you will learn to: |
| | | |
| | | * Define directory server performance goals operationally in accordance with the needs of client applications |
| | |
| | | [#perf-testing] |
| | | === Testing Performance |
| | | |
| | | Even if you do not need high availability, you still need two of everything, because your test environment needs to mimic your production environment as closely as possible if you want to avoid unwelcome surprises. |
| | | Use an isolated server for a first measurement. To estimate production performance, match the production topology, data, and client workload in the test environment. |
| | | |
| | | In your test environment, you set up OpenDJ as you will later in production, and then conduct experiments to determine how best to meet the requirements defined in the SLA. |
| | | |
| | | Use the `make-ldif` command, described in xref:../reference/admin-tools-ref.adoc#makeldif-1[makeldif(1)] in the __Reference__, to generate sample data that match what you expect to find in production. |
| | | Use the `makeldif` command, described in xref:../reference/admin-tools-ref.adoc#makeldif-1[makeldif(1)] in the __Reference__, to generate sample data that match what you expect to find in production. |
| | | |
| | | The OpenDJ LDAP Toolkit provides command-line tools to help with basic performance testing: |
| | | |
| | |
| | | |
| | | All these commands show you information about the response time distributions, and allow you to perform tests at specific levels of throughput. |
| | | |
| | | If you need additional precision when evaluating response times, use the global configuration setting `etime-resolution`, to change elapsed processing time resolution from milliseconds (default) to nanoseconds: |
| | | [#perf-local-example] |
| | | ==== Measure Searches and Modifications |
| | | |
| | | Run these commands from the `opendj` directory of the xref:../getting-started/first-steps.adoc#getting-started-first-directory[Getting Started instance], after adding Alice and before removing her entry. Both tools run for five seconds at a target of 20 operations per second. The modification test replaces the description on the sample entry. |
| | | |
| | | [source,bash] |
| | | ---- |
| | | ./bin/searchrate --hostname localhost --port 1636 --useSSL --trustAll \ |
| | | --bindDN 'cn=Directory Manager' --bindPasswordFile ../quickstart-password.txt \ |
| | | --maxDuration 5 --statInterval 1 --noRebind --targetThroughput 20 \ |
| | | --baseDN 'dc=example,dc=com' '(uid=alice)' cn |
| | | |
| | | ./bin/modrate --hostname localhost --port 1636 --useSSL --trustAll \ |
| | | --bindDN 'cn=Directory Manager' --bindPasswordFile ../quickstart-password.txt \ |
| | | --maxDuration 5 --statInterval 1 --noRebind --targetThroughput 20 \ |
| | | --targetDN 'uid=alice,ou=People,dc=example,dc=com' \ |
| | | --argument 'randstr(12)' 'description:%s' |
| | | ---- |
| | | |
| | | Check `err/sec` for errors. `Entries/Srch` reports the average number of entries per search. This query matches Alice. Throughput is in operations per second and response times are in milliseconds. |
| | | |
| | | To see the server-side totals for this listener, read its monitoring entry. |
| | | |
| | | [source,bash] |
| | | ---- |
| | | ./bin/ldapsearch --hostname localhost --port 1636 --useSSL --trustAll \ |
| | | --bindDN 'cn=Directory Manager' --bindPasswordFile ../quickstart-password.txt \ |
| | | --baseDN 'cn=monitor' '(&(cn=*1636*)(modifyRequests=*))' \ |
| | | searchRequests modifyRequests |
| | | ---- |
| | | |
| | | These totals include all requests of each type on that listener. Compare readings before and after a test to see how much they increased. The listener collects them when `keep-stats` is enabled, as it is by default. |
| | | |
| | | For a replicated test environment, also xref:chap-replication.adoc#repl-local-backlog[check for missing changes] after the write test. |
| | | |
| | | [#perf-elapsed-time] |
| | | ==== Server Processing Time |
| | | |
| | | The rate tools measure elapsed time at the client. To record finer server processing times, set `etime-resolution` to nanoseconds. The default is milliseconds. |
| | | |
| | | [source, console] |
| | | ---- |
| | |
| | | [#perf-java] |
| | | ==== Java Settings |
| | | |
| | | Default Java settings let you evaluate OpenDJ using limited system resources. If you need high performance for production system, test with the following JVM options. These apply to the Sun/Oracle JVM. |
| | | Set `start-ds.java-args` in the instance's `config/java.properties` and restart the server. On UNIX, a nonempty `OPENDJ_JAVA_ARGS` takes precedence. |
| | | |
| | | [TIP] |
| | | ==== |
| | | To apply JVM settings for your server, edit `config/java.properties`, and apply the changes with the `dsjavaproperties` command, described in xref:../reference/admin-tools-ref.adoc#dsjavaproperties-1[dsjavaproperties(1)] in the __Reference__: |
| | | ==== |
| | | -- |
| | | Use `-Xms` and `-Xmx` to set the initial and maximum heap size. Leave room for the database cache and other Java allocations within the heap and for the operating system and native allocations outside it. To measure the default garbage collector on HotSpot, add `-Xlog:gc*` with a writable log path. |
| | | |
| | | `-server`:: |
| | | Use the C2 compiler and optimizer (HotSpot Server VM). |
| | | |
| | | `-d64`:: |
| | | Use this option on 64-bit systems for heaps larger than 3.5 GB. |
| | | |
| | | `-Xms, -Xmx`:: |
| | | Set both minimum and maximum heap size to the same value to avoid resizing. Leave space for the entire DB cache and more. |
| | | |
| | | + |
| | | Use at least a 2 GB heap (`-Xms2G -Xmx2G`) unless your data set is small. |
| | | |
| | | `-Xmn`:: |
| | | When using CMS garbage collection, consider using this option. Do not use it when using G1 garbage collection. |
| | | |
| | | + |
| | | If a server handles high throughput, set the new generation size large enough for the JVM to avoid promoting short-lived objects into the old generation space (`-Xmn512M`). |
| | | |
| | | `-XX:MaxTenuringThreshold=1`:: |
| | | Force OpenDJ directory server to only create objects that have either a short lifetime, or a long lifetime. |
| | | |
| | | `-XX:+UseConcMarkSweepGC`:: |
| | | The CMS garbage collector tends to give the best performance characteristics with the lowest garbage collection pause times. |
| | | |
| | | + |
| | | Consider using the G1 garbage collector only if CMS performance characteristics do not fit your deployment, and testing shows G1 performs better. |
| | | |
| | | `-XX:+UseCompressedOops`:: |
| | | Set this option when you have a 64-bit JVM, and `-Xmx` less than 32 GB. Java object pointers normally have the same size as native machine pointers. If you run a small 64-bit JVM, then compressed object pointers can save space. |
| | | |
| | | `-XX:+PrintGCDetails`,`-XX:+PrintGCTimeStamps`:: |
| | | Use these options when diagnosing JVM tuning problems. You can turn them off when everything is running smoothly. |
| | | |
| | | -- |
| | | [source,properties] |
| | | ---- |
| | | start-ds.java-args=-Xms2g -Xmx2g -Xlog:gc*:file=/path/to/opendj/logs/gc.log:time,uptime,level,tags:filecount=5,filesize=20M |
| | | ---- |
| | | |
| | | |
| | | [#perf-data-storage] |
| | |
| | | |
| | | === Prepare the Environment |
| | | |
| | | Install Java 11 or later, `curl` and `unzip`. Run `java -version` to check the Java runtime. If several runtimes are installed, set `OPENDJ_JAVA_HOME` to the Java installation you want OpenDJ to use. Run the commands below in Bash; on macOS, enter `bash` first if your terminal uses another shell, such as zsh. |
| | | Install Java 11 or later, `curl` and `unzip`. Check Java with `java -version`. If needed, export `OPENDJ_JAVA_HOME` to select another Java installation. Run the commands below in Bash. |
| | | |
| | | Use a host reserved for local evaluation and keep the listener ports inaccessible from other hosts. Ports 1389 (LDAP), 1636 (LDAPS) and 4444 (administration) must be free. The example connects to `localhost`; the setup host name does not restrict listeners to the loopback interface. |
| | | Use an isolated test host with ports 1389 (LDAP), 1636 (LDAPS) and 4444 (administration) available. Setup listens on all interfaces by default, even with `--hostname localhost`. |
| | | |
| | | Download and unpack the server in a new directory: |
| | | Create a private `opendj-quickstart` directory and unpack the ZIP there. |
| | | |
| | | [source,bash,subs="+attributes"] |
| | | ---- |
| | | mkdir opendj-quickstart |
| | | cd opendj-quickstart |
| | | mkdir -m 700 opendj-quickstart && |
| | | cd opendj-quickstart && |
| | | curl --fail --location --output opendj.zip \ |
| | | https://github.com/OpenIdentityPlatform/OpenDJ/releases/download/{opendj-example-version}/opendj-{opendj-example-version}.zip |
| | | https://github.com/OpenIdentityPlatform/OpenDJ/releases/download/{opendj-example-version}/opendj-{opendj-example-version}.zip && |
| | | unzip -q opendj.zip |
| | | ---- |
| | | |
| | | === Set Up and Start the Server |
| | | |
| | | Read the link:https://github.com/OpenIdentityPlatform/OpenDJ/blob/{opendj-example-version}/LICENSE.md[license] before accepting it with the setup command below. Choose a nonempty administrator password. Save it in a file readable only by your account so it does not appear in command arguments or shell history: |
| | | Read the link:https://github.com/OpenIdentityPlatform/OpenDJ/blob/{opendj-example-version}/LICENSE.md[license] before accepting it with the setup command below. Enter a nonempty administrator password. The command block saves it in a private file for setup and the LDAP commands. |
| | | |
| | | [source,bash] |
| | | ---- |
| | | read -r -s -p 'Directory Manager password: ' quickstart_password |
| | | IFS= read -r -s -p 'Directory Manager password: ' quickstart_password |
| | | printf '\n' |
| | | (umask 077; printf '%s\n' "$quickstart_password" > quickstart-password.txt) |
| | | unset quickstart_password |
| | | cd opendj |
| | | cd opendj && |
| | | ./setup --cli --no-prompt --acceptLicense \ |
| | | --hostname localhost --ldapPort 1389 --ldapsPort 1636 \ |
| | | --adminConnectorPort 4444 --generateSelfSignedCertificate \ |
| | |
| | | |
| | | Setup creates the base entry and starts the server. Keep this terminal in the `opendj` directory for the remaining commands. |
| | | |
| | | Verify that the base entry exists: |
| | | Verify that the base entry exists. |
| | | |
| | | [source,bash] |
| | | ---- |
| | |
| | | --baseDN 'dc=example,dc=com' --searchScope base '(objectClass=*)' dn |
| | | ---- |
| | | |
| | | The output should contain `dn: dc=example,dc=com`. The `--trustAll` option accepts the evaluation certificate without validating its identity. For a deployed service, configure a trusted certificate and client trust instead; see xref:../admin-guide/chap-connection-handlers.adoc#setup-server-cert[Preparing For Secure Communications]. |
| | | The output should contain `dn: dc=example,dc=com`. Use `--trustAll` only for this local exercise. It accepts any server certificate. For a deployed service, see xref:../admin-guide/chap-connection-handlers.adoc#setup-server-cert[Preparing For Secure Communications]. |
| | | |
| | | === Add a Person |
| | | |
| | |
| | | --baseDN 'dc=example,dc=com' '(uid=alice)' cn mail |
| | | ---- |
| | | |
| | | The result includes Alice's DN, `cn: Alice Jensen` and `mail: alice@example.com`. |
| | | The search covers the whole subtree under the base DN. The filter selects entries by `uid`, and the trailing attribute names select the fields to return. The result includes Alice's DN, name and email address. |
| | | |
| | | Replace the email address using an LDIF change record: |
| | | |
| | |
| | | --filename update-alice.ldif |
| | | ---- |
| | | |
| | | Repeat the search. It should now return `mail: alice.jensen@example.com`. |
| | | Repeat the search. It should now return `mail: alice.jensen@example.com`. In scripts, check the LDAP tool’s exit status before continuing. |
| | | |
| | | === Restart and Remove the Sample Data |
| | | |
| | |
| | | |
| | | [source,bash] |
| | | ---- |
| | | ./bin/stop-ds |
| | | ./bin/stop-ds && |
| | | ./bin/start-ds |
| | | ---- |
| | | |
| | | Repeat the search to verify that Alice's changed email address survives the restart. |
| | | |
| | | Delete the child entry before its parent: |
| | | While Alice’s entry is still present, you can xref:../admin-guide/chap-tuning.adoc#perf-local-example[measure search and modification rates]. |
| | | |
| | | Pass one DN per line to `ldapdelete`, with the child entry before its parent. |
| | | |
| | | [source,bash] |
| | | ---- |
| | | for dn in 'uid=alice,ou=People,dc=example,dc=com' 'ou=People,dc=example,dc=com'; do |
| | | printf '%s\n' 'uid=alice,ou=People,dc=example,dc=com' 'ou=People,dc=example,dc=com' | |
| | | ./bin/ldapdelete --hostname localhost --port 1636 --useSSL --trustAll \ |
| | | --bindDN 'cn=Directory Manager' --bindPasswordFile ../quickstart-password.txt \ |
| | | "$dn" |
| | | done |
| | | --bindDN 'cn=Directory Manager' --bindPasswordFile ../quickstart-password.txt |
| | | ---- |
| | | |
| | | Repeat the search once more. It should return no entries. The base entry remains available for another exercise. |
| | |
| | | |
| | | === Next Steps |
| | | |
| | | * xref:../admin-guide/chap-privileges-acis.adoc[Configuring Privileges and Access Control] explains how to give application accounts the access they need. |
| | | * See more xref:../server-dev-guide/chap-ldap-operations.adoc#search-ldap[LDAP search] and xref:../server-dev-guide/chap-ldap-operations.adoc#modify-ldap[update] examples. |
| | | * xref:../admin-guide/chap-privileges-acis.adoc#aci-local-exercise[Try Delegating Access Control] checks what a user can do before and after you grant access. |
| | | * xref:../how-to/rest-access.adoc[Access Directory Entries Over REST] uses a separate HTTPS listener. |
| | | * xref:../admin-guide/chap-backup-restore.adoc[Backing Up and Restoring Data] and xref:../admin-guide/chap-monitoring.adoc[Monitoring] cover routine operations. |
| | | * xref:../admin-guide/chap-replication.adoc[Managing Data Replication] covers multiple servers. |
| | | * xref:../admin-guide/chap-replication.adoc#repl-local-exercise[Try Replication on Two Local Servers] verifies that changes reach a second replica. |
| | | * xref:../how-to/tasks.adoc[Find a Procedure] links deployment and integration recipes. |
| | | * xref:../release-notes/release-5.2.0.adoc[OpenDJ 5.2.0 Release Notes] describes this release and links the complete change list. |
| | |
| | | A record containing named attributes. A person entry can have `cn` (common name), `sn` (surname) and `mail` attributes. Some attributes can have multiple values. |
| | | |
| | | Distinguished name (DN):: |
| | | The name identifying an entry in the directory tree. For example, `uid=alice,ou=People,dc=example,dc=com` identifies Alice beneath the People organizational unit. Its parent is `ou=People,dc=example,dc=com`. |
| | | The name identifying an entry in the directory tree. For example, `uid=alice,ou=People,dc=example,dc=com` identifies Alice beneath the People organizational unit. Its relative distinguished name (RDN) is `uid=alice`, and its parent has the DN `ou=People,dc=example,dc=com`. |
| | | |
| | | Base DN:: |
| | | The starting point of a search or the root of a directory suffix. The tutorial creates a suffix with base DN `dc=example,dc=com`. |
| | |
| | | An entry's `objectClass` values determine which attributes are required or permitted. For example, `inetOrgPerson` permits `mail` and requires the inherited `cn` and `sn` attributes. The server checks changes against its schema. |
| | | |
| | | Bind:: |
| | | Authentication of a client connection. The tutorial binds as `cn=Directory Manager`, an administrative account created by setup. Applications should use accounts with only the access they need. |
| | | The LDAP operation that sets the authentication state of a connection. The tutorial binds as `cn=Directory Manager`, an administrative account created by setup. Applications should use accounts with only the access they need. |
| | | |
| | | Search:: |
| | | A request with a base DN, scope and filter. The filter `(uid=alice)` finds entries whose `uid` is `alice`; the attributes requested determine which values are returned. Access controls still apply to matching entries. |
| | | A request with a base DN, scope and filter. Scope `base` searches the base entry, `one` searches its immediate children, and `sub` searches the base and its descendants. The filter `(uid=alice)` finds entries whose `uid` is `alice`. Requested attributes and access controls determine which values the server returns. |
| | | |
| | | LDAP over TLS:: |
| | | LDAPS starts a TLS connection on the secure listener. StartTLS upgrades an existing LDAP connection before credentials are sent. The tutorial uses LDAPS and a certificate generated by setup. |
| | | |
| | | LDIF:: |
| | | LDAP Data Interchange Format, a text format for entries and changes. Each attribute appears as `name: value`, and a blank line separates entries. Change records also specify an operation, such as `changetype: modify`. |
| | |
| | | |
| | | Resetting another user's password requires both the `password-reset` privilege and permission to write that entry's `userPassword` attribute. This recipe grants only that write permission below `ou=People,dc=example,dc=com`. |
| | | |
| | | Use a disposable server containing the sample users from xref:./rest-access.adoc[Access Directory Entries Over REST]. Run these commands before changing the sample password of `user.0`. `--trustAll` accepts the demonstration server's self-signed certificate. |
| | | Use the test server from xref:./rest-access.adoc[Access Directory Entries Over REST]. This exercise changes Barbara Jensen's password. `--trustAll` accepts the local demonstration server's self-signed certificate. |
| | | |
| | | === Create the Delegate and Grant Access |
| | | |
| | |
| | | LDIF |
| | | ---- |
| | | |
| | | The ACI is inherited by entries below People. It does not grant writes to other attributes, permission to add or delete entries, or password resets outside that subtree. Existing ACIs still apply; this example assumes the default access-control configuration. |
| | | The ACI is inherited by entries below People. It grants write access to `userPassword` there. Existing ACIs from the server and `Example.ldif` still apply. |
| | | |
| | | === Verify the Scope |
| | | |
| | |
| | | bin/ldappasswordmodify --hostname localhost --port 1389 --useStartTLS --trustAll \ |
| | | --bindDN 'uid=password-admin,ou=Administrators,dc=example,dc=com' \ |
| | | --bindPassword 'AdminPassword123!' \ |
| | | --authzID 'dn:uid=user.0,ou=People,dc=example,dc=com' \ |
| | | --authzID 'dn:uid=bjensen,ou=People,dc=example,dc=com' \ |
| | | --newPassword 'NewPassword123!' |
| | | ---- |
| | | |
| | |
| | | [source,bash] |
| | | ---- |
| | | bin/ldapsearch --hostname localhost --port 1389 --useStartTLS --trustAll \ |
| | | --bindDN 'uid=user.0,ou=People,dc=example,dc=com' \ |
| | | --bindDN 'uid=bjensen,ou=People,dc=example,dc=com' \ |
| | | --bindPassword 'NewPassword123!' \ |
| | | --baseDN 'uid=user.0,ou=People,dc=example,dc=com' --searchScope base \ |
| | | --baseDN 'uid=bjensen,ou=People,dc=example,dc=com' --searchScope base \ |
| | | '(objectClass=*)' uid |
| | | ---- |
| | | |
| | |
| | | bin/ldapmodify --hostname localhost --port 1389 --useStartTLS --trustAll \ |
| | | --bindDN 'uid=password-admin,ou=Administrators,dc=example,dc=com' \ |
| | | --bindPassword 'AdminPassword123!' <<'LDIF' |
| | | dn: uid=user.0,ou=People,dc=example,dc=com |
| | | dn: uid=bjensen,ou=People,dc=example,dc=com |
| | | changetype: modify |
| | | replace: description |
| | | description: This change must be rejected |
| | |
| | | [source,bash] |
| | | ---- |
| | | curl --fail-with-body --cacert server-cert.pem --user 'password-admin:AdminPassword123!' \ |
| | | --request POST 'https://localhost:8443/api/users/user.0?_action=resetPassword' |
| | | --request POST 'https://localhost:8443/api/users/bjensen?_action=resetPassword' |
| | | ---- |
| | | |
| | | The response contains `generatedPassword`; it replaces the password set above. See xref:../server-dev-guide/chap-rest-operations.adoc#rest-action-reset-password[Resetting Passwords] for the API details. |
| | |
| | | [#how-to-rest-access] |
| | | == Access Directory Entries Over REST |
| | | |
| | | This recipe enables the built-in HTTP handler and reads a user through the default `/api` mapping. Start with a fresh server using xref:../install-guide/chap-install.adoc#command-line-install[command-line installation]. For this recipe, pass `--hostname localhost`, `--sampleData 1000`, `--baseDN dc=example,dc=com`, `--enableStartTLS` and `--generateSelfSignedCertificate` to setup. Use administration port 4444 and LDAP port 1389, with Directory Manager password `password`. The generated certificate and its `localhost` identity are used by the HTTPS and StartTLS checks below. |
| | | Use a fresh ZIP installation on an isolated test host with ports 1389, 4444, and 8443 available. Copy link:../attachments/Example.ldif[Example.ldif] into the `opendj` directory. Read the license before using `--acceptLicense`, then run the commands from that directory. See xref:../install-guide/chap-install.adoc#command-line-install[command-line installation] for setup options. |
| | | |
| | | [source,bash] |
| | | ---- |
| | | ./setup --cli --no-prompt --acceptLicense --hostname localhost \ |
| | | --ldapPort 1389 --adminConnectorPort 4444 \ |
| | | --enableStartTLS --generateSelfSignedCertificate \ |
| | | --rootUserDN 'cn=Directory Manager' --rootUserPassword password \ |
| | | --baseDN dc=example,dc=com --ldifFile Example.ldif |
| | | ---- |
| | | |
| | | === Enable the Handler |
| | | |
| | |
| | | --bindDN 'cn=Directory Manager' --bindPassword password --trustAll --no-prompt |
| | | ---- |
| | | |
| | | Restarting applies the listener and TLS settings. The default `/api` endpoint is enabled and uses `HTTP Basic`. The exact-match identity mapper resolves a username to its `uid` entry. The sample users have password `password`. |
| | | Restarting applies the listener and TLS settings. The default `/api` endpoint is enabled and uses `HTTP Basic`. The exact-match identity mapper resolves a username to its `uid` entry. |
| | | |
| | | === Read a User |
| | | |
| | |
| | | |
| | | [source,bash] |
| | | ---- |
| | | curl --fail-with-body --cacert server-cert.pem --user 'user.0:password' \ |
| | | 'https://localhost:8443/api/users/user.0?_prettyPrint=true' |
| | | api=https://localhost:8443/api |
| | | curl --fail-with-body --cacert server-cert.pem --user 'bjensen:hifalutin' \ |
| | | "$api/users/bjensen?_prettyPrint=true" |
| | | ---- |
| | | |
| | | The JSON response identifies `user.0` and includes its mapped name and contact information. The mapping is in `config/rest2ldap/endpoints/api/example-v1.json`; its default user base is `ou=people,dc=example,dc=com`. Adapt that mapping if you use a different suffix. |
| | | The JSON response identifies `bjensen` and includes her mapped name and contact information. The mapping in `config/rest2ldap/endpoints/api/example-v1.json` uses `ou=people,dc=example,dc=com` as its user base. |
| | | |
| | | === Create, Update, and Delete a User |
| | | |
| | | The sample account `kvaughan` belongs to the Directory Administrators group. Use it to create a temporary user named `rest-example` and read the new entry. The create request returns HTTP 201. |
| | | |
| | | [source,bash] |
| | | ---- |
| | | curl --fail-with-body --cacert server-cert.pem --user 'kvaughan:bribery' \ |
| | | --header 'Content-Type: application/json' \ |
| | | --data '{"_id":"rest-example","_schema":"frapi:opendj:rest2ldap:user:1.0", |
| | | "name":{"givenName":"REST","familyName":"Example"},"displayName":["REST Example"]}' \ |
| | | "$api/users?_action=create&_prettyPrint=true" |
| | | |
| | | curl --fail-with-body --cacert server-cert.pem --user 'kvaughan:bribery' \ |
| | | "$api/users/rest-example?_prettyPrint=true" |
| | | ---- |
| | | |
| | | Replace the writable fields with `PUT`. `If-Match: *` allows any current revision of the existing resource. To require a specific revision, use the `_rev` value returned by `GET`. Check that the response shows the new display name, then delete the test user. |
| | | |
| | | [source,bash] |
| | | ---- |
| | | curl --fail-with-body --cacert server-cert.pem --user 'kvaughan:bribery' \ |
| | | --request PUT --header 'If-Match: *' --header 'Content-Type: application/json' \ |
| | | --data '{"name":{"givenName":"REST","familyName":"Example"}, |
| | | "displayName":["Updated REST Example"]}' \ |
| | | "$api/users/rest-example?_prettyPrint=true" |
| | | |
| | | curl --fail-with-body --cacert server-cert.pem --user 'kvaughan:bribery' \ |
| | | --request DELETE "$api/users/rest-example?_prettyPrint=true" |
| | | ---- |
| | | |
| | | `DELETE` returns the removed resource. A subsequent `GET` for `rest-example` returns HTTP 404. |
| | | |
| | | === Enable Access Logging |
| | | |
| | | To enable HTTP access logging: |
| | | |
| | |
| | | --trustAll --no-prompt |
| | | ---- |
| | | |
| | | See xref:../server-dev-guide/chap-rest-operations.adoc[Performing RESTful Operations] for creating, updating and deleting resources, API versions and password actions. HTTP authentication does not grant additional LDAP privileges or access rights. For read/write delegation, use xref:../admin-guide/chap-privileges-acis.adoc[Configuring Privileges and Access Control] rather than relying on the name or location of a user entry. To delegate password resets, follow xref:./delegate-password-reset.adoc[Delegate Password Reset Permissions]. |
| | | See xref:../server-dev-guide/chap-rest-operations.adoc[Performing RESTful Operations] for more examples. HTTP requests use the authenticated account's LDAP privileges and access rights. See xref:../admin-guide/chap-privileges-acis.adoc[Configuring Privileges and Access Control] or continue with xref:./delegate-password-reset.adoc[Delegate Password Reset Permissions]. |
| | |
| | | information: "Portions copyright [year] [name of copyright owner]". |
| | | |
| | | Copyright 2017 ForgeRock AS. |
| | | Portions Copyright 2024-2026 3A Systems LLC. |
| | | Portions Copyright 2024-2026 3A Systems, LLC. |
| | | //// |
| | | |
| | | :figure-caption!: |
| | |
| | | :opendj-version: x.y.z |
| | | |
| | | |
| | | ifndef::env-site[] |
| | | [#chap-install] |
| | | endif::[] |
| | | == Installing OpenDJ Servers |
| | | |
| | | ifdef::env-site[] |
| | | anchor:chap-install[] |
| | | endif::[] |
| | | |
| | | This chapter covers installation of OpenDJ server software and includes the following procedures: |
| | | |
| | | * xref:#before-you-install["To Prepare For Installation"] |
| | |
| | | |
| | | * xref:#install-properties-file["To Install OpenDJ Directory Server With a Properties File"] |
| | | |
| | | * xref:#chap-jvm-opts["To Configure Java Runtime Options"] |
| | | |
| | | * xref:#install-fips["To Install OpenDJ Directory Server on a FIPS 140 Java Runtime"] |
| | | |
| | | * xref:#pdb-to-je["To Move Data from a PDB Backend to a JE Backend"] |
| | | |
| | | * xref:#install-rest2ldap-servlet["To Install OpenDJ REST to LDAP Gateway"] |
| | | |
| | | * xref:#install-rest2ldap-servlet-3-0["To Install OpenDJ REST to LDAP Gateway (3.0)"] |
| | | * xref:#install-rest2ldap-servlet-3-0["To Install the Legacy OpenDJ 3.0 REST to LDAP Gateway"] |
| | | |
| | | * xref:#install-dsml-gateway["To Install OpenDJ DSML gateway"] |
| | | * xref:#install-dsml-gateway["To Install OpenDJ DSML Gateway"] |
| | | |
| | | |
| | | [#before-you-install] |
| | | .To Prepare For Installation |
| | | ==== |
| | | |
| | | . Make sure you have a required Java environment installed. |
| | | . Install Java 11 or later. See xref:../release-notes/requirements-and-upgrade.adoc#release-requirements["Requirements and Upgrade Considerations"]. |
| | | + |
| | | If your default Java environment is not appropriate, set `OPENDJ_JAVA_HOME` to the path to the correct Java environment, or set `OPENDJ_JAVA_BIN` to the absolute path of the `java` command. The `OPENDJ_JAVA_BIN` environment variable is useful if you have both 32-bit and 64-bit versions of the Java environment installed, and want to make sure you use the 64-bit version. |
| | | To select a different runtime, set `OPENDJ_JAVA_HOME` to its installation directory or `OPENDJ_JAVA_BIN` to the absolute path of its `java` executable. |
| | | |
| | | . Prevent antivirus and intrusion detection systems from interfering with OpenDJ directory server. |
| | | . Ensure that the account running OpenDJ can write to the instance directory, the chosen listener ports are free, and the server host name resolves for clients. |
| | | + |
| | | Antivirus and intrusion detection systems that do a deep inspection of database files are not compatible with OpenDJ directory server. Disable antivirus and intrusion detection systems, or at least prevent them from operating on OpenDJ directory server files. |
| | | Configure file inspection tools to avoid interfering with active OpenDJ database files. |
| | | |
| | | . Download software releases from the link:https://github.com/OpenIdentityPlatform/OpenDJ/releases[GitHub, window=\_blank]. |
| | | + |
| | |
| | | The following OpenDJ {opendj-version} server software is available: |
| | | |
| | | opendj-{opendj-version}.zip:: |
| | | Cross-platform OpenDJ directory server installation files. |
| | | Cross-platform OpenDJ directory server installation files. The `-slim.zip` variant omits the Cassandra and several JDBC drivers included in the full ZIP. |
| | | |
| | | opendj_{opendj-version}-1_all.deb:: |
| | | OpenDJ directory server native package for Debian and related Linux distributions. |
| | |
| | | opendj-{opendj-version}-1.noarch.rpm:: |
| | | OpenDJ directory server native package for Red Hat and related Linux distributions. |
| | | |
| | | opendj-{opendj-version}.msi:: |
| | | OpenDJ directory server package for Windows. |
| | | |
| | | org.openidentityplatform.opendj.opendj-dsml-servlet.war:: |
| | | Cross-platform OpenDJ DSML gateway web archive |
| | | |
| | |
| | | OpenDJ directory server is also published as a Docker image, which brings its own Java environment. See xref:#install-docker["To Run OpenDJ in Docker"]. |
| | | + |
| | | |
| | | . If you plan to install OpenDJ DSML gateway or OpenDJ REST to LDAP gateway, make sure you have an appropriate application server installed. |
| | | . The current gateway WARs require a Jakarta Servlet container such as Apache Tomcat 10.1. See the link:https://tomcat.apache.org/whichversion.html[Tomcat version matrix]. |
| | | + |
| | | |
| | | . If you plan to configure SSL or TLS to secure network communications between the server and client applications, get a properly signed digital certificate that your client applications recognize, such as one that fits with your organization's PKI or one provided by a recognized certificate authority. |
| | | + |
| | | To use the certificate during installation, the certificate must be located in a keystore provided with Java (JKS, JCEKS, PKCS#12), or on a PKCS#11 token. To import a signed certificate into a keystore, use the Java `keytool` command. |
| | | To use the certificate during installation, the certificate must be located in a keystore supported by setup (JKS, JCEKS, PKCS#12, or BCFKS), or on a PKCS#11 token. To import a signed certificate into a keystore, use the Java `keytool` command. |
| | | + |
| | | For details see xref:../admin-guide/chap-connection-handlers.adoc#setup-server-cert["Preparing For Secure Communications"] in the __Administration Guide__. |
| | | |
| | |
| | | |
| | | * (Windows) `opendj\setup.bat` |
| | | |
| | | * (macOS) `opendj/QuickSetup.app` |
| | | |
| | | |
| | | . Follow the instructions in the wizard. |
| | | + |
| | |
| | | |
| | | ** (Windows) `C:\path\to\opendj\bat\control-panel.bat` |
| | | |
| | | ** (macOS) `/path/to/opendj/bin/ControlPanel.app` |
| | | |
| | | |
| | | ==== |
| | | |
| | |
| | | ====== |
| | | Follow these steps to put the configuration, logs, and data files in a different location: |
| | | |
| | | . Before running the `setup` command, create an `instance.loc` file to identify the location. |
| | | . Before running the `setup` command, create the instance directory and an `instance.loc` file to identify the location. |
| | | + |
| | | The `setup` command tries to read `instance.loc` in the same directory as the `setup` command, such as `/path/to/opendj/`. |
| | | + |
| | | The `instance.loc` file contains a single line identifying either the absolute location, such as `/path/to/server`, or the location relative to the `instance.loc` file. |
| | | The `instance.loc` file contains a single line with an absolute path such as `/path/to/server` or a path relative to the installation directory. The account that runs setup and the server needs write access to the instance directory. |
| | | |
| | | . Run the `setup` command to complete OpenDJ directory server installation. |
| | | + |
| | |
| | | + |
| | | When you unzip `opendj-{opendj-version}.zip`, a top-level `opendj` directory is created in the directory where you unzipped the file. On Windows systems if you unzip `opendj-{opendj-version}.zip`, with Right-Click > Extract All, be sure to remove the trailing `opendj-{opendj-version}` directory from the folder you specify. |
| | | |
| | | . Run the `setup --cli` command found in the `/path/to/opendj` directory. |
| | | . In the installation directory, run `./setup --cli` on UNIX or `setup.bat --cli` on Windows. |
| | | + |
| | | This command starts the setup program in interactive mode on the command-line, prompting you for each option. Alternatively, use additional `setup` options to specify values for the options you choose during interactive mode, thus scripting the installation process. See `setup --help` and the notes below. |
| | | + |
| | |
| | | + |
| | | The `setup` command without the `--cli` option runs the GUI installer. |
| | | + |
| | | The following example shows interactive installation of OpenDJ directory server: |
| | | + |
| | | Review the settings on the summary screen before proceeding. From there you can also print the equivalent non-interactive command. |
| | | |
| | | + |
| | | This example creates a base entry with StartTLS and LDAPS on an isolated test host. Save the administrator password in a private file and use its path in the command. |
| | | |
| | | + |
| | | [source, console] |
| | | ---- |
| | | $ /path/to/opendj/setup --cli |
| | | READ THIS SOFTWARE LICENSE AGREEMENT CAREFULLY. BY DOWNLOADING OR INSTALLING |
| | | THE FORGEROCK SOFTWARE, YOU, ON BEHALF OF YOURSELF AND YOUR COMPANY, AGREE TO |
| | | BE BOUND BY THIS SOFTWARE LICENSE AGREEMENT. IF YOU DO NOT AGREE TO THESE |
| | | TERMS, DO NOT DOWNLOAD OR INSTALL THE FORGEROCK SOFTWARE. |
| | | |
| | | ... |
| | | |
| | | Please read the License Agreement above. |
| | | You must accept the terms of the agreement before continuing with the |
| | | installation. |
| | | Accept the license (Yes/No) [No]:Yes |
| | | |
| | | What would you like to use as the initial root user DN for the Directory |
| | | Server? [cn=Directory Manager]: |
| | | Please provide the password to use for the initial root user: |
| | | Please re-enter the password for confirmation: |
| | | |
| | | Provide the fully-qualified directory server host name that will be used when |
| | | generating self-signed certificates for LDAP SSL/StartTLS, the administration |
| | | connector, and replication [opendj.example.com]: |
| | | |
| | | On which port would you like the Directory Server to accept connections from |
| | | LDAP clients? [1389]: |
| | | |
| | | On which port would you like the Administration Connector to accept |
| | | connections? [4444]: |
| | | |
| | | Do you want to create base DNs in the server? (yes / no) [yes]: |
| | | |
| | | Provide the backend type: |
| | | |
| | | 1) JE Backend |
| | | 2) PDB Backend |
| | | |
| | | Enter choice [1]: 2 |
| | | |
| | | Provide the base DN for the directory data: [dc=example,dc=com]: |
| | | |
| | | Options for populating the database: |
| | | |
| | | 1) Only create the base entry |
| | | 2) Leave the database empty |
| | | 3) Import data from an LDIF file |
| | | 4) Load automatically-generated sample data |
| | | |
| | | Enter choice [1]: 3 |
| | | |
| | | Please specify the path to the LDIF file containing the data to import: |
| | | /path/to/Example.ldif |
| | | |
| | | Do you want to enable SSL? (yes / no) [no]: |
| | | |
| | | Do you want to enable Start TLS? (yes / no) [no]: |
| | | |
| | | Do you want to start the server when the configuration is completed? (yes / |
| | | no) [yes]: |
| | | |
| | | |
| | | Setup Summary |
| | | ============= |
| | | LDAP Listener Port: 1389 |
| | | Administration Connector Port: 4444 |
| | | JMX Listener Port: |
| | | LDAP Secure Access: disabled |
| | | Root User DN: cn=Directory Manager |
| | | Directory Data: Create New Base DN dc=example,dc=com. |
| | | Base DN Data: Import Data from LDIF File (/path/to/Example.ldif) |
| | | |
| | | Start Server when the configuration is completed |
| | | |
| | | |
| | | What would you like to do? |
| | | |
| | | 1) Set up the server with the parameters above |
| | | 2) Provide the setup parameters again |
| | | 3) Print equivalent non-interactive command-line |
| | | 4) Cancel and exit |
| | | |
| | | Enter choice [1]: |
| | | |
| | | See /var/.../opendj-setup...log for a detailed log of this operation. |
| | | |
| | | Configuring Directory Server ..... Done. |
| | | Importing LDIF file /path/to/Example.ldif ........... Done. |
| | | Starting Directory Server ........... Done. |
| | | |
| | | To see basic server configuration status and configuration you can launch \ |
| | | /path/to/opendj/bin/status |
| | | $ ./setup --cli --no-prompt --acceptLicense \ |
| | | --hostname localhost --ldapPort 1389 --adminConnectorPort 4444 \ |
| | | --enableStartTLS --ldapsPort 1636 --generateSelfSignedCertificate \ |
| | | --rootUserDN "cn=Directory Manager" --rootUserPasswordFile /path/to/root-password.txt \ |
| | | --baseDN dc=example,dc=com --addBaseEntry |
| | | ---- |
| | | + |
| | | -- |
| | |
| | | The default, `cn=Directory Manager`, is a well-known name. For additional protection, use a different name. |
| | | |
| | | Initial root user password:: |
| | | The root user will use simple, password-based authentication. Later you can limit cleartext access to avoid snooping, but for now use a strong password here unless this is a throwaway server. |
| | | Use a strong password and secure the connection before sending bind credentials. |
| | | |
| | | Fully qualified directory server host name:: |
| | | OpenDJ uses fully qualified host name in self-signed certificates and for identification when you use replication. |
| | |
| | | Administration port:: |
| | | The default is 4444. |
| | | + |
| | | This is the service port used to configure the server and to run tasks. |
| | | This LDAPS port is used to configure the server and run tasks. To serve HTTPS, configure the separate xref:../admin-guide/chap-connection-handlers.adoc#setup-http-connection-handler[HTTP connection handler] after setup. |
| | | |
| | | Create base DNs:: |
| | | You need a base DN, such as `dc=example,dc=com`, to add directory data. If you already have LDIF, the base DN you want is the DN suffix common to all entries in your LDIF. |
| | |
| | | + |
| | | Later you can add more base DNs if your data belongs in more than one suffix. |
| | | |
| | | Import LDIF:: |
| | | LDAP data interchange format (LDIF) is the standard text format for expressing LDAP data. |
| | | Populate the directory:: |
| | | Choose one of `--addBaseEntry`, `--sampleData <number>` or `--ldifFile <path>`. Use `--sampleData` to generate users or import link:../attachments/Example.ldif[Example.ldif] for named sample entries. |
| | | + |
| | | If you have LDIF already, one reason you might not want to import the data right away is because your data uses attributes not defined in the default schema. Add schema definitions after installation, and then import from LDIF. |
| | | + |
| | |
| | | If you are working as a user who cannot open port 636, setup suggests 1636 by default. |
| | | |
| | | TLS:: |
| | | TLS lets you use StartTLS to negotiate a secure connection between a client and server, starting from the same server port you configured for LDAP. |
| | | Pass `--enableStartTLS` to setup to allow TLS negotiation on the LDAP port. OpenDJ LDAP clients request it with `--useStartTLS`. |
| | | |
| | | X.509 certificates:: |
| | | The digital certificate you need for SSL and TLS can be self-signed and created while you are working. Remember that client applications view self-signed certificates like fake IDs, and so do not trust them. |
| | | + |
| | | Self-signed certificates for externally facing ports facilitate testing, but are not intended for production use. |
| | | The installer can generate a self-signed certificate for testing. Clients must explicitly trust that certificate. Use a certificate that your clients already trust for production. |
| | | |
| | | ====== |
| | | |
| | | Start the server:: |
| | | If you do not start the server during installation, you can use the `/path/to/opendj/bin/start-ds` command later. |
| | | Setup starts the server by default. Use `--doNotStart` to defer startup and run `bin/start-ds` when ready. |
| | | |
| | | -- |
| | | |
| | | . Run the `status` command, described in xref:../reference/admin-tools-ref.adoc#status-1[status(1)] in the __Reference__, to make sure your OpenDJ server is working as expected as shown in the following example: |
| | | . Run xref:../reference/admin-tools-ref.adoc#status-1[status(1)] to verify that the server is running and that it has the expected listener ports and base DN. |
| | | + |
| | | |
| | | [source, console, subs="+attributes"] |
| | | [source, console] |
| | | ---- |
| | | $ /path/to/opendj/bin/status |
| | | |
| | | >>>> Specify OpenDJ LDAP connection parameters |
| | | |
| | | Administrator user bind DN [cn=Directory Manager]: |
| | | |
| | | Password for user 'cn=Directory Manager': |
| | | |
| | | --- Server Status --- |
| | | Server Run Status: Started |
| | | Open Connections: 1 |
| | | |
| | | --- Server Details --- |
| | | Host Name: opendj.example.com |
| | | Administrative Users: cn=Directory Manager |
| | | Installation Path: /path/to/opendj |
| | | Version: OpenDJ {opendj-version} |
| | | Java Version: version |
| | | Administration Connector: Port 4444 (LDAPS) |
| | | |
| | | --- Connection Handlers --- |
| | | Address:Port : Protocol : State |
| | | -------------:----------:--------- |
| | | -- : LDIF : Disabled |
| | | 0.0.0.0:161 : SNMP : Disabled |
| | | 0.0.0.0:636 : LDAPS : Disabled |
| | | 0.0.0.0:1389 : LDAP : Enabled |
| | | 0.0.0.0:1689 : JMX : Disabled |
| | | |
| | | --- Data Sources --- |
| | | Base DN: dc=example,dc=com |
| | | Backend ID: userRoot |
| | | Entries: 160 |
| | | Replication: Disabled |
| | | $ ./bin/status |
| | | ---- |
| | | + |
| | | On Windows, run `bat\status.bat`. If prompted, verify the certificate fingerprint and authenticate as the administrator. |
| | | |
| | | [NOTE] |
| | | ====== |
| | | You can install OpenDJ in unattended and silent fashion, too. See the procedure, xref:#install-properties-file["To Install OpenDJ Directory Server With a Properties File"]. |
| | | ====== |
| | | To join servers after CLI setup, see xref:../admin-guide/chap-replication.adoc#enable-repl[Enabling Replication] for replication ports and TLS settings. |
| | | |
| | | ==== |
| | | |
| | |
| | | /opt/opendj/bin/status |
| | | $ sudo systemctl start opendj |
| | | ---- |
| | | + |
| | | On a SysV host, use `sudo /etc/init.d/opendj start`. |
| | | |
| | | . (Optional) Check OpenDJ directory server status: |
| | | . (Optional) Check OpenDJ directory server status. On a SysV host, check the service with `/etc/init.d/opendj status`. |
| | | + |
| | | |
| | | [source, console, subs="+attributes"] |
| | | ---- |
| | | $ systemctl is-active opendj |
| | | active |
| | | $ sudo -u opendj /opt/opendj/bin/status |
| | | |
| | | |
| | | >>>> Specify OpenDJ LDAP connection parameters |
| | | |
| | | Administrator user bind DN [cn=Directory Manager]: |
| | | |
| | | Password for user 'cn=Directory Manager': |
| | | |
| | | --- Server Status --- |
| | | Server Run Status: Started |
| | | Open Connections: 1 |
| | | |
| | | --- Server Details --- |
| | | Host Name: ubuntu.example.com |
| | | Administrative Users: cn=Directory Manager |
| | | Installation Path: /opt/opendj |
| | | Version: OpenDJ {opendj-version} |
| | | Java Version: version |
| | | Administration Connector: Port 4444 (LDAPS) |
| | | |
| | | --- Connection Handlers --- |
| | | Address:Port : Protocol : State |
| | | -------------:------------------------:--------- |
| | | -- : LDIF : Disabled |
| | | 0.0.0.0:161 : SNMP : Disabled |
| | |
| | | /opt/opendj/bin/status |
| | | # systemctl start opendj |
| | | ---- |
| | | + |
| | | On a SysV host, use `/etc/init.d/opendj start`. |
| | | |
| | | . (Optional) Check OpenDJ directory server status: |
| | | . (Optional) Check OpenDJ directory server status. On a SysV host, check the service with `/etc/init.d/opendj status`. |
| | | + |
| | | |
| | | [source, console, subs="+attributes"] |
| | | ---- |
| | | # systemctl is-active opendj |
| | | active |
| | | # runuser -u opendj -- /opt/opendj/bin/status |
| | | |
| | | |
| | | >>>> Specify OpenDJ LDAP connection parameters |
| | | |
| | | Administrator user bind DN [cn=Directory Manager]: |
| | | |
| | | Password for user 'cn=Directory Manager': |
| | | |
| | | --- Server Status --- |
| | | Server Run Status: Started |
| | | Open Connections: 1 |
| | | |
| | | --- Server Details --- |
| | | Host Name: fedora.example.com |
| | | Administrative Users: cn=Directory Manager |
| | | Installation Path: /opt/opendj |
| | | Version: OpenDJ {opendj-version} |
| | | Java Version: version |
| | | Administration Connector: Port 4444 (LDAPS) |
| | | |
| | | --- Connection Handlers --- |
| | | Address:Port : Protocol : State |
| | | -------------:------------------------:--------- |
| | | -- : LDIF : Disabled |
| | | 0.0.0.0:161 : SNMP : Disabled |
| | |
| | | + |
| | | The instance lives under `/opt/opendj/data`. The image declares no volume of its own, so mount one there: a container started without it keeps its instance in the container itself, and removing the container deletes the instance, while a container started again over the same volume serves the same data. The server runs as a non-root user and listens on ports above 1024: LDAP on 1389, LDAPS on 1636, and the administration connector on 4444. The example publishes these ports on the loopback interface of the host only; before you publish them on other interfaces, set a `ROOT_PASSWORD` of your own on the first start. Apart from the replication join described next, the image reads `ROOT_PASSWORD` only when it creates the instance: a container started over an instance that is already there keeps the root password of that instance, which you change with `ldappasswordmodify` as on any other server. A container replicated with `OPENDJ_REPLICATION_TYPE=simple` binds with `ROOT_PASSWORD` to join its topology on every start, so read the link:https://github.com/OpenIdentityPlatform/OpenDJ/blob/master/opendj-packages/opendj-docker/README.md#replication[Replication section of the README of the image, window=\_blank] before you change the root password of one. The root user is `cn=Directory Manager`, with the initial password `ROOT_PASSWORD`, and the base DN is `dc=example,dc=com`; without `ADD_BASE_ENTRY` that suffix is created empty. The `--init` option puts a process in front of the server that reaps the processes left behind to it and passes `SIGTERM` on to it. |
| | | |
| | | . Wait until the container reports itself healthy; `docker inspect` reports `starting` until then, and `unhealthy` once the 5-minute start period is over while the checks still fail: |
| | | . Check the health status. Continue once it reports `healthy`. It reports `starting` during bootstrap and can report `unhealthy` if checks keep failing after the start period. |
| | | + |
| | | |
| | | [source, console] |
| | | ---- |
| | | $ timeout 5m bash -c 'until [ "$(docker inspect -f "{{.State.Health.Status}}" opendj)" = healthy ]; do sleep 5; done' |
| | | $ docker inspect --format '{{.State.Health.Status}}' opendj |
| | | ---- |
| | | + |
| | | On its first start the container starts the server, creates the backend, imports the data that `ADD_BASE_ENTRY` asked for, then stops the server and starts it again, so a client that only waits for the port may see its first requests fail. The container reports itself healthy once all of this has succeeded. A first start that fails never reports healthy: what failed is in `docker logs opendj`. Nor does a later start over the same volume: the volume carries the file `/opt/opendj/data/.bootstrap-pending` from before the first start sets the instance up until it has succeeded, and a container started over a volume that still carries it starts the server so that it can be looked at, logs that the bootstrap did not complete, and does not report itself healthy. To try again, remove the container and its volume, with `docker rm -f opendj` and `docker volume rm opendj-data`, then start over. Alternatively, finish the setup by hand, then remove the file with `docker exec opendj rm /opt/opendj/data/.bootstrap-pending` and restart the container with `docker restart opendj`. |
| | | The first start reports `healthy` after creating the backend, importing the requested data, and restarting the server. If setup fails, check `docker logs opendj`. When `/opt/opendj/data/config` is absent, the next start retries bootstrap after you correct the cause. If the directory exists and the volume still contains `/opt/opendj/data/.bootstrap-pending`, the next start attempts to open the partially configured server for recovery. If the server starts, the container stays `unhealthy`. |
| | | + |
| | | If the container remains running, finish setup by hand, remove the marker with `docker exec opendj rm /opt/opendj/data/.bootstrap-pending`, and run `docker restart opendj`. |
| | | + |
| | | If the container exits, for example because `config.ldif` is missing, keep it stopped and open a temporary shell from the same image. Use `--volumes-from opendj` if the original container has a mount at `/opt/opendj/data`. If its data is in the writable layer, follow the xref:chap-upgrade.adoc#upgrade-docker[upgrade procedure to copy the instance to a new volume]. For the copied instance, set the mount option in the command below to `-v opendj-data:/opt/opendj/data`, using the name of the new volume. |
| | | + |
| | | |
| | | [source, console] |
| | | ---- |
| | | $ opendj_image=$(docker inspect --format '{{.Image}}' opendj) |
| | | $ docker run --rm -it --volumes-from opendj --workdir /opt/opendj \ |
| | | --entrypoint /bin/sh "$opendj_image" |
| | | $ printf '%s\n' /opt/opendj/data > instance.loc |
| | | ---- |
| | | + |
| | | Finish setup from that shell. If OpenDJ started in the temporary container, run `./bin/stop-ds --noPropertiesFile` there and wait for it to succeed. Then remove `/opt/opendj/data/.bootstrap-pending` and exit the shell. If you shared the original data mount, run `docker start opendj` from the host. If you copied the instance, rename the original container to free its name. Create a replacement container from the same image with the original settings and the new data volume. |
| | | + |
| | | To discard the incomplete instance and start over with an empty volume, run `docker rm -f opendj` and `docker volume rm opendj-data`, then repeat the installation. |
| | | |
| | | . (Optional) Check that the server serves the base entry: |
| | | + |
| | |
| | | |
| | | |
| | | [#install-docker-compose] |
| | | Alternatively, save the following as `compose.yaml` and run `docker compose up -d`. This uses a named volume for the same instance directory: |
| | | Alternatively, save the following as `compose.yaml` and run `docker compose up -d --wait`. This uses a named volume for the same instance directory: |
| | | |
| | | [source,yaml] |
| | | ---- |
| | |
| | | opendj-data: |
| | | ---- |
| | | |
| | | Wait for the image's health check to report healthy, as for `docker run` above. `docker compose down` removes the container and network but retains the named volume; `docker compose up -d` then reuses the instance. Adding `--volumes` to `docker compose down` deletes the volume and its directory data. Changing `ROOT_PASSWORD` in the Compose file does not change the password of an existing instance. |
| | | `docker compose down` keeps the named volume for the next `up`. Use `docker compose down --volumes` to delete the instance. `ROOT_PASSWORD` sets the initial password when the instance is created. |
| | | |
| | | ==== |
| | | |
| | | [#install-properties-file] |
| | | .To Install OpenDJ Directory Server With a Properties File |
| | | ==== |
| | | You can install OpenDJ directory server by using the `setup` command with a properties file. |
| | | Map setup options to properties by dropping the leading dashes. Use `true` for a flag such as `enableStartTLS`. If several tools share the file, prefix properties with the tool name, for example `setup.rootUserPasswordFile`. |
| | | |
| | | Property names correspond to the option names, but without leading dashes. Options that take no arguments become boolean properties as in the following example: |
| | | |
| | | [source, ini] |
| | | ---- |
| | | enableStartTLS=true |
| | | ---- |
| | | If you use a properties file with multiple tools, prefix the property name with the tool name followed by a dot (`.`), in the following example: |
| | | |
| | | [source, ini] |
| | | ---- |
| | | setup.rootUserPasswordFile=/tmp/pwd.txt |
| | | ---- |
| | | The following steps demonstrate use of a properties file as part of a scripted installation process: |
| | | |
| | | . Prepare your properties file. |
| | | . In a freshly extracted `opendj` directory on an isolated test host, save the following as `setup.props`. Copy link:../attachments/Example.ldif[Example.ldif] into the same directory and save the administrator password there in a private file named `root-password.txt`. |
| | | + |
| | | This procedure uses the following example properties file: |
| | | + |
| | | |
| | | [source, ini] |
| | | ---- |
| | | # |
| | | # Sample properties file to set up OpenDJ directory server |
| | | # |
| | | hostname =opendj.example.com |
| | | hostname=localhost |
| | | ldapPort =1389 |
| | | adminConnectorPort=4444 |
| | | ldapsPort=1636 |
| | | generateSelfSignedCertificate =true |
| | | enableStartTLS =true |
| | | ldapsPort =1636 |
| | | jmxPort =1689 |
| | | adminConnectorPort =4444 |
| | | rootUserDN =cn=Directory Manager |
| | | rootUserPassword =password |
| | | rootUserPasswordFile=root-password.txt |
| | | baseDN =dc=example,dc=com |
| | | ldifFile =/net/install/dj/Example.ldif |
| | | #sampleData =2000 |
| | | ldifFile=Example.ldif |
| | | ---- |
| | | + |
| | | If you have multiple servers to install, consider scripting creation of the properties files. |
| | | |
| | | . Prepare an installation script: |
| | | . Run setup from that directory. |
| | | + |
| | | |
| | | [source, console, subs="+attributes"] |
| | | ---- |
| | | $ cat /net/install/dj/1/setup.sh |
| | | #!/bin/sh |
| | | |
| | | unzip -d /path/to /net/install/dj/opendj-{opendj-version}.zip && cd /path/to/opendj |
| | | ./setup --cli --propertiesFilePath /net/install/dj/1/setup.props \ |
| | | --acceptLicense --no-prompt |
| | | ---- |
| | | + |
| | | The properties file contains only installation options, and does not fully configure OpenDJ directory server. |
| | | + |
| | | If you also want your script to configure OpenDJ directory server, follow a successful run of the `setup` command with `dsconfig` commands to configure the server. To run a series of configuration commands as a batch using the `dsconfig` command, use either the `--batchFilePath file` option, where __file__ contains the configuration commands, or the `--batch` option to read from standard input as in the following example that creates a backend and sets up indexes: |
| | | + |
| | | |
| | | [source, console] |
| | | ---- |
| | | /path/to/opendj/bin/dsconfig \ |
| | | --port 4444 \ |
| | | --hostname opendj.example.com \ |
| | | --bindDN "cn=Directory Manager" \ |
| | | --bindPassword password \ |
| | | --no-prompt \ |
| | | --trustAll \ |
| | | --batch <<END_OF_COMMAND_INPUT |
| | | create-backend --backend-name newBackend \ |
| | | --type pdb \ |
| | | --set base-dn:"dc=example,dc=org" \ |
| | | --set db-cache-percent:20 \ |
| | | --set enabled:true |
| | | create-backend-index --backend-name newBackend \ |
| | | --type generic \ |
| | | --set index-type:equality \ |
| | | --set index-type:substring \ |
| | | --index-name cn |
| | | create-backend-index --backend-name newBackend \ |
| | | --type generic \ |
| | | --set index-type:equality \ |
| | | --set index-type:substring \ |
| | | --index-name sn |
| | | create-backend-index --backend-name newBackend \ |
| | | --type generic \ |
| | | --set index-type:equality \ |
| | | --index-name uid |
| | | create-backend-index --backend-name newBackend \ |
| | | --type generic \ |
| | | --set index-type:equality \ |
| | | --set index-type:substring \ |
| | | --index-name mail |
| | | END_OF_COMMAND_INPUT |
| | | $ ./setup --cli --propertiesFilePath setup.props --acceptLicense --no-prompt |
| | | ---- |
| | | |
| | | . Run your installation script: |
| | | . Optionally, configure the running server with `dsconfig`. This test example uses `--batch` and trusts the test instance's self-signed certificate. It creates a backend and adds a `displayName` index. Use `--batchFilePath` to read the same commands from a file. |
| | | + |
| | | |
| | | [source, console, subs="+attributes"] |
| | | [source, console] |
| | | ---- |
| | | $ /net/install/dj/1/setup.sh |
| | | Archive: /net/install/dj/opendj-{opendj-version}.zip |
| | | creating: /path/to/opendj |
| | | ... |
| | | inflating: /path/to/opendj/setup |
| | | inflating: /path/to/opendj/uninstall |
| | | inflating: /path/to/opendj/upgrade |
| | | |
| | | READ THIS SOFTWARE LICENSE AGREEMENT CAREFULLY. BY DOWNLOADING OR INSTALLING |
| | | THE FORGEROCK SOFTWARE, YOU, ON BEHALF OF YOURSELF AND YOUR COMPANY, AGREE TO |
| | | BE BOUND BY THIS SOFTWARE LICENSE AGREEMENT. IF YOU DO NOT AGREE TO THESE |
| | | TERMS, DO NOT DOWNLOAD OR INSTALL THE FORGEROCK SOFTWARE. |
| | | |
| | | ... |
| | | |
| | | Do you accept the License Agreement?yes |
| | | See /var/folders/.../opendj-setup-....log for a detailed log of this operation. |
| | | |
| | | Configuring Directory Server ..... Done. |
| | | Configuring Certificates ..... Done. |
| | | Importing LDIF file /net/install/dj/Example.ldif ....... Done. |
| | | Starting Directory Server ....... Done. |
| | | |
| | | To see basic server configuration status and configuration you can launch |
| | | /path/to/opendj/bin/status |
| | | $ ./bin/dsconfig --port 4444 --hostname localhost \ |
| | | --bindDN "cn=Directory Manager" --bindPasswordFile root-password.txt \ |
| | | --no-prompt --trustAll --batch <<COMMANDS |
| | | create-backend --backend-name newBackend --type pdb \ |
| | | --set base-dn:dc=example,dc=org --set db-cache-percent:20 --set enabled:true |
| | | create-backend-index --backend-name newBackend --type generic \ |
| | | --set index-type:equality --index-name displayName |
| | | COMMANDS |
| | | ---- |
| | | + |
| | | At this point you can use OpenDJ directory server, or you can perform additional configuration. |
| | | |
| | | ==== |
| | | |
| | | [#chap-jvm-opts] |
| | | .To Configure Java Runtime Options |
| | | ==== |
| | | Set JVM options on the GUI installer’s Runtime Options screen or edit the instance’s `config/java.properties` after setup. Windows batch launchers read the file from the installation directory. |
| | | |
| | | Set `default.java-home` to select Java, or `<command>.java-home` for a single command. Keep existing options when editing `start-ds.java-args`. Restart the server to apply its settings. |
| | | |
| | | On UNIX, `OPENDJ_JAVA_ARGS` overrides the Java arguments from the file when it is set. For packaged Linux services, check the service environment file described in the package installation procedure. Use the xref:../admin-guide/chap-tuning.adoc#perf-java["Java Settings"] in the __Administration Guide__ to size memory and evaluate garbage collector options for your workload. |
| | | |
| | | ==== |
| | | |
| | |
| | | [#pdb-to-je] |
| | | .To Move Data from a PDB Backend to a JE Backend |
| | | ==== |
| | | Although the `dsconfig` command does not provide a way to change a database backend type, you can move data from a PDB Backend to a JE Backend as demonstrated by the script shown in xref:#example-pdb-to-je["Example Script for Changing a PDB Backend to a JE Backend"]. Alternatively, follow these steps: |
| | | Keep client traffic off the server during migration. For replicated backends, see xref:../admin-guide/chap-replication.adoc#init-repl[replication initialization]. |
| | | |
| | | . List the indexes configured for the PDB backend. |
| | | + |
| | | The following example shows indexes for a `userRoot` PDB backend: |
| | | + |
| | | . Record the base DNs and backend settings with `dsconfig get-backend-prop --advanced`. List the indexes with `dsconfig list-backend-indexes` and `dsconfig list-backend-vlv-indexes`. Save each index's settings with `dsconfig get-backend-index-prop --advanced` or `dsconfig get-backend-vlv-index-prop --advanced`, including settings such as `substring-length` that the list commands omit. |
| | | |
| | | [source, console] |
| | | ---- |
| | | $ dsconfig \ |
| | | list-backend-indexes \ |
| | | --port 4444 \ |
| | | --hostname opendj.example.com \ |
| | | --bindDN "cn=Directory Manager" \ |
| | | --bindPassword password \ |
| | | --backend-name userRoot \ |
| | | --no-prompt \ |
| | | --trustAll |
| | | Backend Index : index-type : index-entry-limit : index-extensible-matching-rule : confidentiality-enabled |
| | | -----------------:---------------------:-------------------:--------------------------------:------------------------ |
| | | aci : presence : 4000 : - : false |
| | | cn : equality, substring : 4000 : - : false |
| | | ds-sync-conflict : equality : 4000 : - : false |
| | | ds-sync-hist : ordering : 4000 : - : false |
| | | entryUUID : equality : 4000 : - : false |
| | | givenName : equality, substring : 4000 : - : false |
| | | mail : equality, substring : 4000 : - : false |
| | | member : equality : 4000 : - : false |
| | | objectClass : equality : 4000 : - : false |
| | | sn : equality, substring : 4000 : - : false |
| | | telephoneNumber : equality, substring : 4000 : - : false |
| | | uid : equality : 4000 : - : false |
| | | uniqueMember : equality : 4000 : - : false |
| | | ---- |
| | | . Stop the server. Back up the full instance, including the PDB database files, and export the backend to LDIF. Save the backup and LDIF outside the backend directory and restrict access to both. |
| | | |
| | | . Export the data in the PDB backend to LDIF. |
| | | + |
| | | For instructions, see xref:../admin-guide/chap-import-export.adoc#importing-exporting-ldif["Importing and Exporting Data"] in the __Administration Guide__. |
| | | . Start the server with client traffic still disabled. Use `dsconfig delete-backend` to remove the PDB backend configuration. The command leaves the PDB database files in place. |
| | | |
| | | . Delete the PDB backend. |
| | | + |
| | | For instructions, see xref:../admin-guide/chap-import-export.adoc#delete-database-backend["Deleting a Database Backend"] in the __Administration Guide__. |
| | | . Use `dsconfig create-backend --type je` with the same backend ID and base DNs. Set `db-directory` to a different directory so the PDB files remain available for recovery. Apply the relevant original settings and recreate your custom indexes as described in xref:../admin-guide/chap-indexing.adoc#configure-indexes["Configuring and Rebuilding Indexes"]. |
| | | |
| | | . Create a JE backend. |
| | | + |
| | | For instructions, see xref:../admin-guide/chap-import-export.adoc#create-database-backend["Creating a New Database Backend"] in the __Administration Guide__. |
| | | |
| | | . Create the same indexes for the JE backend that were present in the PDB backend. |
| | | + |
| | | For instructions, see xref:../admin-guide/chap-indexing.adoc#configure-indexes["Configuring and Rebuilding Indexes"] in the __Administration Guide__. |
| | | |
| | | . Import the data from LDIF into the JE backend. |
| | | . Stop the server and import the LDIF into the JE backend. Start the server and verify the data and indexes before restoring client traffic. If migration fails, keep client traffic disabled and restore the stopped server from the file-system backup. |
| | | |
| | | ==== |
| | | |
| | | [#example-pdb-to-je] |
| | | .Example Script for Changing a PDB Backend to a JE Backend |
| | | .Example Migration of a PDB Backend to a JE Backend |
| | | ==== |
| | | The following Bash script demonstrates how to change a PDB backend to a JE Backend: |
| | | From the installation directory, stop and back up the test instance before starting. The example assumes `userRoot` has the default indexes. Use an unused `db-directory` for the JE files. |
| | | |
| | | [source, bash] |
| | | [source, console] |
| | | ---- |
| | | #!/usr/bin/env bash |
| | | # |
| | | # The contents of this file are subject to the terms of the Common Development and |
| | | # Distribution License (the License). You may not use this file except in compliance with the |
| | | # License. |
| | | # |
| | | # You can obtain a copy of the License at legal-notices/CDDLv1.0.txt. See the License for the |
| | | # specific language governing permission and limitations under the License. |
| | | # |
| | | # When distributing Covered Software, include this CDDL Header Notice in each file and include |
| | | # the License file at legal-notices/CDDLv1.0.txt. If applicable, add the following below the CDDL |
| | | # Header, with the fields enclosed by brackets [] replaced by your own identifying |
| | | # information: "Portions Copyright [year] [name of copyright owner]". |
| | | # |
| | | # Copyright 2017-2018 ForgeRock AS. |
| | | # |
| | | |
| | | if test $# -ne 1 |
| | | then |
| | | echo "Usage: $0 backendID" |
| | | echo "Migrate a PDB backend to a JE backend with all the data." |
| | | echo "Run this script from the server base directory, such as /path/to/opendj." |
| | | exit 1 |
| | | fi |
| | | |
| | | # Check that the server is stopped. |
| | | echo "Verifying that the server is stopped..." |
| | | ./bin/status -n -s > /dev/null |
| | | if test $? -ne 0 |
| | | then |
| | | echo "The Directory Server must be stopped to migrate a backend." |
| | | echo "Please stop the server and relaunch the script." |
| | | exit 1 |
| | | fi |
| | | echo "" |
| | | |
| | | # Check for instance.loc. |
| | | LOC=. |
| | | if [ -f ./instance.loc ] |
| | | then |
| | | LOC=`cat ./instance.loc` |
| | | elif [ -f /etc/opendj/instance.loc ] |
| | | then |
| | | LOC=`cat /etc/opendj/instance.loc` |
| | | fi |
| | | |
| | | # Check the backendID. |
| | | echo "Verifying the backend $1" |
| | | DN=`./bin/ldifsearch --ldifFile "$LOC"/config/config.ldif "(&(objectclass=ds-cfg-pdb-backend)(ds-cfg-backend-id=$1))" dn | grep "^dn:"` |
| | | if [ -z "$DN" ] |
| | | then |
| | | echo "Could not find a PDB backend with this name. Exiting." |
| | | exit 2 |
| | | fi |
| | | |
| | | echo "Exporting data to /tmp/data_$$" |
| | | # Export data from the PDB backend. |
| | | ./bin/export-ldif -n "$1" -l /tmp/data_$$ |
| | | if test $? -ne 0 |
| | | then |
| | | echo "Export from PDB failed." |
| | | exit 3 |
| | | fi |
| | | |
| | | echo "Updating configuration" |
| | | # Change the PDB backend configuration to a JE backend configuration. |
| | | cat > /tmp/changes_$$ << EOF |
| | | $DN |
| | | changetype: modify |
| | | delete: objectClass |
| | | objectClass: ds-cfg-pdb-backend |
| | | - |
| | | add: objectClass |
| | | objectClass: ds-cfg-je-backend |
| | | - |
| | | replace: ds-cfg-java-class |
| | | ds-cfg-java-class: org.opends.server.backends.jeb.JEBackend |
| | | EOF |
| | | |
| | | ./bin/ldifmodify --outputLDIF "$LOC"/config/config.ldif.$$ "$LOC"/config/config.ldif /tmp/changes_$$ |
| | | if test $? -ne 0 |
| | | then |
| | | echo "Modifications failed. Restoring the original configuration" |
| | | rm /tmp/changes_$$ |
| | | exit 4 |
| | | fi |
| | | |
| | | cp "$LOC"/config/config.ldif.$$ "$LOC"/config/config.ldif |
| | | echo "Configuration updates done." |
| | | echo "Importing data..." |
| | | # Import the data into the JE backend. |
| | | ./bin/import-ldif -n $1 -l /tmp/data_$$ |
| | | if test $? -ne 0 |
| | | then |
| | | echo "Importing data failed." |
| | | echo "The exported data file is /tmp/data_$$" |
| | | exit 5 |
| | | fi |
| | | echo "Backend $1 converted successfully from PDB to JE." |
| | | rm /tmp/data_$$ |
| | | rm /tmp/changes_$$ |
| | | rm "$LOC"/config/config.ldif.$$ |
| | | $ (umask 077; ./bin/export-ldif --offline --backendID userRoot --ldifFile /path/to/userRoot.ldif) |
| | | $ ./bin/start-ds |
| | | ---- |
| | | |
| | | The `--trustAll` option in this example is for an isolated test instance. |
| | | |
| | | [source, console] |
| | | ---- |
| | | $ ./bin/dsconfig --hostname localhost --port 4444 --bindDN "cn=Directory Manager" \ |
| | | --bindPasswordFile /path/to/root-password.txt --trustAll --no-prompt --batch <<'COMMANDS' |
| | | delete-backend --backend-name userRoot |
| | | create-backend --backend-name userRoot --type je --set base-dn:dc=example,dc=com --set db-directory:db-je --set enabled:true |
| | | COMMANDS |
| | | $ ./bin/stop-ds |
| | | $ ./bin/import-ldif --offline --backendID userRoot --ldifFile /path/to/userRoot.ldif |
| | | $ ./bin/start-ds |
| | | ---- |
| | | |
| | | Use `status` and an LDAP search to check the backend and its data. Keep the backup until you have verified the migration. |
| | | |
| | | ==== |
| | | |
| | | [#install-rest2ldap-servlet] |
| | | .To Install OpenDJ REST to LDAP Gateway |
| | | ==== |
| | | The OpenDJ REST to LDAP gateway functions as a web application in a web application container, running independently of OpenDJ. Alternatively, you can use the HTTP connection handler in OpenDJ directory server. For instructions see xref:../admin-guide/chap-connection-handlers.adoc#setup-rest2ldap-endpoint["To Set Up REST Access to User Data"] in the __Administration Guide__. |
| | | -- |
| | | You configure the gateway to access your directory service by editing configuration files in the deployed web application: |
| | | For REST access through the directory server itself, see xref:../admin-guide/chap-connection-handlers.adoc#setup-rest2ldap-endpoint["To Set Up REST Access to User Data"]. |
| | | |
| | | `WEB-INF/classes/config.json`:: |
| | | This file defines how the gateway connects to LDAP directory servers, and how user identities extracted from HTTP requests map to LDAP user identities. |
| | | |
| | | . Deploy `org.openidentityplatform.opendj.opendj-rest2ldap-servlet.war` with the context path `/rest2ldap`. The gateway needs `WEB-INF/classes/config.json` as a file on disk. |
| | | + |
| | | For details, see xref:../reference/appendix-rest2ldap.adoc#config-json["Gateway Configuration File"] in the __Reference__. |
| | | |
| | | `WEB-INF/classes/logging.properties`:: |
| | | This file defines logging properties, and can be used when the gateway runs in Apache Tomcat. |
| | | |
| | | `WEB-INF/classes/rest2ldap/rest2ldap.json`:: |
| | | This file defines which LDAP features the gateway uses. |
| | | |
| | | On a Tomcat Host with `unpackWARs=true` (the default), copy the archive into the Host's `appBase` directory (usually `webapps`) as `rest2ldap.war`. |
| | | + |
| | | For details, see xref:../reference/appendix-rest2ldap.adoc#rest2ldap-json["Gateway REST2LDAP Configuration File"] in the __Reference__. |
| | | On a Host with `unpackWARs=false`, keep the archive outside `appBase`. Move any previously deployed `rest2ldap.war` out of `appBase` before unpacking the archive into the `rest2ldap/` directory under `appBase`. |
| | | |
| | | `WEB-INF/classes/rest2ldap/endpoints/api/example-v1.json`:: |
| | | This file defines JSON resource to LDAP entry mappings. |
| | | |
| | | . In `WEB-INF/classes/config.json`, set `ldapConnectionFactories.bind.primaryLdapServers` to the LDAP host and port. Set `ldapConnectionFactories.root.authentication.simple` to a dedicated LDAP account with the `proxied-auth` privilege and an ACI scoped to the users it may represent. HTTP Basic and OAuth 2.0 both require this account. See xref:../server-dev-guide/chap-ldap-operations.adoc#proxied-authz["Configuring Proxied Authorization"]. |
| | | + |
| | | You can edit this file, and define additional files for alternative APIs and versions of APIs. For details, see xref:../reference/appendix-rest2ldap.adoc#mappings-json["Mapping Configuration File"] in the __Reference__. |
| | | |
| | | -- |
| | | Follow these steps to install the OpenDJ REST to LDAP gateway: |
| | | |
| | | . Deploy `org.openidentityplatform.opendj.opendj-rest2ldap-servlet.war` according to the instructions for your application server. |
| | | |
| | | . Edit the configuration files in the deployed gateway web application. |
| | | For LDAPS or StartTLS with a private CA, configure its truststore in the xref:../reference/appendix-rest2ldap.adoc#config-json[gateway configuration file]. |
| | | + |
| | | At minimum adjust the following configuration settings in `WEB-INF/classes/config.json`: |
| | | |
| | | * `primaryLDAPServers`: Set to the correct directory server host names and port numbers. |
| | | |
| | | * `authentication`: Set to the correct simple bind credentials. |
| | | + |
| | | The LDAP account used to authenticate needs to perform proxied authorization as described in xref:../server-dev-guide/chap-ldap-operations.adoc#proxied-authz["Configuring Proxied Authorization"] in the __Directory Server Developer's Guide__. |
| | | + |
| | | The default sample configuration configuration is built to work with generated example data and also the sample content in link:../attachments/Example.ldif[Example.ldif, window=\_blank]. If your data is different, then you must also change the JSON resource to LDAP entry mapping settings, described in xref:../reference/appendix-rest2ldap.adoc#mappings-json["Mapping Configuration File"] in the __Reference__. |
| | | + |
| | | For details regarding the configuration, see xref:../reference/appendix-rest2ldap.adoc#appendix-rest2ldap["REST to LDAP Configuration"] in the __Reference__. |
| | | + |
| | | When connecting to directory servers over LDAPS or LDAP and StartTLS, you can configure the trust manager to use a file-based truststore for server certificates that the gateway should trust. This allows the gateway to validate server certificates signed, for example, by a Certificate Authority not recognized by the Java environment when setting up LDAPS or StartTLS connections. See xref:../admin-guide/chap-connection-handlers.adoc#setup-server-cert["Preparing For Secure Communications"] in the __Administration Guide__ for an example of how to use the Java `keytool` command to import a server certificate into a truststore file. |
| | | The supplied mappings work with generated sample data and link:../attachments/Example.ldif[Example.ldif]. For other data, update xref:../reference/appendix-rest2ldap.adoc#mappings-json[`WEB-INF/classes/rest2ldap/endpoints/api/example-v1.json`]. See xref:../reference/appendix-rest2ldap.adoc#rest2ldap-json[`WEB-INF/classes/rest2ldap/rest2ldap.json`] for LDAP feature settings. |
| | | |
| | | . (Optional) If necessary, adjust the log level. |
| | | + |
| | |
| | | Messages are written to the Jetty log. |
| | | |
| | | |
| | | . Restart the REST to LDAP gateway or the application server to make sure the configuration changes are taken into account. |
| | | |
| | | . Make sure that your directory server is running, and then check that the gateway is connecting correctly. |
| | | . Restart the gateway. With `Example.ldif` loaded, read Babs Jensen's entry over HTTPS. Enter `hifalutin` when prompted. |
| | | + |
| | | The following command reads Babs Jensen's entry through the gateway to a directory server holding data from `Example.ldif`. In this example, the gateway is deployed under `/rest2ldap`: |
| | | + |
| | | |
| | | [source, console] |
| | | ---- |
| | | $ curl http://bjensen:hifalutin@opendj.example.com:8080/rest2ldap/api/users/bjensen |
| | | { |
| | | "_id" : "bjensen", |
| | | "_rev" : "0000000084ebc394", |
| | | "_schema" : "frapi:opendj:rest2ldap:posixUser:1.0", |
| | | "_meta" : { }, |
| | | "userName" : "bjensen@example.com", |
| | | "displayName" : [ "Barbara Jensen", "Babs Jensen" ], |
| | | "name" : { |
| | | "givenName" : "Barbara", |
| | | "familyName" : "Jensen" |
| | | }, |
| | | "description" : "Original description", |
| | | "contactInformation" : { |
| | | "telephoneNumber" : "+1 408 555 1862", |
| | | "emailAddress" : "bjensen@example.com" |
| | | }, |
| | | "uidNumber" : "1076", |
| | | "gidNumber" : "1000", |
| | | "homeDirectory" : "/home/bjensen", |
| | | "manager" : { |
| | | "_id" : "trigden", |
| | | "displayName" : "Torrey Rigden" |
| | | } |
| | | } |
| | | $ curl --fail --user bjensen https://opendj.example.com:8443/rest2ldap/api/users/bjensen |
| | | ---- |
| | | + |
| | | If you generated example data, Babs Jensen's entry is not included. Instead, try a URL such as `\http://user.0:password@opendj.example.com:8080/rest2ldap/api/users/user.0`. |
| | | The result should contain `"_id": "bjensen"`. With generated sample data, use `user.0` for the user and resource ID and `password` at the prompt. |
| | | |
| | | ==== |
| | | |
| | | [#install-rest2ldap-servlet-3-0] |
| | | .To Install OpenDJ REST to LDAP Gateway (3.0) |
| | | .To Install the Legacy OpenDJ 3.0 REST to LDAP Gateway |
| | | ==== |
| | | The OpenDJ REST to LDAP gateway functions as a web application in a web application container, running independently of OpenDJ. Alternatively, you can use the HTTP connection handler in OpenDJ directory server. For instructions see xref:../admin-guide/chap-connection-handlers.adoc#setup-rest2ldap-connection-handler["To Set Up REST Access to OpenDJ Directory Server"] in the __Administration Guide__. |
| | | |
| | | [NOTE] |
| | | ====== |
| | | This procedure applies to OpenDJ REST to LDAP gateway 3.0. If you are using OpenDJ REST to LDAP gateway 3.5, see xref:#install-rest2ldap-servlet["To Install OpenDJ REST to LDAP Gateway"]. |
| | | This historical procedure requires the REST to LDAP gateway WAR from OpenDJ 3.0. For the WAR distributed with current releases, see xref:#install-rest2ldap-servlet["To Install OpenDJ REST to LDAP Gateway"]. |
| | | ====== |
| | | You configure the gateway to access your directory service by editing the configuration file `opendj-rest2ldap-servlet.json` in the deployed OpenDJ REST to LDAP gateway web application: |
| | | |
| | | . Deploy `org.openidentityplatform.opendj.opendj-rest2ldap-servlet.war` according to the instructions for your application server. |
| | | . Deploy the OpenDJ 3.0 REST to LDAP gateway WAR according to the instructions for your application server. |
| | | |
| | | . Edit `opendj-rest2ldap-servlet.json` where you deployed the gateway web application. |
| | | + |
| | |
| | | ==== |
| | | |
| | | [#install-dsml-gateway] |
| | | .To Install OpenDJ DSML gateway |
| | | .To Install OpenDJ DSML Gateway |
| | | ==== |
| | | The OpenDJ DSML gateway functions as a web application in a web application container. The DSML gateway runs independently of OpenDJ directory server. You configure the gateway to access your directory service by editing the `ldap.host` and `ldap.port` parameters in the gateway `WEB-INF/web.xml` configuration file: |
| | | . Deploy `org.openidentityplatform.opendj.opendj-dsml-servlet.war` with the context path `/dsml`. For Tomcat automatic deployment, copy the archive into the `webapps` directory as `dsml.war`. |
| | | |
| | | . Deploy `org.openidentityplatform.opendj.opendj-dsml-servlet.war` according to the instructions for your application server. |
| | | . Set `ldap.host` and `ldap.port` in the deployed `WEB-INF/web.xml` to match the LDAP server. To secure the LDAP connection, configure `ldap.usessl` or `ldap.usestarttls` and the gateway's truststore settings. |
| | | |
| | | . Edit `WEB-INF/web.xml` to ensure the values for `ldap.host` and `ldap.port` are correct. |
| | | . Assign the `dsml-user` role in the servlet container’s security realm. The gateway forwards HTTP Basic credentials to LDAP. With the default settings, use the LDAP bind DN and password as the HTTPS credentials. |
| | | |
| | | . Restart the web application container according to the instructions for your application server. |
| | | . Restart the gateway. Test with a user from `Example.ldif` who has the `dsml-user` role. Enter `hifalutin` when prompted. |
| | | + |
| | | [source, console] |
| | | ---- |
| | | $ curl --fail --user 'uid=bjensen,ou=People,dc=example,dc=com' \ |
| | | --header 'Content-Type: text/xml' --data-binary @- \ |
| | | https://opendj.example.com:8443/dsml/DSMLServlet <<'EOF' |
| | | <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> |
| | | <soap:Body> |
| | | <batchRequest xmlns="urn:oasis:names:tc:DSML:2:0:core"> |
| | | <searchRequest dn="dc=example,dc=com" scope="baseObject" derefAliases="neverDerefAliases"> |
| | | <filter><present name="objectClass"/></filter> |
| | | </searchRequest> |
| | | </batchRequest> |
| | | </soap:Body> |
| | | </soap:Envelope> |
| | | EOF |
| | | ---- |
| | | + |
| | | The SOAP response should contain a `searchResultEntry` for `dc=example,dc=com` and a result code of `0`. |
| | | |
| | | ==== |
| | | |
| | |
| | | information: "Portions copyright [year] [name of copyright owner]". |
| | | |
| | | Copyright 2017 ForgeRock AS. |
| | | Portions Copyright 2024-2026 3A Systems LLC. |
| | | Portions Copyright 2024-2026 3A Systems, LLC. |
| | | //// |
| | | |
| | | :figure-caption!: |
| | |
| | | + |
| | | (UNIX) Run `/path/to/opendj/uninstall`. |
| | | + |
| | | (Windows) Double-click `/path/to/opendj\uninstall.bat`. |
| | | (Windows) Double-click `C:\path\to\opendj\uninstall.bat`. |
| | | + |
| | | (Mac OS X) Double-click `/path/to/opendj/Uninstall.app`. |
| | | (macOS) Double-click `/path/to/opendj/Uninstall.app`. |
| | | + |
| | | The Uninstall Options screen appears. |
| | | |
| | |
| | | .To Uninstall OpenDJ From the Command-Line |
| | | ==== |
| | | |
| | | . Login as the user who installed and runs the server. |
| | | . Log in as the user who installed and runs the server. If you need to retain directory data or configuration, back up the installation and any separate instance directory first. |
| | | |
| | | . Run the `/path/to/opendj/uninstall --cli` command. |
| | | . Run the uninstaller interactively. Select all components or the components to remove. If the server is running, the uninstaller asks whether to stop it. |
| | | + |
| | | This command starts the removal program in interactive mode on the command-line, prompting you for each option. Alternatively, use additional `uninstall` options to specify choices for the options. See `uninstall --help` for more information: |
| | | + |
| | | |
| | | [source, console] |
| | | ---- |
| | | $ /path/to/opendj/uninstall --cli |
| | | Do you want to remove all components of the server or select the components to |
| | | remove? |
| | | |
| | | 1) Remove all components |
| | | 2) Select the components to be removed |
| | | |
| | | q) quit |
| | | |
| | | Enter choice [1]: |
| | | |
| | | The server is currently running and must be stopped before uninstallation can |
| | | continue. |
| | | Stop the Server and permanently delete the files? (yes / no) [yes]: |
| | | |
| | | Stopping Directory Server ..... Done. |
| | | Deleting Files under the Installation Path ..... Done. |
| | | |
| | | The Uninstall Completed Successfully. |
| | | To complete the uninstallation, you must delete manually the following files |
| | | and directories: |
| | | /path/to/opendj/lib |
| | | See /var/....log for a detailed log of this operation. |
| | | ---- |
| | | |
| | | . If the command output tells you to delete files manually, then remove those remaining files to complete the process: |
| | | + |
| | | On Windows, run `uninstall.bat --cli` from the installation directory. To remove all components without prompts, run `uninstall --cli --remove-all --no-prompt`. |
| | | |
| | | [source, console] |
| | | ---- |
| | | $ rm -rf /path/to/opendj |
| | | ---- |
| | | . Review the list of files that the uninstaller could not remove. Delete those files manually when you no longer need them. |
| | | |
| | | ==== |
| | | |
| | |
| | | [source, console] |
| | | ---- |
| | | $ sudo dpkg -r opendj |
| | | (Reading database ... 185725 files and directories currently installed.) |
| | | Removing opendj ... |
| | | *Stopping OpenDJ server... |
| | | Stopping Server... |
| | | [03/Jun/2013:10:00:49 +0200] category=BACKEND severity=NOTICE |
| | | msgID=9896306 msg=The backend userRoot is now taken offline |
| | | [03/Jun/2013:10:00:49 +0200] category=CORE severity=NOTICE |
| | | msgID=458955 msg=The Directory Server is now stopped |
| | | |
| | | $ |
| | | ---- |
| | | + |
| | | Removing the package stops the server but does not remove your data or configuration, nor the dedicated `opendj` system user it created. Remove `/opt/opendj` manually to delete all files, and remove the `opendj` user if you no longer need it. |
| | | Removal leaves the instance data and configuration under `/opt/opendj` and keeps the `opendj` account. Delete them when you no longer need them. |
| | | |
| | | ==== |
| | | |
| | |
| | | [source, console] |
| | | ---- |
| | | # rpm -e opendj |
| | | Pre Uninstall - uninstall |
| | | Stopping Server... |
| | | [03/Jun/2013:10:42:46 +0200] category=BACKEND severity=NOTICE |
| | | msgID=9896306 msg=The backend userRoot is now taken offline |
| | | [03/Jun/2013:10:42:46 +0200] category=CORE severity=NOTICE |
| | | msgID=458955 msg=The Directory Server is now stopped |
| | | Post Uninstall - uninstall |
| | | OpenDJ package removed. Server data (config, db, changelogDb, logs) |
| | | and the opendj system account are kept; remove them manually if they |
| | | are no longer needed. |
| | | # |
| | | ---- |
| | | + |
| | | Removing the package stops the server but does not remove your data or configuration, nor the dedicated `opendj` system user it created. Remove `/opt/opendj` manually to delete all files, and remove the `opendj` user if you no longer need it. |
| | | Removal leaves the instance data and configuration under `/opt/opendj` and keeps the `opendj` account. Delete them when you no longer need them. |
| | | |
| | | ==== |
| | | |
| | |
| | | information: "Portions copyright [year] [name of copyright owner]". |
| | | |
| | | Copyright 2017 ForgeRock AS. |
| | | Portions Copyright 2024-2026 3A Systems LLC. |
| | | Portions Copyright 2024-2026 3A Systems, LLC. |
| | | //// |
| | | |
| | | :figure-caption!: |
| | |
| | | |
| | | * xref:#upgrade-zip["To Upgrade to OpenDJ {opendj-version-short}"] |
| | | |
| | | * xref:#upgrade-zip-example["Upgrading to OpenDJ {opendj-version-short}"] |
| | | * xref:#upgrade-zip-example["Example ZIP Upgrade"] |
| | | |
| | | * xref:#upgrade-msi["To Upgrade the Windows MSI Installation"] |
| | | |
| | | * xref:#upgrade-docker["To Upgrade a Docker Container"] |
| | | |
| | | * xref:#upgrade-dn-parsing["To Check Stored DNs When Upgrading From a Release Before 5.2.0"] |
| | | |
| | | * xref:#upgrade-repl["To Upgrade Replicated Servers"] |
| | | |
| | | * xref:#new-repl-mixed-topology["To Add a New Replica to an Existing Topology"] |
| | |
| | | .Before You Upgrade |
| | | ==== |
| | | |
| | | . Prepare to perform the upgrade procedure as the user who owns the OpenDJ server files. |
| | | + |
| | | Make sure you have the credentials to run commands as the user who owns the server. |
| | | . Run the upgrade as the account that owns the server files. |
| | | |
| | | . (Optional) If OpenDJ directory server runs with Java 7, move to a newer version, at least Java 11, before continuing the upgrade process. |
| | | . Use Java 11 or later for the new server. If the old server needs an earlier runtime, stop it before switching Java. |
| | | + |
| | | To move to a newer version, edit the `default.java-home` setting in the `opendj/config/java.properties` file, and then run the `dsjavaproperties` command. |
| | | For ZIP installations, see xref:chap-install.adoc#chap-jvm-opts["To Configure Java Runtime Options"]. Linux packages use their Java dependency or service environment. Docker supplies Java in the image. |
| | | |
| | | . Download the latest release from the link:https://github.com/OpenIdentityPlatform/OpenDJ/releases[GitHub, window=\_blank] site. |
| | | |
| | | . (Optional) If you are upgrading OpenDJ directory server on Windows, and OpenDJ is registered as a Windows service, disable OpenDJ as a Windows service before upgrade, as in the following example: |
| | | . For a ZIP installation on Windows registered as a service, disable the service before replacing files. For an MSI installation, follow the service instructions in xref:#upgrade-msi["To Upgrade the Windows MSI Installation"]. |
| | | + |
| | | |
| | | [source, console] |
| | |
| | | + |
| | | After upgrade, you can enable OpenDJ as a Windows service again. |
| | | |
| | | . Make sure you perform a full backup of your current OpenDJ installation to revert if the upgrade fails. |
| | | + |
| | | Due to changes to the backup archive format, make sure you stop OpenDJ directory server and back up the file system directory where the current OpenDJ directory server is installed rather than creating a backup archive with the `backup` command. |
| | | . Stop the server. Back up the installation directory, the instance directory named by `instance.loc`, and any configuration or data stored elsewhere. Store the file-system backup outside these directories so you can restore the binaries and data. |
| | | |
| | | ==== |
| | | |
| | | [#upgrade-zip] |
| | | .To Upgrade to OpenDJ {opendj-version-short} |
| | | ==== |
| | | Before starting this procedure, follow the steps in xref:#before-you-upgrade["Before You Upgrade"]. |
| | | Follow xref:#before-you-upgrade["Before You Upgrade"] first. |
| | | |
| | | To upgrade OpenDJ directory server installed from native packages (.deb, .rpm), install the newer package with the system package manager (`sudo apt-get install ./opendj_{opendj-version}-1_all.deb` or `sudo dnf install ./opendj-{opendj-version}-1.noarch.rpm`). The package stops the running server, runs the `upgrade` tool as the dedicated `opendj` user, migrates file ownership under `/opt/opendj` to that user, and restarts the service (systemd, with a SysV init fallback) if it was running before the upgrade. Back up the installation directory first, as described in xref:#before-you-upgrade["Before You Upgrade"]. |
| | | For a native package, install the new package with `sudo apt-get install ./opendj_{opendj-version}-1_all.deb` or `sudo dnf install ./opendj-{opendj-version}-1.noarch.rpm`. The package updates file ownership and runs `upgrade` as `opendj`. If the service is stopped after the upgrade, start it with `sudo systemctl start opendj` or `sudo /etc/init.d/opendj start` on SysV. |
| | | |
| | | After the upgrade the server runs as the non-root `opendj` user. An instance that listens on privileged ports such as LDAP 389 or LDAPS 636 keeps working under systemd, where the service is granted `CAP_NET_BIND_SERVICE`. On non-systemd hosts that use the SysV init script, grant the capability another way (for example `authbind` or an `iptables` redirect) or use ports above 1024, as described in the installation chapter. |
| | | |
| | | [NOTE] |
| | | ====== |
| | | OpenDJ directory server backend storage options have changed since OpenDJ 2.6. The underlying implementation is based on an extensible architecture, allowing you to choose the backend storage type when you create a persistent backend for directory data. |
| | | |
| | | This procedure applies when you upgrade from OpenDJ 2.6, retaining the same underlying backend storage. The configuration changes from a Local DB backend to a JE Backend, and the upgrade procedure migrates the underlying backend database. There is no need to export data to LDIF when following this procedure. |
| | | Upgrading a standard OpenDJ 2.6 installation migrates the Local DB backend to JE in place. |
| | | ====== |
| | | The following steps describe how to upgrade OpenDJ directory server installed from the cross-platform (.zip) delivery: |
| | | For a ZIP installation, follow these steps with the server stopped and backed up. |
| | | |
| | | . Log in as the user who owns the current OpenDJ server. |
| | | |
| | | . Stop the current OpenDJ server. |
| | | |
| | | . (Optional) If you have not already backed up the current OpenDJ server, make a back up copy of the directory where OpenDJ is installed. |
| | | |
| | | . Unpack the new files from the .zip delivery over the current server files. |
| | | . Unpack the new ZIP archive over the existing server files. The archive expands into `opendj`. If your installation uses a different directory name, unpack into a staging directory and copy its contents over the installation, replacing read-only templates as in the example below. |
| | | + |
| | | [NOTE] |
| | | ====== |
| | |
| | | That file is a duplicate library that shipped in older distributions and is no longer part of the delivery, so unpacking the new archive over the existing installation neither overwrites nor removes it. Because the server builds its classpath from `lib/*`, the leftover jar makes the runtime report the old binary version, and the server fails to start after the upgrade with an error such as `The OpenDJ binary version '5.1.1...' does not match the installed version '5.1.2...'. Please run upgrade before continuing`. |
| | | ====== |
| | | |
| | | . Run the `upgrade` command, described in xref:../reference/admin-tools-ref.adoc#upgrade-1[upgrade(1)] in the __Reference__, to bring OpenDJ configuration and application data up to date with the new binary and script files that you copied over the current server files. |
| | | + |
| | | By default, the `upgrade` command requests confirmation before making important configuration changes. For some potentially long-duration tasks, such as rebuilding indexes, the default choice is to defer the tasks until after upgrade. Tasks that are not performed during upgrade must generally be performed after upgrade but before you restart the server. |
| | | + |
| | | You can use the `--no-prompt` option to run the command non-interactively, with the `--acceptLicense` option to accept the license terms non-interactively. |
| | | + |
| | | When using the `--no-prompt` option, if the `upgrade` command cannot complete because it requires confirmation for a potentially very long or critical task, then it exits with an error and a message about how to finish making the changes. You can add the `--force` option to force a non-interactive upgrade to continue in this case, also performing long running and critical tasks. |
| | | . Run xref:../reference/admin-tools-ref.adoc#upgrade-1[upgrade(1)] to update configuration and data. For an unattended run, use `--no-prompt --acceptLicense`. Add `--force` to run tasks that require confirmation. Complete any deferred tasks before restarting. |
| | | |
| | | . Start the upgraded OpenDJ server. |
| | | + |
| | |
| | | |
| | | [NOTE] |
| | | ====== |
| | | When you upgrade to OpenDJ 5.0 from an OpenDJ 3 or earlier, the upgrade procedure leaves the HTTP connection handler disabled. |
| | | The newer configuration supports inheritance and subsresources, but is not compatible with the previous configuration. |
| | | When you upgrade from a release older than 3.5, the upgrade procedure disables the HTTP connection handler by default. The newer configuration supports inheritance and subresources and uses a different format. |
| | | You must rewrite your configuration to the version described in xref:../reference/appendix-rest2ldap.adoc#appendix-rest2ldap["REST to LDAP Configuration"] in the __Reference__, and then reconfigure the server to use the new configuration. For details, see xref:../admin-guide/chap-connection-handlers.adoc#setup-rest2ldap["RESTful Client Access Over HTTP"] in the __Administration Guide__. |
| | | ====== |
| | | |
| | |
| | | ==== |
| | | |
| | | [#upgrade-zip-example] |
| | | .Upgrading to OpenDJ 5.0 |
| | | .Example ZIP Upgrade |
| | | ==== |
| | | The following example upgrades an OpenDJ 2.6.3 directory server, backing up the current server directory in case the upgrade process fails. In this example, the server properties are updated to use Java 11, and the Local DB backend is migrated to a JE backend: |
| | | This UNIX example upgrades 5.1.2 to 5.2.0 with the tools in `renamed-opendj` and data in the sibling directory `instance`. Adjust the paths and review the xref:#upgrade-dn-parsing[stored DN and index checks] first. |
| | | |
| | | [source, console, subs="+attributes"] |
| | | The commands stop at the first failure. `stop-ds --noPropertiesFile` stops the local instance. File replacement starts only after the server stops, the backup is written, and the ZIP is extracted. |
| | | |
| | | [source,bash] |
| | | ---- |
| | | $ cd /path/to/ |
| | | $ sed -e "s/default.java-home=.*/default.java-home=\/path\/to\/jdk11/" \ |
| | | opendj/config/java.properties \ |
| | | > opendj/config/java.properties.new ; \ |
| | | mv opendj/config/java.properties.new opendj/config/java.properties |
| | | $ /path/to/opendj/bin/dsjavaproperties |
| | | $ /path/to/opendj/bin/stop-ds --quiet |
| | | ... msg=The Directory Server is now stopped |
| | | $ zip -rq OpenDJ-backup.zip opendj/ |
| | | $ unzip -o ~/Downloads/opendj-{opendj-version}.zip |
| | | $ /path/to/opendj/upgrade --acceptLicense |
| | | |
| | | >>>> OpenDJ Upgrade Utility |
| | | |
| | | * OpenDJ will be upgraded from version 2.6.3.12667 to |
| | | {opendj-version}.build-hash |
| | | * See '/path/to/opendj/upgrade.log' for a detailed log of this operation |
| | | |
| | | >>>> Preparing to upgrade |
| | | |
| | | OpenDJ {opendj-version} introduced changes to the JE backend configuration and database |
| | | format. The upgrade will update all JE backend configurations, but will only |
| | | migrate JE backend databases which are associated with *enabled* JE |
| | | backends. It is very strongly recommended that any existing data has been |
| | | backed up and that you have read the upgrade documentation before |
| | | proceeding. Do you want to proceed with the upgrade? (yes/no) [no]: yes |
| | | |
| | | OpenDJ {opendj-version} changed the matching rule implementations. All indexes have to |
| | | be rebuilt. This could take a long time to proceed. Do you want to launch |
| | | this process automatically at the end of the upgrade? (yes/no) [no]: yes |
| | | |
| | | OpenDJ {opendj-version} improved the replication changelog storage format. As a |
| | | consequence, the old changelog content of the current replication server |
| | | will be erased by the upgrade. The new changelog content will be |
| | | automatically reconstructed from the changelog of other replication servers |
| | | in the topology. After the upgrade, dsreplication reset-change-number can be |
| | | used to reset the changelog change-number of the current replication server |
| | | to match another replication server. Do you want to proceed with the |
| | | upgrade? (yes/no) [no]: yes |
| | | |
| | | The upgrade is ready to proceed. Do you wish to continue? (yes/no) [yes]: |
| | | |
| | | |
| | | >>>> Performing upgrade |
| | | |
| | | Changing matching rule for 'userCertificate' and 'caCertificate' to |
| | | CertificateExactMatch............................................... 100% |
| | | Configuring 'CertificateExactMatch' matching rule................... 100% |
| | | Replacing schema file '03-pwpolicyextension.ldif'................... 100% |
| | | Removing 'dc=replicationchanges' backend............................ 100% |
| | | Removing ACI for 'dc=replicationchanges'............................ 100% |
| | | Adding default privilege 'changelog-read' to all root DNs........... 100% |
| | | Adding PKCS5S2 password storage scheme configuration................ 100% |
| | | Rerunning dsjavaproperties.......................................... 100% |
| | | Updating ds-cfg-java-class attribute in File-Based Debug Logger..... 100% |
| | | Deleting ds-cfg-default-debug-level attribute in File-Based Debug |
| | | Logger.............................................................. 100% |
| | | Updating ds-cfg-default-severity attribute in File-Based Error |
| | | Logger.............................................................. 100% |
| | | Updating ds-cfg-override-severity attribute in Replication Repair |
| | | Logger.............................................................. 100% |
| | | Removing config for 'Network Groups'................................ 100% |
| | | Removing config for 'Workflows'..................................... 100% |
| | | Removing config for 'Workflow Elements'............................. 100% |
| | | Removing config for 'Network Group Plugin'.......................... 100% |
| | | Removing config for 'Extensions'.................................... 100% |
| | | Removing config for 'File System Entry Cache'....................... 100% |
| | | Removing config for 'Entry Cache Preload'........................... 100% |
| | | Removing file '/path/to/opendj/bin/dsframework'..................... 100% |
| | | Removing file '/path/to/opendj/bat/dsframework.bat'................. 100% |
| | | Migrating JE backend 'userRoot'..................................... 100% |
| | | Convert local DB backends to JE backends............................ 100% |
| | | Convert local DB indexes to backend indexes......................... 100% |
| | | Convert local DB VLV indexes to backend VLV indexes................. 100% |
| | | Removing file '/path/to/opendj/bin/dbtest'.......................... 100% |
| | | Removing file '/path/to/opendj/bat/dbtest.bat'...................... 100% |
| | | Removing content of changelog in '/path/to/opendj/./changelogDb' |
| | | directory........................................................... 100% |
| | | Enable log file based replication changelog storage................. 100% |
| | | Replacing schema file '02-config.ldif'.............................. 100% |
| | | Archiving concatenated schema....................................... 100% |
| | | |
| | | >>>> OpenDJ was successfully upgraded from version 2.6.3.12667 to |
| | | 5.0.0.build-hash |
| | | |
| | | |
| | | >>>> Performing post upgrade tasks |
| | | |
| | | ... |
| | | |
| | | >>>> Post upgrade tasks complete |
| | | |
| | | * See '/path/to/opendj/upgrade.log' for a detailed log of this operation |
| | | |
| | | $ /path/to/opendj/bin/start-ds --quiet |
| | | $ |
| | | cd /path/to && |
| | | ./renamed-opendj/bin/stop-ds --noPropertiesFile && |
| | | backup_dir=$(mktemp -d "$PWD/opendj-backup.XXXXXX") && |
| | | (umask 077 && tar -czf "$backup_dir/opendj-backup.tar.gz" renamed-opendj instance) && |
| | | staging=$(mktemp -d) && |
| | | unzip -q ~/Downloads/opendj-5.2.0.zip -d "$staging" && |
| | | cp -fpR "$staging"/opendj/. renamed-opendj/ && |
| | | export OPENDJ_JAVA_HOME=/path/to/jdk && |
| | | ./renamed-opendj/upgrade --no-prompt --acceptLicense --force |
| | | ---- |
| | | |
| | | Review the upgrade output and `instance/logs/upgrade.log`. Start the server only after the upgrade succeeds and any deferred tasks are complete. |
| | | |
| | | [source, console] |
| | | ---- |
| | | $ ./renamed-opendj/bin/start-ds |
| | | $ ./renamed-opendj/bin/status |
| | | ---- |
| | | |
| | | After startup, verify that the server serves the intended data and that applications can connect before directing traffic to it. |
| | | |
| | | ==== |
| | | |
| | | [#upgrade-msi] |
| | |
| | | |
| | | [source, console] |
| | | ---- |
| | | $ timeout 5m bash -c 'until [ "$(docker inspect -f "{{.State.Health.Status}}" opendj)" = healthy ]; do sleep 5; done' |
| | | $ docker inspect --format '{{.State.Health.Status}}' opendj |
| | | ---- |
| | | + |
| | | The upgrade tasks that take long, such as verifying or rebuilding indexes, are performed before the server starts, since nobody is there to run them afterwards. On a large instance they can take longer than the start period of the health check, so the container may report `unhealthy` until the upgrade is over, and the command above may give up before: `docker logs opendj` shows which task is running, and the command can be run again. A container whose upgrade fails does not report itself healthy: `docker logs opendj` shows why, and the upgrade log `/opt/opendj/data/logs/upgrade.log` has the details. Starting it again does not get past the failure either: the volume carries the file `/opt/opendj/data/.upgrade-pending` from before the upgrade until the upgrade, the tasks that run after it included, has succeeded. An upgrade that failed before it recorded the new version is run again on the next start. When a task that runs after the upgrade fails, such as an index rebuild, the new version is already recorded, and the upgrade would find nothing left to do: a container started over the volume then starts the server, logs that the upgrade did not complete, and does not report itself healthy. Revert as follows, or rebuild the indexes that `upgrade.log` names, as described in xref:../admin-guide/chap-indexing.adoc#rebuild-index["Rebuilding Indexes"] in the __Administration Guide__, then remove the file with `docker exec opendj rm /opt/opendj/data/.upgrade-pending` and restart the container with `docker restart opendj`. |
| | | Index verification and rebuilds can leave a large instance `unhealthy` while they run. Check `docker logs opendj` and `/opt/opendj/data/logs/upgrade.log` for progress or errors. The volume retains `/opt/opendj/data/.upgrade-pending` until the upgrade and its post-upgrade tasks finish. |
| | | + |
| | | If the upgrade fails before recording the new version, the next start retries it. |
| | | + |
| | | If a post-upgrade task fails or is interrupted after the new version is recorded, the next start attempts to open the server for recovery and leaves the container `unhealthy`. Complete all outstanding post-upgrade tasks or restore the backup as shown below. |
| | | + |
| | | For an interrupted DN equality index check, read `/opt/opendj/data/config/config.ldif` to list every enabled pluggable backend, its base DNs, and the attributes it indexes for equality (`ds-cfg-index-type: equality`). An interrupted run can leave base DNs absent from `upgrade.log`. |
| | | + |
| | | For each indexed attribute, resolve its effective equality matching rule using the instance schema in `/opt/opendj/data/config/schema/`. Use the attribute type's `EQUALITY` rule if declared, otherwise follow its `SUP` chain to resolve the inherited rule. If no rule is inherited, use the default equality rule of the attribute's syntax. Include the attributes whose rule is `distinguishedNameMatch` (`2.5.13.1`) or `uniqueMemberMatch` (`2.5.13.23`). For example, a custom attribute `myManager` declared with `SUP distinguishedName` inherits `distinguishedNameMatch`. |
| | | + |
| | | Stop the server and open a temporary shell from the new image with the same volumes. Include any runtime settings the backends need, such as network access to an external database. For every affected backend and base DN, run `backendstat show-index-status` and check the `Valid` column for each affected index. The following example checks the `member.distinguishedNameMatch` index in `userRoot`. |
| | | + |
| | | |
| | | [source, console, subs="+attributes"] |
| | | ---- |
| | | $ docker stop -t 60 opendj |
| | | $ docker run --rm -it --volumes-from opendj --workdir /opt/opendj \ |
| | | --entrypoint /bin/sh openidentityplatform/opendj:{opendj-version} |
| | | $ printf '%s\n' /opt/opendj/data > instance.loc |
| | | $ ./bin/backendstat show-index-status --backendID userRoot --baseDN dc=example,dc=com |
| | | ---- |
| | | + |
| | | If the index is valid, check its contents in the same shell with xref:../admin-guide/chap-indexing.adoc#verify-index[`verify-index`]. |
| | | + |
| | | |
| | | [source, console] |
| | | ---- |
| | | $ ./bin/verify-index --baseDN dc=example,dc=com --index member --countErrors |
| | | ---- |
| | | + |
| | | If `Valid` is `false` or verification reports index errors, xref:../admin-guide/chap-indexing.adoc#rebuild-index[rebuild the index] in the same shell, for example with `./bin/rebuild-index --offline --baseDN dc=example,dc=com --index member`. After the rebuild, check both the index status and its contents again. An untrusted index can pass `verify-index --countErrors`, so require `Valid` to be `true` and verification to pass for every affected index. |
| | | + |
| | | Once all outstanding tasks are complete, remove `/opt/opendj/data/.upgrade-pending` from the temporary shell, exit the shell, and run `docker start opendj` from the host. Restore the backup if you cannot identify all the affected indexes or complete the outstanding work. |
| | | |
| | | To revert, remove the new container, replace the volume with one restored from the backup, and start a container from the older image over it, with the options of the old container. Restore into an empty volume: files that the upgrade added would be left behind in a volume that the archive is extracted over. |
| | | |
| | |
| | | |
| | | . A value with DN syntax that a client wrote with `;`, such as `member: cn=a;dc=example,dc=com`, was indexed under the key of `cn=a`. It now reads as `cn=a,dc=example,dc=com`, so an indexed equality search for that DN misses the entry until the index is rebuilt. The same holds for a value that was stored while its syntax was not enforced, and that only now parses. |
| | | + |
| | | The `upgrade` command therefore offers to verify the equality indexes of the attributes that hold DNs, such as `member`, `uniqueMember`, `owner` or `seeAlso`, in every enabled backend at the end of the upgrade, and rebuilds them under each base DN where they do not match the entries. The verification reads every entry of these backends, so on a large backend it takes a while; the indexes are only rebuilt where it finds a missing key. The default answer is yes, so `upgrade --no-prompt` performs the verification too, as do the Docker image (see xref:#upgrade-docker["To Upgrade a Docker Container"]) and the native packages, which run `upgrade --no-prompt --force`. If you declined it, run `verify-index` on these indexes with the server stopped, and rebuild them where it reports errors, as described in xref:../admin-guide/chap-indexing.adoc#rebuild-index["Rebuilding Indexes"] in the __Administration Guide__. Do the same for a backend that the upgrade could not read, such as a JDBC or Cassandra backend whose database was unreachable: the upgrade then warns, names the indexes and the base DN, and goes on, leaving these indexes as they were. A rebuild that the upgrade started and that fails, for instance because the temporary directory is full, fails the upgrade, as the index rebuilds of other upgrade tasks do: such indexes may be left untrusted, so that searches cannot use them, until they are rebuilt. The upgrade then neither verifies nor rebuilds the indexes of the base DNs that come after, as the same cause would most likely make their rebuild fail too: it names them, and you verify them and rebuild them where needed once the cause is fixed. |
| | | The `upgrade` command therefore offers to verify the equality indexes of the attributes that hold DNs, such as `member`, `uniqueMember`, `owner` or `seeAlso`, in every enabled backend at the end of the upgrade, and rebuilds them under each base DN where they do not match the entries. The verification reads every entry of these backends, so on a large backend it takes a while; the indexes are only rebuilt where it finds a missing key. The default answer is yes, so `upgrade --no-prompt` performs the verification too, as do the Docker image (see xref:#upgrade-docker["To Upgrade a Docker Container"]) and the native packages, which run `upgrade --no-prompt --force`. If you declined it, stop the server and check both the index status with `backendstat show-index-status` and the contents with `verify-index`. Rebuild any invalid or inconsistent indexes and repeat both checks, as described in xref:../admin-guide/chap-indexing.adoc#rebuild-index["Rebuilding Indexes"] in the __Administration Guide__. Do the same for a backend that the upgrade could not read, such as a JDBC or Cassandra backend whose database was unreachable: the upgrade then warns, names the indexes and the base DN, and goes on, leaving these indexes as they were. A rebuild that the upgrade started and that fails, for instance because the temporary directory is full, fails the upgrade, as the index rebuilds of other upgrade tasks do: such indexes may be left untrusted, so that searches cannot use them, until they are rebuilt. The upgrade then neither verifies nor rebuilds the indexes of the base DNs that come after, as the same cause would most likely make their rebuild fail too: it names them, and you verify them and rebuild them where needed once the cause is fixed. |
| | | + |
| | | A stored DN value with other content after an RDN, such as `cn="a"x,dc=example,dc=com`, no longer parses: replace it with the DN that was meant. |
| | | |
| | |
| | | information: "Portions copyright [year] [name of copyright owner]". |
| | | |
| | | Copyright 2017 ForgeRock AS. |
| | | Portions Copyright 2024-2026 3A Systems LLC. |
| | | Portions Copyright 2024-2026 3A Systems, LLC. |
| | | //// |
| | | |
| | | :figure-caption!: |
| | |
| | | |
| | | This guide shows you how to install, upgrade, and remove OpenDJ software. |
| | | |
| | | If you only want to try OpenDJ server software, and you do not plan to store any real or important data that you want to keep, then you need not read this entire guide. Instead read xref:chap-install.adoc#before-you-install["To Prepare For Installation"] and xref:chap-install.adoc#gui-install["To Install OpenDJ Directory Server With the GUI"]. Where Docker is available, xref:chap-install.adoc#install-docker["To Run OpenDJ in Docker"] starts a server with a single command. |
| | | To try OpenDJ with sample data, follow xref:../getting-started/first-steps.adoc[the Getting Started walkthrough] or run the server in xref:chap-install.adoc#install-docker[Docker]. For an installation you intend to keep, start with xref:chap-install.adoc#before-you-install["To Prepare For Installation"]. |
| | | |
| | | [#d67379e160] |
| | | === Who Should Read this Guide |
| | | |
| | | This guide is written for anyone installing OpenDJ who plans to maintain directory services for client applications. Basic OpenDJ installation can be simple and straightforward, particularly if you are already acquainted with directory services. Upgrading a running directory service without a single point of failure that can cause downtime requires at least a little thought and planning. If you are doing a basic installation, you might find yourself wanting more information about the process. |
| | | |
| | | This guide covers the install, upgrade, and removal (uninstall) procedures that you theoretically perform only once per version. This guide aims to provide you with an understand of what happens when you perform the steps. |
| | | |
| | | You do not need to be an LDAP wizard to learn something from this guide, though knowing how to manage directory services helps. You do need to know how to manage servers and services on your operating system of choice. You can nevertheless get started with this guide, and then learn more as you go along. |
| | | |
| | | |
| | |
| | | |
| | | |
| | | [appendix] |
| | | ifndef::env-site[] |
| | | [#appendix-controls] |
| | | endif::[] |
| | | == LDAP Controls |
| | | |
| | | ifdef::env-site[] |
| | | anchor:appendix-controls[] |
| | | endif::[] |
| | | |
| | | Controls provide a mechanism whereby the semantics and arguments of existing LDAP operations may be extended. One or more controls may be attached to a single LDAP message. A control only affects the semantics of the message it is attached to. Controls sent by clients are termed __request controls__, and those sent by servers are termed __response controls__. |
| | | |
| | | OpenDJ software supports the following LDAP controls: |
| | |
| | | information: "Portions copyright [year] [name of copyright owner]". |
| | | |
| | | Copyright 2017 ForgeRock AS. |
| | | Portions Copyright 2024 3A Systems LLC. |
| | | Portions Copyright 2024-2026 3A Systems, LLC. |
| | | //// |
| | | |
| | | :figure-caption!: |
| | |
| | | |
| | | |
| | | [appendix] |
| | | ifndef::env-site[] |
| | | [#appendix-extended-ops] |
| | | endif::[] |
| | | == LDAP Extended Operations |
| | | |
| | | ifdef::env-site[] |
| | | anchor:appendix-extended-ops[] |
| | | endif::[] |
| | | |
| | | Extended operations allow additional operations to be defined for services not already available in the protocol |
| | | |
| | | OpenDJ software supports the following LDAP extended operations: |
| | |
| | | information: "Portions copyright [year] [name of copyright owner]". |
| | | |
| | | Copyright 2017 ForgeRock AS. |
| | | Portions Copyright 2024 3A Systems LLC. |
| | | Portions Copyright 2024-2026 3A Systems, LLC. |
| | | //// |
| | | |
| | | :figure-caption!: |
| | |
| | | |
| | | |
| | | [appendix] |
| | | ifndef::env-site[] |
| | | [#appendix-l10n] |
| | | endif::[] |
| | | == Localization |
| | | |
| | | ifdef::env-site[] |
| | | anchor:appendix-l10n[] |
| | | endif::[] |
| | | |
| | | OpenDJ software stores data in UTF-8 format. It enables you to store and to search for attribute values according to a variety of language specific locales. OpenDJ software is also itself localized for a smaller variety of languages. |
| | | |
| | | [#supported-languages] |
| | |
| | | information: "Portions copyright [year] [name of copyright owner]". |
| | | |
| | | Copyright 2017 ForgeRock AS. |
| | | Portions Copyright 2024-2025 3A Systems LLC. |
| | | Portions Copyright 2024-2026 3A Systems, LLC. |
| | | //// |
| | | |
| | | :figure-caption!: |
| | |
| | | |
| | | |
| | | [appendix] |
| | | ifndef::env-site[] |
| | | [#appendix-rest2ldap-3-0] |
| | | endif::[] |
| | | == REST to LDAP Configuration (3.0) |
| | | |
| | | ifdef::env-site[] |
| | | anchor:appendix-rest2ldap-3-0[] |
| | | endif::[] |
| | | |
| | | |
| | | [NOTE] |
| | | ==== |
| | |
| | | |
| | | |
| | | [appendix] |
| | | ifndef::env-site[] |
| | | [#appendix-rest2ldap] |
| | | endif::[] |
| | | == REST to LDAP Configuration |
| | | |
| | | ifdef::env-site[] |
| | | anchor:appendix-rest2ldap[] |
| | | endif::[] |
| | | |
| | | OpenDJ offers two alternatives for access to directory data over HTTP: |
| | | |
| | | * OpenDJ directory server has an HTTP connection handler that exposes RESTful APIs to directory data over HTTP (or HTTPS). You configure an OpenDJ directory server HTTP connection handler, and the HTTP endpoints that it serves, by using the `dsconfig` command. For each HTTP endpoint served by an HTTP connection handler that exposes your directory data, you configure mappings between JSON resources and LDAP entries. |
| | |
| | | information: "Portions copyright [year] [name of copyright owner]". |
| | | |
| | | Copyright 2017 ForgeRock AS. |
| | | Portions Copyright 2024-2026 3A Systems LLC. |
| | | Portions Copyright 2024-2026 3A Systems, LLC. |
| | | //// |
| | | |
| | | :figure-caption!: |
| | |
| | | :table-caption!: |
| | | |
| | | |
| | | ifndef::env-site[] |
| | | [#chap-ldap-operations] |
| | | endif::[] |
| | | == Performing LDAP Operations |
| | | |
| | | ifdef::env-site[] |
| | | anchor:chap-ldap-operations[] |
| | | endif::[] |
| | | |
| | | OpenDJ directory server includes the OpenDJ control panel browser and also command-line tools for performing LDAP operations. In this chapter, you will learn how to use the command-line tools to perform LDAP operations. |
| | | |
| | | [#cli-overview] |
| | |
| | | [#persistent-search] |
| | | .Search: Performing a Persistent Search |
| | | ==== |
| | | OpenDJ directory server and other LDAP servers support the Internet-Draft for link:http://tools.ietf.org/html/draft-ietf-ldapext-psearch[Persistent Search: A Simple LDAP Change Notification Mechanism, window=\_blank]. A persistent search is like a search that never stops. Every time there is a change to an entry matching the search criteria, the search returns an additional response. Applications can also get change notifications by using OpenDJ directory server's external change log as described in xref:../admin-guide/chap-replication.adoc#repl-change-notification["Change Notification For Your Applications"] in the __Administration Guide__. |
| | | OpenDJ directory server and other LDAP servers support the Internet-Draft for link:https://datatracker.ietf.org/doc/html/draft-ietf-ldapext-psearch[Persistent Search: A Simple LDAP Change Notification Mechanism, window=\_blank]. A persistent search is like a search that never stops. Every time there is a change to an entry matching the search criteria, the search returns an additional response. Applications can also get change notifications by using OpenDJ directory server's external change log as described in xref:../admin-guide/chap-replication.adoc#repl-change-notification["Change Notification For Your Applications"] in the __Administration Guide__. |
| | | |
| | | In order to use the persistent search control with OpenDJ directory server, the user performing the search must be given access to use the control. Persistent searches consume server resources, so directory administrators often limit permission to perform persistent searches to specific applications. If the user does not have access to use the control, the request to use the control causes the search operation to fail with a message such as the following: |
| | | |
| | |
| | | |
| | | a|`\|` |
| | | a|OR operator, to find entries that match one of the specified filter components. |
| | | a|`"\|(sn=Jensen)(sn=Johnson)"` matches entries with surname Jensen or surname Johnson. |
| | | a|`"(\|(sn=Jensen)(sn=Johnson))"` matches entries with surname Jensen or surname Johnson. |
| | | |=== |
| | | |
| | | |
| | | [#compare-ldap] |
| | | === Comparing Attribute Values |
| | | |
| | | The compare operation checks whether an attribute value you specify matches the attribute value stored on one or more directory entries. |
| | | An LDAP compare request checks whether a directory entry has a matching value for an attribute. The `ldapcompare` command can issue the same comparison for several entry DNs. |
| | | |
| | | [#compare-example] |
| | | .Compare: Checking authPassword |
| | | .Compare: Checking a Common Name |
| | | ==== |
| | | In this example, Kirsten Vaughan uses the `ldapcompare` command, described in xref:../reference/admin-tools-ref.adoc#ldapsearch-1[ldapsearch(1)] in the __Reference__, to check whether the hashed password value matches the stored value on `authPassword`: |
| | | Use the `ldapcompare` command, described in xref:../reference/admin-tools-ref.adoc#ldapcompare-1[ldapcompare(1)] in the __Reference__, to check whether an entry has the common name `Kirsten Vaughan`. |
| | | |
| | | [source, console] |
| | | ---- |
| | | $ ldapcompare \ |
| | | --port 1389 \ |
| | | --bindDN "uid=kvaughan,ou=people,dc=example,dc=com" \ |
| | | --bindPassword bribery \ |
| | | 'authPassword:MD5$dFHgpDxXUT8=$qlC4xMXvmVlusJLz9/WJ5Q==' \ |
| | | 'cn:Kirsten Vaughan' \ |
| | | uid=kvaughan,ou=people,dc=example,dc=com |
| | | Comparing type authPassword with value |
| | | MD5$dFHgpDxXUT8=$qlC4xMXvmVlusJLz9/WJ5Q== in entry |
| | | Comparing type cn with value Kirsten Vaughan in entry |
| | | uid=kvaughan,ou=people,dc=example,dc=com |
| | | Compare operation returned true for entry |
| | | uid=kvaughan,ou=people,dc=example,dc=com |
| | |
| | | |
| | | Consider two users, Alice and Bob, both busy and often interrupted. Alice has Babs Jensen's new phone and room numbers. Bob has Babs's new location and description. Both assume that they have all the information that has changed. What can you do to make sure that your application applies the right changes when Alice and Bob simulaneously update Babs Jensen's profile? |
| | | |
| | | OpenDJ directory server includes two features to help you in this situation. One of the features is the LDAP Assertion Control, described in xref:../reference/appendix-controls.adoc#assertion-request-control[Assertion request control] in the __Reference__, used to tell the directory server to perform the modification only if an assertion you make stays true. The other feature is OpenDJ's support for link:http://tools.ietf.org/html/rfc2616#section-3.11[entity tag, window=\_blank] (ETag) attributes, making it easy to check whether the entry in the directory is the same as the entry you read. |
| | | OpenDJ directory server includes two features to help you in this situation. One of the features is the LDAP Assertion Control, described in xref:../reference/appendix-controls.adoc#assertion-request-control[Assertion request control] in the __Reference__, used to tell the directory server to perform the modification only if an assertion you make stays true. The other feature is OpenDJ's support for link:https://www.rfc-editor.org/rfc/rfc9110.html#section-8.8.3[entity tag, window=\_blank] (ETag) attributes, making it easy to check whether the entry in the directory is the same as the entry you read. |
| | | |
| | | Alice and Bob both get Babs's entry. In LDIF, the relevant attributes from the entry look like this. Notice the ETag: |
| | | |
| | |
| | | [#change-password] |
| | | === Changing Passwords |
| | | |
| | | The examples use LDAPS on port 1636 with `--trustAll` on an isolated evaluation server. For deployed services, see xref:../admin-guide/chap-connection-handlers.adoc#setup-server-cert[Preparing For Secure Communications]. |
| | | |
| | | With the `ldappasswordmodify` command, described in xref:../reference/admin-tools-ref.adoc#ldappasswordmodify-1[ldappasswordmodify(1)] in the __Reference__, authorized users can change and reset user passwords. |
| | | |
| | | [#password-reset] |
| | |
| | | [source, console] |
| | | ---- |
| | | $ ldappasswordmodify \ |
| | | --useStartTLS \ |
| | | --port 1389 \ |
| | | --port 1636 --useSSL --trustAll \ |
| | | --bindDN "uid=kvaughan,ou=people,dc=example,dc=com" \ |
| | | --bindPassword bribery \ |
| | | --authzID "dn:uid=scarter,ou=people,dc=example,dc=com" \ |
| | |
| | | |
| | | [TIP] |
| | | ====== |
| | | The `ldappasswordmodify` command uses the LDAP Password Modify extended operation. If this extended operation is performed on a connection that is already associated with a user (in other words, when a user first does a bind on the connection, then requests the LDAP Password Modify extended operation), then the operation is performed as the user associated with the connection. If the user associated with the connection is not the same user whose password is being changed, then OpenDJ considers it a password reset. |
| | | |
| | | Whenever one user changes another user's password, OpenDJ considers it a password reset. Often password policies specify that users must change their passwords again after a password reset. |
| | | |
| | | If you want your application to change a user's password, rather than reset a user's password, have your application request the password change as the user whose password is changing. |
| | | |
| | | To change the password as the user, bind as the user whose password should be changed, and use the link:http://tools.ietf.org/html/rfc3062[LDAP Password Modify extended operation, window=\_blank] with an authorization ID but without performing a bind, or use proxied authorization. For instructions on using proxied authorization, see xref:#proxied-authz["Configuring Proxied Authorization"]. |
| | | The command sends the link:https://www.rfc-editor.org/rfc/rfc3062[LDAP Password Modify extended operation]. OpenDJ treats a change made on behalf of another user as a reset. To change your own password over a bound connection, omit the target identity. OpenDJ then uses the connection’s authorization identity. An application can also use xref:#proxied-authz[proxied authorization] to act for a user. |
| | | ====== |
| | | You could also accomplish a password reset with the `manage-account` command, described in xref:../reference/admin-tools-ref.adoc#manage-account-1[manage-account(1)] in the __Reference__, although `set-password-is-reset` is a hidden option, supported only for testing: |
| | | |
| | | [source, console] |
| | | ---- |
| | | $ manage-account \ |
| | | set-password-is-reset \ |
| | | --bindDN "cn=Directory Manager" \ |
| | | --bindPassword password \ |
| | | --targetDN uid=scarter,ou=people,dc=example,dc=com \ |
| | | --operationValue true |
| | | Password Is Reset: true |
| | | ---- |
| | | ==== |
| | | |
| | | [#change-own-password] |
| | |
| | | [source, console] |
| | | ---- |
| | | $ ldappasswordmodify \ |
| | | --port 1389 \ |
| | | --port 1636 --useSSL --trustAll \ |
| | | --authzID "dn:uid=bjensen,ou=people,dc=example,dc=com" \ |
| | | --currentPassword hifalutin \ |
| | | --newPassword secret12 |
| | | The LDAP password modify operation was successful |
| | | ---- |
| | | The same operation works for `cn=Directory Manager`: |
| | | |
| | | [source, console] |
| | | ---- |
| | | $ ldappasswordmodify \ |
| | | --port 1389 \ |
| | | --authzID "dn:cn=Directory Manager" \ |
| | | --currentPassword password \ |
| | | --newPassword secret12 |
| | | The LDAP password modify operation was successful |
| | | ---- |
| | | ==== |
| | | |
| | | [#non-ascii-password] |
| | |
| | | en_US.utf8 |
| | | |
| | | $ ldappasswordmodify \ |
| | | --port 1389 \ |
| | | --port 1636 --useSSL --trustAll \ |
| | | --bindDN uid=bjensen,ou=People,dc=example,dc=com \ |
| | | --bindPassword hifalutin \ |
| | | --currentPassword hifalutin \ |
| | |
| | | The LDAP password modify operation was successful |
| | | |
| | | $ ldapsearch \ |
| | | --port 1389 \ |
| | | --port 1636 --useSSL --trustAll \ |
| | | --bindDN uid=bjensen,ou=People,dc=example,dc=com \ |
| | | --bindPassword pàsswȏrd \ |
| | | --baseDN dc=example,dc=com \ |
| | | "(uid=bjensen)" cn |
| | | dn: uid=bjensen,ou=People,dc=example,dc=com |
| | | userPassword: {SSHA}k0eEeCxj9YRXUp8yJn0Z/mwqe+wrcFb1N1gg2g== |
| | | cn: Barbara Jensen |
| | | cn: Babs Jensen |
| | | ---- |
| | |
| | | |
| | | In the simplest bind operation, the client provides a zero-length name and a zero-length password. This results in an anonymous bind, meaning the client is authenticated as an anonymous user of the directory. In the simplest examples in xref:#search-ldap["Searching the Directory"], notice that no authentication information is provided. The examples work because the client commands default to requesting anonymous binds when no credentials are provided, and because access controls for the sample data allow anonymous clients to read, search, and compare some directory data. |
| | | |
| | | In a simple bind operation, the client provides an LDAP name, such as the DN identifying its entry, and the corresponding password stored on the `userPassword` attribute of the entry. In xref:#write-ldap["Updating the Directory"], notice that to change directory data, the client provides the bind DN and bind password of a user who has permission to change directory data. The commands do not work with a bind DN and bind password because access controls for the sample data only let authorized users change directory data. |
| | | A simple bind uses the entry DN and its password. The examples in xref:#write-ldap["Updating the Directory"] bind as a user with permission to make the requested change. |
| | | |
| | | Users rarely provide client applications with DNs, however. Instead, users might provide a client application with an identity string like a user ID or an email address. Depending on how the DNs are constructed, the client application can either build the DN directly from the user's identity string, or use a session where the bind has been performed with some other identity to search for the user entry based on the user's identity string. Given the DN constructed or found, the client application can then perform a simple bind. |
| | | |
| | | For example, suppose Babs Jensen enters her email address, `bjensen@example.com`, and her password in order to log in. The client application might search for the entry matching `(mail=bjensen@example.com)` under base DN `dc=example,dc=com`. Alternatively, the client application might know to extract the user ID `bjensen` from the address, then build the corresponding DN, `uid=bjensen,ou=people,dc=example,dc=com` in order to bind. |
| | | When an identifier string provided by the user can be readily mapped to the user's entry DN, OpenDJ directory server can translate between the identifier string and the entry DN. This translation is the job of a component called an identity mapper. Identity mappers are used to perform PLAIN SASL authentication (with a user name and password), SASL GSSAPI authentication (Kerberos V5), SASL CRAM MD5, and DIGEST MD5 authentication. They also handle authorization IDs during password modify extended operations and proxied authorization. |
| | | |
| | | One use of PLAIN SASL is to translate user names from HTTP Basic authentication to LDAP authentication. The following example shows PLAIN SASL authentication using the default Exact Match identity mapper. In this (contrived) example, Babs Jensen reads the hashed value of her password. (According to the access controls in the example data, Babs must authenticate to read her password.) Notice the authentication ID is her user ID, `u:bjensen`, rather than the DN of her entry: |
| | | SASL PLAIN can authenticate with a user ID. The default Exact Match mapper translates `u:bjensen` to Babs Jensen’s entry. This example uses LDAPS on an isolated evaluation server. Use a trusted server certificate in deployed services. |
| | | |
| | | [source, console] |
| | | ---- |
| | | $ ldapsearch \ |
| | | --port 1389 \ |
| | | --useStartTLS \ |
| | | --port 1636 \ |
| | | --useSSL --trustAll \ |
| | | --baseDN dc=example,dc=com \ |
| | | --saslOption mech=PLAIN \ |
| | | --saslOption authid=u:bjensen \ |
| | | --bindPassword hifalutin \ |
| | | "(cn=Babs Jensen)" cn userPassword |
| | | "(cn=Babs Jensen)" cn |
| | | dn: uid=bjensen,ou=People,dc=example,dc=com |
| | | cn: Barbara Jensen |
| | | cn: Babs Jensen |
| | | userPassword: {SSHA}7S4Si+vPE513cYQ7otiqb8hjiCzU7XNTv0RPBA== |
| | | ---- |
| | | The Exact Match identity mapper searches for a match between the string provided (here, `bjensen`) and the value of a specified attribute (by default the `uid` attribute). If you know users are entering their email addresses, you could create an exact match identity mapper for email addresses, then use that for PLAIN SASL authentication as in the following example: |
| | | To authenticate users by email address, configure an Exact Match mapper for `mail` and select it on the PLAIN SASL mechanism. Then repeat the preceding search with `--saslOption authid=u:bjensen@example.com`. |
| | | |
| | | [source, console] |
| | | ---- |
| | |
| | | --set identity-mapper:"Email Mapper" \ |
| | | --no-prompt |
| | | |
| | | $ ldapsearch \ |
| | | --port 1389 \ |
| | | --useStartTLS \ |
| | | --baseDN dc=example,dc=com \ |
| | | --saslOption mech=PLAIN \ |
| | | --saslOption authid=u:bjensen@example.com \ |
| | | --bindPassword hifalutin \ |
| | | "(cn=Babs Jensen)" cn userPassword |
| | | dn: uid=bjensen,ou=People,dc=example,dc=com |
| | | cn: Barbara Jensen |
| | | cn: Babs Jensen |
| | | userPassword: {SSHA}7S4Si+vPE513cYQ7otiqb8hjiCzU7XNTv0RPBA== |
| | | ---- |
| | | OpenDJ directory server's Regular Expression identity mapper uses a regular expression to extract a substring from the string provided, then searches for a match between the substring and the value of a specified attribute. In the case of example data where an email address is __user ID__ + @ + __domain__, you can use the default Regular Expression identity mapper in the same way as the email mapper from the previous example. The default regular expression pattern is `^([^@]+)@.+$`, and the part of the identity string matching `([^@]+)` is used to find the entry by user ID: |
| | | |
| | | [source, console] |
| | | ---- |
| | | $ dsconfig \ |
| | | set-sasl-mechanism-handler-prop \ |
| | | --hostname opendj.example.com \ |
| | | --port 4444 \ |
| | | --bindDN "cn=Directory Manager" \ |
| | | --bindPassword password \ |
| | | --handler-name PLAIN \ |
| | | --set identity-mapper:"Regular Expression" \ |
| | | --no-prompt |
| | | |
| | | $ ldapsearch \ |
| | | --port 1389 \ |
| | | --useStartTLS \ |
| | | --baseDN dc=example,dc=com \ |
| | | --saslOption mech=PLAIN \ |
| | | --saslOption authid=u:bjensen@example.com \ |
| | | --bindPassword hifalutin \ |
| | | "(cn=Babs Jensen)" cn userPassword |
| | | dn: uid=bjensen,ou=People,dc=example,dc=com |
| | | cn: Barbara Jensen |
| | | cn: Babs Jensen |
| | | userPassword: {SSHA}7S4Si+vPE513cYQ7otiqb8hjiCzU7XNTv0RPBA== |
| | | ---- |
| | | Try the `dsconfig` command interactively to experiment with `match-pattern` and `replace-pattern` settings for the Regular Expression identity mapper. The `match-pattern` can be any regular expression supported by `javax.util.regex.Pattern`. |
| | | If the part before `@` is the user ID, select the `Regular Expression` mapper instead. Its default pattern `^([^@]+)@.+$` uses that part to match `uid`. |
| | | |
| | | |
| | | [#proxied-authz] |
| | |
| | | [#client-cert-auth] |
| | | === Authenticating Using a Certificate |
| | | |
| | | One alternative to simple binds with user name/password combinations consists of storing a digital certificate on the user entry, then using the certificate as credentials during the bind. You can use this mechanism, for example, to let applications bind without using passwords. |
| | | Use SASL EXTERNAL over LDAPS or StartTLS to authenticate with a client certificate. TLS validates the certificate. The SASL bind maps the certificate to a directory entry and sets the LDAP authorization identity. |
| | | |
| | | By setting up a secure connection with a certificate, the client is in effect authenticating to the server. The server must close the connection if it cannot trust the client certificate. However, the process of establishing a secure connection does not in itself identify the client to OpenDJ directory server. |
| | | |
| | | Instead, when binding with a certificate, the client must request the SASL External mechanism by which OpenDJ directory server maps the certificate to the client entry in the directory. When it finds a match, OpenDJ sets the authorization identity for the connection to that of the client, and the bind is successful. |
| | | |
| | | For the whole process of authenticating with a certificate to work smoothly, OpenDJ and the client must trust each others' certificates, the client certificate must be stored on the client entry in the directory, and OpenDJ must be configured to map the certificate to the client entry. |
| | | This section includes the following procedures and examples: |
| | | |
| | | * xref:#add-client-cert["To Add Certificate Information to an Entry"] |
| | | |
| | | * xref:#use-pkcs12-trust-store["To Use a PKCS #12 Truststore"] |
| | | |
| | | * xref:#config-cert-mappers["To Configure Certificate Mappers"] |
| | | |
| | | * xref:#auth-with-client-cert["Authenticating With Client Certificates"] |
| | | |
| | | The example uses an isolated evaluation server with LDAPS on port 1636, the default Subject Equals DN mapper, and the `cn=My App,ou=Apps,dc=example,dc=com` entry from link:../attachments/Example.ldif[Example.ldif]. Run the commands from the OpenDJ installation directory. Replace `password` with the Directory Manager password. The `--trustAll` option accepts any server certificate. For a deployed service, configure client trust as described in xref:../admin-guide/chap-connection-handlers.adoc#setup-server-cert[Preparing For Secure Communications]. |
| | | |
| | | [#add-client-cert] |
| | | .To Add Certificate Information to an Entry |
| | | ==== |
| | | Before you try to bind to OpenDJ directory server using a certificate, create a certificate, then add the certificate attributes to the entry. |
| | | |
| | | link:../attachments/Example.ldif[Example.ldif, window=\_blank] includes an entry for `cn=My App,ou=Apps,dc=example,dc=com`. Examples in this section use that entry, and use the Java `keytool` command to manage the certificate: |
| | | |
| | | . Create a certificate using the DN of the client entry as the distinguished name string: |
| | | . Create a client certificate whose subject DN is the directory entry DN and export it. |
| | | + |
| | | |
| | | [source, console] |
| | | ---- |
| | | $ keytool \ |
| | | -genkey \ |
| | | -alias myapp-cert \ |
| | | -keyalg rsa \ |
| | | -dname "cn=My App,ou=Apps,dc=example,dc=com" \ |
| | | -keystore keystore \ |
| | | -storepass changeit \ |
| | | -keypass changeit |
| | | $ keytool -genkeypair -alias myapp-cert -keyalg RSA -storetype PKCS12 \ |
| | | -dname 'CN=My App,OU=Apps,DC=example,DC=com' \ |
| | | -keystore client-keystore.p12 -storepass changeit |
| | | $ keytool -exportcert -alias myapp-cert -keystore client-keystore.p12 \ |
| | | -storepass changeit -file myapp-cert.der |
| | | ---- |
| | | |
| | | . Get the certificate signed. |
| | | . Save this LDIF as `add-cert.ldif`. Replace `/path/to/opendj` with your installation directory. |
| | | + |
| | | If you cannot get the certificate signed by a Certificate Authority, self-sign the certificate: |
| | | + |
| | | |
| | | [source, console] |
| | | [source, ldif] |
| | | ---- |
| | | $ keytool \ |
| | | -selfcert \ |
| | | -alias myapp-cert \ |
| | | -validity 7300 \ |
| | | -keystore keystore \ |
| | | -storepass changeit \ |
| | | -keypass changeit |
| | | ---- |
| | | |
| | | . Make note of the certificate fingerprints. |
| | | + |
| | | Later in this procedure you update the client application entry with the MD5 fingerprint, which in this example is `48:AC:F9:13:11:E0:AB:C4:65:A2:83:9E:DB:FE:0C:37`: |
| | | + |
| | | |
| | | [source, console] |
| | | ---- |
| | | $ keytool \ |
| | | -list \ |
| | | -v \ |
| | | -alias myapp-cert \ |
| | | -keystore keystore \ |
| | | -storepass changeit |
| | | Alias name: myapp-cert |
| | | Creation date: Jan 18, 2013 |
| | | Entry type: PrivateKeyEntry |
| | | Certificate chain length: 1 |
| | | Certificate[1]: |
| | | Owner: CN=My App, OU=Apps, DC=example, DC=com |
| | | Issuer: CN=My App, OU=Apps, DC=example, DC=com |
| | | Serial number: 5ae2277 |
| | | Valid from: Fri Jan 18 18:27:09 CET 2013 until: Thu Jan 13 18:27:09 CET 2033 |
| | | Certificate fingerprints: |
| | | MD5: 48:AC:F9:13:11:E0:AB:C4:65:A2:83:9E:DB:FE:0C:37 |
| | | SHA1: F9:61:54:37:AA:C1:BC:92:45:07:64:4B:23:6C:BC:C9:CD:1D:44:0F |
| | | SHA256: 2D:B1:58:CD:33:40:E9:...:FD:61:EA:C9:FF:6A:19:93:FE:E4:84:E3 |
| | | Signature algorithm name: SHA256withRSA |
| | | Version: 3 |
| | | |
| | | Extensions: |
| | | |
| | | #1: ObjectId: 2.5.29.14 Criticality=false |
| | | SubjectKeyIdentifier [ |
| | | KeyIdentifier [ |
| | | 0000: 54 C0 C5 9C 73 37 85 4B F2 3B D3 37 FD 45 0A AB T...s7.K.;.7.E.. |
| | | 0010: C9 6B 32 95 .k2. |
| | | ] |
| | | ] |
| | | ---- |
| | | |
| | | . Export the certificate to a file in binary format: |
| | | + |
| | | |
| | | [source, console] |
| | | ---- |
| | | $ keytool \ |
| | | -export \ |
| | | -alias myapp-cert \ |
| | | -keystore keystore \ |
| | | -storepass changeit \ |
| | | -keypass changeit \ |
| | | -file myapp-cert.crt |
| | | Certificate stored in file </path/to/myapp-cert.crt> |
| | | ---- |
| | | |
| | | . Modify the entry to add attributes related to the certificate. |
| | | + |
| | | By default, you need the `userCertificate` value. |
| | | + |
| | | If you want OpenDJ to map the certificate to its fingerprint, use the `ds-certificate-fingerprint` attribute. This example uses the MD5 fingerprint, which corresponds to the default setting for the fingerprint certificate mapper. |
| | | + |
| | | If you want to map the certificate subject DN to an attribute of the entry, use the `ds-certificate-subject-dn` attribute: |
| | | + |
| | | |
| | | [source, console] |
| | | ---- |
| | | $ cat addcert.ldif |
| | | dn: cn=My App,ou=Apps,dc=example,dc=com |
| | | changetype: modify |
| | | add: objectclass |
| | | objectclass: ds-certificate-user |
| | | - |
| | | add: ds-certificate-fingerprint |
| | | ds-certificate-fingerprint: 48:AC:F9:13:11:E0:AB:C4:65:A2:83:9E:DB:FE:0C:37 |
| | | - |
| | | add: ds-certificate-subject-dn |
| | | ds-certificate-subject-dn: CN=My App, OU=Apps, DC=example, DC=com |
| | | - |
| | | add: userCertificate;binary |
| | | userCertificate;binary:<file:///path/to/myapp-cert.crt |
| | | |
| | | $ ldapmodify \ |
| | | --port 1389 \ |
| | | --hostname opendj.example.com \ |
| | | --bindDN "cn=Directory Manager" \ |
| | | --bindPassword password \ |
| | | --filename addcert.ldif |
| | | Processing MODIFY request for cn=My App,ou=Apps,dc=example,dc=com |
| | | MODIFY operation successful for DN cn=My App,ou=Apps,dc=example,dc=com |
| | | userCertificate;binary:< file:///path/to/opendj/myapp-cert.der |
| | | ---- |
| | | |
| | | . Check your work: |
| | | + |
| | | |
| | | [source, console] |
| | | ---- |
| | | $ ldapsearch \ |
| | | --port 1389 \ |
| | | --hostname opendj.example.com \ |
| | | --baseDN dc=example,dc=com \ |
| | | "(cn=My App)" |
| | | dn: cn=My App,ou=Apps,dc=example,dc=com |
| | | ds-certificate-fingerprint: 4B:F5:CF:2C:2D:B3:86:14:FF:43:A8:37:17:DD:E7:55 |
| | | userCertificate;binary:: MIIDOzCCAiOgAwIBAgIESfC6IjANBgkqhkiG9w0BAQsFADBOMRMwEQY |
| | | KCZImiZPyLGQBGRYDY29tMRcwFQYKCZImiZPyLGQBGRYHZXhhbXBsZTENMAsGA1UECxMEQXBwczEPMA |
| | | 0GA1UEAxMGTXkgQXBwMB4XDTEzMDExNzE3MTEwM1oXDTEzMDQxNzE3MTEwM1owTjETMBEGCgmSJomT8 |
| | | ixkARkWA2NvbTEXMBUGCgmSJomT8ixkARkWB2V4YW1wbGUxDTALBgNVBAsTBEFwcHMxDzANBgNVBAMT |
| | | Bk15IEFwcDCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAJQYq+jG4ZQdNkyBT4OQBZ0sFkl |
| | | X5o2yBViDMGl1sSWIRGLpFwu6iq1chndPBJYTC+FkT66yEEOwWOpSfcYdFHkMQP0qp5A8mgP6bYkeH1 |
| | | ROvQ1nhLs0ILuksR10CVIQ5b1zv6bGEFhA9gSKmpHfQOSt9PXq8+kuz+4RgZk9Il28tgDNMm91wSJr7 |
| | | kqi5g7a2a7Io5s9L2FeLhVSBYwinWQnASk8nENrhcE0hHkrpGsaxdhIQBQQvm+SRC0dI4E9iwBGI3Lw |
| | | lV3a4KTa5DlYD6cDREI6B8XlSdc1DaIhwC8CbsE0WJQoCERSURdjkuHrPck6f69HKUFRiC7JMT3dFbs |
| | | CAwEAAaMhMB8wHQYDVR0OBBYEFFTAxZxzN4VL8jvTN/1FCqvJazKVMA0GCSqGSIb3DQEBCwUAA4IBAQ |
| | | BXsAIEw7I5XUzLFHvXb2N0hmW/Vmhb/Vlv9LTT8JcCRJy4zaiyS9Q+Sp9zQUkrXauFnNAhJLwpAymjZ |
| | | MCOq1Th1bw9LnIzbccPQ/1+ZHLKDU5pgnc5BcvaV6Zl6COLLH2OOt0XMZ/OrODBV1M6STfhChqcowff |
| | | xp72pWMQe+kpZfzjeDBk4kK2hUNTZsimB9qRyrDAMCIXdmdmFv1o07orxjy8c/6S1329swiiVqFckBR |
| | | aXIa8wCcXjpQbZacDODeKk6wZIKxw4miLg1YByCMa7vkUfz+Jj+JHgbHjyoT/G82mtDbX02chLgXbDm |
| | | xJPFN3mwAC7NEkSPbqd35nJlf3 |
| | | objectClass: person |
| | | objectClass: inetOrgPerson |
| | | objectClass: organizationalPerson |
| | | objectClass: ds-certificate-user |
| | | objectClass: top |
| | | ds-certificate-subject-dn: CN=My App, OU=Apps, DC=example, DC=com |
| | | cn: My App |
| | | sn: App |
| | | $ bin/ldapmodify --hostname localhost --port 1636 --useSSL --trustAll \ |
| | | --bindDN 'cn=Directory Manager' --bindPassword password --filename add-cert.ldif |
| | | ---- |
| | | |
| | | . When using a self-signed certificate, import the client certificate into the truststore for OpenDJ. |
| | | . Add the self-signed client certificate to the server’s truststore. Verify the certificate when `keytool` asks whether to trust it, then restart the server. |
| | | + |
| | | When the client presents its certificate to OpenDJ, by default OpenDJ must trust the client certificate before it can accept the connection. If OpenDJ cannot trust the client certificate, it cannot establish a secure connection: |
| | | + |
| | | |
| | | [source, console] |
| | | ---- |
| | | $ keytool \ |
| | | -import \ |
| | | -alias myapp-cert \ |
| | | -file /path/to/myapp-cert.crt \ |
| | | -keystore /path/to/opendj/config/truststore \ |
| | | -storepass `cat /path/to/opendj/config/keystore.pin` |
| | | Owner: CN=My App, OU=Apps, DC=example, DC=com |
| | | Issuer: CN=My App, OU=Apps, DC=example, DC=com |
| | | Serial number: 5ae2277 |
| | | Valid from: Fri Jan 18 18:27:09 CET 2013 until: Thu Jan 13 18:27:09 CET 2033 |
| | | Certificate fingerprints: |
| | | MD5: 48:AC:F9:13:11:E0:AB:C4:65:A2:83:9E:DB:FE:0C:37 |
| | | SHA1: F9:61:54:37:AA:C1:BC:92:45:07:64:4B:23:6C:BC:C9:CD:1D:44:0F |
| | | SHA256: 2D:B1:58:CD:33:40:E9:...:FD:61:EA:C9:FF:6A:19:93:FE:E4:84:E3 |
| | | Signature algorithm name: SHA256withRSA |
| | | Version: 3 |
| | | |
| | | Extensions: |
| | | |
| | | #1: ObjectId: 2.5.29.14 Criticality=false |
| | | SubjectKeyIdentifier [ |
| | | KeyIdentifier [ |
| | | 0000: 54 C0 C5 9C 73 37 85 4B F2 3B D3 37 FD 45 0A AB T...s7.K.;.7.E.. |
| | | 0010: C9 6B 32 95 .k2. |
| | | ] |
| | | ] |
| | | |
| | | Trust this certificate? [no]: yes |
| | | Certificate was added to keystore |
| | | $ keytool -importcert -alias myapp-cert -file myapp-cert.der \ |
| | | -keystore config/truststore -storepass:file config/keystore.pin |
| | | $ bin/stop-ds --restart |
| | | ---- |
| | | |
| | | . When using a certificate signed by a CA whose certificate is not delivered with the Java runtime environmentfootnote:d0e6685[`$JAVA_HOME/jre/lib/security/cacerts`holds the certificates for many CAs. To get the full list, use the following command:], import the CA certificate either into the Java runtime environment truststore, or into the OpenDJ trust store as shown in the following example: |
| | | + |
| | | |
| | | [source, console] |
| | | ---- |
| | | $ keytool \ |
| | | -import \ |
| | | -alias ca-cert \ |
| | | -file ca.crt \ |
| | | -keystore /path/to/opendj/config/truststore \ |
| | | -storepass `cat /path/to/opendj/config/keystore.pin` |
| | | Owner: EMAILADDRESS=admin@example.com, CN=Example CA, O=Example Corp, C=FR |
| | | Issuer: EMAILADDRESS=admin@example.com, CN=Example CA, O=Example Corp, C=FR |
| | | Serial number: d4586ea05c878b0c |
| | | Valid from: Tue Jan 29 09:30:31 CET 2013 until: Mon Jan 24 09:30:31 CET 2033 |
| | | Certificate fingerprints: |
| | | MD5: 8A:83:61:9B:E7:18:A2:21:CE:92:94:96:59:68:60:FA |
| | | SHA1: 01:99:18:38:3A:57:D7:92:7B:D6:03:8C:7B:E4:1D:37:45:0E:29:DA |
| | | SHA256: 5D:20:F1:86:CC:CD:64:50:1E:54:...:DF:15:43:07:69:44:00:FB:36:CF |
| | | Signature algorithm name: SHA1withRSA |
| | | Version: 3 |
| | | |
| | | Extensions: |
| | | |
| | | #1: ObjectId: 2.5.29.35 Criticality=false |
| | | AuthorityKeyIdentifier [ |
| | | KeyIdentifier [ |
| | | 0000: 30 07 67 7D 1F 09 B6 E6 90 85 95 58 94 37 FD 31 0.g........X.7.1 |
| | | 0010: 03 D4 56 7B ..V. |
| | | ] |
| | | [EMAILADDRESS=admin@example.com, CN=Example CA, O=Example Corp, C=FR] |
| | | SerialNumber: [ d4586ea0 5c878b0c] |
| | | ] |
| | | |
| | | #2: ObjectId: 2.5.29.19 Criticality=false |
| | | BasicConstraints:[ |
| | | CA:true |
| | | PathLen:2147483647 |
| | | ] |
| | | |
| | | #3: ObjectId: 2.5.29.14 Criticality=false |
| | | SubjectKeyIdentifier [ |
| | | KeyIdentifier [ |
| | | 0000: 30 07 67 7D 1F 09 B6 E6 90 85 95 58 94 37 FD 31 0.g........X.7.1 |
| | | 0010: 03 D4 56 7B ..V. |
| | | ] |
| | | ] |
| | | |
| | | Trust this certificate? [no]: yes |
| | | Certificate was added to keystore |
| | | ---- |
| | | |
| | | . If you updated the OpenDJ truststore to add a certificate, restart OpenDJ to make sure it reads the updated truststore and recognizes the certificate: |
| | | + |
| | | |
| | | [source, console] |
| | | ---- |
| | | $ stop-ds --restart |
| | | Stopping Server... |
| | | ... |
| | | ... The Directory Server has started successfully |
| | | ---- |
| | | |
| | | ==== |
| | | |
| | | [#use-pkcs12-trust-store] |
| | | .To Use a PKCS #12 Truststore |
| | | ==== |
| | | The Java `keytool` command does not support importing trusted certificates into a PKCS #12 format store. Yet, Java does support creating a PKCS #12 format keystore, and using an existing PKCS #12 format store as a truststore. You can use a PKCS #12 store as an OpenDJ truststore. |
| | | |
| | | . Add the PKCS #12 format store to OpenDJ's configuration. |
| | | + |
| | | By default, OpenDJ expects the store to be `/path/to/opendj/config/truststore.p12`. The following example uses that default: |
| | | + |
| | | |
| | | [source, console] |
| | | ---- |
| | | $ cp /path/to/pkcs12-store /path/to/opendj/config/truststore.p12 |
| | | ---- |
| | | + |
| | | Here, __pkcs12-store__ is the file name of the PKCS #12 format store. |
| | | |
| | | . Configure the OpenDJ PKCS12 trust manager provider to use the PKCS #12 store, and restart OpenDJ server to force it to read the store. |
| | | + |
| | | In the following example, the store password is `changeit`: |
| | | + |
| | | |
| | | [source, console] |
| | | ---- |
| | | $ dsconfig \ |
| | | set-trust-manager-provider-prop \ |
| | | --port 4444 \ |
| | | --hostname opendj.example.com \ |
| | | --bindDN "cn=Directory Manager" \ |
| | | --bindPassword password \ |
| | | --provider-name PKCS12 \ |
| | | --set enabled:true \ |
| | | --set trust-store-pin:changeit \ |
| | | --no-prompt \ |
| | | --trustAll |
| | | $ stop-ds --restart |
| | | ---- |
| | | |
| | | . Configure a connection handler to use the PKCS12 trust manager provider. |
| | | + |
| | | The following example configures the LDAPS connection handler: |
| | | + |
| | | |
| | | [source, console] |
| | | ---- |
| | | $ dsconfig \ |
| | | set-connection-handler-prop \ |
| | | --port 4444 \ |
| | | --hostname opendj.example.com \ |
| | | --bindDN "cn=Directory Manager" \ |
| | | --bindPassword password \ |
| | | --handler-name "LDAPS Connection Handler" \ |
| | | --set trust-manager-provider:PKCS12 \ |
| | | --no-prompt \ |
| | | --trustAll |
| | | ---- |
| | | |
| | | . Verify SSL mutual authentication to check your work. |
| | | + |
| | | The following example assumes the client certificate for My App is present in the PKCS #12 store, and that the certificate has been added to the entry for My App as in xref:#add-client-cert["To Add Certificate Information to an Entry"]: |
| | | + |
| | | |
| | | [source, console] |
| | | ---- |
| | | $ ldapsearch \ |
| | | --port 1636 \ |
| | | --hostname opendj.example.com \ |
| | | --baseDN dc=example,dc=com \ |
| | | --useSSL \ |
| | | --useSASLExternal \ |
| | | --certNickName myapp-cert \ |
| | | --keyStorePath keystore \ |
| | | --keyStorePassword changeit \ |
| | | --trustStorePath /path/to/opendj/config/keystore \ |
| | | --trustStorePasswordFile /path/to/opendj/config/keystore.pin \ |
| | | "(cn=My App)" userPassword |
| | | dn: cn=My App,ou=Apps,dc=example,dc=com |
| | | userPassword: {SSHA}9jjvsv9wlTW7Ikflzc2/wMNBjAN6G4CbbTKYIw== |
| | | ---- |
| | | |
| | | To use a PKCS #12 server truststore, import the client certificate or its issuing CA certificate with `keytool -importcert -storetype PKCS12`. The OpenDJ PKCS12 trust manager provider defaults to `config/truststore.p12`. Enable that provider, set its PIN, and set the LDAPS connection handler’s `trust-manager-provider` property to `PKCS12`. See xref:../admin-guide/chap-connection-handlers.adoc#setup-server-cert[Preparing For Secure Communications]. |
| | | ==== |
| | | |
| | | [#config-cert-mappers] |
| | | .To Configure Certificate Mappers |
| | | ==== |
| | | -- |
| | | OpenDJ uses certificate mappers during binds to establish a mapping between a client certificate and the entry that corresponds to that certificate. The certificate mappers provided out of the box include the following: |
| | | The SASL EXTERNAL mechanism’s `certificate-mapper` property selects how OpenDJ finds the entry. The Subject Equals DN mapper matches the whole certificate subject DN to the entry DN. Other mappers use an attribute on the entry: |
| | | |
| | | Fingerprint Certificate Mapper:: |
| | | Looks for the MD5 (default) or SHA1 certificate fingerprint in an attribute of the entry (default: `ds-certificate-fingerprint`). |
| | | * `Subject Attribute to User Attribute` maps subject attributes, such as the common name, to directory attributes. |
| | | * `Subject DN to User Attribute` reads the certificate subject DN from `ds-certificate-subject-dn`. |
| | | * `Fingerprint Mapper` reads the certificate fingerprint from `ds-certificate-fingerprint`. To use the SHA-1 fingerprint shown by `keytool -list -v`, set `fingerprint-algorithm:sha1` on the mapper. |
| | | |
| | | Subject Attribute To User Attribute Mapper:: |
| | | Looks for a match between an attribute of the certificate subject and an attribute of the entry (default: match `cn` in the certificate to `cn` on the entry, or match `emailAddress` in the certificate to `mail` on the entry). |
| | | |
| | | Subject DN to User Attribute Certificate Mapper:: |
| | | Looks for the certificate subject DN in an attribute of the entry (default: `ds-certificate-subject-dn`). |
| | | |
| | | Subject Equals DN Certificate Mapper:: |
| | | Looks for an entry whose DN matches the certificate subject DN. |
| | | |
| | | -- |
| | | If the default configurations for the certificate mappers are acceptable, you do not need to change them. They are enabled by default. |
| | | |
| | | The following steps demonstrate how to change the Fingerprint Mapper default algorithm of MD5 to SHA1: |
| | | |
| | | . List the certificate mappers to retrieve the correct name: |
| | | + |
| | | |
| | | [source, console] |
| | | ---- |
| | | $ dsconfig \ |
| | | list-certificate-mappers \ |
| | | --port 4444 \ |
| | | --hostname opendj.example.com \ |
| | | --bindDN "cn=Directory Manager" \ |
| | | --bindPassword password |
| | | |
| | | Certificate Mapper : Type : enabled |
| | | ------------------------------------:-------------------------------------:-------- |
| | | Fingerprint Mapper : fingerprint : true |
| | | Subject Attribute to User Attribute : subject-attribute-to-user-attribute : true |
| | | Subject DN to User Attribute : subject-dn-to-user-attribute : true |
| | | Subject Equals DN : subject-equals-dn : true |
| | | ---- |
| | | |
| | | . Examine the current configuration: |
| | | + |
| | | |
| | | [source, console] |
| | | ---- |
| | | $ dsconfig \ |
| | | get-certificate-mapper-prop \ |
| | | --port 4444 \ |
| | | --hostname opendj.example.com \ |
| | | --bindDN "cn=Directory Manager" \ |
| | | --bindPassword password \ |
| | | --mapper-name "Fingerprint Mapper" |
| | | |
| | | Property : Value(s) |
| | | ----------------------:--------------------------- |
| | | enabled : true |
| | | fingerprint-algorithm : md5 |
| | | fingerprint-attribute : ds-certificate-fingerprint |
| | | user-base-dn : - |
| | | ---- |
| | | |
| | | . Change the configuration as necessary: |
| | | + |
| | | |
| | | [source, console] |
| | | ---- |
| | | $ dsconfig \ |
| | | set-certificate-mapper-prop \ |
| | | --port 4444 \ |
| | | --hostname opendj.example.com \ |
| | | --bindDN "cn=Directory Manager" \ |
| | | --bindPassword password \ |
| | | --mapper-name "Fingerprint Mapper" \ |
| | | --set fingerprint-algorithm:sha1 \ |
| | | --no-prompt |
| | | ---- |
| | | |
| | | . Set the External SASL Mechanism Handler to use the appropriate certificate mapper (default: Subject Equals DN). |
| | | + |
| | | Client applications use the SASL External mechanism during the bind to have OpenDJ set the authorization identifier based on the entry that matches the client certificate: |
| | | + |
| | | |
| | | [source, console] |
| | | ---- |
| | | $ dsconfig \ |
| | | set-sasl-mechanism-handler-prop \ |
| | | --port 4444 \ |
| | | --hostname opendj.example.com \ |
| | | --bindDN "cn=Directory Manager" \ |
| | | --bindPassword password \ |
| | | --handler-name External \ |
| | | --set certificate-mapper:"Fingerprint Mapper" \ |
| | | --no-prompt |
| | | ---- |
| | | |
| | | Use `dsconfig set-certificate-mapper-prop` to configure a mapper and `dsconfig set-sasl-mechanism-handler-prop --handler-name External` to select it. The `ds-certificate-user` auxiliary object class allows the fingerprint and subject DN attributes on an entry. |
| | | ==== |
| | | |
| | | [#auth-with-client-cert] |
| | | .Authenticating With Client Certificates |
| | | ==== |
| | | Instead of providing a bind DN and password as for simple authentication, use the SASL EXTERNAL authentication mechanism, and provide the certificate. As a test with example data, you can try an anonymous search, then try with certificate-based authentication. |
| | | |
| | | Before you try this example, make sure OpenDJ is set up to accept StartTLS from clients, and that you have set up the client certificate as described above. Next, create a password .pin file for your client key store: |
| | | Use `--reportAuthzID` to verify that the server bound the client as the expected entry. |
| | | |
| | | [source, console] |
| | | ---- |
| | | $ echo changeit > keystore.pin |
| | | $ chmod 400 keystore.pin |
| | | ---- |
| | | Also, if OpenDJ directory server uses a certificate for StartTLS that was not signed by a well-known CA, import the appropriate certificate into the client keystore, which can then double as a truststore. For example, if OpenDJ uses a self-signed certificate, import the server certificate into the keystore: |
| | | |
| | | [source, console] |
| | | ---- |
| | | $ keytool \ |
| | | -export \ |
| | | -alias server-cert \ |
| | | -file server-cert.crt \ |
| | | -keystore /path/to/opendj/config/keystore \ |
| | | -storepass `cat /path/to/opendj/config/keystore.pin` |
| | | |
| | | $ keytool \ |
| | | -import \ |
| | | -trustcacerts \ |
| | | -alias server-cert \ |
| | | -file server-cert.crt \ |
| | | -keystore keystore \ |
| | | -storepass `cat keystore.pin` |
| | | ---- |
| | | If OpenDJ directory server uses a CA-signed certificate, but the CA is not well-known, import the CA certificate into your keystore: |
| | | |
| | | [source, console] |
| | | ---- |
| | | $ keytool \ |
| | | -import \ |
| | | -trustcacerts \ |
| | | -alias ca-cert \ |
| | | -file ca-cert.crt \ |
| | | -keystore keystore \ |
| | | -storepass `cat keystore.pin` |
| | | ---- |
| | | Now that you can try the example, notice that OpenDJ does not return the `userPassword` value for an anonymous search: |
| | | |
| | | [source, console] |
| | | ---- |
| | | $ ldapsearch \ |
| | | --port 1389 \ |
| | | --hostname opendj.example.com \ |
| | | --baseDN dc=example,dc=com \ |
| | | --useStartTLS \ |
| | | --trustStorePath keystore \ |
| | | --trustStorePasswordFile keystore.pin \ |
| | | "(cn=My App)" userPassword |
| | | $ bin/ldapsearch --hostname localhost --port 1636 --useSSL --trustAll \ |
| | | --saslOption mech=EXTERNAL --certNickname myapp-cert \ |
| | | --keyStorePath client-keystore.p12 --keyStorePassword changeit \ |
| | | --reportAuthzID --baseDN 'cn=My App,ou=Apps,dc=example,dc=com' \ |
| | | --searchScope base '(objectClass=*)' cn |
| | | # Bound with authorization ID dn:cn=My App,ou=Apps,dc=example,dc=com |
| | | dn: cn=My App,ou=Apps,dc=example,dc=com |
| | | ---- |
| | | OpenDJ does let users read the values of their own `userPassword` attributes after they bind successfully: |
| | | |
| | | [source, console] |
| | | ---- |
| | | $ ldapsearch \ |
| | | --port 1389 \ |
| | | --hostname opendj.example.com \ |
| | | --baseDN dc=example,dc=com \ |
| | | --useStartTLS \ |
| | | --useSASLExternal \ |
| | | --certNickName myapp-cert \ |
| | | --keyStorePath keystore \ |
| | | --keyStorePasswordFile keystore.pin \ |
| | | --trustStorePath keystore \ |
| | | --trustStorePasswordFile keystore.pin \ |
| | | "(cn=My App)" userPassword |
| | | dn: cn=My App,ou=Apps,dc=example,dc=com |
| | | userPassword: {SSHA}vy/vTthOQoV/wH3MciTOBKKR4OX+0dSN/a09Ew== |
| | | ---- |
| | | You can also try the same test with other certificate mappers: |
| | | |
| | | [source, console] |
| | | ---- |
| | | # Fingerprint mapper |
| | | $ dsconfig \ |
| | | set-sasl-mechanism-handler-prop \ |
| | | --port 4444 \ |
| | | --hostname opendj.example.com \ |
| | | --bindDN "cn=Directory Manager" \ |
| | | --bindPassword password \ |
| | | --handler-name External \ |
| | | --set certificate-mapper:"Fingerprint Mapper" \ |
| | | --no-prompt |
| | | |
| | | $ ldapsearch \ |
| | | --port 1389 \ |
| | | --hostname opendj.example.com \ |
| | | --baseDN dc=example,dc=com \ |
| | | --useStartTLS \ |
| | | --useSASLExternal \ |
| | | --certNickName myapp-cert \ |
| | | --keyStorePath keystore \ |
| | | --keyStorePasswordFile keystore.pin \ |
| | | --trustStorePath keystore \ |
| | | --trustStorePasswordFile keystore.pin \ |
| | | "(cn=My App)" userPassword |
| | | dn: cn=My App,ou=Apps,dc=example,dc=com |
| | | userPassword: {SSHA}vy/vTthOQoV/wH3MciTOBKKR4OX+0dSN/a09Ew== |
| | | ---- |
| | | |
| | | [source, console] |
| | | ---- |
| | | # Subject Attribute to User Attribute mapper |
| | | $ dsconfig \ |
| | | set-sasl-mechanism-handler-prop \ |
| | | --port 4444 \ |
| | | --hostname opendj.example.com \ |
| | | --bindDN "cn=Directory Manager" \ |
| | | --bindPassword password \ |
| | | --handler-name External \ |
| | | --set certificate-mapper:"Subject Attribute to User Attribute" \ |
| | | --no-prompt |
| | | |
| | | $ ldapsearch \ |
| | | --port 1389 \ |
| | | --hostname opendj.example.com \ |
| | | --baseDN dc=example,dc=com \ |
| | | --useStartTLS \ |
| | | --useSASLExternal \ |
| | | --certNickName myapp-cert \ |
| | | --keyStorePath keystore \ |
| | | --keyStorePasswordFile keystore.pin \ |
| | | --trustStorePath keystore \ |
| | | --trustStorePasswordFile keystore.pin \ |
| | | "(cn=My App)" userPassword |
| | | dn: cn=My App,ou=Apps,dc=example,dc=com |
| | | userPassword: {SSHA}vy/vTthOQoV/wH3MciTOBKKR4OX+0dSN/a09Ew== |
| | | ---- |
| | | |
| | | [source, console] |
| | | ---- |
| | | # Subject DN to User Attribute mapper |
| | | $ dsconfig \ |
| | | set-sasl-mechanism-handler-prop \ |
| | | --port 4444 \ |
| | | --hostname opendj.example.com \ |
| | | --bindDN "cn=Directory Manager" \ |
| | | --bindPassword password \ |
| | | --handler-name External \ |
| | | --set certificate-mapper:"Subject DN to User Attribute" \ |
| | | --no-prompt |
| | | |
| | | $ ldapsearch \ |
| | | --port 1389 \ |
| | | --hostname opendj.example.com \ |
| | | --baseDN dc=example,dc=com \ |
| | | --useStartTLS \ |
| | | --useSASLExternal \ |
| | | --certNickName myapp-cert \ |
| | | --keyStorePath keystore \ |
| | | --keyStorePasswordFile keystore.pin \ |
| | | --trustStorePath keystore \ |
| | | --trustStorePasswordFile keystore.pin \ |
| | | "(cn=My App)" userPassword |
| | | dn: cn=My App,ou=Apps,dc=example,dc=com |
| | | userPassword: {SSHA}vy/vTthOQoV/wH3MciTOBKKR4OX+0dSN/a09Ew== |
| | | cn: My App |
| | | ---- |
| | | ==== |
| | | |
| | | |
| New file |
| | |
| | | //// |
| | | The contents of this file are subject to the terms of the Common Development and |
| | | Distribution License (the License). You may not use this file except in compliance with the |
| | | License. |
| | | |
| | | You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the |
| | | specific language governing permission and limitations under the License. |
| | | |
| | | When distributing Covered Software, include this CDDL Header Notice in each file and include |
| | | the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL |
| | | Header, with the fields enclosed by brackets [] replaced by your own identifying |
| | | information: "Portions copyright [year] [name of copyright owner]". |
| | | |
| | | Copyright 2026 3A Systems, LLC. |
| | | //// |
| | | |
| | | :table-caption!: |
| | | :opendj-sdk-example-version: 5.2.0 |
| | | :opendj-sdk-javadoc: https://doc.openidentityplatform.org/opendj/apidocs/org/forgerock/opendj |
| | | :opendj-sdk-examples: https://github.com/OpenIdentityPlatform/OpenDJ/blob/{opendj-sdk-example-version}/opendj-ldap-sdk-examples/src/main/java/org/forgerock/opendj/examples |
| | | |
| | | ifndef::env-site[] |
| | | [#chap-ldap-sdk] |
| | | endif::[] |
| | | == Developing Java LDAP Clients |
| | | |
| | | ifdef::env-site[] |
| | | anchor:chap-ldap-sdk[] |
| | | endif::[] |
| | | |
| | | This example uses the OpenDJ LDAP SDK {opendj-sdk-example-version} to check which LDAP versions a server supports. |
| | | |
| | | [#ldap-sdk-maven] |
| | | === Add the SDK to a Maven Project |
| | | |
| | | Use Java 11 or later and Maven 3. Save this `pom.xml`. The `opendj-grizzly` dependency brings in the `opendj-core` SDK and provides its LDAP network transport. |
| | | |
| | | [source,xml,subs="+attributes"] |
| | | ---- |
| | | <project xmlns="http://maven.apache.org/POM/4.0.0"> |
| | | <modelVersion>4.0.0</modelVersion> |
| | | <groupId>com.example</groupId> |
| | | <artifactId>ldap-client</artifactId> |
| | | <version>1.0.0</version> |
| | | <properties> |
| | | <maven.compiler.source>11</maven.compiler.source> |
| | | <maven.compiler.target>11</maven.compiler.target> |
| | | </properties> |
| | | <dependencies> |
| | | <dependency> |
| | | <groupId>org.openidentityplatform.opendj</groupId> |
| | | <artifactId>opendj-grizzly</artifactId> |
| | | <version>{opendj-sdk-example-version}</version> |
| | | </dependency> |
| | | </dependencies> |
| | | </project> |
| | | ---- |
| | | |
| | | [#ldap-sdk-search] |
| | | === Read the Root DSE |
| | | |
| | | Start the evaluation server from xref:../getting-started/first-steps.adoc#getting-started-first-directory[Your First Directory]. The example reads the root DSE, an entry with public server information, from its LDAP listener on port 1389. |
| | | |
| | | Save this class as `src/main/java/ReadCapabilities.java`. |
| | | |
| | | [source,java] |
| | | ---- |
| | | import org.forgerock.opendj.ldap.Connection; |
| | | import org.forgerock.opendj.ldap.LDAPConnectionFactory; |
| | | import org.forgerock.opendj.ldap.RootDSE; |
| | | |
| | | public final class ReadCapabilities { |
| | | public static void main(String[] args) throws Exception { |
| | | try (LDAPConnectionFactory factory = new LDAPConnectionFactory("localhost", 1389); |
| | | Connection connection = factory.getConnection()) { |
| | | RootDSE rootDse = RootDSE.readRootDSE(connection); |
| | | var versions = rootDse.getSupportedLDAPVersions(); |
| | | System.out.println("LDAPv3 supported = " + versions.contains(3)); |
| | | } |
| | | } |
| | | } |
| | | ---- |
| | | |
| | | Run this command from the Maven project directory. |
| | | |
| | | [source,bash] |
| | | ---- |
| | | mvn -q compile exec:java -Dexec.mainClass=ReadCapabilities |
| | | ---- |
| | | |
| | | The program prints `LDAPv3 supported = true`. The link:{opendj-sdk-javadoc}/ldap/RootDSE.html[`RootDSE`] class also exposes naming contexts, supported controls, and extended operations. |
| | | |
| | | [#ldap-sdk-next-steps] |
| | | === Use the SDK in an Application |
| | | |
| | | * For simple authentication, call `Connection.bind` after connecting over LDAPS or StartTLS. Configure link:{opendj-sdk-javadoc}/ldap/LDAPConnectionFactory.html[`LDAPConnectionFactory`] with `SSL_CONTEXT` and a trust configuration that validates the server certificate and identity. Set `SSL_USE_STARTTLS` to `true` to negotiate TLS on an LDAP listener. See `getTrustOptions()` in link:{opendj-sdk-examples}/SimpleAuth.java[`SimpleAuth.java`] for certificate and hostname verification. |
| | | * For SASL PLAIN, use link:{opendj-sdk-examples}/SASLAuth.java[`SASLAuth.java`] to see how to construct the bind request. Its StartTLS setup uses `TrustManagers.trustAll()` for local testing. Use the verified TLS setup above when sending credentials from an application. |
| | | * Use `Connection.search` to read multiple entries. Set a specific base DN, scope and filter, and request the attributes you need. See xref:chap-ldap-operations.adoc#search-ldap[Searching the Directory] for equivalent command-line examples and link:{opendj-sdk-examples}/Search.java[`Search`] for an SDK example that handles entries and continuation references. Follow referrals only to servers your application trusts. Use `Connection.compare` to compare an attribute value and check the LDAP result code for the outcome. |
| | | * Use a connection factory or a pool for repeated operations. Close connections when finished with them and close the factory at application shutdown. Use separate connections for binds as different users. For concurrent operations, see link:{opendj-sdk-examples}/SearchAsync.java[`SearchAsync`] and link:{opendj-sdk-examples}/ModifyAsync.java[`ModifyAsync`]. SDK methods report LDAP failures through `LdapException`, whose result carries the LDAP result code and diagnostic details. |
| | | * Use link:{opendj-sdk-javadoc}/ldap/requests/Requests.html[`Requests`] to construct add, modify, modify DN, delete, and extended operation requests. See link:{opendj-sdk-examples}/Modify.java[`Modify`], link:{opendj-sdk-examples}/UpdateGroup.java[`UpdateGroup`], and link:{opendj-sdk-examples}/ExtendedOperations.java[`ExtendedOperations`]. For request controls, check `supportedControl` before depending on a control and see link:{opendj-sdk-examples}/Controls.java[`Controls`] and link:{opendj-sdk-examples}/UseGenericControl.java[`UseGenericControl`]. |
| | | * For schema discovery, read `subschemaSubentry` or use the link:{opendj-sdk-examples}/ReadSchema.java[`ReadSchema`] example. For files in LDAP Data Interchange Format (LDIF), use the link:{opendj-sdk-javadoc}/ldif/package-summary.html[`org.forgerock.opendj.ldif`] readers and writers. Use an entry reader for entries and a change record reader for LDIF files that describe updates. |
| | | * The SDK uses localized messages. Handle errors by result code and use `getLocalizedMessage()` for messages presented to users. |
| | | * A proxy can reuse connections and distribute them among servers with link:{opendj-sdk-javadoc}/ldap/Connections.html[`Connections`]. For listener and request handler examples, see link:{opendj-sdk-examples}/Proxy.java[`Proxy`] and link:{opendj-sdk-examples}/RewriterProxy.java[`RewriterProxy`]. |
| | |
| | | information: "Portions copyright [year] [name of copyright owner]". |
| | | |
| | | Copyright 2017 ForgeRock AS. |
| | | Portions Copyright 2024-2025 3A Systems LLC. |
| | | Portions Copyright 2024-2026 3A Systems, LLC. |
| | | //// |
| | | |
| | | :figure-caption!: |
| | |
| | | :table-caption!: |
| | | |
| | | |
| | | ifndef::env-site[] |
| | | [#chap-rest-operations-3-0] |
| | | endif::[] |
| | | == Performing RESTful Operations (3.0) |
| | | |
| | | ifdef::env-site[] |
| | | anchor:chap-rest-operations-3-0[] |
| | | endif::[] |
| | | |
| | | OpenDJ lets you access directory data as link:http://json.org[JSON, window=\_blank] resources over HTTP. OpenDJ maps JSON resources onto LDAP entries. As a result, REST clients perform many of the same operations as LDAP clients with directory data. |
| | | |
| | | This chapter demonstrates RESTful client operations by using the default configuration and sample directory data imported into OpenDJ directory server as described in xref:../admin-guide/chap-import-export.adoc#import-ldif["To Import LDIF Data"] in the __Administration Guide__, from the LDIF file link:../attachments/Example.ldif[Example.ldif, window=\_blank]. |
| | | |
| | | [NOTE] |
| | | ==== |
| | | The default configuration has changed in OpenDJ 3.5. |
| | | |
| | | If you are using OpenDJ 3.5, see xref:chap-rest-operations.adoc#chap-rest-operations["Performing RESTful Operations"] and xref:../reference/appendix-rest2ldap.adoc#appendix-rest2ldap["REST to LDAP Configuration"] in the __Reference__. |
| | | These examples document the original OpenDJ 3.0 REST API and its `/users` and `/groups` paths. For the current Rest2ldap endpoint under `/api`, see xref:chap-rest-operations.adoc#chap-rest-operations["Performing RESTful Operations"] and xref:../reference/appendix-rest2ldap.adoc#appendix-rest2ldap["REST to LDAP Configuration"] in the __Reference__. |
| | | ==== |
| | | In this chapter, you will learn how to use the OpenDJ REST API that provides access to directory data over HTTP. In particular, you will learn how to: |
| | | |
| | |
| | | -- |
| | | For query operations, the filter __expression__ is constructed from the following building blocks. Make sure you URL-encode the filter expressions, which are shown here without URL-encoding to make them easier to read. |
| | | |
| | | In filter expressions, the simplest __json-pointer__ is a field of the JSON resource, such as `userName` or `id`. A __json-pointer__ can also point to nested elements as described in the link:http://tools.ietf.org/html/draft-ietf-appsawg-json-pointer[JSON Pointer, window=\_blank] Internet-Draft: |
| | | In filter expressions, the simplest __json-pointer__ is a field of the JSON resource, such as `userName` or `id`. A __json-pointer__ can also point to nested elements as described in the link:https://www.rfc-editor.org/rfc/rfc6901[JSON Pointer (RFC 6901), window=\_blank] specification: |
| | | |
| | | Comparison expressions:: |
| | | [open] |
| | |
| | | information: "Portions copyright [year] [name of copyright owner]". |
| | | |
| | | Copyright 2017 ForgeRock AS. |
| | | Portions Copyright 2024-2025 3A Systems LLC. |
| | | Portions Copyright 2024-2026 3A Systems, LLC. |
| | | //// |
| | | |
| | | :figure-caption!: |
| | |
| | | :table-caption!: |
| | | |
| | | |
| | | ifndef::env-site[] |
| | | [#chap-rest-operations] |
| | | endif::[] |
| | | == Performing RESTful Operations |
| | | |
| | | OpenDJ lets you access directory data as link:http://json.org[JSON, window=\_blank] resources over HTTP. OpenDJ maps JSON resources onto LDAP entries. As a result, REST clients perform many of the same operations as LDAP clients with directory data. |
| | | ifdef::env-site[] |
| | | anchor:chap-rest-operations[] |
| | | endif::[] |
| | | |
| | | This chapter demonstrates RESTful client operations by using the default configuration and sample directory data imported into OpenDJ directory server as described in xref:../admin-guide/chap-import-export.adoc#import-ldif["To Import LDIF Data"] in the __Administration Guide__, from the LDIF file link:../attachments/Example.ldif[Example.ldif, window=\_blank]. |
| | | OpenDJ’s Rest2ldap endpoint maps LDAP entries to JSON resources under `/api`. To run the examples, import link:../attachments/Example.ldif[Example.ldif] and enable the HTTP connection handler. See xref:../admin-guide/chap-import-export.adoc#import-ldif[To Import LDIF Data] and xref:../admin-guide/chap-connection-handlers.adoc#setup-rest2ldap[RESTful Client Access Over HTTP]. Replace `opendj.example.com` with your evaluation server’s hostname. Use HTTPS for deployed client connections that carry credentials. |
| | | |
| | | [NOTE] |
| | | ==== |
| | | The default configuration has changed in OpenDJ 3.5. |
| | | |
| | | If you are using OpenDJ 3.0, see xref:chap-rest-operations-3-0.adoc#chap-rest-operations-3-0["Performing RESTful Operations (3.0)"] and xref:../reference/appendix-rest2ldap-3-0.adoc#appendix-rest2ldap-3-0["REST to LDAP Configuration (3.0)"] in the __Reference__. |
| | | ==== |
| | | In this chapter, you will learn how to use the OpenDJ REST API that provides access to directory data over HTTP. In particular, you will learn how to: |
| | | |
| | | * link:#create-rest[Create] a resource that does not yet exist |
| | | |
| | | * link:#read-rest[Read] a single resource |
| | | |
| | | * link:#update-rest[Update] an existing resource |
| | | |
| | | * link:#delete-rest[Delete] an existing resource |
| | | |
| | | * link:#patch-rest[Patch] part of an existing resource |
| | | |
| | | * Perform a predefined link:#action-rest[action] |
| | | |
| | | * link:#query-rest[Query] a set of resources |
| | | |
| | | * Work with other link:#mime-types-rest[MIME types] for resources like photos |
| | | |
| | | Before trying the examples, enable HTTP access to OpenDJ directory server as described in xref:../admin-guide/chap-connection-handlers.adoc#setup-rest2ldap-endpoint["To Set Up REST Access to User Data"] in the __Administration Guide__. (If you are using OpenDJ 3.0, see xref:../admin-guide/chap-connection-handlers.adoc#setup-rest2ldap-3-0["RESTful Client Access (3.0)"] in the __Administration Guide__ instead.) The examples in this chapter use HTTP, but the procedure also shows how to set up HTTPS access to the server. |
| | | |
| | | Interface stability: Evolving (See xref:../reference/appendix-interface-stability.adoc#interface-stability["Product Interface Stability"] in the __Reference__.) |
| | | |
| | | The OpenDJ REST API is built on a common Open Identity Platform HTTP-based REST API for interacting with JSON Resources. All APIs built on this common layer let you perform the following operations. |
| | | For the original OpenDJ 3.0 handler and gateway, see xref:chap-rest-operations-3-0.adoc#chap-rest-operations-3-0[Performing RESTful Operations (3.0)]. See the xref:../reference/appendix-interface-stability.adoc#interface-stability[Product Interface Stability] reference for the current endpoint’s Evolving interface stability. |
| | | |
| | | [#sec-about-crest] |
| | | === About Common REST |
| | | |
| | | For many REST APIs that are not defined by external standards, Open Identity Platform products provide common ways to access web resources and collections of resources. This section covers what is common across products. Adapt the examples to your types of resources and to your deployment. |
| | | Open Identity Platform products share a set of Common REST conventions. Each endpoint implements the operations and parameters appropriate to its resources. See xref:#patch-rest["Patching Resources"] and xref:#query-rest["Querying Resource Collections"] for the options supported by the OpenDJ Rest2ldap endpoint. |
| | | |
| | | [#about-crest-resources] |
| | | ==== Common REST Resources |
| | |
| | | |
| | | There are two ways to create a resource, either with an HTTP POST or with an HTTP PUT. |
| | | |
| | | To create a resource using POST, perform an HTTP POST with the query string parameter `_action=create` and the JSON resource as a payload. Accept a JSON response. The server creates the identifier if not specified: |
| | | To create a resource using POST, perform an HTTP POST with the query string parameter `_action=create` and the JSON resource as a payload. Accept a JSON response. The collection’s naming strategy determines whether the client or server supplies the identifier. The example `/api/users` mapping requires an `_id` in the JSON body. |
| | | |
| | | [source, httprequest] |
| | | ---- |
| | |
| | | ---- |
| | | [ |
| | | { |
| | | "fruits" : [ "orange", "pineapple", "lime" ], |
| | | "fruits" : [ "orange", "pineapple", "lime" ] |
| | | } |
| | | ] |
| | | ---- |
| | |
| | | |
| | | Some HTTP client libraries do not support the HTTP PATCH operation. Make sure that the library you use supports HTTP PATCH before using this REST operation. |
| | | |
| | | For example, the Java Development Kit HTTP client does not support PATCH as a valid HTTP method. Instead, the method `HttpURLConnection.setRequestMethod("PATCH")` throws `ProtocolException`. |
| | | In Java, use `java.net.http.HttpRequest.Builder.method("PATCH", bodyPublisher)` to build a PATCH request. The older `HttpURLConnection.setRequestMethod("PATCH")` throws `ProtocolException`. |
| | | .Parameters |
| | | -- |
| | | You can use the following parameters. Other parameters might depend on the specific action implementation: |
| | |
| | | The `_pagedResultsCookie` and `_pagedResultsOffset` parameters are mutually exclusive, and not to be used together. |
| | | |
| | | `_pageSize=integer`:: |
| | | Return query results in pages of this size. After the initial request, use `_pagedResultsCookie` or `_pageResultsOffset` to page through the results. |
| | | Return query results in pages of this size. After the initial request, use `_pagedResultsCookie` or `_pagedResultsOffset` to page through the results. |
| | | |
| | | `_totalPagedResultsPolicy=string`:: |
| | | When a `_pageSize` is specified, and non-zero, the server calculates the "totalPagedResults", in accordance with the `totalPagedResultsPolicy`, and provides the value as part of the response. The "totalPagedResults" is either an estimate of the total number of paged results (`_totalPagedResultsPolicy=ESTIMATE`), or the exact total result count (`_totalPagedResultsPolicy=EXACT`). If no count policy is specified in the query, or if `_totalPagedResultsPolicy=NONE`, result counting is disabled, and the server returns value of -1 for "totalPagedResults". |
| | |
| | | [#about-crest-modify-password] |
| | | ==== Change Your Password |
| | | |
| | | |
| | | [NOTE] |
| | | ==== |
| | | This action requires HTTPS to avoid sending the password over an insecure connection. |
| | | ==== |
| | | Perform an HTTPS POST with the header Content-Type: application/json, _action=modifyPassword in the query string, and the old and new passwords in JSON format as the POST data. |
| | | -- |
| | | |
| | | oldPassword:: |
| | | The value of this field is the current password as a UTF-8 string. |
| | | |
| | | |
| | | newPassword:: |
| | | The value of this field is the current password as a UTF-8 string. |
| | | |
| | | -- |
| | | On success, the HTTP status code is 200 OK, and the response body is an empty JSON resource: |
| | | |
| | | [source, console] |
| | | ---- |
| | | $ curl \ |
| | | --request POST \ |
| | | --cacert ca-cert.pem \ |
| | | --user bjensen:hifalutin \ |
| | | --header "Content-Type: application/json" \ |
| | | --data '{"oldPassword": "hifalutin", "newPassword": "chngthspwd"}' \ |
| | | --silent \ |
| | | https://localhost:8443/api/users/bjensen?_action=modifyPassword |
| | | |
| | | {} |
| | | ---- |
| | | |
| | | Use `modifyPassword` over HTTPS and supply the current and new passwords. See xref:#rest-action-modify-password[Changing Passwords] for the request and response. |
| | | |
| | | [#about-crest-reset-password] |
| | | ==== Reset a Password |
| | | |
| | | Whenever one user changes another user’s password, DS servers consider it a password reset. Often, password policies specify that users must change their passwords again after a password reset. |
| | | |
| | | [NOTE] |
| | | ==== |
| | | This action requires HTTPS to avoid sending the password over an insecure connection. |
| | | ==== |
| | | Perform an HTTPS POST with the header Content-Type: application/json, _action=resetPassword in the query string, and an empty JSON document ({}) as the POST data. |
| | | |
| | | The JSON POST DATA must include the following fields: |
| | | |
| | | The following example demonstrates an administrator changing a user’s password. Before trying this example, make sure the password administrator has been given the password-reset privilege. Otherwise, the password administrator has insufficient access. On success, the HTTP status code is 200 OK, and the response body is a JSON resource with a generatedPassword containing the new password: |
| | | |
| | | [source, console] |
| | | ---- |
| | | $ curl \ |
| | | --request POST \ |
| | | --cacert ca-cert.pem \ |
| | | --user kvaughan:bribery \ |
| | | --header "Content-Type: application/json" \ |
| | | --data '{}' \ |
| | | --silent \ |
| | | https://localhost:8443/api/users/bjensen?_action=resetPassword |
| | | {"generatedPassword":"new-password"} |
| | | ---- |
| | | As password administrator, provide the new, generated password to the user. |
| | | |
| | | Use `resetPassword` over HTTPS to generate a password for the target user. See xref:#rest-action-reset-password[Resetting Passwords] for the administrator permissions and request. |
| | | |
| | | [#about-crest-response-codes] |
| | | ==== HTTP Status Codes |
| | |
| | | [#authenticate-rest] |
| | | === Authenticating Over REST |
| | | |
| | | When you first try to read a resource that can be read as an LDAP entry with an anonymous search, you learn that you must authenticate as shown in the following example: |
| | | The default `/api` endpoint uses HTTP Basic authentication and returns HTTP 401 if credentials are missing. With the example data, Babs Jensen authenticates as `bjensen`, the `uid` of her entry `uid=bjensen,ou=People,dc=example,dc=com`. |
| | | |
| | | [source, console] |
| | | ---- |
| | | $ curl http://opendj.example.com:8080/api/users/bjensen |
| | | $ curl --user bjensen:hifalutin http://opendj.example.com:8080/api/users/bjensen |
| | | { |
| | | "code" : 401, |
| | | "reason" : "Unauthorized", |
| | | "message" : "Unauthorized" |
| | | } |
| | | ---- |
| | | HTTP status code 401 indicates that the request requires user authentication. |
| | | |
| | | To prevent OpenDJ directory server from requiring authentication, set the Rest2ldap endpoint `authorization-mechanism` to map anonymous HTTP requests to LDAP requests performed by an authorized user, as in the following example that uses Kirsten Vaughan's identity: |
| | | |
| | | [source, console] |
| | | ---- |
| | | $ dsconfig \ |
| | | set-http-authorization-mechanism-prop \ |
| | | --hostname opendj.example.com \ |
| | | --port 4444 \ |
| | | --bindDN "cn=Directory Manager" \ |
| | | --bindPassword password \ |
| | | --mechanism-name "HTTP Anonymous" \ |
| | | --set enabled:true \ |
| | | --set user-dn:uid=kvaughan,ou=people,dc=example,dc=com \ |
| | | --no-prompt \ |
| | | --trustAll |
| | | |
| | | $ dsconfig \ |
| | | set-http-endpoint-prop \ |
| | | --hostname opendj.example.com \ |
| | | --port 4444 \ |
| | | --bindDN "cn=Directory Manager" \ |
| | | --bindPassword password \ |
| | | --endpoint-name "/api" \ |
| | | --set authorization-mechanism:"HTTP Anonymous" \ |
| | | --no-prompt \ |
| | | --trustAll |
| | | ---- |
| | | By default, both the Rest2ldap endpoint and also the REST to LDAP gateway allow HTTP Basic authentication and HTTP header-based authentication in the style of OpenIDM. The authentication mechanisms translate HTTP authentication to LDAP authentication to the directory server. |
| | | |
| | | When you install OpenDJ either with generated sample user entries or with data from link:../attachments/Example.ldif[Example.ldif, window=\_blank], the relative distinguished name (DN) attribute for sample user entries is the user ID (`uid`) attribute. For example, the DN and user ID for Babs Jensen are: |
| | | |
| | | [source, ldif] |
| | | ---- |
| | | dn: uid=bjensen,ou=People,dc=example,dc=com |
| | | uid: bjensen |
| | | ---- |
| | | Given this pattern in the user entries, the default REST to LDAP configuration translates the HTTP user name to the LDAP user ID. User entries are found directly under `ou=People,dc=example,dc=com`.footnote:d0e1832[In general, REST to LDAP mappings require that LDAP entries mapped to JSON resources be immediate subordinates of the mapping's baseDN.] In other words, Babs Jensen authenticates as `bjensen` (password: `hifalutin`) over HTTP. The corresponding LDAP bind DN is `uid=bjensen,ou=People,dc=example,dc=com`. |
| | | |
| | | HTTP Basic authentication works as shown in the following example: |
| | | |
| | | [source, console] |
| | | ---- |
| | | $ curl \ |
| | | --user bjensen:hifalutin \ |
| | | http://opendj.example.com:8080/api/users/bjensen |
| | | { |
| | | "_rev" : "000000009ce6c3c3", |
| | | "_id": "bjensen", |
| | | ... |
| | | } |
| | | ---- |
| | | The alternative HTTP Basic __username__:__password__@ form in the URL works as shown in the following example: |
| | | |
| | | [source, console] |
| | | ---- |
| | | $ curl \ |
| | | http://bjensen:hifalutin@opendj.example.com:8080/api/users/bjensen |
| | | { |
| | | "_rev" : "000000009ce6c3c3", |
| | | ... |
| | | } |
| | | ---- |
| | | HTTP header based authentication works as shown in the following example: |
| | | The endpoint also accepts `X-OpenIDM-Username` and `X-OpenIDM-Password` headers by default. To change authentication or allow anonymous access to public data, see xref:../admin-guide/chap-connection-handlers.adoc#setup-http-authorization[To Set Up HTTP Authorization]. |
| | | |
| | | [source, console] |
| | | ---- |
| | | $ curl \ |
| | | --header "X-OpenIDM-Username: bjensen" \ |
| | | --header "X-OpenIDM-Password: hifalutin" \ |
| | | http://opendj.example.com:8080/api/users/bjensen |
| | | { |
| | | "_rev" : "000000009ce6c3c3", |
| | | ... |
| | | } |
| | | ---- |
| | | If the directory data is laid out differently or if the user names are email addresses rather than user IDs, for example, then you must update the configuration in order for authentication to work. |
| | | [#rest-default-mapping] |
| | | === Default REST Resources |
| | | |
| | | The REST to LDAP gateway can also translate HTTP user name and password authentication to LDAP PLAIN SASL authentication. Likewise, the gateway falls back to proxied authorization as necessary, using a root DN authenticated connection to LDAP servers. See xref:../reference/appendix-rest2ldap.adoc#appendix-rest2ldap["REST to LDAP Configuration"] in the __Reference__ for details on all configuration choices. |
| | | The default mapping uses LDAP `uid` as the resource `_id` for users and LDAP `cn` for groups. Use the configured JSON field names, such as `displayName` for LDAP `cn`. |
| | | |
| | | * `/api/users` reads and changes entries directly under `ou=People,dc=example,dc=com`. |
| | | * `/api/read-only-users` reads and queries the same entries. Writes are rejected. |
| | | * `/api/all-users` includes nested users in collection queries. For a nested user, query the collection with `_queryFilter`. A direct `/api/all-users/<id>` read looks under the collection’s base DN. |
| | | * `/api/groups` maps groups under `ou=Groups,dc=example,dc=com`. Read an individual group at `/api/groups/<cn>`. |
| | | |
| | | To inspect the configured routes and resource fields, send an authenticated GET to `/api?_api`. OpenDJ returns a Swagger 2.0 description. For custom mappings and standalone gateway authentication, see xref:../reference/appendix-rest2ldap.adoc#appendix-rest2ldap[REST to LDAP Configuration]. |
| | | |
| | | |
| | | [#create-rest] |
| | |
| | | } |
| | | ---- |
| | | |
| | | * To create a resource and let the server choose the ID, perform an HTTP POST with `_action=create` as described in xref:#action-rest["Using Actions"]. |
| | | * To create a resource with POST, put the ID in the JSON body and send it to the collection. See xref:#rest-action-create[Using the Create Resource Action]. |
| | | |
| | | |
| | | |
| | |
| | | [#update-rest] |
| | | === Updating Resources |
| | | |
| | | To update a resource, perform an HTTP PUT with the changes to the resource. Use an `If-Match` header to ensure the resource already exists. For read-only fields, either include unmodified versions, or omit them from your updated version. |
| | | Use HTTP PUT to replace writable fields. In the default mapping, omitting an optional writable field can remove its LDAP value. Omitting a required field such as `displayName` causes the request to fail. Use xref:#patch-rest[PATCH] to update selected fields and keep the rest. You can omit read-only fields. |
| | | |
| | | To update a resource regardless of the revision, use an `If-Match: *` header. The following example writes a new entry with an additional display name for Sam Carter: |
| | | Use `If-Match: *` to update the existing resource regardless of its revision. The following example adds a display name to Sam Carter’s resource: |
| | | |
| | | [source, console] |
| | | ---- |
| | |
| | | } |
| | | } |
| | | ---- |
| | | To update a resource only if the resource matches a particular version, use an `If-Match: revision` header as shown in the following example: |
| | | To update a specific revision, read `_rev` and pass it in `If-Match`. A stale revision returns HTTP 412 Precondition Failed. |
| | | |
| | | [source, console] |
| | | ---- |
| | |
| | | [#patch-rest] |
| | | === Patching Resources |
| | | |
| | | OpenDJ lets you patch JSON resources, updating part of the resource rather than replacing it. For example, you could change Babs Jensen's email address by issuing an HTTP PATCH request as in the following example: |
| | | The Rest2ldap endpoint supports `add`, `remove`, `replace`, and `increment` patch operations. Use these operations to update individual mapped fields. For example, you could change Babs Jensen's email address by issuing an HTTP PATCH request as in the following example: |
| | | |
| | | [source, console] |
| | | ---- |
| | |
| | | [#rest-action-create] |
| | | ==== Using the Create Resource Action |
| | | |
| | | OpenDJ implements an action that lets the server set the resource ID on creation. To use this action, perform an HTTP POST with header `Content-Type: application/json`, and the JSON content of the resource. |
| | | |
| | | The `_action=create` in the query string is optional. |
| | | |
| | | The following example creates a new user entry: |
| | | Send the JSON resource to `/api/users` with HTTP POST. In the default mapping, `_id` supplies the LDAP `uid` and `_schema` selects the resource type. The `_action=create` parameter is optional. |
| | | |
| | | [source, console] |
| | | ---- |
| | | $ curl \ |
| | | --request POST \ |
| | | --user kvaughan:bribery \ |
| | | --header "Content-Type: application/json" \ |
| | | $ curl --user kvaughan:bribery \ |
| | | --header 'Content-Type: application/json' \ |
| | | --data '{ |
| | | "_id": "newuser", |
| | | "contactInformation": { |
| | | "telephoneNumber": "+1 408 555 1212", |
| | | "emailAddress": "newuser@example.com" |
| | | }, |
| | | "name": { |
| | | "familyName": "New", |
| | | "givenName": "User" |
| | | }, |
| | | "displayName": "New User", |
| | | "manager": [ |
| | | { |
| | | "_id": "kvaughan", |
| | | "displayName": "Kirsten Vaughan" |
| | | } |
| | | ] |
| | | "_schema": "frapi:opendj:rest2ldap:user:1.0", |
| | | "displayName": ["New User"], |
| | | "name": {"familyName": "User"} |
| | | }' \ |
| | | http://opendj.example.com:8080/api/users |
| | | { |
| | | "_id": "newuser", |
| | | "_rev": "000000000ace733a", |
| | | "_schema": "frapi:opendj:rest2ldap:user:1.0", |
| | | "_meta": { |
| | | "created": "2016-06-24T12:51:25Z" |
| | | }, |
| | | "userName": "newuser@example.com", |
| | | "displayName": ["New User"], |
| | | "name": { |
| | | "givenName": "User", |
| | | "familyName": "New" |
| | | }, |
| | | "contactInformation": { |
| | | "telephoneNumber": "+1 408 555 1212", |
| | | "emailAddress": "newuser@example.com" |
| | | }, |
| | | "manager": { |
| | | "_id": "kvaughan", |
| | | "displayName": "Kirsten Vaughan" |
| | | } |
| | | } |
| | | ---- |
| | | |
| | | A successful response returns HTTP 201 with the created resource. Server-generated IDs require a mapping configured to supply them. |
| | | |
| | | [#rest-action-password-modify] |
| | | ==== Using the Modify Password and Reset Password Actions |
| | | |
| | | OpenDJ implements actions for resetting and changing passwords. |
| | | |
| | | These actions require HTTPS to avoid sending passwords over insecure connections. Before trying the examples that follow, enable HTTPS on the HTTP connection handler as described in xref:../admin-guide/chap-connection-handlers.adoc#setup-rest2ldap["RESTful Client Access Over HTTP"] in the __Administration Guide__. Notice that the following examples use the exported server certificate, `server-cert.pem`, generated in that procedure. If the connection handler uses a certificate signed by a well-known CA, then you can omit the `--cacert` option. |
| | | Enable HTTPS as described in xref:../admin-guide/chap-connection-handlers.adoc#setup-rest2ldap[RESTful Client Access Over HTTP]. The examples use the exported evaluation server certificate `server-cert.pem`. Omit `--cacert` if curl already trusts the issuing CA. |
| | | |
| | | [#rest-action-modify-password] |
| | | ===== Changing Passwords |
| | | |
| | | The `modifyPassword` action lets a user modify their password given the old password and a new password. |
| | | |
| | | To use this action, perform an HTTP POST over HTTPS with header `Content-Type: application/json`, `_action=modifyPassword` in the query string, and the old and new passwords in JSON format as the POST data. |
| | | -- |
| | | The JSON must include the following fields: |
| | | |
| | | `oldPassword`:: |
| | | The value of this field is the current password as a UTF-8 string. |
| | | |
| | | `newPassword`:: |
| | | The value of this field is the new password as a UTF-8 string. |
| | | |
| | | -- |
| | | The following example demonstrates a user changing their own password. On success, the HTTP status code is 200 OK, and the response body is an empty JSON resource: |
| | | To change your password, POST `oldPassword` and `newPassword` to the `modifyPassword` action. The response is HTTP 200 with an empty JSON object. |
| | | |
| | | [source, console] |
| | | ---- |
| | |
| | | --user bjensen:hifalutin \ |
| | | --header "Content-Type: application/json" \ |
| | | --data '{"oldPassword": "hifalutin", "newPassword": "password"}' \ |
| | | https://opendj.example.com:8443/users/bjensen?_action=modifyPassword |
| | | https://opendj.example.com:8443/api/users/bjensen?_action=modifyPassword |
| | | {} |
| | | ---- |
| | | |
| | |
| | | [#rest-action-reset-password] |
| | | ===== Resetting Passwords |
| | | |
| | | The `resetPassword` action lets a user or password administrator reset a password to a generated password value. |
| | | The `resetPassword` action sets a generated password. An authenticated user can request it for their own entry when their password policy allows changing the password without supplying the current password in the request body. Resetting another user's password requires the `password-reset` privilege and permission to write that user's `userPassword` attribute. |
| | | |
| | | To use this action, perform an HTTP POST over HTTPS with header `Content-Type: application/json`, `_action=resetPassword` in the query string, and an empty JSON document (`{}`) as the POST data. |
| | | The following example demonstrates an administrator changing a user's password. Before trying this example, make sure the password administrator user has been given the `password-reset` privilege as shown in xref:../admin-guide/chap-privileges-acis.adoc#change-individual-privileges["To Add Privileges on an Individual Entry"] in the __Administration Guide__. Otherwise, the password administrator has insufficient access. On success, the HTTP status code is 200 OK, and the response body is a JSON resource with a `generatedPassword` containing the new password: |
| | | The following example uses the local `password-admin` account created in xref:../how-to/delegate-password-reset.adoc[Delegate Password Reset Permissions]. On success, the server returns HTTP 200 and the new password in `generatedPassword`. |
| | | |
| | | [source, console] |
| | | ---- |
| | | $ curl \ |
| | | --request POST \ |
| | | --cacert server-cert.pem \ |
| | | --user kvaughan:bribery \ |
| | | --user 'password-admin:AdminPassword123!' \ |
| | | --header "Content-Type: application/json" \ |
| | | --data '{}' \ |
| | | https://opendj.example.com:8443/users/bjensen?_action=passwordModify |
| | | 'https://localhost:8443/api/users/bjensen?_action=resetPassword' |
| | | {"generatedPassword":"qno66vyz"} |
| | | ---- |
| | | The password administrator communicates the new, generated password to the user. |
| | |
| | | |
| | | To query resource collections, perform an HTTP GET with a `_queryFilter=expression` parameter in the query string. For details about the query filter __expression__, see xref:#about-crest-query["Query"]. |
| | | |
| | | The `_queryId`, `_sortKeys`, and `_totalPagedResultsPolicy` parameters described in xref:#about-crest-query["Query"] are not used in OpenDJ software at present. |
| | | The collection mapping sets the LDAP search scope. See xref:#rest-default-mapping[Default REST Resources] for the scopes of the built-in collections. The endpoint supports paging with `_pageSize` and `_pagedResultsCookie` or `_pagedResultsOffset`. The Common REST parameters `_queryExpression`, `_queryId`, `_sortKeys`, and `_totalPagedResultsPolicy` are unsupported by this endpoint. |
| | | |
| | | The following table shows some LDAP search filters with corresponding examples of query filter expressions. |
| | | |
| | |
| | | -- |
| | | For query operations, the filter __expression__ is constructed from the following building blocks. Make sure you URL-encode the filter expressions, which are shown here without URL-encoding to make them easier to read. |
| | | |
| | | In filter expressions, the simplest __json-pointer__ is a field of the JSON resource, such as `userName` or `id`. A __json-pointer__ can also point to nested elements as described in the link:http://tools.ietf.org/html/draft-ietf-appsawg-json-pointer[JSON Pointer, window=\_blank] Internet-Draft: |
| | | In filter expressions, the simplest __json-pointer__ is a field of the JSON resource, such as `userName` or `id`. A __json-pointer__ can also point to nested elements as described in the link:https://www.rfc-editor.org/rfc/rfc6901[JSON Pointer (RFC 6901), window=\_blank] specification: |
| | | |
| | | Comparison expressions:: |
| | | [open] |
| | |
| | | |
| | | * `_pageSize=integer` |
| | | |
| | | The following example demonstrates how paged results are used: |
| | | The following example demonstrates how paged results are used. Use the cookie from your previous response and URL-encode it for the next request. A numeric offset counts pages starting at zero. |
| | | |
| | | [source, console] |
| | | ---- |
| | |
| | | "remainingPagedResults": -1 |
| | | } |
| | | |
| | | # Request the tenth page of five results. |
| | | # Request the eleventh page of five results (offsets start at zero). |
| | | $ curl \ |
| | | --user bjensen:hifalutin \ |
| | | "http://opendj.example.com:8080/api/users?_queryFilter=true&_fields=userName\ |
| | |
| | | information: "Portions copyright [year] [name of copyright owner]". |
| | | |
| | | Copyright 2017 ForgeRock AS. |
| | | Portions Copyright 2024 3A Systems LLC. |
| | | Portions Copyright 2024-2026 3A Systems, LLC. |
| | | //// |
| | | |
| | | :figure-caption!: |
| | |
| | | + |
| | | The `posixAccount` object class is auxiliary, for example. |
| | | |
| | | * __Abstract__ object classes define base characteristics for other object classes to inherit, and cannot themselves inherit from other object classes. |
| | | * __Abstract__ object classes define base characteristics for other object classes to inherit. An abstract class can inherit from other abstract classes. |
| | | + |
| | | The `top` object class from which others inherit is abstract, for example. |
| | | |
| | |
| | | [#example-reading-schema-definition] |
| | | .Reading an Object Class Schema Definition |
| | | ==== |
| | | The schema entry in OpenDJ directory server is large because it contains all of the schema definitions. Filter the results when reading a specific schema definition. As schema definitions themselves are long strings, pass the `--dontWrap` option to the `ldapsearch` command when reading one. |
| | | Use `ldapsearch --wrapColumn 0` to print each schema definition on one line and filter the result with `grep`. |
| | | |
| | | The example below reads the definition for the `person` object class: |
| | | |
| | |
| | | --port 1389 \ |
| | | --baseDN "cn=schema" \ |
| | | --searchScope base \ |
| | | --dontWrap \ |
| | | "(&)" \ |
| | | --wrapColumn 0 \ |
| | | '(objectClass=*)' \ |
| | | objectClasses \ |
| | | | grep \'person\' |
| | | | grep -F "'person'" |
| | | objectClasses: ( 2.5.6.6 NAME 'person' SUP top STRUCTURAL MUST ( sn $ cn ) |
| | | MAY ( userPassword $ telephoneNumber $ seeAlso $ description ) |
| | | X-ORIGIN 'RFC 4519' ) |
| | | ---- |
| | | Notice the use of the object class name in `grep \'person\'` to filter search results. The actual result would not be wrapped. |
| | | ==== |
| | | The object class defines which attributes an entry of that object class __must__ have and which attributes the entry __may__ optionally have. A `person` entry must have a `cn` and an `sn` attribute. A `person` entry may optionally have `userPassword`, `telephoneNumber`, `seeAlso`, and `description` attributes. |
| | | |
| | |
| | | --port 1389 \ |
| | | --baseDN "cn=schema" \ |
| | | --searchScope base \ |
| | | --dontWrap \ |
| | | "(&)" \ |
| | | --wrapColumn 0 \ |
| | | '(objectClass=*)' \ |
| | | attributeTypes \ |
| | | | grep \'cn\' |
| | | | grep -F "'cn'" |
| | | attributeTypes: ( 2.5.4.3 NAME ( 'cn' 'commonName' ) SUP name X-ORIGIN 'RFC 4519' ) |
| | | ---- |
| | | The `cn` attribute inherits its definition from the `name` attribute. That attribute definition indicates attribute syntax and matching rules as shown in the following example: |
| | |
| | | --port 1389 \ |
| | | --baseDN "cn=schema" \ |
| | | --searchScope base \ |
| | | --dontWrap \ |
| | | "(&)" \ |
| | | --wrapColumn 0 \ |
| | | '(objectClass=*)' \ |
| | | attributeTypes \ |
| | | | grep \'name\' |
| | | | grep -F "'name'" |
| | | attributeTypes: ( 2.5.4.41 NAME 'name' EQUALITY caseIgnoreMatch |
| | | SUBSTR caseIgnoreSubstringsMatch |
| | | SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{32768} X-ORIGIN 'RFC 4519' ) |
| | |
| | | --port 1389 \ |
| | | --baseDN "cn=schema" \ |
| | | --searchScope base \ |
| | | --dontWrap \ |
| | | "(&)" \ |
| | | --wrapColumn 0 \ |
| | | '(objectClass=*)' \ |
| | | ldapSyntaxes \ |
| | | | grep 1.3.6.1.4.1.1466.115.121.1.15 |
| | | | grep -F ' 1.3.6.1.4.1.1466.115.121.1.15 ' |
| | | ldapSyntaxes: ( 1.3.6.1.4.1.1466.115.121.1.15 DESC 'Directory String' ) |
| | | ---- |
| | | Taken together with the information for the `name` attribute, the common name attribute value is a Directory String of at most 32,768 characters. For details about syntaxes, read link:http://tools.ietf.org/html/rfc4517[RFC 4517, Lightweight Directory Access Protocol (LDAP): Syntaxes and Matching Rules, window=\_blank]. That document describes a Directory String as one or more UTF-8 characters. |
| | | The `cn` attribute inherits the link:https://www.rfc-editor.org/rfc/rfc4517.html#section-3.3.6[Directory String syntax] from `name`. The `32768` hint recommends support for strings up to that length. See link:https://www.rfc-editor.org/rfc/rfc4512.html#section-4.1.2[RFC 4512]. |
| | | ==== |
| | | |
| | | |
| | |
| | | This file contains a core set of attribute type and object class definitions from the following Internet-Drafts, RFCs, and standards: |
| | | + |
| | | [none] |
| | | * link:https://tools.ietf.org/html/draft-ietf-boreham-numsubordinates[draft-ietf-boreham-numsubordinates, window=\_blank] |
| | | * link:https://datatracker.ietf.org/doc/html/draft-boreham-numsubordinates-01[numSubordinates draft, window=\_blank] |
| | | * link:https://tools.ietf.org/html/draft-findlay-ldap-groupofentries[draft-findlay-ldap-groupofentries, window=\_blank] |
| | | * link:https://tools.ietf.org/html/draft-furuseth-ldap-untypedobject[draft-furuseth-ldap-untypedobject, window=\_blank] |
| | | * link:https://tools.ietf.org/html/draft-good-ldap-changelog[draft-good-ldap-changelog, window=\_blank] |
| | |
| | | information: "Portions copyright [year] [name of copyright owner]". |
| | | |
| | | Copyright 2017 ForgeRock AS. |
| | | Portions Copyright 2024-2026 3A Systems LLC. |
| | | Portions Copyright 2024-2026 3A Systems, LLC. |
| | | //// |
| | | |
| | | :figure-caption!: |
| | | :example-caption!: |
| | | :table-caption!: |
| | | :opendj-version: x.y.z |
| | | |
| | | |
| | | [#chap-writing-plugins] |
| | |
| | | [#try-example-plugin] |
| | | === Trying the Example Server Plugin |
| | | |
| | | The example plugin is bundled with OpenDJ directory server as `example-plugin.zip`, which holds a Maven-based project. The example plugin is a startup plugin that displays a "Hello World" message when the directory server starts. For general information about OpenDJ directory server plugins, read xref:#about-server-plugins["About OpenDJ Directory Server Plugins"]. For more specific information, read xref:#about-example-plugin["About the Example Plugin Project Files"]. |
| | | |
| | | [NOTE] |
| | | ==== |
| | | This version of the example plugin is new in OpenDJ directory server 3.5. |
| | | ==== |
| | | The server ZIP distribution includes `example-plugin.zip`, a Maven project for a plugin that writes `HELLO WORLD` at startup. Use an evaluation installation, Apache Maven 3, and a JDK supported by the server release. |
| | | |
| | | ==== |
| | | Follow these steps to try the example plugin: |
| | | |
| | | . Install OpenDJ directory server as described in xref:../install-guide/chap-install.adoc#chap-install["Installing OpenDJ Servers"] in the __Installation Guide__. |
| | | |
| | | . Install Apache Maven 3.0.5 or later. |
| | | . From the OpenDJ installation directory, extract the project. |
| | | + |
| | | When you finish, make sure `mvn` is on your PATH: |
| | | + |
| | | |
| | | [source, console] |
| | | ---- |
| | | $ mvn -version |
| | | Apache Maven version |
| | | Maven home: /path/to/maven |
| | | Java version: ... |
| | | $ unzip -q example-plugin.zip |
| | | $ cd opendj-server-example-plugin |
| | | ---- |
| | | |
| | | . Unpack the example plugin project sources: |
| | | . In the extracted `pom.xml`, make sure `<build>` includes both resources below. Add the `<resources>` block if it is missing. The generated resources let `dsconfig` find the `example` plugin type. |
| | | + |
| | | [source,xml] |
| | | ---- |
| | | <resources> |
| | | <resource> |
| | | <directory>src/main/resources</directory> |
| | | </resource> |
| | | <resource> |
| | | <directory>${project.build.directory}/generated-resources</directory> |
| | | </resource> |
| | | </resources> |
| | | ---- |
| | | |
| | | . Build and unpack the plugin, then copy its `config/` and `lib/` files into the stopped server. The example assumes that the administration connector listens on port 4444. Use your Directory Manager password in place of `password`. |
| | | + |
| | | [source, console] |
| | | ---- |
| | | $ unzip /path/to/opendj/example-plugin.zip |
| | | Archive: /path/to/opendj/example-plugin.zip |
| | | creating: opendj-server-example-plugin/ |
| | | ... |
| | | ---- |
| | | |
| | | . Build the example plugin: |
| | | + |
| | | |
| | | [source, console] |
| | | ---- |
| | | $ cd opendj-server-example-plugin/ |
| | | $ mvn install |
| | | ... |
| | | [INFO] ------------------------------------------------------------------------ |
| | | [INFO] BUILD SUCCESS |
| | | [INFO] ------------------------------------------------------------------------ |
| | | ... |
| | | ---- |
| | | |
| | | . Install the example plugin in OpenDJ directory server: |
| | | + |
| | | |
| | | [source, console, subs="+attributes"] |
| | | ---- |
| | | $ cd /path/to/opendj |
| | | |
| | | # Stop the server before installing the example plugin: |
| | | $ mvn clean package |
| | | $ unzip -q target/org.openidentityplatform.opendj.opendj-server-example-plugin.zip -d target |
| | | $ cd .. |
| | | $ bin/stop-ds |
| | | |
| | | # Unpack the plugin files into the proper locations of the server layout, |
| | | # skipping the base directory. |
| | | # The following example works with bsdtar, |
| | | # which might require installing a bsdtar package. |
| | | $ bsdtar -xvf \ |
| | | /path/to/opendj-server-example-plugin/target/opendj-server-example-plugin-{opendj-version}.zip \ |
| | | -s'|[^/]*/||' |
| | | x README.example.plugin |
| | | x config/ |
| | | x config/schema/ |
| | | x config/example-plugin.ldif |
| | | x config/schema/99-example-plugin.ldif |
| | | x lib/ |
| | | x lib/extensions/ |
| | | x lib/extensions/opendj-server-example-plugin-{opendj-version}.jar |
| | | x lib/extensions/... |
| | | |
| | | # Start the server and create the plugin configuration: |
| | | $ plugin_files=opendj-server-example-plugin/target/org.openidentityplatform.opendj.opendj-server-example-plugin |
| | | $ cp -R "$plugin_files/config" "$plugin_files/lib" . |
| | | $ bin/start-ds |
| | | $ bin/dsconfig \ |
| | | create-plugin \ |
| | | --hostname opendj.example.com \ |
| | | --port 4444 \ |
| | | --bindDN "cn=Directory Manager" \ |
| | | --bindPassword password \ |
| | | --plugin-name "Example Plugin" \ |
| | | --type example \ |
| | | --set enabled:true \ |
| | | --set plugin-type:startup \ |
| | | --trustAll \ |
| | | --no-prompt |
| | | ... |
| | | INFO: Loaded extension from file |
| | | '/path/to/opendj/lib/extensions/opendj-server-example-plugin-{opendj-version}.jar' |
| | | (build <unknown>, revision <unknown>) |
| | | $ bin/dsconfig create-plugin \ |
| | | --hostname localhost --port 4444 \ |
| | | --bindDN "cn=Directory Manager" --bindPassword password \ |
| | | --plugin-name "Example Plugin" --type example \ |
| | | --set enabled:true --set plugin-type:startup --trustAll --no-prompt |
| | | ---- |
| | | |
| | | . Restart the server and check the message in the error log. |
| | | + |
| | | Notice the locations where the example plugin files are unpacked. The locations must follow the server conventions in order for OpenDJ directory server to recognize the plugin. |
| | | + |
| | | For the example plugin, you see that: |
| | | |
| | | * Schema definitions are unpacked into `config/schema/`. |
| | | |
| | | * Plugin .jar files and the .jar files they depend on are unpacked into `lib/extensions/`. |
| | | |
| | | + |
| | | Also notice that after the plugin configuration is created OpenDJ directory server has loaded the plugin as an extension. |
| | | |
| | | . Restart OpenDJ directory server to see the startup message from the plugin: |
| | | + |
| | | |
| | | [source, console] |
| | | ---- |
| | | $ bin/stop-ds --restart |
| | | ... |
| | | ... msg=Example plugin message 'HELLO WORLD'. |
| | | ... |
| | | $ grep "Example plugin message 'HELLO WORLD'" logs/errors |
| | | ---- |
| | | |
| | | . Now that you have seen the example plugin display its message, see xref:#about-example-plugin["About the Example Plugin Project Files"] to understand the key parts of the example plugin project. |
| | | |
| | | ==== |
| | | |
| | | |
| | | [#about-example-plugin] |
| | | === About the Example Plugin Project Files |
| | | |
| | | The example plugin project builds a server plugin that displays a "Hello World" message when OpenDJ directory server starts, as shown in xref:#try-example-plugin["Trying the Example Server Plugin"]. This section describes the example plugin project. For general information about OpenDJ directory server plugins, read xref:#about-server-plugins["About OpenDJ Directory Server Plugins"] instead. |
| | | |
| | | [NOTE] |
| | | ==== |
| | | This version of the example plugin project is new in OpenDJ directory server 3.5. |
| | | ==== |
| | | The project combines the plugin’s Java code, configuration definition, LDAP schema, and message bundles. |
| | | |
| | | [#example-plugin-maven] |
| | | ==== Maven Project |
| | |
| | | As you can see in the `pom.xml` file for the project, the plugin depends on the OpenDJ directory server module. |
| | | The plugin project uses these Open Identity Platform Maven plugins: |
| | | |
| | | * The `i18n-maven-plugin` generates message source files from properties files in the resource bundle. |
| | | * The `org.openidentityplatform.commons.i18n-framework:maven-plugin` plugin generates message source files from properties files in the resource bundle. |
| | | + |
| | | This plugin must run in order to resolve static imports from `com.example.opendj.ExamplePluginMessages`. |
| | | |
| | |
| | | + |
| | | If a longer description is required, add a `<description>`, which can include XHTML markup. The `<description>` is used in addition to the synopsis, so there is no need to duplicate the synopsis in the description. |
| | | |
| | | * The `<property>` element defines a property specific to this example plugin, including its purpose, its the default value, its type, and how the property maps to an LDAP attribute in the configuration entry. |
| | | * The `<property>` element defines a property specific to this example plugin, including its purpose, its default value, its type, and how the property maps to an LDAP attribute in the configuration entry. |
| | | + |
| | | The `name` attribute is used to identify the property in the configuration. |
| | | |
| | |
| | | |
| | | This means that a server plugin built with one version of OpenDJ directory server will not necessarily work or even compile with a different version of the server. |
| | | ==== |
| | | `ExamplePlugin` statically imports everything from the generated message implementation sources. Resolution of `ExamplePluginMessages.*` fails until the implementation is generated by the `i18n-maven-plugin`. |
| | | `ExamplePlugin` statically imports everything from the generated message implementation sources. Resolution of `ExamplePluginMessages.*` fails until the implementation is generated by the i18n Maven plugin. |
| | | |
| | | `ExamplePlugin` extends link:https://doc.openidentityplatform.org/opendj/apidocs/org/opends/server/api/plugin/DirectoryServerPlugin.html[DirectoryServerPlugin, window=\_blank] with its own type of configuration, `ExamplePluginCfg`. The implementation for `ExamplePluginCfg` is generated from the configuration declared in XML. Therefore, resolution of `ExamplePluginCfg` fails until the sources are generated by the `opendj-maven-plugin`. |
| | | |
| | |
| | | information: "Portions copyright [year] [name of copyright owner]". |
| | | |
| | | Copyright 2017 ForgeRock AS. |
| | | Portions Copyright 2024 3A Systems LLC. |
| | | Portions Copyright 2024-2026 3A Systems, LLC. |
| | | //// |
| | | |
| | | = Directory Server Developer's Guide |
| | |
| | | :toc: |
| | | :authors: Mark Craig |
| | | :copyright: Copyright 2015-2017 ForgeRock AS. |
| | | :copyright: Portions Copyright 2024 3A Systems LLC. |
| | | :copyright: Portions Copyright 2024-2026 3A Systems, LLC. |
| | | |
| | | :imagesdir: ../ |
| | | :figure-caption!: |
| | | :example-caption!: |
| | | :table-caption!: |
| | | [abstract] |
| | | Hands-on guide to using OpenDJ directory server with an emphasis on command-line tools. The OpenDJ project offers open source LDAP directory services in Java. |
| | | Hands-on guide to accessing OpenDJ directory server through LDAP and REST, developing Java LDAP clients, and writing server plugins. |
| | | |
| | | include::./preface.adoc[] |
| | | include::./chap-rest-operations.adoc[] |
| | |
| | | include::./chap-groups.adoc[] |
| | | include::./chap-virtual-attrs-collective-attrs.adoc[] |
| | | include::./chap-referrals.adoc[] |
| | | include::./chap-ldap-sdk.adoc[] |
| | | include::./chap-writing-plugins.adoc[] |
| | |
| | | information: "Portions copyright [year] [name of copyright owner]". |
| | | |
| | | Copyright 2017 ForgeRock AS. |
| | | Portions Copyright 2024 3A Systems LLC. |
| | | Portions Copyright 2024-2026 3A Systems, LLC. |
| | | //// |
| | | |
| | | :figure-caption!: |
| | |
| | | [#preface] |
| | | == Preface |
| | | |
| | | This guide shows you how to develop scripts that use OpenDJ tools. |
| | | |
| | | If you are building a Java-based LDAP client application, refer to the __OpenDJ LDAP SDK Developer's Guide__ instead. |
| | | In reading and following the instructions in this guide, you will learn how to: |
| | | |
| | | * Access OpenDJ directory server by using REST APIs over HTTP |
| | | |
| | | * Access OpenDJ directory server using the LDAP tools delivered with the server |
| | | |
| | | * Use LDAP schema |
| | | |
| | | * Work with standard LDAP groups and OpenDJ-specific groups |
| | | |
| | | * Work with LDAP collective attributes and OpenDJ virtual attributes |
| | | |
| | | * Work with LDAP referrals in search results |
| | | |
| | | This guide covers LDAP and REST clients, directory data, and server plugins. For a Java client example, see xref:chap-ldap-sdk.adoc#chap-ldap-sdk[Developing Java LDAP Clients]. |
| | | |
| | | [#using-this-guide] |
| | | === Using This Guide |
| | | |
| | | This guide is intended for directory administrators who write scripts that use OpenDJ directory services. |
| | | This guide is written with the expectation that you already have basic familiarity with the following topics: |
| | | |
| | | * Installing OpenDJ directory server, if the server is not yet installed |
| | | + |
| | | If you are not yet familiar with OpenDJ directory server installation, read the xref:../install-guide/index.adoc[Installation Guide] first. |
| | | |
| | | * Using command-line tools |
| | | |
| | | * LDAP and directory services |
| | | |
| | | * Basic OpenDJ server configuration |
| | | + |
| | | Some examples in this guide require OpenDJ configuration steps. |
| | | |
| | | * HTTP, JavaScript Object Notation (JSON), and web applications |
| | | The examples assume familiarity with LDAP and command-line tools. The REST examples also use HTTP and JSON. If you need a server, see the xref:../install-guide/index.adoc[Installation Guide]. |
| | | |
| | | include::../partials/sec-formatting-conventions.adoc[] |
| | | |
| | |
| | | docker build -t openidentityplatform/opendj . |
| | | ``` |
| | | |
| | | Run image |
| | | Run OpenDJ with a named volume at `/opt/opendj/data` so the instance can be reused when you |
| | | replace the container. |
| | | |
| | | ```bash |
| | | docker run -d -p 1389:1389 -p 1636:1636 -p 4444:4444 --name opendj openidentityplatform/opendj |
| | | docker run -d -p 1389:1389 -p 1636:1636 -p 4444:4444 --name opendj \ |
| | | -v opendj-data:/opt/opendj/data openidentityplatform/opendj |
| | | ``` |
| | | |
| | | ## Health check |
| | |
| | | `ADD_BASE_ENTRY` and `SAMPLE_DATA` asked to be imported into it, and, where replication is |
| | | asked for, the join of the replication topology (see [Replication](#replication)). Waiting |
| | | for that status is therefore enough before the first search of what the bootstrap was told |
| | | to create: |
| | | to create. To try the following example, start with an empty `opendj-data` volume. |
| | | |
| | | ```bash |
| | | docker run -d --name opendj -e ADD_BASE_ENTRY=--addBaseEntry openidentityplatform/opendj |
| | | docker run -d --name opendj -v opendj-data:/opt/opendj/data \ |
| | | -e ADD_BASE_ENTRY=--addBaseEntry openidentityplatform/opendj |
| | | timeout 5m bash -c 'until [ "$(docker inspect -f "{{.State.Health.Status}}" opendj)" = healthy ]; do sleep 5; done' |
| | | ``` |
| | | |
| | |
| | | password - the probe reads it from there, so it never shows on a command line: |
| | | |
| | | ```bash |
| | | docker run -d --name opendj -v /path/to/secrets:/var/secrets/healthcheck:ro \ |
| | | docker run -d --name opendj -v opendj-data:/opt/opendj/data \ |
| | | -v /path/to/secrets:/var/secrets/healthcheck:ro \ |
| | | -e HEALTHCHECK_BIND_DN="uid=monitor,ou=people,dc=example,dc=com" \ |
| | | -e HEALTHCHECK_BIND_PASSWORD_FILE=/var/secrets/healthcheck/password \ |
| | | openidentityplatform/opendj |
| | |
| | | that only waits for the port can have its first requests fail in between. |
| | | |
| | | A bootstrap that imports `SAMPLE_DATA` can take minutes on a small container, which is what the |
| | | start period allows for. A bootstrap that fails - or an upgrade that fails when starting over |
| | | an instance that is already there - never reports healthy: what failed is in `docker logs`, and |
| | | where the server is up at all the container is left running to be looked at, turning |
| | | `unhealthy` once the start period is over. Nor does any later start over the same volume: a |
| | | volume carries `.bootstrap-pending` in its data directory from before its bootstrap until the |
| | | bootstrap succeeded, and a container started over a volume that still carries it upgrades the |
| | | instance when it is of another version, starts the server, logs that the bootstrap did not |
| | | complete, and stays `unhealthy`. This holds for a volume of the background join as well: it |
| | | runs no join, since an initialize from the topology would bring the data of the topology but |
| | | nothing else the bootstrap was to configure. Remove the volume and start over, or finish the |
| | | setup by hand and remove the file; a volume of the background join then joins on the restart |
| | | and takes the data of the topology, as on its first start: |
| | | start period allows for. If bootstrap fails, check `docker logs`. The volume retains |
| | | `.bootstrap-pending` until bootstrap succeeds. If `/opt/opendj/data/config` is absent, the |
| | | next start retries bootstrap after you correct the cause. |
| | | |
| | | If the directory and marker both exist, the next start attempts to open the server for |
| | | recovery. The image first upgrades the instance if needed. If the server starts, the |
| | | container stays `unhealthy` and replication join stays paused until bootstrap is complete. |
| | | |
| | | If the container remains running, finish setup by hand, then remove the marker and restart. |
| | | |
| | | ```bash |
| | | docker exec opendj rm /opt/opendj/data/.bootstrap-pending |
| | | docker restart opendj |
| | | ``` |
| | | |
| | | If the container exits, for example because `config.ldif` is missing, keep it stopped and |
| | | open a temporary shell from the same image. Use `--volumes-from opendj` if the original |
| | | container has a mount at `/opt/opendj/data`. If its data is in the writable layer, follow the |
| | | [upgrade guide to copy the instance to a new volume](../../opendj-doc-generated-ref/src/main/asciidoc/install-guide/chap-upgrade.adoc#upgrade-docker). |
| | | For the copied instance, set the mount option in the command below to |
| | | `-v opendj-data:/opt/opendj/data`, using the name of the new volume. |
| | | |
| | | ```bash |
| | | opendj_image=$(docker inspect --format '{{.Image}}' opendj) |
| | | docker run --rm -it --volumes-from opendj --workdir /opt/opendj \ |
| | | --entrypoint /bin/sh "$opendj_image" |
| | | ``` |
| | | |
| | | In the temporary shell, run `printf '%s\n' /opt/opendj/data > instance.loc` and finish setup. |
| | | If OpenDJ started in the temporary container, run `./bin/stop-ds --noPropertiesFile` there |
| | | and wait for it to succeed. Then remove `/opt/opendj/data/.bootstrap-pending` and exit the |
| | | shell. If you shared the original data mount, run `docker start opendj` from the host. If |
| | | you copied the instance, rename the original container to free its name. Create a replacement |
| | | container from the same image with the original settings and the new data volume. |
| | | |
| | | A volume configured for background join then joins and takes the data of the topology as |
| | | on its first start. You can also discard the incomplete volume and start over. |
| | | |
| | | Started over an instance of an older version, the container runs `upgrade --no-prompt --force` |
| | | before the server: the upgrade tasks that take long, such as verifying or rebuilding indexes, |
| | | are performed then, since nobody is there to run them afterwards. On a large instance they can |
| | | take longer than the start period, so the container may report `unhealthy` until the upgrade |
| | | is over; `docker logs` shows which task is running. |
| | | |
| | | An upgrade that fails never reports healthy, and neither does any later start over the same |
| | | volume, even though the upgrade records the new version before its post-upgrade tasks - the |
| | | index rebuilds and verifications - and a second run would find nothing left to do: the volume |
| | | carries `.upgrade-pending` in its data directory from before the upgrade until the upgrade, |
| | | post-upgrade tasks included, succeeded. An upgrade that failed before it recorded the new |
| | | version is run again on the next start. Once it has recorded it, a container started over the |
| | | marked volume starts the server, logs that the upgrade did not complete, and stays `unhealthy`: |
| | | `/opt/opendj/data/logs/upgrade.log` names the task that failed. Rebuild the indexes it names |
| | | and remove the file, or restore the backup taken before the upgrade: |
| | | The volume carries `.upgrade-pending` until the upgrade and its post-upgrade tasks complete. |
| | | The next start retries an upgrade that failed before recording the new version. If it failed |
| | | or was interrupted after recording the version, the next start attempts to open the server |
| | | for recovery and the container stays `unhealthy`. |
| | | |
| | | ```bash |
| | | docker exec opendj /opt/opendj/bin/rebuild-index --hostname localhost --port 4444 \ |
| | | --bindDN "cn=Directory Manager" --bindPassword password --trustAll \ |
| | | --baseDN dc=example,dc=com --index <index> |
| | | docker exec opendj rm /opt/opendj/data/.upgrade-pending |
| | | docker restart opendj |
| | | ``` |
| | | Check `/opt/opendj/data/logs/upgrade.log` for outstanding work. An interruption can leave base |
| | | DNs absent from the log. For the DN equality index check, list enabled pluggable backends, |
| | | base DNs, and equality-indexed attributes from `/opt/opendj/data/config/config.ldif`. Resolve |
| | | their effective equality rules using the instance schema in `/opt/opendj/data/config/schema/`, |
| | | including rules inherited through `SUP`. Check indexes that use `distinguishedNameMatch` or |
| | | `uniqueMemberMatch`. |
| | | |
| | | With the server stopped, require `Valid=true` in `backendstat show-index-status` and a |
| | | successful `verify-index --countErrors` for each affected index and base DN. Rebuild invalid |
| | | or inconsistent indexes and repeat both checks. Remove the marker and start the container |
| | | only after all outstanding tasks are complete. Restore the pre-upgrade backup if you cannot |
| | | identify all the affected indexes or complete the outstanding work. [Docker upgrade and recovery procedure](../../opendj-doc-generated-ref/src/main/asciidoc/install-guide/chap-upgrade.adoc#upgrade-docker) |
| | | |
| | | The server runs as PID 1 of the container, and a JVM does not reap the processes left |
| | | behind to it - those of a health check that ran past its timeout, say. Run the container |
| | |
| | | fi |
| | | sh ./upgrade -n --force || return 1 |
| | | if [ "$from" = "$to" ] && [ -f "$UPGRADE_PENDING" ]; then |
| | | echo "The upgrade of this volume from $(cat "$UPGRADE_PENDING") did not complete on an earlier start: its post-upgrade tasks failed or were cut off, which /opt/opendj/data/logs/upgrade.log tells. Rebuild the indexes it names with rebuild-index and remove $UPGRADE_PENDING, or restore the backup taken before the upgrade" |
| | | echo "The upgrade of this volume from $(cat "$UPGRADE_PENDING") did not complete on an earlier start." \ |
| | | "Check /opt/opendj/data/logs/upgrade.log and the backend configuration." \ |
| | | "With the server stopped, verify the indexes for every affected base DN and rebuild as needed." \ |
| | | "Remove $UPGRADE_PENDING only after all outstanding tasks are complete, or restore the pre-upgrade backup." |
| | | return 1 |
| | | fi |
| | | rm -f "$UPGRADE_PENDING" |