Lead your team forward
OCT 24 / 9AM ET Register nowHTTP Dispatcher
The HTTP Dispatcher receives all HTTP requests, distributes them for processing to deployed services, and initiates request role resolution. The incoming HTTP request is analyzed, and if it contains an Authorization header, the username and password are extracted. Resolved roles are stored into the request context and can be used later in the Online Services Component to check if access to the service should be allowed or not.
Currently, the HTTP Dispatcher cannot be used in MDM and access to the Admin Center cannot be restricted. |
Sample Http Dispatcher configuration
Click here to expand
<component disabled="false" class="com.ataccama.dqc.web.HttpDispatcher">
<listeners>
<listener name="console" port="8887" threads="5" ssl="false">
<contexts>
<listenerContext path="/">
<securityFilter class="com.ataccama.server.http.security.def.NoSecurity"/>
<filterChains>
<filterChain path="/*" filters="accessLog, securityResponseHeaders, securityFilter"/>
<conditions/>
</filterChains>
</listenerContext>
</contexts>
</listener>
<listener name="ssl" port="443" threads="5" ssl="true" keyStoreFile="c:/keystore" keyStorePassword="secret">
<contexts>
<listenerContext path="/">
<securityFilter class="com.ataccama.server.http.security.def.NoSecurity"/>
<filterChains>
<filterChain path="/*" filters="accessLog, loggingFilter, securityResponseHeaders, securityFilter"/>
</filterChains>
</listenerContext>
</contexts>
</listener>
</listeners>
<servletFilters>
<servletFilter name="accessLog" class="com.ataccama.dqc.web.filters.RequestResponseTimeLogger">
<headers>
<header>soapAction</header>
<header>host</header>
</headers>
<level>INFO</level>
<appendClientInfo>false</appendClientInfo>
</servletFilter>
<servletFilter name="loggingFilter" class="com.ataccama.dqc.web.filters.LoggingFilter">
<logFile>../logs/request.log</logFile>
<maxRequestLogSize>10000</maxRequestLogSize>
<maxResponseLogSize>10000</maxResponseLogSize>
<appendLog>false</appendLog>
</servletFilter>
<servletFilter name="securityResponseHeaders" class="com.ataccama.server.http.filters.ResponseHeadersFilter">
<headers>
<header name="Referrer-Policy" value="strict-origin"/>
<header name="Content-Security-Policy" value="default-src 'self'; style-src 'self' 'unsafe-inline'; connect-src 'self'; script-src 'self' 'unsafe-eval' 'sha256-LUuXJZWv+iqAoiEz+MR1HORFiNthxhltt8do2N6NPik=' 'sha256-/mbPbpM/5kbI0U1nQQaSnj/7MnXyUvjKw/L8Idja3aM=' 'sha256-p84Nz3iaL6DfouAdT0PYnH2faQMd0JnPZwbTGcMKruU=' 'sha256-x7+pkV1goejarh4RQD5Y42rGzOTq5Eua3ewQ05/JuII=' 'sha256-XOzDrAubQd8HYnvuIR+gLUroMdKPJpC815MJZALgsbY=' 'sha256-+31JvG/At7T/70nPaNMoqrnWyK9HknCKNU6QFh4BfHs='; img-src 'self' data:"/>
<header name="X-Permitted-Cross-Domain-Policies" value="none"/>
</headers>
</servletFilter>
</servletFilters>
</component>
The configuration has three different parts:
-
Filters (deprecated)
Listeners
The listeners
section defines listener threads that receive requests on the specified TCP ports and specifies if the listener should communicate via SSL or not.
It is possible to define several listeners, each of them accepting requests on a different TCP/IP port.
Each listener has the configuration parameters listed here.
- General configuration
-
-
name - Unique name that is used by other Server Components to identify the listener where the components should register its service handlers.
-
port - The TCP/IP port number where the listener accepts new requests.
-
threads - The maximum number of threads that are used to process incoming requests, that is, the maximum number of simultaneously processed requests.
-
maxWaitingRequests (optional) - The maximum number of requests waiting in the queue for an available thread. In case of too many requests that cannot fit into the queue, the HTTP code
503
is returned.If set to
0
, the requests wait indefinitely. If not defined, the default value10
is used. -
threadPoolTimeout (optional) - The maximum amount of time (ms) the server waits for a free thread that will handle the connection request. After the timeout expires, the server returns error code
408
: request timeout. -
contexts - Defines the behavior for individual context paths (security, filter chains, custom error pages).
-
keyManager (optional) - Key Manager Algorithm. Used in case SSL is enabled.
-
keyPassword - (optional) - Contains the password that is used for keyManager in case SSL is enabled. If left empty, it has the same value as KeyStorePassword. Can be encrypted.
-
keyStoreFile (optional) - Location of the file that contains the server certificate in case SSL is enabled.
-
keyStorePassword (optional) - Contains the password that is used to read the keyStoreFile in case SSL is enabled. Can be encrypted.
-
keyStoreType (optional) - Keystore type. Used in case SSL is enabled.
-
trustStoreFile (optional) - Location of the file that contains the certificates from certification authorities (CA) if SSL is enabled.
-
trustStorePassword (optional) - Contains the password that is used to read the trustStoreFile in case SSL is enabled. Can be encrypted.
-
servletOnly - If
true
, then the listener can be used only for new service handlers and cannot be used for online services, ONE Runtime Server Admin, and so on. -
ssl - Defines whether the listener communicates using the SSL (HTTPS) protocol or unsecured HTTP.
-
clientAuth - If
true
, mutual authentication (mTLS) between the server and the client is enabled. In that case, the connection is only accepted if the client’s SSL certificate or one of the intermediate certificate authorities can be validated against the server’s truststore.
-
- Advanced configuration
-
-
backlog (optional) - The maximum length of the OS-managed receiver queue of the server socket. If not defined, the default value
50
is used.An expert setting, relevant only for very specific cases. We do not recommend changing the value unless it’s done in consultation with Ataccama Support.
-
healthStateRecoveryTimeout - Set the amount of time before the server reports that it is not in good condition after the last incident. Default value:
300000
(ms). -
healthStateRefreshRate - Sets the time period during which the server tries to detect if there is a problem somewhere. Default value:
60000
(ms). -
waitingRequestsWarningThreshold - Allowed number of waiting requests. Default value is
1
, which means that more than one waiting requests issues a warning.
-
- Obsolete properties
-
-
handlerSecurity - No longer used, it stays in the component configuration for compatibility reasons. Use securityFilter to configure security instead.
-
Contexts
For each listener, you can define one or several contexts that contain specific settings for the listener:
-
path - Specifies the mapping location of the listener context.
-
filterChains - list filters through which the request should pass before getting to the server.
-
securityFilter - Specifies the security settings for the context.
-
htmlErrorPages - If
true
, it generates a user-friendly HTML error page that shows up in case an HTTP error code occurs (for example, 404 not found, 500 internal server error). Iffalse
, the user is provided with the default HTML error page.
Filter chains
Filter chains specify which filters (defined in servletFilters) should be used when accessing a location defined by the path and the conditions that trigger the filters.
In a filter chain, you can group multiple filters together and assign all of them to a specific location. The filters are evaluated in the order of appearance. Every request that goes through a filter is processed, validated, then the output is passed to the next filter and so on.
The response from the server goes back through the filters in the reverse order. If no filters are specified, requests go directly to the server.
We recommend placing the securityFilter as the last filter in the chain. |
-
conditions - Filters are applied only if all conditions are met. The following implementations are available:
-
inetAddressCondition - Tests if the requestor’s network address matches the address and network mask specified in the parameters
address
andmask
. -
requestHeaderCondition - Tests if the request header specified by
headerName
parameter matches the value in the parametervalue
orregexp
. -
requestParamCondition - Tests if the value of the request parameter specified by the
paramName
parameter matches the value in the attributevalue
orregexp
. -
soapActionCondition - Tests if the request is a SOAP request and the
SoapAction
value matches the value in the parametervalue
orregexp
.
-
-
filters - Comma-separated list of filters that should be applied to incoming requests. Use the names of filters that were defined in the servletFilters section. Use the securityFilter name to refer to the security filter for the context.
-
path - Mapping location of the filter chain.
Security filter
Each context contains a security filter definition that can be one of these types:
-
Keycloak Security - Authentication is managed by Keycloak (see Identity providers).
-
No Security (default) - Use if you do not wish to secure the server. There will be no authorization dialog and no security on the listener.
-
Xml Spring Security - Authentication is configured in an external XML file using the Spring framework. Generally not recommended as it has very specific use cases. It can be configured to behave as Keycloak.
Identity providers
The following settings are needed if you want to use Keycloak Security.
This setting is used to secure particular parts of the server by mapping the URL pattern to the client configuration for a particular client (app) accessing the server. The Keycloak client configuration can be defined either in a client adapter JSON file or inside the Runtime Configuration (see section Keycloak deployment connection). You can also combine both options in your solution.
Keycloak client configuration inside the runtime configuration file is available only for the applications running on the Ataccama server. Currently, it does not work with web applications. |
Depending on how you define your Keycloak clients, set the following parameters:
Client configuration in a .runtimeConfig
-
clientId - Specifies the Keycloak client configuration. Should correspond to the client id in the runtime configuration.
-
configName - Specifies the Keycloak configuration. Should correspond to the keycloakConfig name in the runtime configuration. The parameter is optional if there is only a single keycloakConfig defined in the runtime configuration.
-
pattern - The location on the server to which the client configuration (specified by clientId) applies, for example,
/**
. Patterns are evaluated top-to-bottom.
Client configuration in a .json
file
-
configFile - The path to the client adapter JSON file (for example,
keycloak.json
,keycloak-admin-center.json
). The path is relative to the server configuration file. -
pattern - The location on the server to which the client configuration (specified by configFile) applies, for example,
/**
. Patterns are evaluated top-to-bottom.
Intercept URLs
The setting maps URL patterns to the access conditions. It has the following parameters:
-
pattern - Specifies the location of the service to secure.
-
access - Specifies the access conditions to the endpoint specified by pattern. Uses Spring Security expression syntax. For example,
hasRole('roleName1') or hasRole('roleName2')
.
Patterns are evaluated in the order in which they are defined. Hence, the more specific patterns should be defined higher in the list than less specific patterns (in a top-down order). |
Sample security filter configuration
<securityFilter loginUrl="/sso/login" class="com.ataccama.server.http.security.keycloak.KeycloakSecurity">
<identityProviders>
<identityProvider configName="localKeycloak" clientId="one-admin-center" pattern="/**"/>
</identityProviders>
<interceptUrls>
<interceptUrl access="permitAll" pattern="/welcome/"/>
<interceptUrl access="hasRole('USER')" pattern="/licenses/"/>
<interceptUrl access="isAuthenticated()" pattern="/**"/>
</interceptUrls>
</securityFilter>
Servlet filters
The servlet filters section is used to define the actions that have to be done for each incoming request. One example of a filter is logging requests and responses, another is encrypting requests.
Specify a filter implementation and a name that will be used to refer to the filter in the listener context.
Logging filter
The logging filter enables the logging of incoming requests and responses. In the filter mapping part, you can select URL patterns that you want to log.
It is also possible to have multiple loggers at once, so different URLs can log requests to different files.
<servletFilter name="loggingFilter" class="com.ataccama.dqc.web.filters.LoggingFilter">
<logFile>../logs/request.log</logFile>
<maxRequestLogSize>10000</maxRequestLogSize>
<maxResponseLogSize>10000</maxResponseLogSize>
<appendLog>false</appendLog>
</servletFilter>
The filter in the example has the following properties:
-
logFile
- The file to log to. The file can contain date format parts in the${pattern}
form, wherepattern
follows the Java SimpleDateFormat class formatting. For example, defining the log file asrequest__${yyyyMMdd}.log
creates a new log file every day. -
appendLog
- Iftrue
, then when starting the server the contents oflogFile
are not removed. Otherwise, the contents are cleared. -
maskedHeaders
- Selected headers are masked with the masking string within the log file. -
maskingString
- Pattern of the string that is used for masking selected headers within the log file. By default, it is set to*****
. -
maxResponseLogSize
- The maximum size in bytes of the response logged; if the size of the response is bigger than this number, only the part up to the sizemaxResponseLogSize
is logged. -
maxRequestLogSize
- The maximum size in bytes of the request logged; see also the description formaxResponseLogSize
. IflogFile
contains date format part, that part is evaluated for every request and thus enables log rotation.
Reply with headers filter
The ReplyWithHeadersFilter copies the named header values from the request to the response. This is useful for request tracking in an SOA environment.
To configure the filter, list the headers that should be returned in the headers
section.
<filter class="com.ataccama.dqc.web.filters.ReplyWithHeadersFilter">
<headers>
<header>soapAction</header>
<header>User-Agent</header>
</headers>
</filter>
Request response time logger
The RequetsResponseTimeLogger
filter is used to log the amount of time that has been spent handling the incoming requests and responding to them.
This filter does not have any additional parameters except mappings
.
See How to Log Online Services for step by step instructions on how to log request and response times.
-
name
- Name of the logger that appears in square brackets in the log. -
level
- Severity level that is used forRequestResponseTimeLogger
messages, the default one is DEBUG. -
headers
- List of sub-elements each containing the HTTP header name that is printed together with the log message. -
appendClientInfo
- If set, the message includes the client IP address and port, the default value isfalse
.
Response headers filter
The responseHeadersFilter
adds specified headers to server responses that are processed with this filter.
For example, you can add security headers to improve security.
The filter has two parameters:
-
name
- The header name. -
value
- The header value.
All server components that communicate via the HTTP protocol are using the HTTP Dispatcher component, so security-related headers should be set by configuring this filter.
-
Create configuration for
ResponseHeadersFilter
(it adds all mentioned headers to each HTTP response that is processed with this filter).<servletFilters> <servletFilter name="responseHeaders" class="com.ataccama.server.http.filters.ResponseHeadersFilter"> <headers> <header name="Referrer-Policy" value="strict-origin"/> <header name="X-Permitted-Cross-Domain-Policies" value="none"/> <header name="Content-Security-Policy" value="default-src 'self'; style-src 'self' 'unsafe-inline'; connect-src 'self'; script-src 'self' 'unsafe-eval' 'sha256-LUuXJZWv+iqAoiEz+MR1HORFiNthxhltt8do2N6NPik=' 'sha256-/mbPbpM/5kbI0U1nQQaSnj/7MnXyUvjKw/L8Idja3aM=' 'sha256-p84Nz3iaL6DfouAdT0PYnH2faQMd0JnPZwbTGcMKruU=' 'sha256-x7+pkV1goejarh4RQD5Y42rGzOTq5Eua3ewQ05/JuII=' 'sha256-XOzDrAubQd8HYnvuIR+gLUroMdKPJpC815MJZALgsbY=' 'sha256-+31JvG/At7T/70nPaNMoqrnWyK9HknCKNU6QFh4BfHs='; img-src 'self' data:"/> </headers> </servletFilter> </servletFilters>
-
Add the filter to one or multiple filter chains (
filterChain
element) to specify for which requests it should be used. For a default configuration, add the filter to a filter chain mapped to the/*
path (that is, add it to all requests) and place it beforesecurityFilter
:<listenerBean .....> <contexts> <listenerContext path="/"> <filterChains> <securityFilter class=...../> <filterChain path="/*" filters="responseHeaders,securityFilter"/> <!-- other filter chain mappings --> </filterChains> <!-- other configuration --> </listenerContext> <!-- other contexts configuration --> </contexts> </listenerBean>
CORS response headers filter
For security reasons, you are not able to process cross-domain requests. This can cause problems when using services in web applications (for example, if your web application is running on one server and your API endpoint is on a different server). If this is the case, Cross Origin Resource Sharing (CORS) can be used.
Add the following configuration to the HTTP Dispatcher component and map the filter to the required endpoints.
<servletFilters>
<servletFilters>
<servletFilter name="CORSResponseHeaders" class="com.ataccama.server.http.filters.ResponseHeadersFilter">
<headers>
<header name="Access-Control-Allow-Origin" value="*"/>
</headers>
</servletFilter>
</servletFilters>
<filterChains>
<filterChain path="/nme-rest/*" filters="CORSResponseHeaders">
<conditions/>
</filterChain>
</filterChains>
Xslt transform filter
The XsltTransform
is used to apply XSL transformations to server requests and responses commonly needed for third-party SOAP integration.
-
requestTransformation
- Request XSL transformation filename. -
responseTransformation
- Response XSL transformation filename. -
poolMinimum
- The minimum size of the pool of XSL Transformers. Default value:1
. -
poolMaximum
- The maximum size of the pool of XSL Transformers. Default value:10
.
Filters
The filters
section is obsolete and should be ignored.
It stays in the HTTP Dispatcher configuration for compatibility reasons.
Use servletFilters
instead.
Was this page useful?