mirror of https://github.com/OpenIdentityPlatform/OpenDJ.git

Valery Kharseko
8 hours ago dd0cbf71a166a384baa2dbae5717c5a2e61b7515
Document LDAP alias dereferencing in the administration guide (#1322)

## Summary

- Add an Administration Guide chapter on LDAP alias dereferencing. It
covers all four search policies and includes LDIF and `ldapsearch`
examples.
- Explain how OpenDJ applies the filter and scope to aliases found below
the search base. The one-level example shows the results of
`(objectClass=person)` and `(cn=Support)`, and the policy section
explains how to search the target's subtree.
- Use the Antora title and anchor pattern from #1321. After rebasing
onto `master`, `AntoraPageTitlesIT` covers both the alias dereferencing
and Subordinate Backends chapters.

## Validation

- Exercised all four policies on OpenDJ 5.2.1-SNAPSHOT. Verified both
one-level filter results and confirmed when a subtree search includes
descendants of the alias target.
- Passed 26 Asciidoctor extension tests and 12 `AntoraPageTitlesIT`
cases. Checked 646 cross-guide references across 78 pages.
- Verified the chapter title and anchors in the combined Administration
Guide during the initial documentation check.
2 files modified
1 files added
140 ■■■■■ changed files
opendj-doc-generated-ref/src/main/asciidoc/admin-guide/chap-alias-dereferencing.adoc 134 ●●●●● patch | view | raw | blame | history
opendj-doc-generated-ref/src/main/asciidoc/admin-guide/index.adoc 1 ●●●●● patch | view | raw | blame | history
opendj-doc-generated-ref/src/test/java/org/openidentityplatform/opendj/doc/AntoraPageTitlesIT.java 5 ●●●●● patch | view | raw | blame | history
opendj-doc-generated-ref/src/main/asciidoc/admin-guide/chap-alias-dereferencing.adoc
New file
@@ -0,0 +1,134 @@
////
The contents of this file are subject to the terms of the Common Development and
Distribution License (the License). You may not use this file except in compliance with the
License.
You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the
specific language governing permission and limitations under the License.
When distributing Covered Software, include this CDDL Header Notice in each file and include
the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL
Header, with the fields enclosed by brackets [] replaced by your own identifying
information: "Portions copyright [year] [name of copyright owner]".
Copyright 2026 3A Systems, LLC.
////
:table-caption!:
ifndef::env-site[]
[#chap-alias-dereferencing]
endif::[]
== Dereferencing LDAP Aliases in Searches
ifdef::env-site[]
anchor:chap-alias-dereferencing[]
endif::[]
An LDAP alias is an entry of object class `alias`. Its `aliasedObjectName` attribute holds the DN of another entry. An alias can give applications a stable DN for a target that moves, as long as you keep `aliasedObjectName` up to date. A search that dereferences the alias returns the target under the target's own DN.
[#alias-dereferencing-policies]
=== Search Dereferencing Policies
The client sets the dereferencing policy for each LDAP search request. In OpenDJ's `ldapsearch`, use `-a` or `--dereferencePolicy`. See xref:../reference/admin-tools-ref.adoc#ldapsearch-1[ldapsearch(1)] and https://datatracker.ietf.org/doc/html/rfc4511#section-4.5.1.3[RFC 4511, Section 4.5.1.3].
[cols="1,2,2",options="header"]
|===
| Policy
| Alias at the search base DN
| Aliases found below the search base
| `never` (default)
| Keep the alias as the base.
| Return matching alias entries as stored.
| `find`
| Start the search at the target.
| Return matching alias entries as stored.
| `search`
| For scope `sub`, start the search at the target. For scopes `base` and `one`, keep the alias as the base.
| Dereference matching alias entries.
| `always`
| Start the search at the target.
| Dereference matching alias entries.
|===
When OpenDJ dereferences the search base, it searches from the target using the requested scope and filter.
For aliases below the search base, OpenDJ applies the search filter to the alias before dereferencing it. OpenDJ can return the target entry even if it fails the filter or lies outside the original search scope. Dereferencing each matching alias returns only the target entry, even with scope `sub`.
To search the target's subtree through an alias, use the alias DN as the base with scope `sub` and policy `find` or `always`.
[#alias-dereferencing-example]
=== Create and Search an Alias
On a test server with an existing `dc=example,dc=com` base entry, save the following entries in `aliases.ldif`. The example uses `extensibleObject` to allow `cn` as the alias entry's naming attribute.
[source,ldif]
----
dn: cn=Alice Example,dc=example,dc=com
objectClass: top
objectClass: person
cn: Alice Example
sn: Example
dn: ou=Aliases,dc=example,dc=com
objectClass: top
objectClass: organizationalUnit
ou: Aliases
dn: cn=Support,ou=Aliases,dc=example,dc=com
objectClass: top
objectClass: alias
objectClass: extensibleObject
cn: Support
aliasedObjectName: cn=Alice Example,dc=example,dc=com
----
Add the entries with `ldapmodify`. Adjust the port and password file for your test instance.
[source,bash]
----
bin/ldapmodify --hostname localhost --port 1389 \
  --bindDN 'cn=Directory Manager' --bindPasswordFile /path/to/dm-password \
  -a aliases.ldif
----
Read the alias entry itself with a base search using `never`. The result contains `dn: cn=Support,ou=Aliases,dc=example,dc=com` and its `aliasedObjectName` value.
[source,bash]
----
bin/ldapsearch --hostname localhost --port 1389 \
  --bindDN 'cn=Directory Manager' --bindPasswordFile /path/to/dm-password \
  --baseDN 'cn=Support,ou=Aliases,dc=example,dc=com' --searchScope base \
  --dereferencePolicy never '(objectClass=*)' aliasedObjectName
----
Change the policy to `find` to read the target entry. This search returns `dn: cn=Alice Example,dc=example,dc=com` and its `cn` value.
[source,bash]
----
bin/ldapsearch --hostname localhost --port 1389 \
  --bindDN 'cn=Directory Manager' --bindPasswordFile /path/to/dm-password \
  --baseDN 'cn=Support,ou=Aliases,dc=example,dc=com' --searchScope base \
  --dereferencePolicy find '(objectClass=*)' cn
----
Use `search` to dereference an alias found below a regular base entry. The following one-level search starts at `ou=Aliases` and returns Alice's entry, which is stored outside that branch.
[source,bash]
----
bin/ldapsearch --hostname localhost --port 1389 \
  --bindDN 'cn=Directory Manager' --bindPasswordFile /path/to/dm-password \
  --baseDN 'ou=Aliases,dc=example,dc=com' --searchScope one \
  --dereferencePolicy search '(objectClass=*)' cn
----
With the same base and scope, changing the filter to `(objectClass=person)` returns no entries because Support is an alias. Changing it to `(cn=Support)` matches the alias and returns Alice's entry.
[#alias-dereferencing-troubleshooting]
=== Check Alias Targets
If a search omits an expected target, read the alias with `--dereferencePolicy never` and look up its `aliasedObjectName` DN directly. OpenDJ skips an alias found below the search base when the target is missing. If a target is renamed or moved, verify that the alias points to its current DN. Repeat the search using the application's bind identity to check what it can read.
opendj-doc-generated-ref/src/main/asciidoc/admin-guide/index.adoc
@@ -32,6 +32,7 @@
include::./preface.adoc[]
include::./chap-understanding-ldap.adoc[]
include::./chap-admin-tools.adoc[]
include::./chap-alias-dereferencing.adoc[]
include::./chap-server-process.adoc[]
include::./chap-import-export.adoc[]
include::./chap-subordinate-backends.adoc[]
opendj-doc-generated-ref/src/test/java/org/openidentityplatform/opendj/doc/AntoraPageTitlesIT.java
@@ -69,7 +69,10 @@
                             "_restart_and_remove_the_sample_data", "_next_steps" } },
            { "admin-guide", "chap-subordinate-backends", "Subordinate Backends",
              new String[] { "chap-subordinate-backends", "subordinate-backends-uses", "subordinate-backends-create",
                             "subordinate-backends-migrate", "subordinate-backends-operations" } }
                             "subordinate-backends-migrate", "subordinate-backends-operations" } },
            { "admin-guide", "chap-alias-dereferencing", "Dereferencing LDAP Aliases in Searches",
              new String[] { "chap-alias-dereferencing", "alias-dereferencing-policies",
                             "alias-dereferencing-example", "alias-dereferencing-troubleshooting" } }
        };
    }