--- title: HTTP access description: This page describes how to configure HTTP ports for DS servers. component: pingds version: 8.1 page_id: pingds:config-guide:http-access canonical_url: https://docs.pingidentity.com/pingds/8.1/config-guide/http-access.html revdate: 2025-10-22T14:42:39Z keywords: ["Features", "REST API", "Setup & Configuration"] section_ids: setup-http-connection-handler: Set the HTTP port setup-https-access: Set the HTTPS port setup-http-authorization: Configure HTTP authorization setup-admin-endpoint: Use administrative APIs --- # 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](admin-access.html). ## 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: ```console $ 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: ```console $ 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: ```console $ 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](#setup-admin-endpoint). ## 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: ```console $ 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: ```console $ 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: ```console $ 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](#setup-admin-endpoint). ## 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](../rest-guide/rest-operations.html#authenticate-rest-bearer). * 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](https://www.rfc-editor.org/info/rfc7235) 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](../ldap-guide/client-auth.html#client-auth-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)](../monitoring-guide/http-monitoring.html#monitoring-liveness-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)](../monitoring-guide/http-monitoring.html#monitoring-health-http). * `/metrics/prometheus/0.0.4` Access the server monitoring information in [Prometheus monitoring software](https://prometheus.io/) 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](../security-guide/admin.html#admin-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=)`. The username `kvaughan` maps to the example entry with DN `uid=kvaughan,ou=People,dc=example,dc=com`. For details, refer to [Identity mappers](../ldap-guide/client-auth.html#client-auth-identity-mappers) and [Configure HTTP authorization](#setup-http-authorization). 3. Test access to the endpoint as an authorized user.