Log LDAP Access to Files

JSON Format

When you install DS using procedures from Installation, the primary JSON-based LDAP access log file is logs/ldap-access.audit.json. The name of the access log publisher in the configuration is Json File-Based Access Logger.

The sample DS Docker image logs to standard output instead of files. This makes it easy to read log messages with the docker logs command, and is a pattern you should follow when creating your own DS Docker images. The name of the LDAP access log publisher configuration in the sample image is Console LDAP Access Logger.

Primary access logs include messages for each LDAP operation. They can grow quickly, but are particularly useful for analyzing overall client behavior:

  1. Decide whether to trust transaction IDs sent by client applications, used to correlate requests as they traverse multiple servers.

    Client applications using the ForgeRock Common Audit event framework send transaction IDs with their requests. The transaction IDs correlate audit events, tracing the request through multiple applications.

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

    By default, DS servers do not trust transaction IDs sent with client application requests.

    When a server trusts transaction IDs from client application requests, outgoing requests reuse the incoming ID. For each outgoing request in the transaction, the request’s transaction ID has the form original-transaction-id/sequence-number, where sequence-number reflects the position of the request in the series of requests for this transaction. For example, if the original-transaction-id is abc123, the first outgoing request has the transaction ID abc123/0, the second abc123/1, the third abc123/2, and so on. This lets you distinguish specific requests within a transaction when correlating audit events from multiple services.

    To trust transactions, set the advanced global server property, trust-transaction-ids:true:

    $ dsconfig \
     set-global-configuration-prop \
     --advanced \
     --hostname localhost \
     --port 4444 \
     --bindDN uid=admin \
     --bindPassword password \
     --set trust-transaction-ids:true \
     --usePkcs12TrustStore /path/to/opendj/config/keystore \
     --trustStorePassword:file /path/to/opendj/config/keystore.pin \
     --no-prompt
  2. Edit the default access log publisher as necessary.

    The following example applies the default settings for DS installed locally, not in a Docker image:

    $ dsconfig \
     set-log-publisher-prop \
     --hostname localhost \
     --port 4444 \
     --bindDN uid=admin \
     --bindPassword password \
     --publisher-name "Json File-Based Access Logger" \
     --set enabled:true \
     --add "rotation-policy:24 Hours Time Limit Rotation Policy" \
     --add "rotation-policy:Size Limit Rotation Policy" \
     --set "retention-policy:File Count Retention Policy" \
     --usePkcs12TrustStore /path/to/opendj/config/keystore \
     --trustStorePassword:file /path/to/opendj/config/keystore.pin \
     --no-prompt

Filtered JSON Format

DS servers write messages to a filtered access log file, logs/filtered-ldap-access.audit.json. This log grows more slowly than the primary access log. It includes only messages about the following:

  • Administrative requests related to backing up and restoring data, scheduling tasks, and reading and writing configuration settings

  • Authentication failures

  • Requests from client applications that are misbehaving

  • Requests that take longer than one second for the server to process

  • Search requests that return more than 1000 entries

  • Unindexed searches

Follow these steps to change the configuration:

  1. Edit the filtered access log publisher as necessary.

    The following example updates the configuration to include control OIDs in log records:

    $ dsconfig \
     set-log-publisher-prop \
     --hostname localhost \
     --port 4444 \
     --bindDN uid=admin \
     --bindPassword password \
     --publisher-name "Filtered Json File-Based Access Logger" \
     --set log-control-oids:true \
     --usePkcs12TrustStore /path/to/opendj/config/keystore \
     --trustStorePassword:file /path/to/opendj/config/keystore.pin \
     --no-prompt
  2. Edit the filtering criteria as necessary.

    The following commands list the relevant default filtering criteria settings for the filtered access log:

    $ dsconfig \
     get-access-log-filtering-criteria-prop \
     --hostname localhost \
     --port 4444 \
     --bindDN uid=admin \
     --bindPassword password \
     --publisher-name "Filtered Json File-Based Access Logger" \
     --criteria-name "Administrative Requests" \
     --usePkcs12TrustStore /path/to/opendj/config/keystore \
     --trustStorePassword:file /path/to/opendj/config/keystore.pin \
     --no-prompt
    
    log-record-type                        : add, bind, compare, delete, extended,
                                           : modify, rename, search
    request-target-dn-equal-to             : "**,cn=config", "**,cn=tasks",
                                           : cn=config, cn=tasks
    
    $ dsconfig \
     get-access-log-filtering-criteria-prop \
     --hostname localhost \
     --port 4444 \
     --bindDN uid=admin \
     --bindPassword password \
     --publisher-name "Filtered Json File-Based Access Logger" \
     --criteria-name "Auth Failures" \
     --usePkcs12TrustStore /path/to/opendj/config/keystore \
     --trustStorePassword:file /path/to/opendj/config/keystore.pin \
     --no-prompt
    
    log-record-type                        : add, bind, compare, delete, extended,
                                           : modify, rename, search
    response-result-code-equal-to          : 7, 8, 13, 48, 49, 50, 123
    
    $ dsconfig \
     get-access-log-filtering-criteria-prop \
     --hostname localhost \
     --port 4444 \
     --bindDN uid=admin \
     --bindPassword password \
     --publisher-name "Filtered Json File-Based Access Logger" \
     --criteria-name "Long Requests" \
     --usePkcs12TrustStore /path/to/opendj/config/keystore \
     --trustStorePassword:file /path/to/opendj/config/keystore.pin \
     --no-prompt
    
    log-record-type                        : add, bind, compare, delete, extended,
                                           : modify, rename, search
    response-etime-greater-than            : 1000
    
    $ dsconfig \
     get-access-log-filtering-criteria-prop \
     --hostname localhost \
     --port 4444 \
     --bindDN uid=admin \
     --bindPassword password \
     --publisher-name "Filtered Json File-Based Access Logger" \
     --criteria-name "Misbehaving Clients" \
     --usePkcs12TrustStore /path/to/opendj/config/keystore \
     --trustStorePassword:file /path/to/opendj/config/keystore.pin \
     --no-prompt
    
    log-record-type                        : add, bind, compare, delete, extended,
                                           : modify, rename, search
    response-result-code-equal-to          : 1, 2, 17, 18, 19, 21, 34, 60, 61, 64,
                                           : 65, 66, 67, 69
    
    $ dsconfig \
     get-access-log-filtering-criteria-prop \
     --hostname localhost \
     --port 4444 \
     --bindDN uid=admin \
     --bindPassword password \
     --publisher-name "Filtered Json File-Based Access Logger" \
     --criteria-name "Searches Returning 1000+ Entries" \
     --usePkcs12TrustStore /path/to/opendj/config/keystore \
     --trustStorePassword:file /path/to/opendj/config/keystore.pin \
     --no-prompt
    
    log-record-type                        : search
    search-response-nentries-greater-than  : 1000
    
    $ dsconfig \
     get-access-log-filtering-criteria-prop \
     --hostname localhost \
     --port 4444 \
     --bindDN uid=admin \
     --bindPassword password \
     --publisher-name "Filtered Json File-Based Access Logger" \
     --criteria-name "Unindexed Searches" \
     --usePkcs12TrustStore /path/to/opendj/config/keystore \
     --trustStorePassword:file /path/to/opendj/config/keystore.pin \
     --no-prompt
    
    log-record-type                        : search
    search-response-is-indexed             : false

    For details about the LDAP result codes listed in the criteria, see LDAP Result Codes.

    For details about how filtering works, see Access Log Filtering.

CSV Format

A CSV handler sends messages to a comma-separated variable (CSV) file.

The CSV handler does not sanitize messages when writing to CSV log files.

Do not open CSV logs in spreadsheets and other applications that treat data as code.

The default CSV LDAP access log file is logs/ldap-access.csv:

  1. Decide whether to trust transaction IDs sent by client applications, used to correlate requests as they traverse multiple servers.

    Client applications using the ForgeRock Common Audit event framework send transaction IDs with their requests. The transaction IDs correlate audit events, tracing the request through multiple applications.

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

    By default, DS servers do not trust transaction IDs sent with client application requests.

    When a server trusts transaction IDs from client application requests, outgoing requests reuse the incoming ID. For each outgoing request in the transaction, the request’s transaction ID has the form original-transaction-id/sequence-number, where sequence-number reflects the position of the request in the series of requests for this transaction. For example, if the original-transaction-id is abc123, the first outgoing request has the transaction ID abc123/0, the second abc123/1, the third abc123/2, and so on. This lets you distinguish specific requests within a transaction when correlating audit events from multiple services.

    To trust transactions, set the advanced global server property, trust-transaction-ids:true:

    $ dsconfig \
     set-global-configuration-prop \
     --advanced \
     --hostname localhost \
     --port 4444 \
     --bindDN uid=admin \
     --bindPassword password \
     --set trust-transaction-ids:true \
     --usePkcs12TrustStore /path/to/opendj/config/keystore \
     --trustStorePassword:file /path/to/opendj/config/keystore.pin \
     --no-prompt
  2. Create an enabled CSV file access logger with optional rotation and retention policies:

    $ dsconfig \
     create-log-publisher \
     --hostname localhost \
     --port 4444 \
     --bindDN uid=admin \
     --bindPassword password \
     --publisher-name "Common Audit Csv File Access Logger" \
     --type csv-file-access \
     --set enabled:true \
     --set "rotation-policy:24 Hours Time Limit Rotation Policy" \
     --set "rotation-policy:Size Limit Rotation Policy" \
     --set "retention-policy:File Count Retention Policy" \
     --usePkcs12TrustStore /path/to/opendj/config/keystore \
     --trustStorePassword:file /path/to/opendj/config/keystore.pin \
     --no-prompt
  3. For tamper-evident logs, follow these steps.

    Tamper-evident logging relies on digital signatures and regularly flushing messages to the log system. In high-volume directory deployments with heavy access patterns, signing log messages has a severe negative impact on server performance, reducing throughput by orders of magnitude.

    Be certain to test the performance impact with realistic access patterns for your deployment before enabling the feature in production.

    1. Prepare a keystore.

      For details, see Make Tampering Evident.

    2. Enable the tamper-evident capability:

      $ dsconfig \
       set-log-publisher-prop \
       --hostname localhost \
       --port 4444 \
       --bindDN uid=admin \
       --bindPassword password \
       --publisher-name "Common Audit Csv File Access Logger" \
       --set tamper-evident:true \
       --set key-store-file:config/audit-keystore \
       --set key-store-pin:"&{audit.keystore.pin}" \
       --usePkcs12TrustStore /path/to/opendj/config/keystore \
       --trustStorePassword:file /path/to/opendj/config/keystore.pin \
       --no-prompt

      In this example, AUDIT_KEYSTORE_PIN is an environment variable containing the PIN.

Backwards-Compatible Format

This access log format was the default for older DS servers. Use this log format if you already have software configured to consume that format. The default log file is logs/access:

  1. Enable the LDAP access logger:

    $ dsconfig \
     set-log-publisher-prop \
     --hostname localhost \
     --port 4444 \
     --bindDN uid=admin \
     --bindPassword password \
     --publisher-name "File-Based Access Logger" \
     --set enabled:true \
     --usePkcs12TrustStore /path/to/opendj/config/keystore \
     --trustStorePassword:file /path/to/opendj/config/keystore.pin \
     --no-prompt

    By default, this access log contains a message for each request, and a message for each response. It also includes messages for connection and disconnection.

    Write messages only on responses by setting the log-format:combined property. The setting is useful when filtering messages based on response criteria. It causes the server to log one message per operation, rather than one for each request and response.