PEP for Apache HTTP server

This page covers features that are specific to the Policy Enforcement Point written in C (CPEP) for Apache HTTP Server. For general properties describing PEP, please refer to the corresponding section. CPEP is built on a single shared codebase, which serves both Apache HTTP Server and IIS. However, each architecture has its own set of specific features and configurations. Currently, we provide support for Apache HTTP Server on Windows, Red Hat Linux 8, Red Hat Linux 9, and SUSE Linux Enterprise 15. For information about IIS-specific features, please refer to the dedicated IIS CPEP page.

Supported version of Apache HTTP server for Windows is 2.4.51 and higher, because CPEP binary expects OpenSSL version 3.0 and higher.

Installation

CPEP is distributed as a zip archive, where there is an installation guide (installation.txt) for each architecture. Here the installation process will be described in general, for specific information for the given architecture, please refer to this file. The archive also includes a configuration file (dirxaccess.conf), a CPEP binary (mod_dxa_pep.so) and boost libraries (boost_context-<vc-version>-mt-x64-<boost-version>.dll and boost_url-<vc-version>-mt-x64-<boost-version>.dll), where <vc-version> and <boost-version> can differ depending on the version of the CPEP.

Stop the Apache HTTP Server process.
Copy the CPEP binary (mod_dxa_pep.so) into the <apache_root_directory>\modules directory.
1. Make sure the path specified after the LoadModule command in the dirxaccess.conf file is correct.
Copy the boost libraries
1. Windows: (boost_context-<vc-version>-mt-x64-<boost-version>.dll and boost_url-<vc-version>-mt-x64-<boost-version>.dll) into the <apache_root_directory>\bin directory.
2. Linux: If you do not have the required Boost version installed, do one of the following:
  1. Update LD_LIBRARY_PATH to include the directory containing the Boost .so files from the provided archive:
    
    export LD_LIBRARY_PATH=/path/to/boost/libs:$LD_LIBRARY_PATH
  2. or Copy the .so files into a standard library directory (e.g., /usr/lib64 or /usr/local/lib64)
Add following configuration to the dirxaccess.conf file:
- {client_id}
  - The configuration identifier of the “Apache HTTP server” PEP type in the DirX Access configuration.
- {dirx_access_services_hostname}
  - The hostname of the DirX Access Server instance to fetch the PEP remote configuration for the first time, e.g my-server1.my-company.example.
- {dirx_access_services_port}
  - The port of the DirX Access Server instance to fetch the PEP remote configuration for the first time, e.g. 11111.
- {dirx_access_services_port_ssl}
  - The SSL port of the DirX Access Server instance to fetch the PEP remote configuration for the first time, e.g. 11112.
- A description of all configuration parameters can be found in the Configuration section.
Generate the sec-comm.client.p12 keystore to enable secure communication between the PEP and DirX Access Server instances.
1. Find the dxaCryptoGenerateKeystoreSecCommClient.json template within the DirX Access <installation_directory>\Services\templates\instance\etc\templates\sysactions
2. Recall the issuer of the “Keystore Crypto Container” of the respective server port assignment of the {dirx_access_services_port_ssl} SSL port of the server. A description of Port Assignment configuration can be found at:
  1. Port Assignment
  2. Port Assignments
3. Use the same issuer in the dxaCryptoGenerateKeystoreSecCommClient.json template.
4. Choose and remember the keystore password of the dxaCryptoGenerateKeystoreSecCommClient.json template. The same password will be applied at the step 5).
5. You can choose from two options:
  1. (Preferred) Apply the template to the <installation_directory>\Services\instances\<instance_name>\startup directory of the running instance and restart the instance (sec-comm.client.p12 will be located in c:\Users\Administrator\Downloads)
  2. Go to the DirX Access Manager -> System actions -> Keystore management -> Generate keystore and apply the configuration of the template here.
Copy the generated sec-comm.client.p12 keystore to the desired location
1. open dirxaccess.conf file and set both {client.keystore.filename} and {sec-comm.client_keystore_password} accordingly.
Copy the modified dirxaccess.conf file to the <apache_root_directory>\conf directory.

It is expected that the root configuration file (httpd.conf / apache2.conf) contains:

### DirXAccess Start ###

Include <apache_root_directory>\conf\dirxaccess.conf

### DirXAccess End ###

Configuration

The following parameters express local configuration options. The parameters should be part of dirxaccess.conf file referenced by httpd.conf file (main Apache httpd configuration file).

Parameter name Description Mandatory Default Value

client.id

DirX Access PEP configuration identifier that will be used to download the remote PEP configuration.

false

DirX Access PEP

server.primary.host

DirX Access primary server hostname or IP that will be used to download the remote PEP configuration and cluster information.

false

127.0.0.1

server.primary.port

DirX Access primary server communication port that will be used to download the remote PEP configuration and cluster information.

false

11111

server.primary.port.ssl

DirX Access primary server (TLS/SSL) communication port that will be used to download the remote PEP configuration and cluster information.

false

11112

server.primary.config.port

This parameter is valid only when server.primary.port is not set. It must be used if the configuration and sso interfaces run on a different port. It specifies port for the REST configuration API. PEP downloads the remote configuration from there.

false

server.primary.config.port.ssl

Same as previous, but for (TLS/SSL) communication.

false

server.primary.config.path

Specifies the context path to the REST configuration API. Must start with ‘/’.

false

/odata4/config/1_0_0

server.primary.sso.port

Same as server.primary.config.port, but for the SSO REST API.

false

server.primary.sso.port.ssl

Same as server.primary.config.port.ssl, but for the SSO REST API.

false

server.primary.sso.path

Same as server.primary.config.path, but for the SSO REST API.

false

/odata4/sso/1_0_0

server.secondary.host

Same as server.secondary.host but for the secondary server.

false

server.secondary.port

Same as server.secondary.port but for the secondary server.

false

server.secondary.port.ssl

Same as server.secondary.port.ssl but for the secondary server.

false

server.secondary.config.port

Same as server.primary.config.port but for the secondary server.

false

server.secondary.config.port.ssl

Same as `server.primary.config.ssl`but for the secondary server.

false

server.secondary.config.path

Same as `server.primary.config.path`but for the secondary server.

false

/odata4/config/1_0_0

server.secondary.sso.port

Same as server.primary.sso.port but for the secondary server.

false

server.secondary.sso.port.ssl

Same as server.primary.sso.port.ssl but for the secondary server.

false

server.secondary.sso.path

Same as server.primary.sso.path but for the secondary server.

false

/odata4/sso/1_0_0

client.keystore.filename

The keystore file relative path to be able to establish TLS/SSL communication with DirX Access server - (TLS/SSL) communication port.

false

client.keystore.passphrase

The keystore passphrase use for TLS/SSL communication with DirX Access server.

false

cluster.update.timeout.secs

The time interval (in seconds) the PEP downloads the fresh information about the servers in cluster.

This value can affect server performance. If you don’t need a quick config update, consider setting it to a very high value or use 0 to disable it.

false

60

server.reintegration.timeout.secs

Obsolete. See Reintegration of an unavailable server for more information.

false

120

server.operation.timeout.secs

Timeout for socket I/O calls.

false

15

server.operation.retry.count

Number of retries to the same DirX Access server after request failure.

false

3

client.shm.path

Defines where shared files are created. Path must be writeable for the apache run user.

false

ServerRoot configuration parameter for Apache HTTP server or module location for IIS HTTP server.

Multi-Processing Modules (MPMs)

Not only the CPEP setting itself affects its properties. For better performance of CPEP, it is a good idea to adjust the settings of the MPM module. In order to ensure that the Apache HTTP server runs efficiently across various platforms, it includes a set of MPM (Multi-Processing Module) modules. These modules are responsible for binding to network ports, accepting requests, and dispatching child processes to handle the requests.

Different MPM modules can lead to significant variations in the behavior of the server. For Windows, the mpm_winnt module is supported, which is based on pure thread parallelism and has lower memory requirements.

For Linux, there are three variants of MPM modules available: Event, Worker, and Prefork. Event and Worker modules are similar and use a combination of processes and threads, while the Prefork module only uses processes. All of these implementations take advantage of process isolation, but using processes results in higher memory requirements. Currently, only the mpm_prefork version is supported for Linux implementations.

Configuration of the MPM module might affect the performance of CPEP implementation. For the best performance we recommend to follow this tutorial: Apache HTTP Server Performance Tuning

Architecture

In Figure 1, we can see how CPEP works inside the HTTP server. When a request arrives at the server, it is automatically captured by the CPEP module, which then selects the corresponding server based on the cookie contained in the request or according to the round-robin algorithm. Then it sends a Perform SSO request to the selected server. Following this, the DXA Server verifies whether the given user has access to the requested resource and responds accordingly. Based on the response, CPEP then forwards the request to other modules, which will handle the transfer of the appropriate client resource in case of successful authorization, or, in case of unsuccessful authorization, sends the result of the query directly to the client.

Figure 1. Server processing request, when using CPEP module

Logging

Logging settings are derived from the value after the LogLevel command in the root configuration file (httpd.conf/apache2.conf).

Specific features

URL Rewriting

A preferred way to provide SSO functionality in Web environments is to use HTTP cookies to exchange (references for) the required authentication information between subsequent requests that try to access. This method requires the client to allow/accept cookies from the PEP and enable the PEP by setting the PEP option Enable HTTP cookie to true. See the chapter “Administrative Tasks - Managing Configuration Data - Managing Policy Enforcement Points” in the DirX Access Administration Guide for more details.

If the PEP configuration option Enable HTTP cookie is set to false, the PEP will not return cookies to the client in the responses of the HTTP request, and thus, the session token generated after a successful authentication cannot be transported this way to subsequent requests to provide SSO functionality.

Additionally, even if the Enable HTTP cookie is set to true in the PEP configuration, but the HTTP client does not support cookies or has prohibited them (which the PEP does not know in advance), the setting of cookies in the HTTP response will not be stored and re-transmitted in follow-up requests from the client.

To provide SSO functionality, the session token must be appended somewhere else in the response output of the targeted resource. This output is typically either the content of a static web page, content that is generated dynamically by an application (for example, PHP, CGI, and so on), or a redirection to the actual resource after a successful authentication (for example, via form-based authentication).

There is currently no support for “static” targets like Web pages without any dynamic content, as this would require on-the-fly analysis and modification of the resulting response of such static Web pages.

C-PEP Approach

Because of the technical differences to the Java environment (Servlet specification), the support for URL rewriting in C PEPs relies on a Web application, which means that the necessary information (session token) is provided to the Web application by “forwarding” the information to the Web application via request header. However, the dynamic application remains responsible for modifying the dynamic URLs by appending the session token to provide SSO. The following forwarding rules apply:

The forwarding does not occur if the PEP receives a session token cookie in the request header.
The forwarding occurs if the PEP detects the session token from the received URL or the received body.
The forwarding occurs after a successful generation/reuse of a session token (that is, after a successful authentication/authorization).

The forwarded session token is added to the HTTP request header in the format:

<CookieName> : <session token>

For example:

DXASESSIONIDMYCOMPANY : eyJ4LXBhcnQiOjI0MiwiYWxnIjoiUlMyNTYiLCJ4NXQjUzI1NiI6Imd5Tnl3MldKLVc5Q0pEeWdXaVVZbjJQdGxUYnZ3R0JQTXBBNGk5ejM1a1kifQ.eyJhdWQiOiJEaXJYIEFjY2VzcyBNeS1Db21wYW55IENsdXN0ZXIiLCJzdWIiOiJBcnQgVGFoaXIiLCJpc3MiOiJEaXJYIEFjY2VzcyBNeS1Db21wYW55IENsdXN0ZXIiLCJzZXNzaW9uRXhwIjoxNzI1MjYwNDcwNjk5LCJhc3N1cmFuY2VMZXZlbCI6IjUiLCJzZXNzaW9uSWQiOiI5MTAtZ2J0ZGUtcWt0bW1najZ5aXZiNGZkZ25hNHd4YXlnNXZhMzZmYndldjZvaTVsMmQ3anF6bGdvaGg1Nm8iLCJhdXRobk1ldGhvZHMiOiJGb3JtIEF1dGhlbnRpY2F0aW9uIiwiYXV0aG5UaW1lIjoiMTcyNTI1Njg3MDY2MiIsImV4cCI6MTcyNTI1NzQ3MCwiaWF0IjoxNzI1MjU2ODcwLCJqdGkiOiJxdHpsdHkycXcycm1nM3lyY2ZjcjQzZHJrZndidzMzdmJxam5rdjdjaXM3YjZ1d3o0ZzVzdmFoaWNycGR3Mm9hM2VmcTZmZWZnZ2JvZTZuZ3BidnV5ZGVhdGJ6YnppcnhyM2pmY3VpIn0.q4Sea9Ume_tFKFvUh3Y4JQHY-GV1x2jFFR8U3j6D6n0WXQ-d3-2eqOAK0vLgvaHbcIfaH274-_NlkkeOTnbu4lJkmWkPS0Vt9XD8IXkIf0LFSKmdesbGOKJ-DLpVUEI5x-CAYJ7lYehZ06C0tDnXcFZ1xVevSLBLVU4q5pTTLcbdilm6tBMJHc3At02jEQ9ERQz5PeeQ99RCeLZLpCctsg2Hr84Ii-3AIaDQXwikN5vE_F2cS55E-Fb-5MQrZM5VW8-dLFmt77HFoyt7bkdMMVdef4hPWze9pGDDgvRws9Q3nMKBdZsaIdhZpkVTwMeLlmkVtKE1Z0-fVgcM9HegNg

The is defined by the field Cookie name in corresponding PEP configuration object.

The dynamic Web page or its Web application retrieves this information from the HTTP request header and if present, appends it to all URLs it writes to the generated response output and for which SSO shall be provided; for example, like this:

<a href="intranet/home.html?DXASESSIONIDMYCOMPANY=eyJ4LXBhcnQiOjI0MiwiYWxnIjoiUlMyNTYiLCJ4NXQjUzI1NiI6Imd5Tnl3MldKLVc5Q0pEeWdXaVVZbjJQdGxUYnZ3R0JQTXBBNGk5ejM1a1kifQ.eyJhdWQiOiJEaXJYIEFjY2VzcyBNeS1Db21wYW55IENsdXN0ZXIiLCJzdWIiOiJBcnQgVGFoaXIiLCJpc3MiOiJEaXJYIEFjY2VzcyBNeS1Db21wYW55IENsdXN0ZXIiLCJzZXNzaW9uRXhwIjoxNzI1MjYwNDcwNjk5LCJhc3N1cmFuY2VMZXZlbCI6IjUiLCJzZXNzaW9uSWQiOiI5MTAtZ2J0ZGUtcWt0bW1najZ5aXZiNGZkZ25hNHd4YXlnNXZhMzZmYndldjZvaTVsMmQ3anF6bGdvaGg1Nm8iLCJhdXRobk1ldGhvZHMiOiJGb3JtIEF1dGhlbnRpY2F0aW9uIiwiYXV0aG5UaW1lIjoiMTcyNTI1Njg3MDY2MiIsImV4cCI6MTcyNTI1NzQ3MCwiaWF0IjoxNzI1MjU2ODcwLCJqdGkiOiJxdHpsdHkycXcycm1nM3lyY2ZjcjQzZHJrZndidzMzdmJxam5rdjdjaXM3YjZ1d3o0ZzVzdmFoaWNycGR3Mm9hM2VmcTZmZWZnZ2JvZTZuZ3BidnV5ZGVhdGJ6YnppcnhyM2pmY3VpIn0.q4Sea9Ume_tFKFvUh3Y4JQHY-GV1x2jFFR8U3j6D6n0WXQ-d3-2eqOAK0vLgvaHbcIfaH274-_NlkkeOTnbu4lJkmWkPS0Vt9XD8IXkIf0LFSKmdesbGOKJ-DLpVUEI5x-CAYJ7lYehZ06C0tDnXcFZ1xVevSLBLVU4q5pTTLcbdilm6tBMJHc3At02jEQ9ERQz5PeeQ99RCeLZLpCctsg2Hr84Ii-3AIaDQXwikN5vE_F2cS55E-Fb-5MQrZM5VW8-dLFmt77HFoyt7bkdMMVdef4hPWze9pGDDgvRws9Q3nMKBdZsaIdhZpkVTwMeLlmkVtKE1Z0-fVgcM9HegNg">Financial Management</a>

This action transports the session token to the next request if the client selects the corresponding link. Notes:

If the HTTP client has sent a session token cookie, it means that the client allows/supports cookies and therefore the session token cookie will also be present in subsequent requests from the client. In this case, URL rewriting is unnecessary.
The forwarding is independent from the Enable HTTP cookie configuration option. This method makes it easier for the dynamic application, as it is only necessary to look for the session token header, and if present, add it to the URLs.

Reintegration of an unavailable server

While CPEP is running, there may be DXA Server outages due to errors or overload. Since CPEP is connected directly to the servers without a load balancer, it needs to be able to react to server unavailability in order to avoid sending requests to a server that is unable to handle them.

The parameters set for CPEP are crucial in this regard, specifically server.operation.retry.count and server.operation.timeout.secs. The retry count determines how many consecutive failed attempts there are before the server is marked as unavailable. On the other hand, the server operation timeout specifies how long it takes to wait for the request to be processed before it is marked as failed. In addition, the number of concurrently running workers in the Apache HTTP server also affects the mechanism.

Let’s consider two possible scenarios. In one scenario, the server is overloaded and fails to process the request at times. Under heavy load, a large number of workers will run concurrently to process multiple requests. In such a case, the failure of multiple workers can lead to a significant increase in the number of failed attempts. Hence, a high Retry Count parameter is desirable under heavy load.

In the second scenario, on the contrary, only one user uses the server, so the workload is small, but there is a real outage of one of the servers. In such situations, we want the Retry Count to be as low as possible, because each failure incurs a certain amount of time, as specified by server.operation.timeout.secs. With more retries, the user would likely give up sending the request before CPEP marks the server as unavailable.

For this reason, the Retry Count is calculated based on the time elapsed since the first failure. The shorter the time, the greater the number of failures must be for the server to be marked as unavailable. The calculation takes into account the server.operation.retry.count, server.operation.timeout.secs, and ServerLimit set for the MPM module.

In case the server was mistakenly marked as unavailable (e.g., the retry count was exceeded due to a short-term outage), it is retried every server.operation.timeout.secs seconds.

We can see that server.reintegration.timeout.secs is not needed anymore because unavailable server is retried every server.operation.timeout.secs seconds.

Performance

See PEP for Apache HTTP Server - Performance.