PingAuthorize Server Documentation Index
Configuration Reference Home

HTTP Connection Handler

The HTTP Connection Handler may be used to interact with clients using the HyperText Transport Protocol, used by Web clients and services.

Parent Component
Relations from This Component
Properties
dsconfig Usage

Parent Component

The HTTP Connection Handler component inherits from the Connection Handler

Relations from This Component

The following components have a direct aggregation relation from HTTP Connection Handlers:

Properties

The properties supported by this managed object are as follows:


Basic Properties: Advanced Properties:
↓ description ↓ keep-stats
↓ enabled ↓ accept-backlog
↓ listen-address ↓ allow-tcp-reuse-address
↓ listen-port ↓ idle-time-limit
↓ use-ssl ↓ low-resources-connection-threshold
↓ ssl-cert-nickname ↓ low-resources-idle-time-limit
↓ http-servlet-extension ↓ enable-multipart-mime-parameters
↓ web-application-extension ↓ use-forwarded-headers
↓ http-operation-log-publisher ↓ http-request-header-size
↓ ssl-protocol ↓ ssl-client-auth-policy
↓ ssl-cipher-suite
↓ key-manager-provider
↓ trust-manager-provider
↓ num-request-handlers
↓ response-header
↓ use-correlation-id-header
↓ correlation-id-response-header
↓ correlation-id-request-header

Basic Properties

description

Description
A description for this Connection Handler
Default Value
None
Allowed Values
A string
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

enabled

Description
Indicates whether the Connection Handler is enabled.
Default Value
None
Allowed Values
true
false
Multi-Valued
No
Required
Yes
Admin Action Required
None. Modification requires no further action

listen-address

Description
Specifies the address on which to listen for connections from HTTP clients. If no value is defined, the server will listen on all addresses on all interfaces.
Default Value
The server will listen on all addresses on all interfaces.
Allowed Values
An IP address
Multi-Valued
No
Required
No
Admin Action Required
The HTTP Connection Handler must be disabled and re-enabled for changes to this setting to take effect. In order for this modification to take effect, the component must be restarted, either by disabling and re-enabling it, or by restarting the server

listen-port

Description
Specifies the port number on which the HTTP Connection Handler will listen for connections from clients. Only a single port number may be provided.
Default Value
None
Allowed Values
An integer value. Lower limit is 1. Upper limit is 65535 .
Multi-Valued
No
Required
Yes
Admin Action Required
The HTTP Connection Handler must be disabled and re-enabled for changes to this setting to take effect. In order for this modification to take effect, the component must be restarted, either by disabling and re-enabling it, or by restarting the server

use-ssl

Description
Indicates whether the HTTP Connection Handler should use SSL. If enabled, the HTTP Connection Handler will use SSL to encrypt communication with the clients.
Default Value
false
Allowed Values
true
false
Multi-Valued
No
Required
No
Admin Action Required
The HTTP Connection Handler must be disabled and re-enabled for changes to this setting to take effect. In order for this modification to take effect, the component must be restarted, either by disabling and re-enabling it, or by restarting the server

ssl-cert-nickname

Description
Specifies the nickname (also called the alias) of the certificate that the HTTP Connection Handler should use when performing SSL communication. This is only applicable when the HTTP Connection Handler is configured to use SSL.
Default Value
Let the server decide.
Allowed Values
A string
Multi-Valued
No
Required
No
Admin Action Required
The HTTP Connection Handler must be disabled and re-enabled for changes to this setting to take effect. In order for this modification to take effect, the component must be restarted, either by disabling and re-enabling it, or by restarting the server

http-servlet-extension

Description
Specifies information about servlets that will be provided via this connection handler. Adding custom servlet extensions may impact the performance and stability of the PingAuthorize Server. Monitor the error log for initialization errors and exceptions to identify any problems.
Default Value
None
Allowed Values
The DN of any HTTP Servlet Extension.
Multi-Valued
Yes
Required
No
Admin Action Required
The HTTP Connection Handler must be disabled and re-enabled for changes to this setting to take effect. In order for this modification to take effect, the component must be restarted, either by disabling and re-enabling it, or by restarting the server

web-application-extension

Description
Specifies information about web applications that will be provided via this connection handler. Adding custom web applications may impact the performance and stability of the PingAuthorize Server. Monitor the error log for initialization errors and exceptions to identify any problems.
Default Value
None
Allowed Values
The DN of any Web Application Extension.
Multi-Valued
Yes
Required
No
Admin Action Required
The HTTP Connection Handler must be disabled and re-enabled for changes to this setting to take effect. In order for this modification to take effect, the component must be restarted, either by disabling and re-enabling it, or by restarting the server

http-operation-log-publisher

Description
Specifies the set of HTTP operation loggers that should be used to log information about requests and responses for operations processed through this HTTP Connection Handler.
Default Value
None
Allowed Values
The DN of any HTTP Operation Log Publisher. The associated HTTP operation logger must be enabled.
Multi-Valued
Yes
Required
No
Admin Action Required
None. Modification requires no further action

ssl-protocol

Description
Specifies the names of the SSL protocols that are allowed for use in SSL communication. The set of supported ssl protocols can be viewed via the ssl context monitor entry.
Default Value
Uses the default set of SSL protocols provided by the server's JVM.
Allowed Values
A string
Multi-Valued
Yes
Required
No
Admin Action Required
The HTTP Connection Handler must be disabled and re-enabled for changes to this setting to take effect. In order for this modification to take effect, the component must be restarted, either by disabling and re-enabling it, or by restarting the server

ssl-cipher-suite

Description
Specifies the names of the SSL cipher suites that are allowed for use in SSL communication. The set of supported cipher suites can be viewed via the ssl context monitor entry. If no values are provided, the server will automatically select a set of cipher suites that provide a combination of good security and client compatibility. The default set of SSL cipher suites can be modified by adding entries that are pre-pended with either a '+' or a '-' character. Using a '+' will append the specified suite to the default set. Likewise, a '-' will remove the specified suite from the default set. Finally, an exact set of desired suites can be defined by adding entries that only contain the suite name. Exact values and modifications (+ or -) can not be combined. Doing so will result in configuration exception. The available set of cipher suites can be found in the monitor data under "cn=SSL Context,cn=monitor".
Default Value
The server will automatically select a set of cipher suites that provide a combination of good security and client compatibility.
Allowed Values
A string
Multi-Valued
Yes
Required
No
Admin Action Required
The HTTP Connection Handler must be disabled and re-enabled for changes to this setting to take effect. In order for this modification to take effect, the component must be restarted, either by disabling and re-enabling it, or by restarting the server

key-manager-provider

Description
Specifies the key manager provider that will be used to obtain the certificate to present to HTTPS clients. This must be provided if use-ssl is set to true.
Default Value
None
Allowed Values
The DN of any Key Manager Provider. The referenced key manager provider must be enabled if SSL is to be used.
Multi-Valued
No
Required
No
Admin Action Required
The HTTP Connection Handler must be disabled and re-enabled for changes to this setting to take effect. In order for this modification to take effect, the component must be restarted, either by disabling and re-enabling it, or by restarting the server

trust-manager-provider

Description
Specifies the trust manager provider that will be used to validate any certificates presented by HTTPS clients. This must be provided if use-ssl is set to true.
Default Value
None
Allowed Values
The DN of any Trust Manager Provider. The referenced trust manager provider must be enabled if SSL is to be used.
Multi-Valued
No
Required
No
Admin Action Required
The HTTP Connection Handler must be disabled and re-enabled for changes to this setting to take effect. In order for this modification to take effect, the component must be restarted, either by disabling and re-enabling it, or by restarting the server

num-request-handlers

Description
Specifies the number of threads that will be used for accepting connections and reading requests from clients. A value of zero will cause the number of request handlers to be based on the number of available CPUs.
Default Value
0
Allowed Values
An integer value. Lower limit is 0.
Multi-Valued
No
Required
No
Admin Action Required
The HTTP Connection Handler must be disabled and re-enabled for changes to this setting to take effect. In order for this modification to take effect, the component must be restarted, either by disabling and re-enabling it, or by restarting the server

response-header

Description
Specifies HTTP header fields and values added to response headers for all requests. Values specified here must specify both the header field name and the value in conformance with RFC 2616. Fields may only be specified once; multiple values for the same header should be comma-separated. See RFC 7231 for a standard set of field names.
Any response headers configured for a HTTP Servlet Extension will either supplement or, in the case of a duplicate, override response headers defined on the HTTP Connection Handler.
Default Value
None
Allowed Values
Colon-separated header field name and value
Multi-Valued
Yes
Required
No
Admin Action Required
The HTTP Connection Handler must be disabled and re-enabled for changes to this setting to take effect. In order for this modification to take effect, the component must be restarted, either by disabling and re-enabling it, or by restarting the server

use-correlation-id-header

Description
If enabled, a correlation ID header will be added to outgoing HTTP responses. The correlation ID value is either generated by the server when an HTTP request is received or is taken from an HTTP request header, if specified by the correlation-id-request-header property. The correlation ID value can be used to correlate request and response log messages across server boundaries.
Default Value
true
Allowed Values
true
false
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

correlation-id-response-header

Description
Specifies the name of the HTTP response header that will contain a correlation ID value. Example values are "Correlation-Id", "X-Amzn-Trace-Id", and "X-Request-Id". This property can be used to specify a custom response header name for correlation IDs. The default header name is "Correlation-Id".
This property is ignored if the use-correlation-id-header property is not enabled.
Default Value
Correlation-Id
Allowed Values
A string
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

correlation-id-request-header

Description
Specifies the set of HTTP request headers that may contain a value to be used as the correlation ID. Example values are "Correlation-Id", "X-Amzn-Trace-Id", and "X-Request-Id". If specified, then the correlation ID used in the HTTP response will be derived from this set of request headers. These headers will be checked in the order listed in the configuration, and the first header found in the request will be used. If no header from this set is found in the request, or if this property is not defined, then a new correlation ID will be generated by the server.
This property is ignored if the use-correlation-id-header property is not enabled.
Default Value
If no source headers are specified, then the correlation ID will always be generated by the server.
Allowed Values
A string
Multi-Valued
Yes
Required
No
Admin Action Required
None. Modification requires no further action


Advanced Properties

keep-stats (Advanced Property)

Description
Indicates whether to enable statistics collection for this connection handler.
Default Value
true
Allowed Values
true
false
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

accept-backlog (Advanced Property)

Description
Specifies the number of concurrent outstanding connection attempts that the connection handler should allow. The default value should be acceptable in most cases, but it may need to be increased in environments that may attempt to establish large numbers of connections simultaneously.
Default Value
128
Allowed Values
An integer value. Lower limit is 1.
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

allow-tcp-reuse-address (Advanced Property)

Description
Indicates whether the server should attempt to reuse socket descriptors. This may be useful in environments with a high rate of connection establishment and termination.
Default Value
true
Allowed Values
true
false
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

idle-time-limit (Advanced Property)

Description
Specifies the maximum idle time for a connection. The max idle time is applied when waiting for a new request to be received on a connection, when reading the headers and content of a request, or when writing the headers and content of a response.
Default Value
200 seconds
Allowed Values
A duration. Lower limit is 1 milliseconds.
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

low-resources-connection-threshold (Advanced Property)

Description
Specifies the number of connections, which if exceeded, places this handler in a low resource state where a different idle time limit is applied on the connections. A value of zero indicates that the server will enforce the low resource idle time limit automatically whenever there are not enough request handlers allocated to handle the current load.
Default Value
0
Allowed Values
An integer value. Lower limit is 0.
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

low-resources-idle-time-limit (Advanced Property)

Description
Specifies the maximum idle time for a connection when this handler is in a low resource state as defined by low-resource-connections. The max idle time is applied when waiting for a new request to be received on a connection, when reading the headers and content of a request, or when writing the headers and content of a response.
Default Value
200 seconds
Allowed Values
A duration. Lower limit is 1 milliseconds.
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

enable-multipart-mime-parameters (Advanced Property)

Description
Determines whether request form parameters submitted in multipart/ form-data (RFC 2388) format should be processed as request parameters. Most web applications use the "application/x-url-encoded" method to submit form parameters in a compact format, e.g. param1=value1¶m2=value2. There is no opportunity to apply differing charsets, content-types or transfer-encodings as described in RFC 2388. Enabling multipart-mime form parameter processing allows the form parameters above to be expressed as named parts with greater content control in HTTP servlet extensions. Form processing in web application extensions is unaffected. This is an example of a multipart/form entity:
Content-Type: multipart/form-data; boundary=separator

--separator
content-disposition: form-data; name="param1"
content-type: text/plain;charset=utf-8
content-transfer-encoding: 8bit

value1
--separator
content-disposition: form-data; name="param2"
content-type: text/plain;charset=windows-1250
content-transfer-encoding: quoted-printable

value2
--separator--
Default Value
false
Allowed Values
true
false
Multi-Valued
No
Required
No
Admin Action Required
The HTTP Connection Handler must be disabled and re-enabled for changes to this setting to take effect. In order for this modification to take effect, the component must be restarted, either by disabling and re-enabling it, or by restarting the server

use-forwarded-headers (Advanced Property)

Description
Indicates whether to use "Forwarded" and "X-Forwarded-*" request headers to override corresponding HTTP request information available during request processing. These headers are usually set by proxies to disclose information about the original request that would otherwise be lost during the proxying process. The information in these headers will be used to update the request information exposed to Logging, Web Application Extensions, and HTTP Servlet Extensions. The following headers are supported:
  • Forwarded (RFC 7239)
  • X-Forwarded-Host
  • X-Forwarded-Server
  • X-Forwarded-Port
  • X-Forwarded-For
  • X-Forwarded-Proto
  • X-Forwarded-Https
  • X-Forwarded-Prefix
When both the "Forwarded" and "X-Forwarded-*" headers are included in the request, the "Forwarded" header will take precedence. The "X-Forwarded-Prefix" header will only override the context path for HTTP Servlet Extensions but not Web Application Extensions.
Default Value
false
Allowed Values
true
false
Multi-Valued
No
Required
No
Admin Action Required
The HTTP Connection Handler must be disabled and re-enabled for changes to this setting to take effect. In order for this modification to take effect, the component must be restarted, either by disabling and re-enabling it, or by restarting the server

http-request-header-size (Advanced Property)

Description
Specifies the maximum buffer size of an http request including the request uri and all of the request headers. The default value may be increased if the server is required to process unusually large GET requests or if a large amount of client state needs to be maintained via headers.
Default Value
8192
Allowed Values
An integer value. Lower limit is 8192.
Multi-Valued
No
Required
No
Admin Action Required
The HTTP Connection Handler must be disabled and re-enabled for changes to this setting to take effect. In order for this modification to take effect, the component must be restarted, either by disabling and re-enabling it, or by restarting the server

ssl-client-auth-policy (Advanced Property)

Description
Specifies the policy that the HTTP Connection Handler should use regarding client SSL certificates. In order for a client certificate to be accepted it must be known to the trust-manager-provider associated with this HTTP Connection Handler. Client certificates received by the HTTP Connection Handler are by default used for TLS mutual authentication only, as there is no support for user authentication. This is only applicable if clients are allowed to use SSL.
Default Value
disabled
Allowed Values
disabled - Clients are not required to provide their own certificates when performing SSL negotiation.

optional - Clients are requested to provide their own certificates when performing SSL negotiation, but still accept the connection even if the client does not provide a certificate.

required - Clients are required to provide their own certificates when performing SSL negotiation and are refused access if they do not provide a certificate.
Multi-Valued
No
Required
No
Admin Action Required
The HTTP Connection Handler must be disabled and re-enabled for changes to this setting to take effect. In order for this modification to take effect, the component must be restarted, either by disabling and re-enabling it, or by restarting the server


dsconfig Usage

To list the configured Connection Handlers:

dsconfig list-connection-handlers
     [--property {propertyName}] ...

To view the configuration for an existing Connection Handler:

dsconfig get-connection-handler-prop
     --handler-name {name}
     [--tab-delimited]
     [--script-friendly]
     [--property {propertyName}] ...

To update the configuration for an existing Connection Handler:

dsconfig set-connection-handler-prop
     --handler-name {name}
     (--set|--add|--remove) {propertyName}:{propertyValue}
     [(--set|--add|--remove) {propertyName}:{propertyValue}] ...

To create a new HTTP Connection Handler:

dsconfig create-connection-handler
     --handler-name {name}
     --type http
     --set enabled:{propertyValue}
     --set listen-port:{propertyValue}
     [--set {propertyName}:{propertyValue}] ...

To delete an existing Connection Handler:

dsconfig delete-connection-handler
     --handler-name {name}