If you can't find the product or version you're looking for, visit support.ataccama.com/downloads

HTTP 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. From this version, if you are using the new MDM Admin Center, you can set the permissions to full access or read-only in the application properties.

For more information, see MDM Server Application Properties, section Admin Center permissions.

For MDM old Admin Center and RDM Admin Center, you can set permissions using the requiredRole property in the Web Console component. For details, see Web Console Component.

Sample Http Dispatcher configuration (v14.5.0)

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>

Sample Http Dispatcher configuration (v14.5.1 and later)

Click here to expand

<component disabled="false" class="com.ataccama.dqc.web.HttpDispatcher">
    <listeners>
        <listenerBean healthstateRefreshRate="60000" maxWaitingRequests="10" backlog="50" waitingRequestsWarningThreshold="1" port="8889" threadPoolTimeout="10000" healthStateRecoveryTimeout="300000" name="default" threads="10" servletOnly="false" ssl="false" clientAuth="false">
            <contexts>
                <listenerContext path="/" htmlErrorPages="false">
                    <filterChains>
                        <filterChain path="/*" filters="securityFilter">
                            <conditions/>
                        </filterChain>
                    </filterChains>
                    <securityFilter class="com.ataccama.server.http.security.keycloak.KeycloakSecurity">
                        <identityProvider configFile="keycloak.json" roleMapping="realm_access.roles"/>
                        <interceptUrls>
                            <interceptUrl access="hasRole('ADMIN')" pattern="/console/**">
                            <interceptUrl access="isAuthenticated()" pattern="/**"/>
                        </interceptUrls>
                    </securityFilter>
                </listenerContext>
            </contexts>
        </listenerBean>
    </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:

Listeners
Servlet filters
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 value 10 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).
publicUrl - The URL where the listener is available. Should be set when the listener is behind a reverse proxy as in that case, the host, port, and protocol might differ from the listener configuration. You can also set only the port, in which case the host is determined from the request and the protocol remains the same as in the listener configuration.
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). If false, 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 and mask.
- requestHeaderCondition - Tests if the request header specified by headerName parameter matches the value in the parameter value or regexp.
- requestParamCondition - Tests if the value of the request parameter specified by the paramName parameter matches the value in the attribute value or regexp.
- soapActionCondition - Tests if the request is a SOAP request and the SoapAction value matches the value in the parameter value or regexp.
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.

From 14.5.1, this setting is obsolete and only one identityProvider element is allowed (see Sample Http Dispatcher configuration (v14.5.1 and later)).

For backward compatibility, the server still starts if the configuration contains the identityProviders setting as long as the following conditions are met:

Only one identityProvider element is specified within it.
The identityProvider uses the default pattern (/**).

Otherwise, the server does not start and the following error message is logged: Field identityProviders is now deprecated. Please use identityProvider instead.

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:

Starting from 14.5.1, if Keycloak properties are loaded from keycloak.json or the runtime configuration, only the following properties are taken into account: resource (the client ID in Keycloak), realm, auth-server-url, credentials, secret( for authenticating to Keycloak clients).

Other properties (such as ssl-required and confidential-port) are ignored.

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.

Obsolete from 14.5.1. The pattern attribute can still be present in the configuration for backward compatibility purposes as explained earlier in this article.

roleMapping - Applies starting from 14.5.1. Determines how roles are retrieved from Keycloak. Default value: realm_access.roles (used if no value is set in the server configuration).

Make sure the following options are set in Keycloak Admin Console:

In Client Scopes > [role], on the Settings tab, select Include in Token Scope.
In Client Scopes > Mappers > [realm roles]:
- Enable Add to ID token and Add to user info.
- Check whether Token Claim Name matches the value of roleMapping.

To verify your setup, you can navigate to Clients > [your client ID] > Client Scopes > Evaluate > [user] and select Evaluate. The sections Generated ID Token and Generated User Info should contain the necessary roles.

If you start the server with incorrect settings, the same instructions are available in the server log.

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.

Obsolete from 14.5.1. The pattern attribute can still be present in the configuration for backward compatibility purposes as explained earlier in this article.

roleMapping - Applies starting from 14.5.1. Determines how roles are retrieved from Keycloak. Default value: realm_access.roles (used if no value is set in the server configuration).

Make sure the following options are set in Keycloak Admin Console:

In Client Scopes > [role], on the Settings tab, select Include in Token Scope.
In Client Scopes > Mappers > [realm roles]:
- Enable Add to ID token and Add to user info.
- Check whether Token Claim Name matches the value of roleMapping.

If you start the server with incorrect settings, the same instructions are available in the server log.

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 (v14.5.0)

<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(&#39;USER&#39;)" pattern="/licenses/"/>
        <interceptUrl access="isAuthenticated()" pattern="/**"/>
    </interceptUrls>
</securityFilter>

Sample security filter configuration (v14.5.1 and later)

<securityFilter class="com.ataccama.server.http.security.keycloak.KeycloakSecurity">
    <identityProvider configName="localKeycloak" clientId="one-admin-center" roleMapping="realm_access.roles"/>
    <interceptUrls>
        <interceptUrl access="permitAll" pattern="/welcome/"/>
        <interceptUrl access="hasRole('USER')" pattern="/licenses/"/>
        <interceptUrl access="isAuthenticated()" pattern="/**"/>
    </interceptUrls>
<!-- <usePlatformDeployment>rdm</usePlatformDeployment> -->
</securityFilter>

Use platform deployments

Applies from 14.5.1. Used to enable different security settings on different endpoints on the server, which is typically needed for RDM in cloud deployments.

In this case, InternalJWT authentication is applied to internal communication between ONE modules. The value of the element must match the value of the name attribute of the platformDeployment element, defined in the runtime configuration.

The setting is preconfigured and no user action is needed.

<usePlatformDeployment>rdm</usePlatformDeployment>

Handler security

The property is obsolete and should be ignored. It stays in the component configuration for compatibility reasons.

Use securityFilter instead.

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, where pattern follows the Java SimpleDateFormat class formatting. For example, defining the log file as request__${yyyyMMdd}.log creates a new log file every day.
appendLog - If true, then when starting the server the contents of logFile 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 size maxResponseLogSize is logged.
maxRequestLogSize - The maximum size in bytes of the request logged; see also the description for maxResponseLogSize. If logFile 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 for RequestResponseTimeLogger 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 is false.

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 before securityFilter:

<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?