mirror of https://github.com/OpenIdentityPlatform/OpenDJ.git
opendj-doc-generated-ref/README.md
New file @@ -0,0 +1,73 @@ <!-- 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. --> # Maintaining the AsciiDoc guides Edit `src/main/asciidoc/how-to`, not the generated site modules or the former wiki tutorials. Each task has one maintained procedure. Link to the Installation, Administration or Developer's Guide when that procedure already exists there. The `how-to/index.adoc` book includes its chapters using `include::./name.adoc[]`. The Maven `documents` list selects guides for preprocessing, Antora conversion and PDF generation. Register navigation and the generated PDF filename separately in `opendj/antora.yml` in the documentation-site repository. Do not hand-edit the generated `modules` tree there: deployment replaces it. Use `xref:../guide/chapter.adoc#anchor[Title]` for cross-guide links and `xref:./chapter.adoc[Title]` for another How-To. Each chapter must define any attributes it uses, because the site renders chapters separately. Use `subs="+attributes"` on a code block only when it intentionally substitutes an AsciiDoc attribute. Keep language expressions such as Java placeholders literal. ## Getting Started and Release Notes `getting-started` contains the introductory concepts and a runnable first-directory exercise. Keep its download pinned to a published release, even when this repository builds a SNAPSHOT. Re-run the exercise when changing its version or commands. `release-notes` contains version-specific summaries and installation/upgrade considerations. Verify release facts against the tagged source and the GitHub release record. Link to the complete changelog and security advisories instead of copying their full contents. Add a chapter and update the book includes when documenting a new release; do not silently relabel an older release's notes. Both books follow the same Maven, Antora and PDF pipeline as How-To. Their site PDF filenames are `Getting_Started.pdf` and `Release_Notes.pdf`. Register their navigation before the Installation Guide. The historical DocBook sources are maintained separately and are not inputs to these new guides. ## Wiki migration inventory Source: [OpenDJ wiki](https://github.com/OpenIdentityPlatform/OpenDJ/wiki), revision `d0a4db8af19b58815710a5eca7ebc6c0d188c9e0`. | Former wiki page | Maintained destination | | --- | --- | | How To Run OpenDJ in Kubernetes | [how-to/kubernetes](https://doc.openidentityplatform.org/opendj/how-to/kubernetes) | | How to Setup OpenDJ with BCFKS FIPS Key Store Type support | [how-to/bcfks](https://doc.openidentityplatform.org/opendj/how-to/bcfks) | | Using a Relational Database as an LDAP Backend | [how-to/jdbc-backend](https://doc.openidentityplatform.org/opendj/how-to/jdbc-backend) | | How to Run OpenDJ based Embedded LDAP in Spring Boot Application | [how-to/embedded-ldap](https://doc.openidentityplatform.org/opendj/how-to/embedded-ldap) | | REST Access to OpenDJ Directory Server | [how-to/rest-access](https://doc.openidentityplatform.org/opendj/how-to/rest-access) | | How to delegate password reset permissions | [how-to/delegate-password-reset](https://doc.openidentityplatform.org/opendj/how-to/delegate-password-reset) | | How to generate test LDIF data and import to LDAP server OpenDJ | [how-to/generate-test-data](https://doc.openidentityplatform.org/opendj/how-to/generate-test-data) | | TIP: How to Persist OpenDJ Docker Container Data Between Restarts | [install-guide/chap-install#install-docker](https://doc.openidentityplatform.org/opendj/install-guide/chap-install#install-docker) | | How To Guides | [how-to/](https://doc.openidentityplatform.org/opendj/how-to/) | | How To | How-To task directory and the recipes below | | Recipe in the former How To collection | Destination | | --- | --- | | Get last version; setup server | Installation Guide: command-line installation | | Clean and reinstall server | Installation Guide: uninstall, then install | | Check server status | Administration Guide: monitoring | | Backup and restore | Administration Guide: backup and restore | | Initialize replication; disable replication | Administration Guide: replication | | List indexes; rebuild degraded indexes | Administration Guide: indexing | | List TLS protocols/ciphers; restrict TLS | Administration Guide: TLS protocols and cipher suites | | Use a certificate with Docker | Connection handlers: certificate preparation; Docker image README: OPENDJ_SSL_OPTIONS | | Cassandra backend | how-to/cassandra-backend.adoc | | JDBC backend | how-to/jdbc-backend.adoc | | Debug instance | how-to/debug-instance.adoc | | Jira integration | Existing link to Atlassian's instructions, retained in how-to/tasks.adoc | The staged wiki changes are provided in [`wiki-how-to-migration.patch`](wiki-how-to-migration.patch). Apply the patch to a checkout of the wiki only after the publication checks below pass. ## Publication order 1. Merge and deploy the OpenDJ documentation sources, then register the new navigation and PDF link in the site repository once the generated modules are available. Preview both changes together before publication. 2. Verify all destinations above, the How-To menu, PDF download and search results on the published site. 3. Replace the eight former tutorial bodies with short relocation notices, and the How To collection with a link directory. Keep their filenames so existing wiki URLs remain useful. Keep How To Guides as a link to the new guide. Prepare wiki notices locally, but do not publish them before their destinations exist. The wiki history retains the original text. Do not maintain or synchronize a second full copy of the articles. opendj-doc-generated-ref/pom.xml
@@ -731,10 +731,13 @@ </goals> <configuration> <documents> <document>release-notes</document> <document>getting-started</document> <document>install-guide</document> <document>admin-guide</document> <document>server-dev-guide</document> <document>reference</document> <document>how-to</document> </documents> </configuration> </execution> opendj-doc-generated-ref/src/main/asciidoc/getting-started/first-steps.adoc
New file @@ -0,0 +1,171 @@ //// 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. //// :opendj-example-version: 5.2.0 [#getting-started-first-directory] == Your First Directory This exercise uses the published OpenDJ {opendj-example-version} ZIP distribution on Linux or macOS with Bash. It creates a new evaluation instance, uses a self-signed certificate for LDAPS, and leaves existing installations alone. For Windows, native packages or Docker, use the xref:../install-guide/chap-install.adoc[Installation Guide]. === 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. 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. Download and unpack the server in a new directory: [source,bash,subs="+attributes"] ---- mkdir 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 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: [source,bash] ---- 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 ./setup --cli --no-prompt --acceptLicense \ --hostname localhost --ldapPort 1389 --ldapsPort 1636 \ --adminConnectorPort 4444 --generateSelfSignedCertificate \ --rootUserDN 'cn=Directory Manager' \ --rootUserPasswordFile ../quickstart-password.txt \ --baseDN 'dc=example,dc=com' --addBaseEntry ---- 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: [source,bash] ---- ./bin/ldapsearch --hostname localhost --port 1636 --useSSL --trustAll \ --bindDN 'cn=Directory Manager' --bindPasswordFile ../quickstart-password.txt \ --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]. === Add a Person Create a People organizational unit and Alice's entry in an LDIF file. The parent entry must precede its child: [source,bash] ---- cat > people.ldif <<'LDIF' dn: ou=People,dc=example,dc=com objectClass: top objectClass: organizationalUnit ou: People dn: uid=alice,ou=People,dc=example,dc=com objectClass: top objectClass: inetOrgPerson uid: alice cn: Alice Jensen sn: Jensen mail: alice@example.com LDIF ./bin/ldapmodify --hostname localhost --port 1636 --useSSL --trustAll \ --bindDN 'cn=Directory Manager' --bindPasswordFile ../quickstart-password.txt \ --defaultAdd --filename people.ldif ---- Both additions should succeed. Alice is a directory record here; this example does not assign her a password or configure application access. === Search and Change the Entry Search below the base DN for Alice, requesting only her name and email address: [source,bash] ---- ./bin/ldapsearch --hostname localhost --port 1636 --useSSL --trustAll \ --bindDN 'cn=Directory Manager' --bindPasswordFile ../quickstart-password.txt \ --baseDN 'dc=example,dc=com' '(uid=alice)' cn mail ---- The result includes Alice's DN, `cn: Alice Jensen` and `mail: alice@example.com`. Replace the email address using an LDIF change record: [source,bash] ---- cat > update-alice.ldif <<'LDIF' dn: uid=alice,ou=People,dc=example,dc=com changetype: modify replace: mail mail: alice.jensen@example.com LDIF ./bin/ldapmodify --hostname localhost --port 1636 --useSSL --trustAll \ --bindDN 'cn=Directory Manager' --bindPasswordFile ../quickstart-password.txt \ --filename update-alice.ldif ---- Repeat the search. It should now return `mail: alice.jensen@example.com`. === Restart and Remove the Sample Data Stop and restart the server as the same operating-system user who ran setup: [source,bash] ---- ./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: [source,bash] ---- for dn in 'uid=alice,ou=People,dc=example,dc=com' 'ou=People,dc=example,dc=com'; do ./bin/ldapdelete --hostname localhost --port 1636 --useSSL --trustAll \ --bindDN 'cn=Directory Manager' --bindPasswordFile ../quickstart-password.txt \ "$dn" done ---- Repeat the search once more. It should return no entries. The base entry remains available for another exercise. Stop the evaluation server and remove the temporary password and LDIF files when finished: [source,bash] ---- ./bin/stop-ds rm ../quickstart-password.txt people.ldif update-alice.ldif ---- The installation and its database remain on disk. To use it again, run `./bin/start-ds` and re-create `../quickstart-password.txt` with the same administrator password and restrictive permissions before repeating the client commands. To remove it, follow xref:../install-guide/chap-uninstall.adoc[Removing OpenDJ Servers]. === Next Steps * xref:../admin-guide/chap-privileges-acis.adoc[Configuring Privileges and Access Control] explains how to give application accounts the access they need. * 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:../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. opendj-doc-generated-ref/src/main/asciidoc/getting-started/index.adoc
New file @@ -0,0 +1,27 @@ //// 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. //// = Getting Started :doctype: book :toc: :copyright: Copyright 2026 3A Systems, LLC. :imagesdir: ../ [abstract] Learn the directory concepts used by OpenDJ, then install a local evaluation server and add, find, change and delete an LDAP entry. include::./overview.adoc[] include::./first-steps.adoc[] opendj-doc-generated-ref/src/main/asciidoc/getting-started/overview.adoc
New file @@ -0,0 +1,45 @@ //// 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. //// [#getting-started-overview] == Directory Concepts OpenDJ stores directory entries and makes them available to applications through LDAP. A directory is commonly used to hold users, groups and application configuration. Applications bind to the server to authenticate, then search or update entries according to their access rights. Entry:: 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`. 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`. Object class and schema:: 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. 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. 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`. A server stores a suffix in a backend. Replication can synchronize directory data between servers; it does not replace backups. This tutorial uses one server and one backend. Continue with xref:./first-steps.adoc[Your First Directory]. For a fuller explanation, see xref:../admin-guide/chap-understanding-ldap.adoc[Understanding Directory Services]. opendj-doc-generated-ref/src/main/asciidoc/how-to/bcfks.adoc
New file @@ -0,0 +1,90 @@ //// 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. //// :figure-caption!: :example-caption!: :table-caption!: [#how-to-bcfks] == Set Up OpenDJ With a BCFKS Keystore This recipe creates a BCFKS keystore and uses it for a fresh OpenDJ server. It demonstrates Bouncy Castle FIPS provider registration, not certification of a deployment or configuration of an operating system's FIPS mode. Use the provider shipped with your OpenDJ distribution, rather than downloading the old library versions from the wiki example. Prepare a fresh unpacked installation using xref:../install-guide/chap-install.adoc#before-you-install[the installation prerequisites]. Run the following commands from its root directory with the same Java installation that will run OpenDJ. The example uses a self-signed certificate for `localhost`; see xref:../admin-guide/chap-connection-handlers.adoc#setup-server-cert[Preparing For Secure Communications] for CA-signed certificates. === Create the Keystore Store the keystore outside the installation so setup does not overwrite it. Replace the example password before using the procedure outside a disposable test. [source,bash] ---- umask 077 mkdir -p ../opendj-certs CERT_DIR="$(cd ../opendj-certs && pwd)" printf '%s\n' 'KeystorePassword123!' > "$CERT_DIR/keystore.pin" keytool -genkeypair -alias server-cert -keyalg RSA -keysize 2048 \ -sigalg SHA256withRSA -dname 'CN=localhost' -ext 'SAN=dns:localhost' \ -validity 365 -storetype BCFKS -keystore "$CERT_DIR/server.bcfks" \ -providerclass org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider \ -providerpath lib/org.bouncycastle.bc-fips.jar \ -storepass:file "$CERT_DIR/keystore.pin" -keypass:file "$CERT_DIR/keystore.pin" keytool -genkeypair -alias admin-cert -keyalg RSA -keysize 2048 \ -sigalg SHA256withRSA -dname 'CN=localhost' -ext 'SAN=dns:localhost' \ -validity 365 -storetype BCFKS -keystore "$CERT_DIR/server.bcfks" \ -providerclass org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider \ -providerpath lib/org.bouncycastle.bc-fips.jar \ -storepass:file "$CERT_DIR/keystore.pin" -keypass:file "$CERT_DIR/keystore.pin" keytool -list -storetype BCFKS -keystore "$CERT_DIR/server.bcfks" \ -providerclass org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider \ -providerpath lib/org.bouncycastle.bc-fips.jar \ -storepass:file "$CERT_DIR/keystore.pin" ---- The listing should report `BCFKS`, provider `BCFIPS`, and two private-key entries: `server-cert` for LDAP TLS and `admin-cert` for the administration connector. Pass both aliases to setup so its truststores include both certificates and it can verify startup through the administration connector. The JAR has a stable distribution filename even when its bundled version changes. === Configure and Start OpenDJ Register the provider in each environment used to start the server or its tools: [source,bash] ---- export OPENDJ_JAVA_ARGS="${OPENDJ_JAVA_ARGS:-} -Dorg.openidentityplatform.opendj.fips.register=true" ./setup --cli --no-prompt --acceptLicense \ --hostname localhost --ldapPort 1389 --ldapsPort 1636 --adminConnectorPort 4444 \ --enableStartTLS --useBcfksKeystore "$CERT_DIR/server.bcfks" \ --keyStorePasswordFile "$CERT_DIR/keystore.pin" \ --certNickname server-cert --certNickname admin-cert \ --rootUserDN 'cn=Directory Manager' --rootUserPassword password \ --baseDN dc=example,dc=com --addBaseEntry bin/ldapsearch --hostname localhost --port 1636 --useSSL --trustAll \ --bindDN 'cn=Directory Manager' --bindPassword password \ --baseDN dc=example,dc=com --searchScope base '(objectClass=*)' dn ---- The search should return the base entry over LDAPS. Also verify the administration connector: [source,bash] ---- bin/dsconfig list-backends --hostname localhost --port 4444 \ --bindDN 'cn=Directory Manager' --bindPassword password --trustAll --no-prompt ---- Expect the enabled `userRoot` backend. `--trustAll` is only used to check this local self-signed installation. Configure certificate trust for normal client use; do not replace a system truststore merely to make this example work. Preserve the provider setting in the service environment for subsequent starts. opendj-doc-generated-ref/src/main/asciidoc/how-to/cassandra-backend.adoc
New file @@ -0,0 +1,47 @@ //// 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. //// :figure-caption!: :example-caption!: :table-caption!: [#how-to-cassandra-backend] == Store Directory Data in Cassandra This recipe preserves the Cassandra backend setup from the wiki's task collection. It requires a reachable Cassandra cluster and a data center name matching that cluster's configuration. Prepare a fresh OpenDJ installation from the full server ZIP (not the slim ZIP, which omits the Cassandra driver), without a base DN, using only the `./setup` command in xref:./jdbc-backend.adoc[the JDBC setup procedure]. Do not run its `create-backend` command: the Cassandra backend below will use the same `userRoot` name. Setup starts the server without `OPENDJ_JAVA_ARGS`. After setup finishes, append the driver settings to every `java-args` value in `config/java.properties` and restart the server before creating the backend. The server and offline tools such as `import-ldif --offline` and `rebuild-index` each read their own Java arguments. For a local Cassandra node on port 9042 in data center `datacenter1`: [source,bash] ---- unset OPENDJ_JAVA_ARGS sed -i.bak 's/^[a-z0-9.-]*java-args=.*/& -Ddatastax-java-driver.basic.contact-points.0=localhost:9042 -Ddatastax-java-driver.basic.load-balancing-policy.local-datacenter=datacenter1/' config/java.properties bin/stop-ds bin/start-ds ---- The start scripts ignore the Java arguments in `config/java.properties` while `OPENDJ_JAVA_ARGS` is set. Leave it unset in shells and services that start the server or run offline tools. Configure authentication and TLS in the driver for a secured cluster. Create the backend with keyspace name `ldap_example_com`: [source,bash] ---- bin/dsconfig create-backend --hostname localhost --port 4444 \ --bindDN 'cn=Directory Manager' --bindPassword password \ --backend-name userRoot --type cas \ --set db-directory:ldap_example_com --set base-dn:dc=example,dc=com \ --set enabled:true --trustAll --no-prompt ---- Follow xref:./generate-test-data.adoc[Generate and Load Test LDIF Data] to add entries and check LDAP searches. Choose Cassandra replication and durability settings for your topology before using this backend for persistent directory data; this local recipe does not configure a production cluster. opendj-doc-generated-ref/src/main/asciidoc/how-to/debug-instance.adoc
New file @@ -0,0 +1,34 @@ //// 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. //// :figure-caption!: :example-caption!: :table-caption!: [#how-to-debug-instance] == Attach a Java Debugger to a Local Instance Stop the disposable instance with `bin/stop-ds`, then start it with a JDWP listener on the loopback interface: [source,bash] ---- export OPENDJ_JAVA_ARGS="${OPENDJ_JAVA_ARGS:-} -agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=127.0.0.1:9000" bin/start-ds --nodetach ---- Attach the IDE's remote Java debugger to `localhost:9000`. With `suspend=y`, startup waits for the debugger before the server opens its LDAP listener. Set `suspend=n` if startup should proceed without a debugger. Run clients from a second terminal without the JDWP setting, otherwise they try to bind the same debug port. After debugging, stop the foreground server and remove the JDWP option from `OPENDJ_JAVA_ARGS` before starting it normally. Keep this unauthenticated debug listener local; it grants control of the JVM to anyone who can connect. opendj-doc-generated-ref/src/main/asciidoc/how-to/delegate-password-reset.adoc
New file @@ -0,0 +1,107 @@ //// 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. //// :figure-caption!: :example-caption!: :table-caption!: [#how-to-delegate-password-reset] == Delegate Password Reset Permissions 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. === Create the Delegate and Grant Access Create a delegate outside the target People subtree, so its own entry is not in the delegated reset scope: [source,bash] ---- bin/ldapmodify --hostname localhost --port 1389 --useStartTLS --trustAll \ --bindDN 'cn=Directory Manager' --bindPassword password <<'LDIF' dn: ou=Administrators,dc=example,dc=com changetype: add objectClass: organizationalUnit ou: Administrators dn: uid=password-admin,ou=Administrators,dc=example,dc=com changetype: add objectClass: inetOrgPerson cn: Password Administrator sn: Administrator uid: password-admin userPassword: AdminPassword123! ds-privilege-name: password-reset dn: ou=People,dc=example,dc=com changetype: modify add: aci aci: (targetattr="userPassword")(version 3.0; acl "Delegate password resets in People"; allow (write) userdn="ldap:///uid=password-admin,ou=Administrators,dc=example,dc=com";) 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. === Verify the Scope Reset a sample user's password: [source,bash] ---- 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' \ --newPassword 'NewPassword123!' ---- The password-modify operation should succeed. Verify the new password by binding as the user: [source,bash] ---- bin/ldapsearch --hostname localhost --port 1389 --useStartTLS --trustAll \ --bindDN 'uid=user.0,ou=People,dc=example,dc=com' \ --bindPassword 'NewPassword123!' \ --baseDN 'uid=user.0,ou=People,dc=example,dc=com' --searchScope base \ '(objectClass=*)' uid ---- Check that the delegate cannot change another attribute: [source,bash] ---- 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 changetype: modify replace: description description: This change must be rejected LDIF ---- Expect LDAP result 50, `Insufficient Access Rights`. A successful change indicates that another ACI grants broader access. If the loopback HTTPS handler from xref:./rest-access.adoc[the REST recipe] is enabled, the same delegate can request a generated password through REST: [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' ---- 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. opendj-doc-generated-ref/src/main/asciidoc/how-to/embedded-ldap.adoc
New file @@ -0,0 +1,116 @@ //// 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. //// :figure-caption!: :example-caption!: :table-caption!: [#how-to-embedded-ldap] == Run Embedded LDAP in a Spring Boot Application :opendj-version: 5.2.0 Use `opendj-embedded` for an LDAP server owned by your application's lifecycle, for example in integration tests. Each `EmbeddedOpenDJ` instance creates a temporary installation and deletes it on `close()`. Use a standalone server when directory data must survive application restarts. Run one embedded server at a time in a JVM, with its LDAP, administration and JMX ports available. === Add the Dependency In an existing Spring Boot Maven application, add: [source,xml,subs="+attributes"] ---- <dependency> <groupId>org.openidentityplatform.opendj</groupId> <artifactId>opendj-embedded</artifactId> <version>{opendj-version}</version> </dependency> ---- Use a JDK supported by your Spring Boot version and at least Java 11 for OpenDJ. === Configure the Bean and Import Data Put this configuration in your application's component-scan package. It imports `src/main/resources/test-directory.ldif` after startup and calls the server's `close()` method when the Spring context closes or initialization fails: [source,java] ---- import java.io.IOException; import java.io.InputStream; import org.openidentityplatform.opendj.embedded.Config; import org.openidentityplatform.opendj.embedded.EmbeddedOpenDJ; import org.springframework.beans.factory.annotation.Value; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; @Configuration public class LdapConfiguration { @Bean(destroyMethod = "close") public EmbeddedOpenDJ embeddedOpenDJ( @Value("${opendj.password:TestPassword123!}") String password) throws Exception { Config config = new Config(); config.setBaseDN("dc=example,dc=com"); config.setAdminPassword(password); config.setPort(1389); config.setAdminPort(4444); config.setJmxPort(1689); EmbeddedOpenDJ server = new EmbeddedOpenDJ(config); try { server.run(); try (InputStream data = getClass().getResourceAsStream("/test-directory.ldif")) { if (data == null) { throw new IOException("Missing test-directory.ldif"); } server.importData(data); } return server; } catch (Exception e) { server.close(); throw e; } } } ---- Use this LDIF file. `importData` adds entries; it does not replace existing entries. Check the logs for rejected additions and verify the imported entry: [source,ldif] ---- dn: dc=example,dc=com objectClass: domain dc: example dn: ou=people,dc=example,dc=com objectClass: organizationalUnit ou: people dn: uid=jdoe,ou=people,dc=example,dc=com objectClass: inetOrgPerson cn: John Doe sn: Doe uid: jdoe ---- === Verify Through LDAP With the Spring application running, use `ldapsearch` from an OpenDJ distribution: [source,bash] ---- bin/ldapsearch --hostname localhost --port 1389 \ --bindDN 'cn=Directory Manager' --bindPassword 'TestPassword123!' \ --baseDN 'uid=jdoe,ou=people,dc=example,dc=com' --searchScope base \ '(objectClass=*)' uid cn ---- Expect `uid: jdoe` and `cn: John Doe`. Use the same assertion in your application's integration tests, for example with Spring LDAP's `LdapTemplate`. Closing the context calls `close()` to stop the server and clean up its temporary files. If the server cannot be stopped, the instance stays open and retains its directory and shutdown hook so that a later `close()` call or JVM exit can retry the stop. opendj-doc-generated-ref/src/main/asciidoc/how-to/generate-test-data.adoc
New file @@ -0,0 +1,55 @@ //// 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. //// :figure-caption!: :example-caption!: :table-caption!: [#how-to-generate-test-data] == Generate and Load Test LDIF Data Use `makeldif` to generate repeatable sample data, then add it through LDAP. This works with a running backend, including the JDBC backend in xref:./jdbc-backend.adoc[Use a Relational Database as an LDAP Backend]. For offline bulk import and its replacement semantics, use xref:../admin-guide/chap-import-export.adoc#import-ldif[Importing Data] instead. === Generate the File Use an empty backend with base DN `dc=example,dc=com`: do not populate it with `--addBaseEntry` or `--sampleData` during setup. The generated file includes the base entry, `ou=People`, and 100 users. See xref:../admin-guide/chap-import-export.adoc#generating-ldif[Generating Test Data] to customize the template. [source,bash] ---- bin/makeldif --outputLDIF test.ldif --randomSeed 0 \ --constant suffix=dc=example,dc=com --constant numusers=100 \ config/MakeLDIF/example.template ---- Expect 102 generated entries. Change `numusers` for a larger test; the unmodified template defaults to 10,000 users. The file contains sample passwords; use it for a disposable test directory. === Add and Verify Entries With the server running and StartTLS enabled on port 1389: [source,bash] ---- bin/ldapmodify --hostname localhost --port 1389 --useStartTLS --trustAll \ --bindDN 'cn=Directory Manager' --bindPassword password \ --defaultAdd --filename test.ldif bin/ldapsearch --hostname localhost --port 1389 --useStartTLS --trustAll \ --bindDN 'cn=Directory Manager' --bindPassword password \ --baseDN 'ou=People,dc=example,dc=com' \ '(|(uid=user.0)(uid=user.1)(uid=user.2))' uid cn ---- The search returns three entries. Unlike offline import, LDAP add does not replace the existing database: repeating the load reports `Entry Already Exists`. Use a fresh backend for another complete load. `--trustAll` is for the self-signed certificate in this local example. opendj-doc-generated-ref/src/main/asciidoc/how-to/index.adoc
New file @@ -0,0 +1,38 @@ //// 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. //// = How-To Guides :doctype: book :toc: :copyright: Copyright 2026 3A Systems, LLC. :imagesdir: ../ :figure-caption!: :example-caption!: :table-caption!: [abstract] Practical recipes for running and integrating OpenDJ. These guides are maintained in the OpenDJ repository; the former wiki articles link here. For procedures already covered by another guide, see the task directory below. include::./tasks.adoc[] include::./kubernetes.adoc[] include::./bcfks.adoc[] include::./jdbc-backend.adoc[] include::./embedded-ldap.adoc[] include::./rest-access.adoc[] include::./delegate-password-reset.adoc[] include::./generate-test-data.adoc[] include::./cassandra-backend.adoc[] include::./debug-instance.adoc[] opendj-doc-generated-ref/src/main/asciidoc/how-to/jdbc-backend.adoc
New file @@ -0,0 +1,63 @@ //// 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. //// :figure-caption!: :example-caption!: :table-caption!: [#how-to-jdbc-backend] == Use a Relational Database as an LDAP Backend This example stores LDAP entries in PostgreSQL while clients continue to use LDAP. It requires Docker and a fresh OpenDJ installation from the full server ZIP, prepared according to xref:../install-guide/chap-install.adoc#before-you-install[the installation prerequisites]. Use Java 11 or later. === Start PostgreSQL [source,bash] ---- docker run -d --name opendj-postgres \ -p 127.0.0.1:5432:5432 \ -e POSTGRES_DB=opendj -e POSTGRES_PASSWORD=password \ postgres:17 docker exec opendj-postgres pg_isready -U postgres -d opendj ---- Wait until `pg_isready` reports that the database accepts connections. This container is a disposable demonstration; configure database persistence and credentials for a lasting deployment. === Create the LDAP Backend Run setup from the unpacked OpenDJ directory without a base DN, so it does not create `userRoot`: [source,bash] ---- ./setup --cli --no-prompt --acceptLicense \ --hostname localhost --ldapPort 1389 --adminConnectorPort 4444 \ --enableStartTLS --generateSelfSignedCertificate \ --rootUserDN 'cn=Directory Manager' --rootUserPassword password bin/dsconfig create-backend --hostname localhost --port 4444 \ --bindDN 'cn=Directory Manager' --bindPassword password \ --backend-name userRoot --type jdbc \ --set base-dn:dc=example,dc=com \ --set 'db-directory:jdbc:postgresql://localhost:5432/opendj?user=postgres&password=password' \ --set enabled:true --trustAll --no-prompt ---- Quote the JDBC URL so the shell does not interpret `&`. The example's database credentials are stored in the backend configuration; restrict access to the instance files. The PostgreSQL driver is included in the full server ZIP; `opendj-<version>-slim.zip` leaves out the Cassandra, Oracle, MySQL, SQL Server and PostgreSQL drivers. For another supported database, check the backend's SQL dialect support as well as the JDBC driver; a JDBC driver alone does not make every database compatible. The backend is initially empty. Follow xref:./generate-test-data.adoc[Generate and Load Test LDIF Data] to populate it and verify LDAP searches. See xref:../reference/dsconfig-subcommands-ref.adoc#dsconfig-create-backend[dsconfig create-backend] for configuration properties. When finished, stop OpenDJ with `bin/stop-ds`, then remove the demonstration database with `docker rm -fv opendj-postgres`. The `-v` option also removes its anonymous data volume and discards the demonstration database. opendj-doc-generated-ref/src/main/asciidoc/how-to/kubernetes.adoc
New file @@ -0,0 +1,129 @@ //// 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. //// :figure-caption!: :example-caption!: :table-caption!: [#how-to-kubernetes] == Run OpenDJ in Kubernetes :opendj-version: 5.2.0 This recipe runs one directory server with persistent storage in a local Minikube cluster. It requires `minikube`, `kubectl`, and a default StorageClass that supports dynamic volume provisioning. It does not configure replication; increasing the replica count alone does not create a replicated directory. [source,bash] ---- minikube start --cpus=4 --memory=8g kubectl create namespace opendj-demo kubectl -n opendj-demo create secret generic opendj-root \ --from-literal=password='DemoPassword123!' ---- === Create the Service and StatefulSet Save the following as `opendj.yaml`. The root password comes from the Secret. A PersistentVolumeClaim keeps the instance under `/opt/opendj/data`, the same location described in xref:../install-guide/chap-install.adoc#install-docker[Running OpenDJ in Docker]. `fsGroup` lets the non-root server write to the mounted volume on storage that supports Kubernetes volume ownership management. [source,yaml,subs="+attributes"] ---- apiVersion: v1 kind: Service metadata: name: opendj spec: clusterIP: None selector: app: opendj ports: - name: ldap port: 1389 - name: ldaps port: 1636 - name: admin port: 4444 --- apiVersion: apps/v1 kind: StatefulSet metadata: name: opendj spec: serviceName: opendj replicas: 1 selector: matchLabels: app: opendj template: metadata: labels: app: opendj spec: terminationGracePeriodSeconds: 60 securityContext: fsGroup: 1001 containers: - name: opendj image: openidentityplatform/opendj:{opendj-version} env: - name: ROOT_PASSWORD valueFrom: secretKeyRef: name: opendj-root key: password - name: ADD_BASE_ENTRY value: --addBaseEntry ports: - containerPort: 1389 - containerPort: 1636 - containerPort: 4444 readinessProbe: exec: command: [/opt/opendj/healthcheck.sh] periodSeconds: 10 timeoutSeconds: 30 volumeMounts: - name: data mountPath: /opt/opendj/data volumeClaimTemplates: - metadata: name: data spec: accessModes: [ReadWriteOnce] resources: requests: storage: 1Gi ---- [source,bash] ---- kubectl -n opendj-demo apply -f opendj.yaml kubectl -n opendj-demo rollout status statefulset/opendj --timeout=600s kubectl -n opendj-demo get pods,pvc ---- Wait for the pod to be Ready. The readiness probe checks completed bootstrap and LDAP availability; a listening TCP port alone is insufficient during first startup. If the claim stays Pending, check the StorageClass. If the pod does not become Ready, inspect `kubectl -n opendj-demo logs opendj-0` and `kubectl -n opendj-demo describe pod opendj-0`. === Verify the Directory and Persistence [source,bash] ---- kubectl -n opendj-demo exec opendj-0 -- /opt/opendj/bin/ldapsearch \ --hostname localhost --port 1389 \ --bindDN 'cn=Directory Manager' --bindPassword 'DemoPassword123!' \ --baseDN dc=example,dc=com --searchScope base '(objectClass=*)' dn ---- Expect `dn: dc=example,dc=com`. Entries added to this instance remain on the claim when the pod is replaced. To verify, add a test entry, delete only the pod with `kubectl -n opendj-demo delete pod opendj-0`, wait for the replacement to become Ready, and search for the entry again. Do not delete the claim during this check. Deleting the StatefulSet normally retains its claim. Deleting the demonstration namespace with `kubectl delete namespace opendj-demo` also deletes its claims and can delete the backing storage, depending on its reclaim policy. opendj-doc-generated-ref/src/main/asciidoc/how-to/rest-access.adoc
New file @@ -0,0 +1,82 @@ //// 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. //// :figure-caption!: :example-caption!: :table-caption!: [#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. === Enable the Handler Bind HTTPS to loopback and reuse the JKS certificate generated during setup. Password-reset actions require a secure connection, even on loopback. See xref:../admin-guide/chap-connection-handlers.adoc#setup-http-connection-handler[Setting Up an HTTP Connection Handler] for other certificate configurations. `--trustAll` below is for the local server's self-signed administration certificate. [source,bash] ---- bin/dsconfig set-connection-handler-prop \ --hostname localhost --port 4444 \ --bindDN 'cn=Directory Manager' --bindPassword password \ --handler-name 'HTTP Connection Handler' \ --set listen-address:127.0.0.1 --set listen-port:8443 \ --set use-ssl:true --set key-manager-provider:JKS --set enabled:true \ --trustAll --no-prompt bin/stop-ds --restart bin/dsconfig list-http-authorization-mechanisms \ --hostname localhost --port 4444 \ --bindDN 'cn=Directory Manager' --bindPassword password --trustAll --no-prompt bin/dsconfig list-http-endpoints \ --hostname localhost --port 4444 \ --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`. === Read a User Export the locally generated certificate so `curl` can verify it: [source,bash] ---- keytool -exportcert -rfc -alias server-cert -keystore config/keystore \ -storepass:file config/keystore.pin -file server-cert.pem ---- [source,bash] ---- curl --fail-with-body --cacert server-cert.pem --user 'user.0:password' \ 'https://localhost:8443/api/users/user.0?_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. To enable HTTP access logging: [source,bash] ---- bin/dsconfig set-log-publisher-prop \ --hostname localhost --port 4444 \ --bindDN 'cn=Directory Manager' --bindPassword password \ --publisher-name 'File-Based HTTP Access Logger' --set enabled:true \ --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]. opendj-doc-generated-ref/src/main/asciidoc/how-to/tasks.adoc
New file @@ -0,0 +1,53 @@ //// 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. //// :figure-caption!: :example-caption!: :table-caption!: [#how-to-tasks] == Find a Procedure The examples use a disposable local instance and illustrative passwords. Run server commands from the installation directory. Follow the xref:../install-guide/chap-install.adoc#before-you-install[installation prerequisites], including Java 11 or later, before starting. [cols="1,2",options="header"] |=== |Task |Procedure |Download and set up a server, with an empty suffix or sample data |xref:../install-guide/chap-install.adoc#command-line-install[Command-line installation] |Stop, remove and reinstall a disposable server |xref:../install-guide/chap-uninstall.adoc[Uninstalling OpenDJ]; then follow command-line installation. Back up any data to keep before removal. |Check server status |xref:../admin-guide/chap-monitoring.adoc[Monitoring OpenDJ] |Back up and restore data |xref:../admin-guide/chap-backup-restore.adoc[Backing Up and Restoring Data] |Enable and initialize replication, or remove a replica |xref:../admin-guide/chap-replication.adoc[Managing Data Replication] |Inspect indexes and rebuild degraded indexes |xref:../admin-guide/chap-indexing.adoc[Managing Indexes] |List supported TLS protocols and cipher suites, or restrict them |xref:../admin-guide/chap-connection-handlers.adoc#tls-protocols-cipher-suites[TLS Protocols and Cipher Suites] |Use an existing certificate or create a self-signed certificate |xref:../admin-guide/chap-connection-handlers.adoc#setup-server-cert[Preparing For Secure Communications] |Keep Docker data when replacing a container, including with Compose |xref:../install-guide/chap-install.adoc#install-docker[Running OpenDJ in Docker] |Pass a PKCS#12 certificate to the Docker image |link:https://github.com/OpenIdentityPlatform/OpenDJ/blob/master/opendj-packages/opendj-docker/README.md[Docker image configuration] (`OPENDJ_SSL_OPTIONS`) |Use OpenDJ with Jira |link:https://support.atlassian.com/jira/kb/how-to-use-opendj-with-jira/[Atlassian's integration instructions] |=== The following chapters cover additional tasks. Each procedure has one maintained location; use the links above for the full instructions rather than a second copy of them. opendj-doc-generated-ref/src/main/asciidoc/install-guide/chap-install.adoc
@@ -701,6 +701,32 @@ To stop the server, stop the container with `docker stop opendj`; `docker start opendj` starts it again. `docker stop` gives the server 10 seconds to shut down before it kills it: give a server with much data more time, for example with `docker stop -t 60 opendj`. [#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: [source,yaml] ---- services: opendj: image: openidentityplatform/opendj init: true ports: - "127.0.0.1:1389:1389" - "127.0.0.1:1636:1636" - "127.0.0.1:4444:4444" environment: ROOT_PASSWORD: password ADD_BASE_ENTRY: --addBaseEntry volumes: - opendj-data:/opt/opendj/data stop_grace_period: 60s volumes: 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. ==== [#install-properties-file] opendj-doc-generated-ref/src/main/asciidoc/release-notes/index.adoc
New file @@ -0,0 +1,27 @@ //// 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. //// = Release Notes :doctype: book :toc: :copyright: Copyright 2026 3A Systems, LLC. :imagesdir: ../ [abstract] Release information for Open Identity Platform OpenDJ, including requirements, selected changes and upgrade considerations. Consult the linked release records for the complete change history. include::./release-5.2.0.adoc[] include::./requirements-and-upgrade.adoc[] opendj-doc-generated-ref/src/main/asciidoc/release-notes/release-5.2.0.adoc
New file @@ -0,0 +1,58 @@ //// 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. //// [#release-5-2-0] == OpenDJ 5.2.0 OpenDJ 5.2.0 was published on 21 October 2026. These notes describe that released version. Documentation built from a development branch can also describe changes intended for a later release; a `SNAPSHOT` build is not a published release. The link:https://github.com/OpenIdentityPlatform/OpenDJ/releases/tag/5.2.0[5.2.0 release record] is the authoritative list of release assets and changes. The link:https://github.com/OpenIdentityPlatform/OpenDJ/compare/5.1.2...5.2.0[complete comparison with 5.1.2] provides the corresponding source history. For newer releases, consult the link:https://github.com/OpenIdentityPlatform/OpenDJ/releases[release list]. === Selected Changes The release includes the following changes, among others: * Security fixes for the DSML gateway, OAuth2 file token authorization, LDAP connection handling, and access control for sort and virtual list view (VLV) requests. Review the link:https://github.com/OpenIdentityPlatform/OpenDJ/security/advisories[published security advisories] for affected versions, impact and remediation details. * Directory and replication reliability fixes, including startup failure reporting when a replication server cannot open its port or changelog, and persistent-search notification handling. * JDBC backend fixes for Microsoft SQL Server upsert conflicts and deadlocks. * Docker improvements for arbitrary user IDs in group 0, secret handling, health checks, background replication joining and upgrades from a released image. * REST to LDAP fixes for HTTP Basic credentials and bind templates, and reloading file-based key stores and trust stores when their files change. This is a summary, not a second copy of the full change list. Use the release record to identify individual fixes and their pull requests. === Distributions The release provides the following assets: [cols="1,2",options="header"] |=== |Asset |Purpose |`opendj-5.2.0.zip` |Cross-platform directory server; used by the Getting Started exercise. |`opendj-5.2.0-slim.zip` |Slim server distribution without the Cassandra, Oracle, MySQL, SQL Server and PostgreSQL drivers. |`opendj_5.2.0-1_all.deb` |Debian package. |`opendj-5.2.0-1.noarch.rpm` |RPM package. |`opendj-5.2.0.msi` |Windows installer. |`org.openidentityplatform.opendj.opendj-ldap-toolkit.zip` |LDAP client toolkit. |`org.openidentityplatform.opendj.opendj-rest2ldap-servlet.war` |REST to LDAP gateway for deployment in a servlet container. |`org.openidentityplatform.opendj.opendj-dsml-servlet.war` |DSML gateway for deployment in a servlet container. |`OpenDJ.Doc.Generated.References-pdf.zip` |Documentation PDFs packaged with the release. |`Dockerfile.zip` |Docker image build files. |`opendj-openshift-template.yaml` |OpenShift deployment template. |=== The project also publishes the link:https://hub.docker.com/r/openidentityplatform/opendj/[OpenDJ Docker image]. See xref:../install-guide/chap-install.adoc#install-docker[Running OpenDJ in Docker] for image variants, configuration and persistent data. Before installation or upgrade, read xref:./requirements-and-upgrade.adoc[Requirements and Upgrade Considerations]. For a first evaluation, follow xref:../getting-started/first-steps.adoc[Your First Directory]. opendj-doc-generated-ref/src/main/asciidoc/release-notes/requirements-and-upgrade.adoc
New file @@ -0,0 +1,54 @@ //// 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. //// [#release-requirements] == Requirements and Upgrade Considerations === Java and Installation Environment OpenDJ 5.2.0 requires Java 11 or later. This is the minimum in the link:https://github.com/OpenIdentityPlatform/OpenDJ/blob/5.2.0/README.md[release README]; the server ZIP does not supply a Java runtime. The Docker image supplies its own Java environment. Install with an operating-system account that can write the server's configuration, database and logs. Ensure the selected listener ports are available and the server host name resolves as intended. Choose memory, disk space and file-descriptor limits for the size of your directory and workload; the small Getting Started exercise is not production sizing guidance. See xref:../install-guide/chap-install.adoc#before-you-install[Preparing For Installation] and xref:../admin-guide/chap-tuning.adoc[Tuning Servers]. The standalone server does not require a servlet container. The separate REST to LDAP and DSML WAR files do; follow their installation procedures in the xref:../install-guide/chap-install.adoc[Installation Guide]. === Plan an Upgrade Read the release records for every version between your installed release and the target version. Test the upgrade with a copy of your configuration and data, including application binds, searches, access controls, custom schema, plugins and replication. Back up the installation before replacing its files, and retain the original binaries and configuration for recovery. Follow the xref:../install-guide/chap-upgrade.adoc#before-you-upgrade[upgrade preparation] and the procedure for your installation type: * xref:../install-guide/chap-upgrade.adoc#upgrade-zip[ZIP and native packages]. * xref:../install-guide/chap-upgrade.adoc#upgrade-msi[Windows MSI]. * xref:../install-guide/chap-upgrade.adoc#upgrade-docker[Docker containers]. * xref:../install-guide/chap-upgrade.adoc#upgrade-repl[Replicated servers]. The `upgrade` tool updates configuration and data for the new binaries. With `--no-prompt`, `--acceptLicense` accepts the license; `--force` also performs tasks that otherwise require confirmation. These options have different purposes. Inspect the upgrade result and logs before returning the instance to service. === Compatibility Checks * Move installations using Java older than 11 to a suitable runtime before running OpenDJ 5.2.0. Check `OPENDJ_JAVA_HOME`, `OPENDJ_JAVA_BIN` and configured Java properties if different tools select different runtimes. * For upgrades from releases before 5.2.0, check stored DNs and access control instructions as described in xref:../install-guide/chap-upgrade.adoc#upgrade-dn-parsing[To Check Stored DNs When Upgrading From a Release Before 5.2.0]. An ACI whose DN has other content after an RDN puts the server into lockdown mode after the upgrade; a global ACI of that form stops the server from starting. DN-syntax values written with `;` need their equality indexes verified and rebuilt where necessary. The upgrade runs this index verification by default; review its warnings for skipped backends or indexes that still need attention. * The JMX names of monitor MBeans whose RDN value holds characters other than letters, digits and spaces change in 5.2.0: these characters are now percent-encoded. Update exporter rules and monitoring checks that match the old names; see xref:../install-guide/chap-upgrade.adoc#upgrade-dn-parsing[the DN parsing and monitor name changes]. * For ZIP upgrades from releases before 5.1.2, review the stale `lib/org.openidentityplatform.opendj.opendj-server-legacy.jar` warning in the xref:../install-guide/chap-upgrade.adoc#upgrade-zip[ZIP upgrade procedure]. Unpacking an archive does not remove obsolete files. * When migrating from OpenDJ 3 or earlier to the 5.x line, review the REST to LDAP configuration change described in the xref:../install-guide/chap-upgrade.adoc#upgrade-zip[upgrade procedure]. Do not assume an old HTTP mapping can be reused unchanged; see the xref:../reference/appendix-rest2ldap.adoc[REST to LDAP configuration reference]. * For a container upgrade, retain the data volume and check the documented image upgrade procedure and health status. Replacing a container without its persistent volume creates a different instance. === Known Issues and Help The link:https://github.com/OpenIdentityPlatform/OpenDJ/issues[issue tracker] records reported problems and ongoing work. An open issue is not, by itself, proof that a particular released version is affected: read its description, reproduction and linked fixes. Consult the link:https://github.com/OpenIdentityPlatform/OpenDJ/security/advisories[security advisories] separately for published security information. For usage questions, use the link:https://github.com/OpenIdentityPlatform/OpenDJ/discussions[community discussions]. A useful bug report includes the OpenDJ and Java versions, installation type, relevant configuration, reproduction steps and sanitized logs. Follow the project's link:https://github.com/OpenIdentityPlatform/OpenDJ/security/policy[security policy] when reporting a suspected vulnerability. opendj-doc-generated-ref/wiki-how-to-migration.patch
New file @@ -0,0 +1,1300 @@ diff --git a/How-To-Guides.md b/How-To-Guides.md index 82e2e0c..3e366ed 100644 --- a/How-To-Guides.md +++ b/How-To-Guides.md @@ -1 +1,19 @@ -See [[How To]] \ No newline at end of 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]". + +Portions Copyright 2026 3A Systems, LLC. +--> + +This guide has moved to [the OpenDJ documentation](https://doc.openidentityplatform.org/opendj/how-to/). + +Please submit documentation changes to the [OpenDJ repository](https://github.com/OpenIdentityPlatform/OpenDJ/tree/master/opendj-doc-generated-ref/src/main/asciidoc). diff --git a/How-To-Run-OpenDJ-in-Kubernetes.md b/How-To-Run-OpenDJ-in-Kubernetes.md index 9db58cd..03019aa 100644 --- a/How-To-Run-OpenDJ-in-Kubernetes.md +++ b/How-To-Run-OpenDJ-in-Kubernetes.md @@ -1,161 +1,19 @@ -## Preface +<!-- +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. -This article describes how to deploy [OpenDJ](/opendj) on Kubernetes. -We will use OpenDJ Docker image from Docker Hub Registry -[https://hub.docker.com/r/openidentityplatform/opendj/](https://hub.docker.com/r/openidentityplatform/opendj/) +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. -In this tutorial, we will use Minikube as a local Kubernetes cluster. -`kubectl` should also be installed +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]". -Start Minikube with at least 4 cores, and 8 GB of memory to avoid insufficient resources errors. +Portions Copyright 2026 3A Systems, LLC. +--> -``` -minikube start --cpus=4 --memory=8g -``` +This guide has moved to [the OpenDJ documentation](https://doc.openidentityplatform.org/opendj/how-to/kubernetes). -## Create OpenDJ Service - -The following service will be used for DNS lookups between OpenAM Pods and clients. - -Create `opendj-service.yaml` file with the following contents: - -**`opendj-service.yaml`**: -```yaml -apiVersion: v1 -kind: Service -metadata: - labels: - app: opendj - name: opendj -spec: - clusterIP: None - ports: - - port: 1389 - name: ldap - - port: 1636 - name: ldaps - - port: 4444 - name: admin - selector: - app: opendj -``` - -Then create service in Kubernetes using `kubectl`: -``` -kubectl apply -f opendj-service.yaml -``` -Make sure the service has been created: - -``` -kubectl get svc opendj - -NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE -opendj ClusterIP None <none> 1389/TCP,1636/TCP,4444/TCP 39s -``` - -## Create OpenAM StatefulSet - -Create `opendj-statefulset.yaml` file with the following contents: - -**`opendj-statefulset.yaml`**: -```yaml -apiVersion: apps/v1 -kind: StatefulSet -metadata: - name: opendj - labels: - app: opendj -spec: - serviceName: opendj - replicas: 1 - selector: - matchLabels: - app: opendj - template: - metadata: - labels: - app: opendj - spec: - containers: - - name: opendj - image: openidentityplatform/opendj - imagePullPolicy: Always - ports: - - containerPort: 1389 - protocol: TCP - - containerPort: 1636 - protocol: TCP - - containerPort: 4444 - protocol: TCP - resources: {} - terminationMessagePath: /dev/termination-log - terminationMessagePolicy: File - volumeMounts: - - name: opendj-data - mountPath: /opt/opendj/data - volumeClaimTemplates: - - metadata: - name: opendj-data - spec: - accessModes: [ "ReadWriteOnce" ] - resources: - requests: - storage: 1Gi -``` - -Create OpenDJ StatefulSet in Kubernetes -``` -kubectl apply -f opendj-statefulset.yaml -``` - -Check if StatefulSet is wokring -``` -kubectl get statefulset opendj - -NAME READY AGE -opendj 1/1 2m -``` -Wait for pod is created - -Get created Pods -``` -kubectl get pods -l="app=opendj" -NAME READY STATUS RESTARTS AGE -opendj-0 1/1 Running 0 2m42s -``` - -## Check OpenDJ status - -Lets check OpenDJ pod status -``` -$ kubectl exec -it opendj-0 -- /opt/opendj/bin/status --bindDN "cn=Directory Manager" --bindPassword password - - --- Server Status --- -Server Run Status: Started -Open Connections: 1 - - --- Server Details --- -Host Name: opendj-0.opendj.default.svc.cluster.local -Administrative Users: cn=Directory Manager -Installation Path: /opt/opendj -Instance Path: /opt/opendj/data -Version: OpenDJ Server 4.4.3 -Java Version: 1.8.0_111 -Administration Connector: Port 4444 (LDAPS) - - --- Connection Handlers --- -Address:Port : Protocol : State --------------:------------------------:--------- --- : LDIF : Disabled -0.0.0.0:161 : SNMP : Disabled -0.0.0.0:1389 : LDAP (allows StartTLS) : Enabled -0.0.0.0:1636 : LDAPS : Enabled -0.0.0.0:1689 : JMX : Disabled -0.0.0.0:8080 : HTTP : Disabled - - --- Data Sources --- -Base DN: dc=example,dc=com -Backend ID: userRoot -Entries: 1 -Replication: -``` \ No newline at end of file +Please submit documentation changes to the [OpenDJ repository](https://github.com/OpenIdentityPlatform/OpenDJ/tree/master/opendj-doc-generated-ref/src/main/asciidoc). diff --git a/How-To.md b/How-To.md index faa10f3..33a1d4c 100644 --- a/How-To.md +++ b/How-To.md @@ -1,129 +1,97 @@ -# Get last version -```bash -export VERSION="$(curl -i -o - --silent https://api.github.com/repos/OpenIdentityPlatform/OpenDJ/releases/latest | grep -m1 "\"name\"" | cut -d\" -f4)" -echo "last release: $VERSION" -curl -L https://github.com/OpenIdentityPlatform/OpenDJ/releases/download/$VERSION/opendj-$VERSION.zip --output opendj.zip -unzip opendj -cd opendj -``` - -# Setup server -```bash -#with clean baseDN -./setup --addBaseEntry -h localhost -p 1389 --ldapsPort 1636 --adminConnectorPort 4444 --enableStartTLS --generateSelfSignedCertificate --rootUserDN "cn=Directory Manager" --rootUserPassword password --baseDN dc=example,dc=com --cli --acceptLicense --no-prompt - -#with sample data -./setup --sampleData 100000 -h localhost -p 1389 --ldapsPort 1636 --adminConnectorPort 4444 --enableStartTLS --generateSelfSignedCertificate --rootUserDN "cn=Directory Manager" --rootUserPassword password --baseDN dc=example,dc=com --cli --acceptLicense --no-prompt -``` - -# Clean and reinstall server -```bash -bin/stop-ds -rm -rf {config,db,changelogDb,logs} -./setup -h localhost -p 1389 --ldapsPort 1636 --adminConnectorPort 4444 --enableStartTLS --generateSelfSignedCertificate --rootUserDN "cn=Directory Manager" --rootUserPassword password --baseDN dc=example,dc=com --addBaseEntry --cli --acceptLicense --no-prompt -``` - -# Check server status -```bash -bin/status --bindDN "cn=Directory Manager" --bindPassword password -``` - -# Backup and restore -```bash -bin/backup --port 4444 --bindDN "cn=Directory Manager" --bindPassword password --backUpAll --backupDirectory bak --start 0 && tail -f logs/errors -bin/restore --port 4444 --bindDN "cn=Directory Manager" --bindPassword password --backupDirectory bak/userRoot/ --start 0 && tail -f logs/errors -``` - -# Initialize replication between two servers -```bash -bin/dsreplication enable --host1 localhost --port1 4444 --bindDN1 "cn=Directory Manager" --bindPassword1 password --replicationPort1 2389 --host2 localhost --port2 4445 --bindDN2 "cn=Directory Manager" --bindPassword2 password --replicationPort2 2390 --adminUID admin --adminPassword password --baseDN dc=example,dc=com -X -n -bin/dsreplication initialize --baseDN dc=example,dc=com --adminUID admin --adminPassword password --hostSource localhost --portSource 4444 --hostDestination localhost --portDestination 4445 -X -n -``` - -# Disable replication on server -```bash -bin/dsreplication disable --disableAll --port 4444 --hostname localhost --bindDN "cn=Directory Manager" --adminPassword password --trustAll --no-prompt -``` - -# List all indexes -```bash -bin/backendstat show-index-status --backendID userRoot --baseDN dc=example,dc=com -``` - -# Rebuild Degraded Indexes ONLINE -```bash -bin/rebuild-index --hostname localhost --port 4444 --bindDN "cn=Directory Manager" --bindPassword password --baseDN dc=example,dc=com --rebuildDegraded --trustAll -``` - -# List the available protocols and cipher suites, read the supportedTLSProtocols and supportedTLSCiphers -```bash -bin/ldapsearch --hostname localhost --port 1636 --useSSL --trustAll --baseDN "" --searchScope base "(objectclass=*)" supportedTLSCiphers supportedTLSProtocols -``` - -# Allow only TLSv1.2 ssl-protocol -```bash -#LDAPS / LDAP / HTTP Connection Handlers -bin/dsconfig --hostname localhost --port 4444 --bindDN "cn=Directory Manager" --bindPassword password set-connection-handler-prop --handler-name "LDAPS Connection Handler" --add ssl-protocol:TLSv1.2 --trustAll --no-prompt -#Administration Connector -bin/dsconfig --hostname localhost --port 4444 --bindDN "cn=Directory Manager" --bindPassword password set-administration-connector-prop --add ssl-protocol:TLSv1.2 --trustAll --no-prompt -#Crypto Manager -bin/dsconfig --hostname localhost --port 4444 --bindDN "cn=Directory Manager" --bindPassword password set-crypto-manager-prop --add ssl-protocol:TLSv1.2 --trustAll --no-prompt -``` - -# Use Self Signed Certificate -Create the store with the following command. You'll be asked to enter a password for the .pfx file. -```bash -openssl pkcs12 -export -out opendj.pfx -inkey private.key -in server.crt -certfile cachain.crt -``` -Then when you run the container just set this environment variable with the pfx path and the password. -```bash -OPENDJ_SSL_OPTIONS="--usePkcs12keyStore /data/opendj.pfx --keyStorePassword PASSWORD" -``` - -# Store LDAP catalog data in CASSANDRA noSQL cluster -```bash -export OPENDJ_JAVA_ARGS="-server -Ddatastax-java-driver.basic.contact-points.0=localhost:9042 -Ddatastax-java-driver.basic.load-balancing-policy.local-datacenter=datacenter1" - -#setup without backend -./setup -h localhost -p 1389 --ldapsPort 1636 --adminConnectorPort 4444 --enableStartTLS --generateSelfSignedCertificate --rootUserDN "cn=Directory Manager" --rootUserPassword password --cli --acceptLicense --no-prompt - -#create backend with keyspace: ldap_example_com -bin/dsconfig create-backend \ - --hostname localhost --port 4444 --bindDN "cn=Directory Manager" --bindPassword password \ - --backend-name=userRoot \ - --type cas --set db-directory:ldap_example_com \ - --set base-dn:dc=example,dc=com \ - --set enabled:true \ - --no-prompt --trustAll -``` - -# Store LDAP catalog data in JDBC databse -```bash -#setup without backend -./setup -h localhost -p 1389 --ldapsPort 1636 --adminConnectorPort 4444 --enableStartTLS --generateSelfSignedCertificate --rootUserDN "cn=Directory Manager" --rootUserPassword password --cli --acceptLicense --no-prompt - -#create backend jdbc:postgresql://localhost:5432/database_name?user=postgres&password=password -bin/dsconfig create-backend \ - --hostname localhost --port 4444 --bindDN "cn=Directory Manager" --bindPassword password \ - --backend-name=userRoot \ - --type jdbc --set db-directory:jdbc:postgresql://localhost:5432/database_name?user=postgres\&password=password \ - --set base-dn:dc=example,dc=com \ - --set enabled:true \ - --no-prompt --trustAll -``` - -# Debug instance -```bash -export OPENDJ_JAVA_ARGS="-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=9000" -bin/start-ds -``` - -* [[How to generate test LDIF data and import to LDAP server OpenDJ]] -* [[REST Access to OpenDJ Directory Server]] -* [[How to delegate password reset permissions]] -* [[How to Run OpenDJ based Embedded LDAP in Spring Boot Application]] -* [[How To Run OpenDJ in Kubernetes]] -* [[How to Setup OpenDJ with BCFKS FIPS Key Store Type support]] -* [[TIP: How to Persist OpenDJ Docker Container Data Between Restarts]] -* [[Using a Relational Database as an LDAP Backend]] -* [How to use OpenDJ with JIRA](https://support.atlassian.com/jira/kb/how-to-use-opendj-with-jira/) +<!-- +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]". + +Portions Copyright 2026 3A Systems, LLC. +--> + +# How-To Guides + +The maintained guides are now part of the [OpenDJ documentation](https://doc.openidentityplatform.org/opendj/how-to/). + +* [Find a procedure](https://doc.openidentityplatform.org/opendj/how-to/tasks) — installation, status, backup, replication, indexes, TLS and Docker persistence. +* [How To Run OpenDJ in Kubernetes](https://doc.openidentityplatform.org/opendj/how-to/kubernetes) +* [How to Setup OpenDJ with BCFKS FIPS Key Store Type support](https://doc.openidentityplatform.org/opendj/how-to/bcfks) +* [Using a Relational Database as an LDAP Backend](https://doc.openidentityplatform.org/opendj/how-to/jdbc-backend) +* [How to Run OpenDJ based Embedded LDAP in Spring Boot Application](https://doc.openidentityplatform.org/opendj/how-to/embedded-ldap) +* [REST Access to OpenDJ Directory Server](https://doc.openidentityplatform.org/opendj/how-to/rest-access) +* [How to delegate password reset permissions](https://doc.openidentityplatform.org/opendj/how-to/delegate-password-reset) +* [How to generate test LDIF data and import to LDAP server OpenDJ](https://doc.openidentityplatform.org/opendj/how-to/generate-test-data) +* [TIP: How to Persist OpenDJ Docker Container Data Between Restarts](https://doc.openidentityplatform.org/opendj/install-guide/chap-install#install-docker) +* [Cassandra backend](https://doc.openidentityplatform.org/opendj/how-to/cassandra-backend) +* [Debug a local instance](https://doc.openidentityplatform.org/opendj/how-to/debug-instance) + +Please submit documentation changes to the [OpenDJ repository](https://github.com/OpenIdentityPlatform/OpenDJ/tree/master/opendj-doc-generated-ref/src/main/asciidoc). + +## Former recipe locations + +The headings below retain links into the former collection. + +## Get last version + +See [the maintained procedure](https://doc.openidentityplatform.org/opendj/install-guide/chap-install#command-line-install). + +## Setup server + +See [the maintained procedure](https://doc.openidentityplatform.org/opendj/install-guide/chap-install#command-line-install). + +## Clean and reinstall server + +See [the maintained procedure](https://doc.openidentityplatform.org/opendj/install-guide/chap-uninstall). + +## Check server status + +See [the maintained procedure](https://doc.openidentityplatform.org/opendj/admin-guide/chap-monitoring#monitoring-status-and-tasks). + +## Backup and restore + +See [the maintained procedure](https://doc.openidentityplatform.org/opendj/admin-guide/chap-backup-restore). + +## Initialize replication between two servers + +See [the maintained procedure](https://doc.openidentityplatform.org/opendj/admin-guide/chap-replication). + +## Disable replication on server + +See [the maintained procedure](https://doc.openidentityplatform.org/opendj/admin-guide/chap-replication#stop-repl-permanent). + +## List all indexes + +See [the maintained procedure](https://doc.openidentityplatform.org/opendj/admin-guide/chap-indexing). + +## Rebuild Degraded Indexes ONLINE + +See [the maintained procedure](https://doc.openidentityplatform.org/opendj/admin-guide/chap-indexing#rebuild-degraded-indexes-example). + +## List the available protocols and cipher suites, read the supportedTLSProtocols and supportedTLSCiphers + +See [the maintained procedure](https://doc.openidentityplatform.org/opendj/admin-guide/chap-connection-handlers#tls-protocols-cipher-suites). + +## Allow only TLSv1.2 ssl-protocol + +See [the maintained procedure](https://doc.openidentityplatform.org/opendj/admin-guide/chap-connection-handlers#tls-protocols-cipher-suites). + +## Use Self Signed Certificate + +See [the maintained procedure](https://doc.openidentityplatform.org/opendj/admin-guide/chap-connection-handlers#setup-server-cert). For the Docker image, pass a PKCS#12 file with `OPENDJ_SSL_OPTIONS`; see [the Docker image README](https://github.com/OpenIdentityPlatform/OpenDJ/blob/master/opendj-packages/opendj-docker/README.md). + +## Store LDAP catalog data in CASSANDRA noSQL cluster + +See [the maintained procedure](https://doc.openidentityplatform.org/opendj/how-to/cassandra-backend). + +## Store LDAP catalog data in JDBC databse + +See [the maintained procedure](https://doc.openidentityplatform.org/opendj/how-to/jdbc-backend). + +## Debug instance + +See [the maintained procedure](https://doc.openidentityplatform.org/opendj/how-to/debug-instance). diff --git a/How-to-Run-OpenDJ-based-Embedded-LDAP-in-Spring-Boot-Application.md b/How-to-Run-OpenDJ-based-Embedded-LDAP-in-Spring-Boot-Application.md index 9767e52..c410b1a 100644 --- a/How-to-Run-OpenDJ-based-Embedded-LDAP-in-Spring-Boot-Application.md +++ b/How-to-Run-OpenDJ-based-Embedded-LDAP-in-Spring-Boot-Application.md @@ -1,174 +1,19 @@ -# Introduction +<!-- +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. -In the following article we will setup a Spring Boot application with embedded OpenDJ-based LDAP server. This may be needed for integration testing or for productive use. For example, it could be useful for authentication via LDAP. +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]". -# Create a Project -Create an empty Spring Boot project using the Spring Initializer site or manually. Add the `opendj-embedded` dependency to the `pom.xml` file of the Spring Boot application. +Portions Copyright 2026 3A Systems, LLC. +--> -```xml -<dependency> - <groupId>org.openidentityplatform.opendj</groupId> - <artifactId>opendj-embedded</artifactId> - <version>4.6.4</version> -</dependency> -``` +This guide has moved to [the OpenDJ documentation](https://doc.openidentityplatform.org/opendj/how-to/embedded-ldap). -Add Java 8 compatibility arguments to the project properties - -```xml -<properties> - ... - <jvm.compatibility.args> - --add-exports java.base/sun.security.tools.keytool=ALL-UNNAMED - --add-exports java.base/sun.security.x509=ALL-UNNAMED - </jvm.compatibility.args> -</properties> -``` - -Then add these arguments to `spring-boot-maven-plugin`: - -```xml -<plugin> - <groupId>org.springframework.boot</groupId> - <artifactId>spring-boot-maven-plugin</artifactId> - <configuration> - <jvmArguments>${jvm.compatibility.args}</jvmArguments> - </configuration> -</plugin> -``` - -Add bean Embedded OpenDJ to your Spring Boot application. - -```java -@Bean -public EmbeddedOpenDJ embeddedOpenDJ() { - EmbeddedOpenDJ embeddedOpenDJ = new EmbeddedOpenDJ(); - embeddedOpenDJ.run(); - return embeddedOpenDJ; -} -``` - -In principle, this is all you need to start the embedded OpenDJ. There are still some nuances left. Let's take a look at how to change the default OpenDJ configuration: - -## Change the Default Configuration - -Create a new configuration class inherited from the `org.openidentityplatform.opendj.embedded.Config` class and overload the required properties, such as baseDN and admin password: - -```java -@Configuration -public class OpenDJConfiguration extends Config { - - @Override - @Value("${opendj.basedn:dc=example,dc=openidentityplatform,dc=org}") - public void setBaseDN(String baseDN) { - super.setBaseDN(baseDN); - } - - @Override - @Value("${opendj.adminpwd:passw0rd}") - public void setAdminPassword(String adminPassword) { - super.setAdminPassword(adminPassword); - } -} -``` - -Add the configuration to the bean `EmbeddedOpenDJ` initialization - -```java -@Bean -public EmbeddedOpenDJ embeddedOpenDJ(OpenDJConfiguration configuration) throws IOException, EmbeddedDirectoryServerException { - EmbeddedOpenDJ embeddedOpenDJ = new EmbeddedOpenDJ(configuration); - embeddedOpenDJ.run(); - return embeddedOpenDJ; -} -``` - -## Data Import - -For demonstration purposes, we import the initial ldif data from the string. - -```java -@Bean -public EmbeddedOpenDJ embeddedOpenDJ(OpenDJConfiguration configuration) throws IOException, EmbeddedDirectoryServerException { - EmbeddedOpenDJ embeddedOpenDJ = new EmbeddedOpenDJ(configuration); - embeddedOpenDJ.run(); - String data = """ -dn: dc=example,dc=openidentityplatform,dc=org -objectClass: top -objectClass: domain -dc: example - -dn: ou=people,dc=example,dc=openidentityplatform,dc=org -objectclass: top -objectclass: organizationalUnit -ou: people - -dn: uid=jdoe,ou=people,dc=example,dc=openidentityplatform,dc=org -objectclass: top -objectclass: person -objectclass: organizationalPerson -objectclass: inetOrgPerson -cn: John Doe -sn: John -uid: jdoe -"""; - InputStream inputStream = new ByteArrayInputStream(data.getBytes(StandardCharsets.UTF_8)); - embeddedOpenDJ.importData(inputStream); - return embeddedOpenDJ; -} -``` - -If necessary, you can import data from any `InputStream`, such as a file read stream. - -# Testing - -You can use the `spring-ldap-core` library to test the embedded LDAP functionality - -Add dependencies to the project to run the tests - -```xml -<dependency> - <groupId>org.springframework.boot</groupId> - <artifactId>spring-boot-starter-test</artifactId> - <scope>test</scope> -</dependency> -<dependency> - <groupId>org.springframework.ldap</groupId> - <artifactId>spring-ldap-core</artifactId> - <scope>test</scope> -</dependency> -``` - -Add compatibility options to the `maven-surefire-plugin` - -```xml -<plugin> - <artifactId>maven-surefire-plugin</artifactId> - <configuration> - <argLine>${jvm.compatibility.args}</argLine> - </configuration> -</plugin> -``` - -A simple test that will run a Spring Boot application with built-in OpenDJ authenticate and look for an imported record - -```java -@SpringBootTest -class OpenDJEmbeddedApplicationTest { - @Test - public void test() { - LdapContextSource contextSource = new LdapContextSource(); - contextSource.setUrl("ldap://localhost:1389"); - contextSource.setBase("dc=example,dc=openidentityplatform,dc=org"); - contextSource.setUserDn("cn=Directory Manager"); - contextSource.setPassword("passw0rd"); - contextSource.setPooled(true); - contextSource.afterPropertiesSet(); - - LdapTemplate template = new LdapTemplate(contextSource); - Object user = template.lookup("uid=jdoe,ou=people"); - assertNotNull(user); - } -} -``` \ No newline at end of file +Please submit documentation changes to the [OpenDJ repository](https://github.com/OpenIdentityPlatform/OpenDJ/tree/master/opendj-doc-generated-ref/src/main/asciidoc). diff --git a/How-to-Setup-OpenDJ-with-BCFKS-FIPS-Key-Store-Type-support.md b/How-to-Setup-OpenDJ-with-BCFKS-FIPS-Key-Store-Type-support.md index fd96d9f..d4b5a17 100644 --- a/How-to-Setup-OpenDJ-with-BCFKS-FIPS-Key-Store-Type-support.md +++ b/How-to-Setup-OpenDJ-with-BCFKS-FIPS-Key-Store-Type-support.md @@ -1,84 +1,19 @@ -## 1. Prepare server with DISA STIG profile (RHEL 8.5>) -For example https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html-single/security_hardening/index#assembly_installing-the-system-in-fips-mode_security-hardening +<!-- +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. -Or set OpenDJ system properties for non-strict FIPS mode +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. -Add `org.openidentityplatform.opendj.fips.enabled` to the `OPENDJ_JAVA_ARGS` environment variable: -```bash -export OPENDJ_JAVA_ARGS="... -Dorg.openidentityplatform.opendj.fips.register=true" -``` +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]". +Portions Copyright 2026 3A Systems, LLC. +--> -## 2. Generate BCFKS FIPS compatible keystore -```bash -cat > /tmp/opendj.keystore.pin -Password -EOF -``` +This guide has moved to [the OpenDJ documentation](https://doc.openidentityplatform.org/opendj/how-to/bcfks). -```bash -keytool -genkey -alias server-cert -keyalg rsa -dname "CN=example.com,O=OpenDJ RSA Self-Signed Certificate" \ - -keystore /etc/certs/opendj.bcfks -storetype BCFKS -validity 3650 -providername BCFIPS \ - -provider org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider \ - -providerpath /tmp/libs/bc-fips-1.0.2.3.jar:/tmp/libs/bcpkix-fips-1.0.7.jar \ - -keypass:file /tmp/opendj.keystore.pin -storepass:file /tmp/opendj.keystore.pin \ - -keysize 2048 -sigalg SHA256WITHRSA -``` -```bash -keytool -selfcert -alias server-cert -keystore /etc/certs/opendj.bcfks -storetype BCFKS -validity 3650 \ - -providername BCFIPS -provider org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider \ - -providerpath /tmp/libs/bc-fips-1.0.2.3.jar:/tmp/libs/bcpkix-fips-1.0.7.jar -storepass:file /tmp/opendj.keystore.pin -``` -```bash -keytool -genkey -alias admin-cert -keyalg rsa -dname "CN=example.com,O=Administration Connector RSA Self-Signed Certificate" \ - -keystore /etc/certs/opendj.bcfks -storetype BCFKS -validity 3650 -providername BCFIPS \ - -provider org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider \ - -providerpath /tmp/libs/bc-fips-1.0.2.3.jar:/tmp/libs/bcpkix-fips-1.0.7.jar \ - -keypass:file /tmp/opendj.keystore.pin -storepass:file /tmp/opendj.keystore.pin \ - -keysize 2048 -sigalg SHA256WITHRSA -``` -```bash -keytool -selfcert -alias admin-cert -keystore /etc/certs/opendj.bcfks -storetype BCFKS -validity 3650 \ - -providername BCFIPS -provider org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider \ - -providerpath /tmp/libs/bc-fips-1.0.2.3.jar:/tmp/libs/bcpkix-fips-1.0.7.jar -storepass:file /tmp/opendj.keystore.pin -``` - - Check keystore -```bash -keytool -list -storetype BCFKS -providername BCFIPS -provider org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider -providerpath /tmp/libs/bc-fips-1.0.2.1.jar:/tmp/libs/bcpkix-fips-1.0.5.jar -keystore /etc/certs/opendj.bcfks -storepass:file /tmp/opendj.keystore.pin -Output: -Keystore type: BCFKS -Keystore provider: BCFIPS -admin-cert, Sep 20, 2023, PrivateKeyEntry, -Certificate fingerprint (SHA-256): 0D:62:B3:85:7C:58:27:4F:00:D3:68:DE:83:50:92:C8:DB:5F:0D:81:4D:14:77:47:C6:C2:D2:B1:05:D2:CB:B0 -server-cert, Sep 20, 2023, PrivateKeyEntry, -Certificate fingerprint (SHA-256): B4:BC:55:1F:48:28:43:19:0F:0D:D8:06:F8:53:A5:AE:40:B1:EC:DE:99:0C:E4:F1:2E:F7:3D:56:14:ED:BA:F7 - -``` -Your keystore contains 2 entries - -``` -10:55:35 04/15/22 Running: /opt/opendj/setup --no-prompt --cli --propertiesFilePath /opt/opendj/opendj-setup.properties.bcfks --acceptLicense --doNotStart -``` - -## 3. Prepare OpenDJ setup properties -``` -... -useBcfksKeystore =/etc/certs/opendj.bcfks -keyStorePasswordFile =/tmp/opendj.keystore.pin -... -``` - - - -## 6. Run OpenDJ setup -```bash -/opt/opendj/setup --no-prompt --cli --propertiesFilePath /opt/opendj/opendj-setup.properties.bcfks --acceptLicense --doNotStart -``` - -In order to run OpenDJ tools we need to specify additional parameters: `--trustStorePath /opt/opendj/config/admin-truststore --trustStorePasswordFile /opt/opendj/config/keystore.pin` - -In order to use OpenDJ tools without additional parameters we can import OpenDJ trustore into sysatem PKCS11 trustore -```bash -keytool -importkeystore -destkeystore NONE -deststoretype PKCS11 -deststorepass changeit -srckeystore /opt/opendj/config/truststore -srcstoretype JKS -srcstorepass:file /opt/opendj/config/keystore.pin -noprompt -``` \ No newline at end of file +Please submit documentation changes to the [OpenDJ repository](https://github.com/OpenIdentityPlatform/OpenDJ/tree/master/opendj-doc-generated-ref/src/main/asciidoc). diff --git a/How-to-delegate-password-reset-permissions.md b/How-to-delegate-password-reset-permissions.md index a733a7c..dcb38ff 100644 --- a/How-to-delegate-password-reset-permissions.md +++ b/How-to-delegate-password-reset-permissions.md @@ -1,38 +1,19 @@ -# Insufficient Access Rights: You do not have sufficient privileges to perform password reset operations +<!-- +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. -Some operations require both privileges and also access control instructions. For example, in order to reset user's passwords, an administrator needs both the **password-reset** privilege and also access control to write **userPassword** values on the user entries. +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. -By combining an access control instruction with a privilege, you can effectively restrict the scope of that privilege to a particular branch of the Directory Information Tree. +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]". -```shell -$ bin/ldapmodify --port 1389 --bindDN "cn=Directory Manager" --bindPassword password -dn: uid=admin,ou=write-rest,ou=people,dc=example,dc=com -changetype: modify -add: ds-privilege-name -ds-privilege-name: password-reset +Portions Copyright 2026 3A Systems, LLC. +--> -Processing MODIFY request for -uid=admin,ou=write-rest,ou=people,dc=example,dc=com -MODIFY operation successful for DN -uid=admin,ou=write-rest,ou=people,dc=example,dc=com +This guide has moved to [the OpenDJ documentation](https://doc.openidentityplatform.org/opendj/how-to/delegate-password-reset). -dn: ou=People,dc=example,dc=com -changetype: modify -add: aci -aci: (target="ldap:///ou=People,dc=example,dc=com") (targetattr ="*||+")(version 3.0;acl "Admins"; allow(all) userdn ="ldap:///uid=admin,ou=write-rest,ou=people,dc=example,dc=com";) - -Processing MODIFY request for ou=People,dc=example,dc=com -MODIFY operation successful for DN ou=People,dc=example,dc=com -^C -``` -test **ldappasswordmodify** -```shell -$ bin/ldappasswordmodify --port 1389 --bindDN "uid=admin,ou=write-rest,ou=people,dc=example,dc=com" --bindPassword password --authzID "dn:uid=user.0,ou=People,dc=example,dc=com" --newPassword changeit -The LDAP password modify operation was successful -``` - -test [REST Access to OpenDJ Directory Server](https://github.com/OpenIdentityPlatform/OpenDJ/wiki/REST-Access-to-OpenDJ-Directory-Server) -```shell -$ curl -u "admin:password" --request POST -v -k https://localhost:8443/api/users/user.0?_action=resetPassword -{"generatedPassword":"xvu91dui"} -``` +Please submit documentation changes to the [OpenDJ repository](https://github.com/OpenIdentityPlatform/OpenDJ/tree/master/opendj-doc-generated-ref/src/main/asciidoc). diff --git a/How-to-generate-test-LDIF-data-and-import-to-LDAP-server-OpenDJ.md b/How-to-generate-test-LDIF-data-and-import-to-LDAP-server-OpenDJ.md index 7a4c35f..3b366f7 100644 --- a/How-to-generate-test-LDIF-data-and-import-to-LDAP-server-OpenDJ.md +++ b/How-to-generate-test-LDIF-data-and-import-to-LDAP-server-OpenDJ.md @@ -1,94 +1,19 @@ -```bash -$ export VERSION="$(curl -i -o - --silent https://api.github.com/repos/OpenIdentityPlatform/OpenDJ/releases/latest | grep -m1 "\"name\"" | cut -d\" -f4)" +<!-- +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. -$ echo "last release: $VERSION" -last release: 4.9.2 +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. -$ curl -L https://github.com/OpenIdentityPlatform/OpenDJ/releases/download/$VERSION/opendj-$VERSION.zip --output opendj.zip +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]". - % Total % Received % Xferd Average Speed Time Time Time Current - Dload Upload Total Spent Left Speed - 0 0 0 0 0 0 0 0 --:--:-- --:--:-- --:--:-- 0 -100 72.4M 100 72.4M 0 0 865k 0 0:01:25 0:01:25 --:--:-- 1024k +Portions Copyright 2026 3A Systems, LLC. +--> -$ unzip opendj -Archive: opendj.zip - creating: opendj/ - creating: opendj/QuickSetup.app/ +This guide has moved to [the OpenDJ documentation](https://doc.openidentityplatform.org/opendj/how-to/generate-test-data). -$ cd opendj - -$ bin/makeldif -o test.ldif -c numusers=10000000 template/config/MakeLDIF/example.template -Processed 1000 entries -Processed 2000 entries -Processed 3000 entries -... -Processed 10000000 entries -LDIF processing complete. 10000002 entries written - -$ ./setup --addBaseEntry -h localhost -p 1389 --ldapsPort 1636 --adminConnectorPort 4444 --enableStartTLS --generateSelfSignedCertificate --rootUserDN "cn=Directory Manager" --rootUserPassword password --baseDN dc=example,dc=com --cli --acceptLicense --no-prompt - -Configuring Directory Server ..... Done. -Configuring Certificates ..... Done. -Creating Base Entry dc=example,dc=com ..... Done. -Starting Directory Server ....... Done. - -To see basic server configuration status and configuration, you can launch -/private/tmp/opendj/bin/status - -$ bin/import-ldif --ldifFile test.ldif --backendID=userRoot -h localhost -p 4444 --bindDN "cn=Directory Manager" --bindPassword password --trustAll - -Import task 20250228170246618 scheduled to start immediately -[28/февр./2025:17:02:46 +0300] severity="NOTICE" msgCount=0 msgID=org.opends.messages.backend-413 message="Import task 20250228170246618 started execution" -[28/февр./2025:17:02:46 +0300] severity="NOTICE" msgCount=1 msgID=org.opends.messages.backend-370 message="The backend userRoot is now taken offline" -[28/февр./2025:17:02:46 +0300] severity="NOTICE" msgCount=2 msgID=org.opends.messages.runtime-21 message="Installation Directory: /private/tmp/opendj" -[28/февр./2025:17:02:46 +0300] severity="NOTICE" msgCount=3 msgID=org.opends.messages.runtime-23 message="Instance Directory: /private/tmp/opendj" -[28/февр./2025:17:02:46 +0300] severity="NOTICE" msgCount=4 msgID=org.opends.messages.runtime-17 message="JVM Information: 23 by Homebrew, 64-bit architecture, 2147483648 bytes heap size" -[28/февр./2025:17:02:46 +0300] severity="NOTICE" msgCount=5 msgID=org.opends.messages.runtime-18 message="JVM Host: localhost, running Mac OS X 15.3.1 x86_64, 8589934592 bytes physical memory size, number of processors available 8" -[28/февр./2025:17:02:46 +0300] severity="NOTICE" msgCount=6 msgID=org.opends.messages.runtime-19 message="JVM Arguments: "--add-exports=java.base/sun.security.x509=ALL-UNNAMED", "--add-exports=java.base/sun.security.tools.keytool=ALL-UNNAMED", "--add-opens=java.base/jdk.internal.loader=ALL-UNNAMED", "-Dorg.opends.server.scriptName=start-ds"" -[28/февр./2025:17:02:46 +0300] severity="INFORMATION" msgCount=7 msgID=org.opends.messages.backend-410 message="JE backend 'userRoot' does not specify the number of cleaner threads: defaulting to 8 threads" -[28/февр./2025:17:02:46 +0300] severity="INFORMATION" msgCount=8 msgID=org.opends.messages.backend-411 message="JE backend 'userRoot' does not specify the number of lock tables: defaulting to 17" -[28/февр./2025:17:02:46 +0300] severity="NOTICE" msgCount=9 msgID=org.opends.messages.backend-533 message="OpenDJ Server 4.9.2 starting import (build 20250204155540, R2fa7a955ea1b9132f6bcfcce18f2979b31085734)" -[28/февр./2025:17:02:46 +0300] severity="NOTICE" msgCount=10 msgID=org.opends.messages.backend-528 message="The amount of free memory available to the import task is 1932735283 bytes. The number of phase one buffers required is 160 buffers" -[28/февр./2025:17:02:46 +0300] severity="NOTICE" msgCount=11 msgID=org.opends.messages.backend-520 message="Setting DB cache size to 33554432 bytes and phase one buffer size to 3623878 bytes" -[28/февр./2025:17:02:47 +0300] severity="NOTICE" msgCount=12 msgID=org.opends.messages.backend-534 message="Import Thread Count: 4 threads" -[28/февр./2025:17:10:59 +0300] severity="NOTICE" msgCount=13 msgID=org.opends.messages.backend-531 message="Total import time was 489 seconds. Phase one processing completed in 345 seconds, phase two processing completed in 144 seconds" -[28/февр./2025:17:10:59 +0300] severity="NOTICE" msgCount=14 msgID=org.opends.messages.backend-519 message="Processed 10000002 entries, imported 10000002, skipped 0, rejected 0 and migrated 0 in 492 seconds (average rate 20285,8/sec)" -[28/февр./2025:17:10:59 +0300] severity="NOTICE" msgCount=15 msgID=org.opends.messages.backend-526 message="Import LDIF environment close took 0 seconds" -[28/февр./2025:17:10:59 +0300] severity="NOTICE" msgCount=16 msgID=org.opends.messages.backend-518 message="Flushing data to disk" -[28/февр./2025:17:10:59 +0300] severity="INFORMATION" msgCount=17 msgID=org.opends.messages.backend-410 message="JE backend 'userRoot' does not specify the number of cleaner threads: defaulting to 8 threads" -[28/февр./2025:17:10:59 +0300] severity="INFORMATION" msgCount=18 msgID=org.opends.messages.backend-411 message="JE backend 'userRoot' does not specify the number of lock tables: defaulting to 17" -[28/февр./2025:17:11:00 +0300] severity="NOTICE" msgCount=19 msgID=org.opends.messages.backend-513 message="The database backend userRoot containing 10000002 entries has started" -[28/февр./2025:17:11:00 +0300] severity="NOTICE" msgCount=20 msgID=org.opends.messages.backend-414 message="Import task 20250228170246618 finished execution in the state Completed successfully" -Import task 20250228170246618 has been successfully completed - -$ bin/status --bindDN "cn=Directory Manager" --bindPassword password - - --- Server Status --- -Server Run Status: Started -Open Connections: 1 - - --- Server Details --- -Host Name: MacBook-Pro-Harseko.local -Administrative Users: cn=Directory Manager -Installation Path: /private/tmp/opendj -Version: OpenDJ Server 4.9.2 -Java Version: 23 -Administration Connector: Port 4444 (LDAPS) - - --- Connection Handlers --- -Address:Port : Protocol : State --------------:------------------------:--------- --- : LDIF : Disabled -0.0.0.0:161 : SNMP : Disabled -0.0.0.0:1389 : LDAP (allows StartTLS) : Enabled -0.0.0.0:1636 : LDAPS : Enabled -0.0.0.0:1689 : JMX : Disabled -0.0.0.0:8080 : HTTP : Disabled - - --- Data Sources --- -Base DN: dc=example,dc=com -Backend ID: userRoot -Entries: 10000002 -Replication: -``` \ No newline at end of file +Please submit documentation changes to the [OpenDJ repository](https://github.com/OpenIdentityPlatform/OpenDJ/tree/master/opendj-doc-generated-ref/src/main/asciidoc). diff --git a/REST-Access-to-OpenDJ-Directory-Server.md b/REST-Access-to-OpenDJ-Directory-Server.md index 63de688..f251e94 100644 --- a/REST-Access-to-OpenDJ-Directory-Server.md +++ b/REST-Access-to-OpenDJ-Directory-Server.md @@ -1,150 +1,19 @@ -# Check Java 1.8+ requirement +<!-- +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. -```shell -$ java -version +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. -openjdk version "22.0.1" 2024-04-16 -OpenJDK Runtime Environment Homebrew (build 22.0.1) -OpenJDK 64-Bit Server VM Homebrew (build 22.0.1, mixed mode, sharing) -``` +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]". -# Get the Latest Version of the OpenDJ LDAP Server +Portions Copyright 2026 3A Systems, LLC. +--> -```shell -$ cd /tmp +This guide has moved to [the OpenDJ documentation](https://doc.openidentityplatform.org/opendj/how-to/rest-access). -$ export VERSION="$(curl -i -o - --silent https://api.github.com/repos/OpenIdentityPlatform/OpenDJ/releases/latest | grep -m1 "\"name\"" | cut -d\" -f4)" && echo "last release: $VERSION" - -last release: 4.6.4 - -$ curl -L https://github.com/OpenIdentityPlatform/OpenDJ/releases/download/$VERSION/opendj-$VERSION.zip --output opendj.zip - - % Total % Received % Xferd Average Speed Time Time Time Current - Dload Upload Total Spent Left Speed - 0 0 0 0 0 0 0 0 --:--:-- --:--:-- --:--:-- 0 -100 59.7M 100 59.7M 0 0 6770k 0 0:00:09 0:00:09 --:--:-- 8013k - -$ unzip opendj && cd opendj - -... - inflating: opendj/template/config/wordlist.txt -``` - -# Setup Server With a Sample Data - -```shell -$ ./setup --sampleData 1000 -h localhost -p 1389 --ldapsPort 1636 --adminConnectorPort 4444 --enableStartTLS --generateSelfSignedCertificate --rootUserDN "cn=Directory Manager" --rootUserPassword password --baseDN dc=example,dc=com --cli --acceptLicense --no-prompt - -Configuring Directory Server ..... Done. -Configuring Certificates ..... Done. -Importing Automatically-Generated Data (1000 Entries) ....... Done. -Starting Directory Server ....... Done. - -To see basic server configuration status and configuration, you can launch -/private/tmp/opendj/bin/status - -``` - -# Enable the REST HTTP Connection Handler - -```shell -$ bin/dsconfig set-connection-handler-prop --hostname localhost --port 4444 --bindDN "cn=Directory Manager" --bindPassword password --handler-name "HTTP Connection Handler" --set enabled:true --no-prompt --trustAll -``` - -# List http-authorization-mechanisms - -```shell -$ bin/dsconfig list-http-authorization-mechanisms --hostname localhost --port 4444 --bindDN "cn=Directory Manager" --bindPassword password --trustAll - -HTTP Authorization Mechanism : Type -------------------------------------------:-------------------------------------------------------- -HTTP Anonymous : http-anonymous-authorization-mechanism -HTTP Basic : http-basic-authorization-mechanism -HTTP OAuth2 CTS : http-oauth2-cts-authorization-mechanism -HTTP OAuth2 File : http-oauth2-file-authorization-mechanism -HTTP OAuth2 OpenAM : http-oauth2-openam-authorization-mechanism -HTTP OAuth2 Token Introspection (RFC7662) : http-oauth2-token-introspection-authorization-mechanism -``` - -# List http-endpoints - -```shell -$ bin/dsconfig list-http-endpoints --hostname localhost --port 4444 --bindDN "cn=Directory Manager" --bindPassword password --trustAll - - -HTTP Endpoint : Type : enabled ---------------:--------------------:-------- -/admin : admin-endpoint : true -/api : rest2ldap-endpoint : true -``` - -# Enable the File-Based HTTP Access Logger - -```shell -$ bin/dsconfig set-log-publisher-prop --hostname localhost --port 4444 --bindDN "cn=Directory Manager" --bindPassword password --publisher-name "File-Based HTTP Access Logger" --set enabled:true --no-prompt --trustAll -``` - -# Create a User With Read/Write Permissions - -```shell -$ bin/ldapmodify --port 1389 --bindDN "cn=Directory Manager" --bindPassword password - -dn: ou=write-rest,ou=people,dc=example,dc=com -objectClass: top -objectClass: organizationalUnit -ou: write-rest -description: REST administrators - -Processing ADD request for ou=write-rest,ou=people,dc=example,dc=com -ADD operation successful for DN ou=write-rest,ou=people,dc=example,dc=com - -dn: uid=admin,ou=write-rest,ou=people,dc=example,dc=com -objectClass: top -objectClass: inetOrgPerson -objectClass: organizationalPerson -objectClass: person -cn: admin -uid: admin -sn: admin -description: REST admin -userPassword: password - -Processing ADD request for uid=admin,ou=write-rest,ou=people,dc=example,dc=com -ADD operation successful for DN -uid=admin,ou=write-rest,ou=people,dc=example,dc=com - - -^C - -``` - -# Test Reading Other Users - -```shell -$ curl -u "admin:password" http://localhost:8080/api/users/user.0?_prettyPrint=true -{ - "_id" : "user.0", - "_rev" : "00000000595bb0ca", - "_schema" : "frapi:opendj:rest2ldap:user:1.0", - "_meta" : { }, - "userName" : "user.0@maildomain.net", - "displayName" : [ "Aaccf Amar" ], - "name" : { - "givenName" : "Aaccf", - "familyName" : "Amar" - }, - "description" : "This is the description for Aaccf Amar.", - "contactInformation" : { - "telephoneNumber" : "+1 685 622 6202", - "emailAddress" : "user.0@maildomain.net" - } - -``` - -For more info about REST operations see [Performing RESTful Operations](https://doc.openidentityplatform.org/opendj/server-dev-guide/chap-rest-operations). - -To change the configuration modify the default file [config/rest2ldap/endpoints/api/example-v1.json](https://github.com/OpenIdentityPlatform/OpenDJ/blob/master/opendj-server-legacy/resource/config/rest2ldap/endpoints/api/example-v1.json) - -[Set User Password via REST API in OpenDJ](https://github.com/OpenIdentityPlatform/OpenDJ/discussions/355) - -[[How to delegate password reset permissions]] \ No newline at end of file +Please submit documentation changes to the [OpenDJ repository](https://github.com/OpenIdentityPlatform/OpenDJ/tree/master/opendj-doc-generated-ref/src/main/asciidoc). diff --git a/TIP:-How-to-Persist-OpenDJ-Docker-Container-Data-Between-Restarts.md b/TIP:-How-to-Persist-OpenDJ-Docker-Container-Data-Between-Restarts.md index b1ef15f..ac0ee0e 100644 --- a/TIP:-How-to-Persist-OpenDJ-Docker-Container-Data-Between-Restarts.md +++ b/TIP:-How-to-Persist-OpenDJ-Docker-Container-Data-Between-Restarts.md @@ -1,23 +1,19 @@ -If you want persist the OpenDJ configuration data, you need to specify a volume that maps `/opt/opendj/data` container directory to a local directory. Example with `docker-compose.yaml` +<!-- +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. -```yaml -services: - opendj: - image: openidentityplatform/opendj:latest - ports: - - 1389:1389 - - 1636:1636 - - 4444:4444 - volumes: - - ./opendj-data:/opt/opendj/data -``` +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. -With `docker run` command: +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]". -``` -docker run -h ldap-01.domain.com \ - -p 1389:1389 -p 1636:1636 -p 4444:4444 \ - --name ldap-01 \ - -v ./opendj-data:/opt/opendj/data \ - openidentityplatform/opendj -``` +Portions Copyright 2026 3A Systems, LLC. +--> + +This guide has moved to [the OpenDJ documentation](https://doc.openidentityplatform.org/opendj/install-guide/chap-install#install-docker). + +Please submit documentation changes to the [OpenDJ repository](https://github.com/OpenIdentityPlatform/OpenDJ/tree/master/opendj-doc-generated-ref/src/main/asciidoc). diff --git a/Using-a-Relational-Database-as-an-LDAP-Backend.md b/Using-a-Relational-Database-as-an-LDAP-Backend.md index 3871bfa..1e9aff2 100644 --- a/Using-a-Relational-Database-as-an-LDAP-Backend.md +++ b/Using-a-Relational-Database-as-an-LDAP-Backend.md @@ -1,159 +1,19 @@ -# Preparation +<!-- +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. -First, you must have Java at least 1.8 installed and Docker installed. Run the PostgreSQL Docker image with the following command: +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. -``` -docker run -it -d -p 5432:5432 -e POSTGRES_DB=database_name -e POSTGRES_PASSWORD=password --name postgres postgres -``` -Download the latest OpenDJ version from the GitHub using the following commands: -``` -export VERSION="$(curl -i -o - --silent https://api.github.com/repos/OpenIdentityPlatform/OpenDJ/releases/latest | grep -m1 "\"name\"" | cut -d\" -f4)" -echo "last release: $VERSION" -curl -L https://github.com/OpenIdentityPlatform/OpenDJ/releases/download/$VERSION/opendj-$VERSION.zip --output opendj.zip -``` +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]". -Or manually from your browser [https://github.com/OpenIdentityPlatform/OpenDJ/releases](https://github.com/OpenIdentityPlatform/OpenDJ/releases). +Portions Copyright 2026 3A Systems, LLC. +--> +This guide has moved to [the OpenDJ documentation](https://doc.openidentityplatform.org/opendj/how-to/jdbc-backend). -Unzip the distribution - -``` -unzip opendj.zip -``` - -Run the OpenDJ setup command - -``` -./opendj/setup -h localhost -p 1389 --ldapsPort 1636 --adminConnectorPort 4444 --enableStartTLS --generateSelfSignedCertificate --rootUserDN "cn=Directory Manager" --rootUserPassword password --cli --acceptLicense --no-prompt - -Configuring Directory Server ..... Done. -Configuring Certificates ..... Done. -Starting Directory Server ....... Done. - -To see basic server configuration status and configuration, you can launch -/home/user/opendj-postgres/opendj/bin/status -``` - -Pay attention to the parameters `rootUserDN` and `rootUserPassword`. Here are the parameters for connecting to OpenDJ with administrative rights. - -Check the OpenDJ status - -``` -./opendj/bin/status --bindDN "cn=Directory Manager" --bindPassword password - - --- Server Status --- -Server Run Status: Started -Open Connections: 1 - - --- Server Details --- -Host Name: MacBook-Pro-Maxim.local -Administrative Users: cn=Directory Manager -Installation Path: -/home/user/opendj-postgres/opendj -Version: OpenDJ Server 4.9.0 -Java Version: 21.0.2 -Administration Connector: Port 4444 (LDAPS) - - --- Connection Handlers --- -Address:Port : Protocol : State --------------:------------------------:--------- --- : LDIF : Disabled -0.0.0.0:161 : SNMP : Disabled -0.0.0.0:1389 : LDAP (allows StartTLS) : Enabled -0.0.0.0:1636 : LDAPS : Enabled -0.0.0.0:1689 : JMX : Disabled -0.0.0.0:8080 : HTTP : Disabled - - --- Data Sources --- --No LDAP Databases Found- -``` - -As you can see from the output of the command, the LDAP database has not yet been created. - -# OpenDJ Setup - -Create OpenDJ backend using PostgreSQL database - -``` -./opendj/bin/dsconfig create-backend -h localhost -p 4444 --bindDN "cn=Directory Manager" --bindPassword password --backend-name=userRoot --type jdbc --set base-dn:dc=example,dc=com --set 'db-directory:jdbc:postgresql://localhost:5432/database_name?user=postgres&password=password' --set enabled:true --no-prompt --trustAll -``` - - -Note the arguments `--type`, which must be set to `jdbc` to use a relational database, and `--set` `'db-directory:jdbc:...'`, a string for connecting to a JDBC-compliant data source. - -> The DBMS can be almost any database for which there is a JDBC-compatible driver. For example, you can use MySQL, MS SQL Server, and so on. To use a JDBC-compatible database, you need to download the appropriate driver and copy it to the `./opendj/lib` directory and modify the connection string to the JDBC source in the `--set` argument. Example connection string for MySQL: `db-directory:jdbc:mysql://mysqlhost:3306/database_name?user=mysql&password=password`. For more details, refer to the the documentation for the corresponding driver - - -You can read more about the parameters of the `dsconfig create-backend` command at the following link - -[https://doc.openidentityplatform.org/opendj/reference/dsconfig-subcommands-ref#dsconfig-create-backend](https://doc.openidentityplatform.org/opendj/reference/dsconfig-subcommands-ref#dsconfig-create-backend). - -# Test the Solution - -For demonstration purposes, create and load test data in OpenDJ - -Create ldif file with test data from the template: - -``` -./opendj/bin/makeldif -o /tmp/test.ldif -c suffix=dc=example,dc=com ./opendj/config/MakeLDIF/example.template -Processed 1000 entries -Processed 2000 entries -Processed 3000 entries -Processed 4000 entries -Processed 5000 entries -Processed 6000 entries -Processed 7000 entries -Processed 8000 entries -Processed 9000 entries -Processed 10000 entries -LDIF processing complete. 10002 entries written -``` - -Load ldif file into OpenDJ - -``` -./opendj/bin/ldapmodify --hostname localhost --port 1636 --bindDN "cn=Directory Manager" --bindPassword password --useSsl --trustAll -f /tmp/test.ldif -a -Processing ADD request for dc=example,dc=com -ADD operation successful for DN dc=example,dc=com -Processing ADD request for ou=People,dc=example,dc=com -ADD operation successful for DN ou=People,dc=example,dc=com -Processing ADD request for uid=user.0,ou=People,dc=example,dc=com -ADD operation successful for DN uid=user.0,ou=People,dc=example,dc=com -Processing ADD request for uid=user.1,ou=People,dc=example,dc=com -ADD operation successful for DN uid=user.1,ou=People,dc=example,dc=com -Processing ADD request for uid=user.2,ou=People,dc=example,dc=com -ADD operation successful for DN uid=user.2,ou=People,dc=example,dc=com -.... -Processing ADD request for uid=user.9998,ou=People,dc=example,dc=com -ADD operation successful for DN uid=user.9998,ou=People,dc=example,dc=com -Processing ADD request for uid=user.9999,ou=People,dc=example,dc=com -ADD operation successful for DN uid=user.9999,ou=People,dc=example,dc=com -``` - -Check the loaded data in OpenDJ: - -``` -./opendj/bin/ldapsearch --hostname localhost --port 1389 --bindDN "cn=Directory Manager" --bindPassword password --baseDN "ou=People,dc=example,dc=com" -s one -a always -z 3 "(objectClass=*)" "hasSubordinates" "objectClass" -dn: uid=user.0,ou=People,dc=example,dc=com -hasSubordinates: false -objectClass: inetOrgPerson -objectClass: organizationalPerson -objectClass: person -objectClass: top - -dn: uid=user.1,ou=People,dc=example,dc=com -hasSubordinates: false -objectClass: inetOrgPerson -objectClass: organizationalPerson -objectClass: person -objectClass: top - -dn: uid=user.10,ou=People,dc=example,dc=com -hasSubordinates: false -objectClass: inetOrgPerson -objectClass: organizationalPerson -objectClass: person -objectClass: top - -... -``` \ No newline at end of file +Please submit documentation changes to the [OpenDJ repository](https://github.com/OpenIdentityPlatform/OpenDJ/tree/master/opendj-doc-generated-ref/src/main/asciidoc). opendj-embedded/pom.xml
@@ -68,6 +68,8 @@ <artifactId>maven-surefire-plugin</artifactId> <version>3.2.5</version> <configuration> <!-- Exercise the documented embedded startup without module-opening flags. --> <argLine>-Xmx512m -Dorg.bouncycastle.native.cpu_variant=java</argLine> <properties> <property> <name>usedefaultlisteners</name>
