PingDS

HTTP access

This page describes how to configure HTTP ports for DS servers.

Alternatively, you can configure unified connection handlers to process HTTP and LDAP on the same port. Learn more in Administrative and unified access.

Set the HTTP port

The following steps demonstrate how to set up an HTTP port if none was configured at setup time with the --httpPort option:

  1. Create an HTTP connection handler:

    $ dsconfig \
 create-connection-handler \
 --hostname localhost \
 --port 4444 \
 --bindDN uid=admin \
 --bindPassword password \
 --handler-name HTTP \
 --type http \
 --set enabled:true \
 --set listen-port:8080 \
 --no-prompt \
 --trustStorePath /path/to/opendj/config/keystore \
 --trustStoreType PKCS12 \
 --trustStorePassword:file /path/to/opendj/config/keystore.pin

  2. Enable an HTTP access log.

    1. The following command enables JSON-based HTTP access logging:

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

    2. The following command enables HTTP access logging:

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

  3. After you set up an HTTP port, enable an HTTP endpoint.

    For details, refer to Use administrative APIs.

Set the HTTPS port

At setup time use the --httpsPort option.

Later, follow these steps to set up an HTTPS port:

  1. Create an HTTPS connection handler.

    The following example sets the port to 8443 and uses the default server certificate:

    $ dsconfig \
 create-connection-handler \
 --hostname localhost \
 --port 4444 \
 --bindDN uid=admin \
 --bindPassword password \
 --handler-name HTTPS \
 --type http \
 --set enabled:true \
 --set listen-port:8443 \
 --set use-ssl:true \
 --set key-manager-provider:PKCS12 \
 --set trust-manager-provider:"JVM Trust Manager" \
 --trustStorePath /path/to/opendj/config/keystore \
 --trustStoreType PKCS12 \
 --trustStorePassword:file /path/to/opendj/config/keystore.pin \
 --no-prompt

    If the key manager provider has multiple key pairs that DS could use for TLS, where the secret key was generated with the same key algorithm, such as EC or RSA, you can specify which key pairs to use with the --set ssl-cert-nickname:server-cert option. The server-cert is the certificate alias of the key pair. This option is not necessary if there is only one server key pair, or if each secret key was generated with a different key algorithm.

  2. Enable the HTTP access log.

    1. The following command enables JSON-based HTTP access logging:

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

    2. The following command enables HTTP access logging:

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

  3. If the deployment requires SSL client authentication, set the properties ssl-client-auth-policy and trust-manager-provider appropriately.

  4. After you set up an HTTPS port, enable an HTTP endpoint.

    For details, refer to Use administrative APIs.

Configure HTTP authorization

HTTP authorization mechanisms map HTTP credentials to LDAP credentials.

Multiple HTTP authorization mechanisms can be enabled simultaneously.

These HTTP authorization mechanisms are supported:

HDAP (enabled by default)

Process anonymous, basic and bearer authorization requests.

This mechanism treats anonymous requests like the HTTP Anonymous mechanism.

For HTTP Basic requests, this mechanism matches an HDAP resource _id to the DN. The _id matches the suffix of the path to the resource. For example, the default directory superuser _id is uid=admin. Babs Jensen’s _id is dc=com/dc=example/ou=People/uid=bjensen.

For HTTP Bearer requests, this mechanism uses a JSON Web Token (JWT). Get the JWT with the HDAP authenticate action. Learn more in Bearer auth.

HTTP Anonymous (enabled by default)

Process anonymous HTTP requests, optionally binding with a specified DN.

If the client does not specify a bind DN (default), it binds as an anonymous LDAP user.

HTTP Basic (enabled by default)

Process HTTP Basic authorization requests by mapping the HTTP Basic identity to a user’s directory account.

By default, DS uses the exact match identity mapper with its default configuration to map the HTTP Basic username to an LDAP uid. DS searches all local public naming contexts to find the user’s entry based in the uid value. Learn more in Identity mappers.

Use administrative APIs

The APIs for configuring and monitoring DS servers are under the following endpoints:

/alive

Check whether the server is currently alive, meaning its internal checks have not found any errors that would require administrative action.

By default, this endpoint returns a status code to anonymous requests and supports authenticated requests. For details, refer to Server is alive (HTTP).

/healthy

Check whether the server is currently healthy, meaning it’s alive, the replication server is accepting connections on the configured port, and any replication delays are below the configured threshold.

By default, this endpoint returns a status code to anonymous requests, and supports authenticated requests. For details, refer to Server health (HTTP).

/metrics/prometheus/0.0.4

Access the server monitoring information in Prometheus monitoring software format.

By default, DS protects this endpoint with the HTTP Basic authorization mechanism. Users reading monitoring information must have the monitor-read privilege.

To use these APIs, follow these steps:

  1. Grant access to the /metrics/prometheus/0.0.4 endpoint, if necessary, by assigning the monitor-read privilege.

    For details, refer to Administrative privileges.

    Alternatively, create a monitor user with the setup command when installing DS.

  2. Adjust the authorization-mechanism settings for the Admin endpoint.

    By default, DS uses the HTTP Basic authorization mechanism. The HTTP Basic authorization mechanism default configuration resolves the user identity extracted from the HTTP request to an LDAP user identity as follows:

    • If the request has an Authorization: Basic header for HTTP Basic authentication, DS extracts the username and password.

    • If the request has X-OpenIDM-Username and X-OpenIDM-Password headers, DS extracts the username and password.

    • DS uses the default exact match identity mapper to search for a unique match between the username and the UID attribute value of an entry in the local public naming contexts of the DS server.

      In LDAP terms, it searches all user base DNs for (uid=<http-username>). The username kvaughan maps to the example entry with DN uid=kvaughan,ou=People,dc=example,dc=com.

      For details, refer to Identity mappers and Configure HTTP authorization.

  3. Test access to the endpoint as an authorized user.