Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update documentation issues and update links #470

Merged
merged 1 commit into from
Jan 31, 2025
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@
information: "Portions copyright [year] [name of copyright owner]".

Copyright 2017 ForgeRock AS.
Portions Copyright 2024 3A Systems LLC.
Portions Copyright 2024-2025 3A Systems LLC.
////
:figure-caption!:
Expand Down Expand Up @@ -1251,7 +1251,8 @@ When more than one authentication mechanism is specified, mechanisms are applied
There are many possibilities when configuring HTTP authorization mechanisms. __This procedure shows only one OAuth 2.0 example.__
The example that follows demonstrates an OpenDJ directory server configured for tests (insecure connections) to request OAuth 2.0 token information from OpenAM. Download ForgeRock Access Management or OpenAM software from link:https://backstage.forgerock.com/downloads/[https://backstage.forgerock.com/downloads/, window=\_top].
The example that follows demonstrates an OpenDJ directory server configured for tests (insecure connections) to request OAuth 2.0 token information from OpenAM.
Download OpenAM software from link:https://github.com/OpenIdentityPlatform/OpenAM/releases[https://github.com/OpenIdentityPlatform/OpenAM/releases, window=\_top].
[#d67723e3953]
.Settings for OAuth 2.0 Example With OpenAM
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@
information: "Portions copyright [year] [name of copyright owner]".

Copyright 2017 ForgeRock AS.
Portions Copyright 2024 3A Systems LLC.
Portions Copyright 2024-2025 3A Systems LLC.
////

:figure-caption!:
Expand Down Expand Up @@ -40,7 +40,7 @@ OpenDJ control panel provides basic monitoring capabilities under Monitoring > G

OpenDJ exposes monitoring information over LDAP under the entry `cn=monitor`. Many different types of information are exposed. The following example shows monitoring information about the `userRoot` backend holding Example.com data:

Interface stability: Evolving (See xref:../reference/appendix-interface-stability.adoc#interface-stability["ForgeRock Product Interface Stability"] in the __Reference__)
Interface stability: Evolving (See xref:../reference/appendix-interface-stability.adoc#interface-stability["Product Interface Stability"] in the __Reference__)

[source, console]
----
Expand Down Expand Up @@ -163,7 +163,7 @@ SNMPv2-SMI::mib-2.66.1.1.2.1 = STRING: "/path/to/opendj"

OpenDJ provides JMX-based monitoring. A number of tools support JMX, including `jconsole` and `jvisualvm`, which are bundled with the Sun/Oracle Java platform. JMX is not configured by default. Use the `dsconfig` command to configure the JMX connection handler:

Interface stability: Evolving (See xref:../reference/appendix-interface-stability.adoc#interface-stability["ForgeRock Product Interface Stability"] in the __Reference__)
Interface stability: Evolving (See xref:../reference/appendix-interface-stability.adoc#interface-stability["Product Interface Stability"] in the __Reference__)

Configure the server to activate JMX access. The following example uses the reserved port number, 1689:

Expand Down Expand Up @@ -301,7 +301,7 @@ example-20110623030000000 Backup Waiting on start time

By default OpenDJ stores access and errors logs, and a server process ID file under the `logs/` directory. For the replication service, OpenDJ also keeps a replication log there. You can also configure a debug log. You can also configure policies about how logs are rotated, and how they are retained. You configure logging using the `dsconfig` command.

Each log depends on a __log publisher__, whose type corresponds to the type of log. OpenDJ provides a number of file-based log publishers out of the box, and supports the ForgeRock common audit event framework, sometimes referred to as Common Audit. The ForgeRock common audit event framework provides log handlers for publishing to CSV files, relational databases, and the UNIX system log (Syslog) as described in xref:#log-common-audit["Common ForgeRock Access Logs"]. The framework makes it possible to plug in additional handlers as well.
Each log depends on a __log publisher__, whose type corresponds to the type of log. OpenDJ provides a number of file-based log publishers out of the box, and supports the Open Identity Platform common audit event framework, sometimes referred to as Common Audit. The ForgeRock common audit event framework provides log handlers for publishing to CSV files, relational databases, and the UNIX system log (Syslog) as described in xref:#log-common-audit["Common ForgeRock Access Logs"]. The framework makes it possible to plug in additional handlers as well.

[#log-access]
==== Access Logs
Expand All @@ -325,14 +325,14 @@ Notice that by default OpenDJ directory server logs a message for the search req


[#log-common-audit]
==== Common ForgeRock Access Logs
==== Common Open Identity Platform Access Logs

In addition to the default file-based access log formats, OpenDJ directory server supports the ForgeRock common audit event framework. OpenDJ uses the framework to write access logs in formats that are compatible with all products using the framework. The framework uses transaction IDs that make it easy to correlate requests as they traverse the platform. This makes it easier to monitor activity and to enrich reports.
In addition to the default file-based access log formats, OpenDJ directory server supports the Open Identity Platform common audit event framework. OpenDJ uses the framework to write access logs in formats that are compatible with all products using the framework. The framework uses transaction IDs that make it easy to correlate requests as they traverse the platform. This makes it easier to monitor activity and to enrich reports.

Interface stability: Evolving (See xref:../reference/appendix-interface-stability.adoc#interface-stability["ForgeRock Product Interface Stability"] in the __Reference__)
Interface stability: Evolving (See xref:../reference/appendix-interface-stability.adoc#interface-stability["Product Interface Stability"] in the __Reference__)

The ForgeRock common audit event framework is built around audit event handlers. Audit event handlers can encapsulate their own configurations. Audit event handlers are the same in each product in the ForgeRock platform. As a result, you can plug in custom handlers that comply with the framework without having to upgrade OpenDJ directory server.
The ForgeRock common audit event framework includes handlers for logging audit event messages to local files and facilities, as well as to remote systems. Handlers for the following are supported:
The Open Identity Platform common audit event framework is built around audit event handlers. Audit event handlers can encapsulate their own configurations. Audit event handlers are the same in each product in the Open Identity Platform. As a result, you can plug in custom handlers that comply with the framework without having to upgrade OpenDJ directory server.
The Open Identity Platform common audit event framework includes handlers for logging audit event messages to local files and facilities, as well as to remote systems. Handlers for the following are supported:

* CSV files, with support for tamper-evident logs.
+
Expand All @@ -350,7 +350,7 @@ You configure the JDBC handler as an external log publisher that logs access mes
+
Although it is rarely used for access events, you can configure the Syslog handler as an external log publisher that logs access messages to the UNIX Syslog facility.

The ForgeRock common audit event framework supports a variety of audit event topics. OpenDJ currently supports handling for access events, which are system boundary events such as the initial request and final response to that request. In other words, the implementation in OpenDJ is focused only on access logging. Based on the connection handler for the request, OpenDJ divides access events into `ldap-access` events and `http-access` events.
The Open Identity Platform common audit event framework supports a variety of audit event topics. OpenDJ currently supports handling for access events, which are system boundary events such as the initial request and final response to that request. In other words, the implementation in OpenDJ is focused only on access logging. Based on the connection handler for the request, OpenDJ divides access events into `ldap-access` events and `http-access` events.
To enable common audit-based logging, follow one of these procedures:

* xref:#log-common-audit-ldap-csv["To Enable LDAP CSV Access Logs"]
Expand Down Expand Up @@ -692,7 +692,7 @@ $ dsconfig \
[#log-common-audit-trust-transaction-ids]
.To Trust Transaction IDs
====
Client applications using the ForgeRock common audit event framework send transaction IDs with their requests. The transaction IDs are used to correlate audit events for monitoring and reporting that trace the request through multiple applications.
Client applications using the Open Identity Platform common audit event framework send transaction IDs with their requests. The transaction IDs are used to correlate audit events for monitoring and reporting that trace the request through multiple applications.

Transaction IDs are sent over LDAP using an internal OpenDJ request control. They are sent over HTTP in an HTTP header.

Expand Down Expand Up @@ -1702,7 +1702,7 @@ The following `errors` log excerpt shows log entries for a backup task, with lin

For the HTTP Connection Handler, OpenDJ maintains a separate access log in `logs/http-access`. This access log, by default configured as the File Based HTTP Access Log Publisher, uses a different format than the LDAP access log. This HTTP access log uses link:http://www.w3.org/TR/WD-logfile.html[Extended Log File Format, window=\_blank] with fields described in link:http://www.microsoft.com/technet/prodtechnol/WindowsServer2003/Library/IIS/676400bc-8969-4aa7-851a-9319490a9bbb.mspx?mfr=true[Microsoft's implementation, window=\_blank] as well.

Interface stability: Evolving (See xref:../reference/appendix-interface-stability.adoc#interface-stability["ForgeRock Product Interface Stability"] in the __Reference__)
Interface stability: Evolving (See xref:../reference/appendix-interface-stability.adoc#interface-stability["Product Interface Stability"] in the __Reference__)
--
The following default fields are shown here in the order they occur in the log file:

Expand Down Expand Up @@ -1755,7 +1755,7 @@ When using this field to match HTTP requests with internal operations in the LDA
Execution time in milliseconds needed by OpenDJ to service the HTTP request

`x-transaction-id`::
ForgeRock common audit event framework transaction ID for the request
Open Identity Platform common audit event framework transaction ID for the request

+
This defaults to `0` unless you configure OpenDJ to trust transaction IDs as described in xref:#log-common-audit-trust-transaction-ids["To Trust Transaction IDs"].
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@
information: "Portions copyright [year] [name of copyright owner]".

Copyright 2017 ForgeRock AS.
Portions Copyright 2024 3A Systems LLC.
Portions Copyright 2024-2025 3A Systems LLC.
////
:figure-caption!:
Expand Down Expand Up @@ -62,7 +62,7 @@ If your default Java environment is not appropriate, set `OPENDJ_JAVA_HOME` to t
+
Antivirus and intrusion detection systems that do a deep inspection of database files are not compatible with OpenDJ directory server. Disable antivirus and intrusion detection systems, or at least prevent them from operating on OpenDJ directory server files.
. Download enterprise software releases through the ForgeRock link:https://backstage.forgerock.com/[BackStage, window=\_blank] site. ForgeRock enterprise releases are thoroughly validated builds for ForgeRock customers who run OpenDJ in production deployments, and for those who want to try or test with release builds.
. Download software releases from the link:https://github.com/OpenIdentityPlatform/OpenDJ/releases[GitHub, window=\_blank].
+
--
The following OpenDJ 3.5.3 server software is available:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@
information: "Portions copyright [year] [name of copyright owner]".

Copyright 2017 ForgeRock AS.
Portions Copyright 2024 3A Systems LLC.
Portions Copyright 2024-2025 3A Systems LLC.
////

:figure-caption!:
Expand All @@ -25,7 +25,7 @@

This chapter covers upgrade from previous versions.

If the OpenDJ directory server version is older than 2.6.0, you must upgrade your deployment to use at least OpenDJ directory server 2.6.0 before following the procedures in this chapter. For details on upgrading to that version, see link:https://backstage.forgerock.com/docs/opendj/2.6/install-guide/#chap-upgrade[Upgrading to OpenDJ 2.6.0, window=\_blank].
If the OpenDJ directory server version is older than 2.6.0, you must upgrade your deployment to use at least OpenDJ directory server 2.6.0 before following the procedures in this chapter.

[TIP]
====
Expand Down Expand Up @@ -70,7 +70,7 @@ To move to a newer version, edit the `default.java-home` setting in the `opendj/

. (Optional) If you are upgrading to OpenDJ OEM edition from OpenDJ 2.6, make sure there is enough disk space to export all of the data to LDIF files.

. Download enterprise software releases through the ForgeRock link:https://backstage.forgerock.com/[BackStage, window=\_blank] site. ForgeRock enterprise releases are thoroughly validated builds for ForgeRock customers who run OpenDJ in production deployments, and for those who want to try or test with release builds.
. Download enterprise releases from the link:https://github.com/OpenIdentityPlatform/OpenDJ/releases[GitHub, window=\_blank] site.

. (Optional) If you are upgrading OpenDJ directory server on Windows, and OpenDJ is registered as a Windows service, disable OpenDJ as a Windows service before upgrade, as in the following example:
+
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@
information: "Portions copyright [year] [name of copyright owner]".

Copyright 2017 ForgeRock AS.
Portions Copyright 2024 3A Systems LLC.
Portions Copyright 2024-2025 3A Systems LLC.
////

:figure-caption!:
Expand All @@ -38,7 +38,7 @@ OpenDJ offers two alternatives for RESTful access to directory data:
--
The JSON format configuration can hold the following configuration objects. Some of the configuration settings are available only in the REST LDAP gateway configuration. The order here is the order shown in the default configuration file:

Interface stability: Evolving (See xref:../reference/appendix-interface-stability.adoc#interface-stability["ForgeRock Product Interface Stability"])
Interface stability: Evolving (See xref:../reference/appendix-interface-stability.adoc#interface-stability["Product Interface Stability"])

"ldapConnectionFactories" (required, gateway only)::
Configures how the gateway connects to LDAP servers. This entire configuration object applies only to the REST to LDAP gateway.
Expand Down Expand Up @@ -198,7 +198,7 @@ Default: "default"
The gateway authenticates by simple bind using the credentials specified:
+

[source, javascript]
[source, json]
----
{
"authentication": {
Expand Down Expand Up @@ -334,10 +334,10 @@ Specifies how to handle LDAP authorization. The following values are supported:


"proxyAuthzIdTemplate" (gateway only)::
Specifies the template to derive the authorization ID from the security context created during authentication. Use `{dn}` to indicate the user's bind DN or `{id}` to indicate the user name provided for authentication.
Specifies the template to derive the authorization ID from the security context created during authentication. Use `\{dn\}` to indicate the user's bind DN or `\{id\}` to indicate the user name provided for authentication.

+
Default: "dn:{dn}"
Default: "dn:\{dn\}"

"mappings"::
For each collection URI such as `/users` and `/groups`, you configure a mapping between the JSON resource returned over HTTP, and the LDAP entry returned by the directory service.
Expand Down Expand Up @@ -401,7 +401,7 @@ The following naming strategies are supported:
* RDN and resource ID are both derived from a single user attribute in the LDAP entry, as in the following example, where the `uid` attribute is the RDN and its value is the JSON resource ID:
+

[source, javascript]
[source, json]
----
{
"namingStrategy": {
Expand All @@ -414,7 +414,7 @@ The following naming strategies are supported:
* RDN and resource ID are derived from separate user attributes in the LDAP entry, as in the following example where the RDN attribute is `uid` but the JSON resource ID is the value of the `mail` attribute:
+

[source, javascript]
[source, json]
----
{
"namingStrategy": {
Expand All @@ -428,7 +428,7 @@ The following naming strategies are supported:
* RDN is derived from a user attribute and the resource ID from an operational attribute in the LDAP entry, as in the following example, where the RDN attribute is `uid` but the JSON resource ID is the value of the `entryUUID` operational attribute:
+

[source, javascript]
[source, json]
----
{
"namingStrategy": {
Expand All @@ -444,7 +444,7 @@ The following naming strategies are supported:
LDAP attributes to include during LDAP add operations as an array of type-value lists, such as the following example:
+

[source, javascript]
[source, json]
----
{
"additionalLDAPAttributes": [
Expand Down Expand Up @@ -476,7 +476,7 @@ Maps a single JSON attribute to a fixed value.
This can be useful as in the default case where each JSON resource "schemas" takes the SCIM URN, and so the value is not related to the underlying LDAP entries:
+

[source, javascript]
[source, json]
----
{
"schemas": {
Expand All @@ -494,7 +494,7 @@ Maps a JSON field to an LDAP attribute.
Simple mappings are used where the correspondence between JSON fields and LDAP attributes is one-to-one:
+

[source, javascript]
[source, json]
----
{
"userName": {
Expand Down Expand Up @@ -555,7 +555,7 @@ Maps a JSON field to an LDAP entry found by reference.
This mapping works for LDAP attributes whose values reference other entries. This is shown in the following example from the default configuration. The LDAP `manager` attribute values are user entry DNs. Here, the JSON `manager` field takes the user ID and name from the entry referenced by the LDAP attribute. On updates, changes to the JSON manager `_id` affect which manager entry is referenced, yet any changes to the manager's name are discarded, because changing managers only affects which user entry to point to, not the referenced user's name:
+

[source, javascript]
[source, json]
----
{
"manager": {
Expand Down Expand Up @@ -589,7 +589,7 @@ This mapping works for LDAP attributes whose values reference other entries. Thi
Babs Jensen's manager in the sample LDAP data is Torrey Rigden, who has user ID `trigden`. Babs's entry has `manager: uid=trigden,ou=People,dc=example,dc=com`. With this mapping, the resulting JSON field is the following:
+

[source, javascript]
[source, json]
----
{
"manager": [
Expand Down Expand Up @@ -631,7 +631,7 @@ Default: `false`
The default mappings expose a SCIM view of user and group data:
+

[source, javascript]
[source, json]
----
{
"/users": {
Expand Down
Loading