Cloud Foundry PEP

The DirX Access Cloud Foundry Policy Enforcement Point (PEP) is intended to protect Cloud Foundry Web applications with respect to all possible requests. The PEP is designed to act as a request filter with rich configuration options, much like other DirX Access PEPs. It is based on Cloud Foundry Route Service⁶ and is written as a Spring Boot Application⁷.

The PEP can delegate authentication either to a third-party authentication application or to the DirX Access Authentication Application. The PEP supports authorization and request injection functionality.

Flow

The following figure illustrates how each request is processed.

attachments/att++_++15++_++for++_++110526498

Figure 1. Cloud Foundry PEP Request Processing Flow

Interception

The main feature of the PEP is the interception of all requests. It is noteworthy to stress that the filtering is applicable to all requests and resources, which means that all resources (images, css, icons) are protected.

Cookie Existence Check

The PEP checks whether there is a cookie with the DirX Access Session identifier. Cookies can be issued in two ways:

An Authentication Application resides in the same domain as Cloud Foundry PEP:
- A cookie with the DirX Access Session identifier is issued directly by the Authentication Application after successful authentication.
An Authentication Application resides in different domain as Cloud Foundry PEP:
- It does not make sense for the Authentication Application to issue a cookie with the DirX Access Session identifier because the browser will not use such a cross-domain cookie. Instead, the Authentication Application places the DirX Access Session identifier into an HTTP request parameter and a cookie is created by the PEP itself.

Session Parameter Existence Check

The PEP checks if there is a DirX Access Session identifier in a defined HTTP request parameter. The PEP seeks the identifier in HTTP request body parameters for an HTTP POST request and in HTTP request query parameters for an HTTP GET request.

Session Validity Check

A session coming from a cookie is checked for validity against the DirX Access Restful Client Services. The rest call is protected via TLS and is sent to the locally configured DirX Access Services container address. For more information about DirX Access Restful Client Services, see the “Client Services” section in the DirX Access Administration Guide.

Authorization

A previously authenticated user is checked whether he is authorized to access the requested resource. This check is backed by a call against DirX Access Restful Client Services. Actual authorization decision making is driven by standard DirX Access configuration for this purpose. For more information, see “General PEP Settings” section in the DirX Access Administration Guide.

Request Injection

DirX Access Restful Client Services provide a feature to get session data from the DirX Access Server. The feature is used to insert the data into HTTP request headers coming to the protected application. This action enables passing user data or DirX Access Server related information into the protected application. For more information, see the section “Request Injection-based External Subject Representations” in the DirX Access Administration Guide.

Requirements

The PEP is written in Java 8 and packaged as a self-executable JAR file for the Cloud Foundry framework.

The package is located in DirXAccessInstallFolder/PolicyEnforcementPoints/CloudFoundry.

The location also contains manifest.yml file which is necessary for Cloud Foundry deployment and provides sample bootstrap configuration.

Configuration

The configuration can be separated into the bootstrap configuration, the TLS configuration and additional configuration steps.

Bootstrap Configuration

The bootstrap configuration is required to be set for proper PEP functionality in manifest.yml file.

ENV_PEP_IDENTIFIER

The identifier determines a PEP configuration located in a DirX Access Services container. The PEP does not have to be a Cloud PEP type if you don’t want to download additional configuration. See the section “Additional configuration” for details.

ENV_ADMINISTRATOR_LOGIN_NAME

The login name is used to access DirX Access Restful Client Services (Configuration, Sessioning, AuthorizationDecision and RequestInjection).

ENV_ADMINISTRATOR_PASSWORD

The obfuscated password is used to access DirX Access Restful Client Services.

ENV_DXA_SERVICES_URL

The location of DirX Access Services container is used to build all DirX Access Restful Client Services locations. TLS configuration must be set if HTTPS is used.

TLS Configuration

If HTTPs is used to access DirX Access Restful Client Services, at least one of the following items must be included in the manifest.yml file:

ENV_TRUST_ANY_DXA_SERVICES

The Boolean value may be set to true if there is no way to use HTTP to the DirX Access Services container and there is a technical reason not to set a trusted certificate. This configuration is intended for testing purposes only! The default value is false.

ENV_TRUST_DXA_SERVICES_CERTIFICATE

The trusted X.509 certificate8 to be set if you want to use HTTPS connection to the DirX Access Services container. The string value should be in Base64 format (DER certificate without “—–BEGIN CERTIFICATE—–” and “—–END CERTIFICATE—–”).

Additional Configuration

Additional configuration is either downloaded from the DirX Access Server or can be located in the manifest.yml file. The first option requires the Cloud Foundry PEP type configuration to be entered; in particular, DirX Access Server. The second option is available for older DirX Access versions which do not support the Cloud PEP type.

ENV_DOWNLOAD_CONFIGURATION

The Boolean value enables/disables the configuration download from the DirX Access Services container. This is usable for old DirX Access versions but adds the requirement to enter additional configuration in manifest.yml file instead of DirX Access Manager. The default value is true.

ENV_AA_URL

The intercepted requests are redirected to this Authentication Application location if the user is not authenticated. The PEP also supports third-party authentication applications if the following prerequisites are satisfied (the same requirement applies for the DirX Access Authentication Application):

The third-party authentication application understands authentication target URL parameter name and this name corresponds to the name specified in the additional configuration.
The third-party authentication application can issue a cookie or session parameter name and the names correspond to the names specified in the additional configuration.

ENV_AUTHN_TARGET_URL_PARAMETER_NAME

The authentication target URL parameter name is intended for an authentication application and the parameter (in case of a redirect to an authentication application) contains the location to redirect back to from the authentication application after a successful authentication.

ENV_COOKIE_NAME

The configuration contains a name of a cookie where the DirX Access Session identifier is stored for session-long usage.

ENV_COOKIE_DOMAIN

The configuration contains a cookie domain for a cookie to be created if the DirX Access Session identifier is received in the Session parameter. For more information, see the “Session Parameter Existence Check” section.

ENV_ENABLE_SESSION_QUERY_PARAMETER

The Boolean value must be set to true if the authentication application sends the DirX Access Session identifier (URL rewriting) in the HTTP GET request query string. The default value is false.

We recommend sending the session identifier in the HTTP POST request body.

ENV_SESSION_PARAM_NAME

The configuration contains a session parameter name for a parameter which is used for the transfer of a DirX Access Session identifier. The parameter name should be chosen with respect to the authentication application in use.

ENV_AUTHORIZATION_FAILED_PATH

The configuration contains a custom page to be redirected to if authorization fails (authenticated user is not authorized to access the requested resource). This configuration item is not mandatory and there is a default page to be shown if this configuration item is not set.

ENV_LOGOUT_ACTION

The configuration contains a specification of a logout action path. This configuration item is not mandatory and logout action is not active if this configuration item is not set. The default value is null. The session is terminated upon accessing the matching URL.

ENV_LOGOUT_TARGET_URL_PARAMETER_NAME

The configuration contains a custom page to be redirected to after the logout procedure is complete. This configuration item is not mandatory and there is a default page to be shown if this configuration item is not set.

ENV_RESOURCE_EXCLUSION_EXTENSION_FILTER

The configuration allows excluding particular file extensions from the PEP filtering. Separate excluded extensions (without the dot) with commas (,). For example: gif,css,jpg

This configuration item is not mandatory and no extension is excluded if this configuration item is not set. For more information about PEP exclusions, see “Configuring Common PEP Settings” in the DirX Access Administration Guide.

ENV_RESOURCE_EXCLUSION_FULL_PATH_FILTER

The configuration allows excluding full paths from the PEP filtering. Separate excluded full paths with commas (,). For example: /root/intranet/travel.html, /root/intranet/liability.html

ENV_RESOURCE_EXCLUSION_BEGIN_PATH_FILTER

The configuration allows excluding paths from the PEP filtering if the path is prefixed with one of the prefixes contained in this comma-separated list. For example: /root/intranet/,/root/extranet/

ENV_RESOURCE_EXCLUSION_END_PATH_FILTER

The configuration allows excluding paths from the PEP filtering if the path is suffixed with one of the suffixes contained in this comma-separated list. For example: error.html,logout.html,tnastyle.css

Deployment

This section contains instructions to be followed to deploy DirX Access Cloud Foundry PEP into a Cloud Foundry provider and set particular routes for proper functionality.

Prerequisites

Deployment of the PEP has the following prerequisites:

The Cloud Foundry provider account is created⁹.
The command line tool (CLI) is installed¹⁰.
Authentication to the Cloud Foundry provider API, organization and space has been performed.

Instructions

In order to automate the deployment process as much as possible, the DirX Access installation directory contains the aforementioned Cloud Foundry manifest.yml file.

The manifest.yml file should contain a path¹¹ to dirx.access.pep.cloud-foundry-.jar and at least the bootstrap configuration. For more information about configuration, please see the “Configuration” section.

To deploy DirX Access PEP into Cloud Foundry, run the following command in the same directory as manifest.yml file:

$ cf push

To delete it from a Cloud Foundry, run the following command:

$ cf delete cloud-foundry-pep -r

Route Service

A user-provided service must be created to contain the route service information. The service must be created after the DirX Access Cloud Foundry PEP is successfully deployed.

Substitute the address that a route service (already deployed PEP) is listening on:

$ cf create-user-provided-service pep-route-service -r https://<ROUTE-SERVICE-ADDRESS>

To delete the service:

$ cf delete-service pep-route-service

Protecting a Cloud Foundry Application

This action assumes two prerequisites:

The DirX Access Cloud Foundry PEP is already running and the route service has been created.
An application to be protected is already running and you know its location (its domain and host name).

Commands:

To protect an application (bind to the route service), run the following command. Substitute the domain and host name of the application to be protected:

$ cf bind-route-service <APPLICATION-DOMAIN> pep-route-service --hostname <APPLICATION-HOST>

For example, an application running on http://wro-php-app.apps.eu01.cf.canopy-cloud.com/:

$ cf bind-route-service apps.eu01.cf.canopy-cloud.com pep-route-service --hostname wro-php-app

To unbind an application:

$ cf unbind-route-service <APPLICATION-DOMAIN> pep-route-service --hostname <APPLICATION-HOST>

Logging

The PEP contains the logback.xml configuration for logging configuration.

To start logging from the console:

$ cf logs cloud-foundry-pep