PingAuthorize Server Documentation Index
Configuration Reference Home

Sideband API HTTP Servlet Extension

The Sideband API HTTP Servlet Extension is used by a third-party API Gateway to authorize JSON-based HTTP request and response data.

The Sideband API HTTP Servlet Extension allows the PingAuthorize Server to act as a policy enforcement point (PEP) for a third-party API Gateway; it enforces business rules by applying policies to HTTP requests and responses provided by the API Gateway. To configure routes accepted by the Sideband API HTTP Servlet Extension, define one or more Sideband API Endpoints.

Parent Component
Relations from This Component
Properties
dsconfig Usage

Parent Component

The Sideband API HTTP Servlet Extension component inherits from the HTTP Servlet Extension

Relations from This Component

The following components have a direct aggregation relation from Sideband API HTTP Servlet Extensions:

Properties

The properties supported by this managed object are as follows:


Basic Properties: Advanced Properties:
↓ description  None
↓ cross-origin-policy
↓ response-header
↓ correlation-id-response-header
↓ request-limit
↓ request-context-method
↓ shared-secret-header-name
↓ shared-secrets

Basic Properties

description

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

cross-origin-policy

Description
The cross-origin request policy to use for the HTTP Servlet Extension. A cross-origin policy is a group of attributes defining the level of cross-origin request supported by the HTTP Servlet Extension.
Default Value
No cross-origin policy is defined and no CORS headers are recognized or returned.
Allowed Values
The DN of any HTTP Servlet Cross Origin Policy.
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

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 this HTTP Servlet Extension will be combined with response headers configured on the corresponding Connection Handler. In the case of duplicates, the headers configured on this HTTP Servlet Extension will be used instead of the headers configured on the Connection Handler.
Default Value
None
Allowed Values
Colon-separated header field name and value
Multi-Valued
Yes
Required
No
Admin Action Required
HTTP Connection Handlers hosting this HTTP Servlet Extension must be disabled and then re-enabled, or the server restarted, in order for this change to take effect.

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 value specified here will override the correlation-id-response-header property of the HTTP Connection Handler hosting this HTTP Servlet Extension.

If the use-correlation-id-header property of the HTTP Connection Handler hosting this HTTP Servlet Extension is not enabled, then this property will be ignored.

Default Value
The correlation-id-response-header property of the HTTP Connection Handler hosting this HTTP Servlet Extension will be used.
Allowed Values
A string
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

request-limit

Description
The maximum number of bytes allowed per request body. The server will return the status 413 Request Entity Too Large if a request exceeds the configured limit.
Default Value
No size limit will be enforced on requests.
Allowed Values
A positive integer representing a size. Lower limit is 1.
Multi-Valued
No
Required
No
Admin Action Required
The Sideband API HTTP Servlet Extension 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

request-context-method

Description
The mechanism that the Sideband API response endpoint uses to accept data about the related request. This setting governs how a client may provide HTTP request data, such as the request headers and body, in addition to response data when making a call to the Sideband API response endpoint. Doing this makes it possible for policies to authorize response endpoint requests using request context information that would not otherwise be available, including authentication data.

The following settings may be used:

  • none - A client cannot provide HTTP request data in a request to the Sideband API response endpoint.
  • state - Responses to the Sideband API request endpoint will include a "state" field generated by the server, containing request data reflecting the results of access token validation and policy processing. When making a call to the response endpoint, the client may include this value in the "state" field.
  • request - When making a call to the response endpoint, the client may include a "request" field containing HTTP request metadata and data.
When this property is set to either "state" or "request", the following additional policy request attributes will be included in the policy decision requests for the Sideband API response endpoint:
  • HttpRequest.RequestHeaders
  • HttpRequest.RequestBody
When the "state" option is used, there is no need to re-validate any access token used in the request, and all access token-related policy request attributes, such as TokenOwner, will be provided without incurring the cost of access token validation and token resource owner lookup. If the "request" option is used on the other hand, the PingAuthorize Server will invoke one or more Access Token Validators and Token Resource Lookup Methods to validate the access token and look up the token owner resource.
Default Value
none
Allowed Values
none - No mechanism will be accepted for providing request data to the Sideband API response endpoint.

state - The request endpoint will include a "state" field in its responses, which clients may provide in requests to the response endpoint.

request - The client may provide request data in requests to the response endpoint via the "request" field.
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

shared-secret-header-name

Description
The request header used to find the shared secret header for incoming Sideband API HTTP Servlet Extension requests. The Sideband API HTTP Servlet Extension will use this header name when inspecting incoming HTTP requests for the shared secret value(s).
Default Value
PDG-TOKEN
Allowed Values
RFC 2616-conformant HTTP header field name
Multi-Valued
No
Required
Yes
Admin Action Required
None. Modification requires no further action

shared-secrets

Description
Shared secrets between the third-party API Gateway and Sideband API HTTP Servlet Extension. A request will be considered authenticated by the Sideband API HTTP Servlet Extension if the incoming shared secret matches any active shared secrets in this list.
Default Value
The Sideband API HTTP Servlet Extension will treat all requests as authenticated regardless of the shared secret header value.
Allowed Values
The DN of any Sideband API Shared Secret.
Multi-Valued
Yes
Required
No
Admin Action Required
None. Modification requires no further action


dsconfig Usage

To list the configured HTTP Servlet Extensions:

dsconfig list-http-servlet-extensions
     [--property {propertyName}] ...

To view the configuration for an existing HTTP Servlet Extension:

dsconfig get-http-servlet-extension-prop
     --extension-name {name}
     [--tab-delimited]
     [--script-friendly]
     [--property {propertyName}] ...

To update the configuration for an existing HTTP Servlet Extension:

dsconfig set-http-servlet-extension-prop
     --extension-name {name}
     (--set|--add|--remove) {propertyName}:{propertyValue}
     [(--set|--add|--remove) {propertyName}:{propertyValue}] ...