Configure the DirX Identity Business User Interface with DirX Access Policy Enforcement (PEP)

This chapter describes all configuration steps required to configure BUI to work with DirX Access Policy Enforcement (DXA PEP).

The DirX Access PEP enable an authentication and authorization layer above any web application. For this scenario, DXA PEP acts as a security layer for DirX Identity REST services application, and the BUI needs to provide a security token (cookie) to access these services.

DirX Access PEP Environment
Figure 1. DirX Access PEP Environment

Configure DirX Access with Policy Enforcement Points (PEP)

This guide is for DirX Access version 9.x and for this use case, DXA PEP is configured only for authentication purposes, because DXI REST services implements its own the authorization layer and authorization features from DXA are not used.

Starting DirX Access Services

Following Windows/Linux services are required for this scenario:

  • Start DirX Directory

The DirX Directory must contain DirX Access configuration and a repository with DirX Identity Business User Interface users.

  • Start “DirX Access Services domain” service (e.g., DirX Access Services My-Company).

  • Start “DirX Access domain LoadBalancer” service (e.g., DirX Access My-Company LoadBalancer). This service needs to be start if DirX Access is configured with load balancer).

  • Start “DirX Access Extensions Apps” - optional - This step is optional and starts additional DXA application that can be used to check and test different DXA features.

Configure DirX Access for PEP

The DXA configuration is available through a web interface, DXA console.

  • Open in the web browser (recommended: Google Chrome) the DXA console. The access URL should be similar with:

http(s)://dxa_server.dxa_domain:dxa_port/console/ManagementFrameSet

For DXA Demo server this URL is:
http://my-server.my-company.example:10114/console/ManagementFrameSet

  • Authenticate to DXA console (default DXA console credentials are: dirxaccesadmin/dirxaccess).

  • Create and configure port assignments

    • Navigate to Servers→Port Assignments

    • Create or duplicate new port assignments

    • Save changes.

  • Create a new DXA server or duplicate an existing one

    • Navigate to Servers→Server list

    • Create a new DXA server (top-right button, above the server list table)

    • Configure DXA server:

      • “Identifier “- mandatory - DXA server identifier

      • “Description “- optional - DXA server description text

      • “Cache IP address (local)” - mandatory - DXA IP address

      • “Server hostname” - mandatory - DXA server hostname

      • “Port assignment identifiers” - mandatory - Set port assignment identifiers (from Port Assignments list available top-right in Selectable objects tab)

  • Check and validate users list

    • Navigate to Users→List

    • Check if users are available, connection to DirX Directory is working.

    • If the list is not available, check settings in Configuration→User repository

  • Configure Request injection

    • Navigate to Subjects→Request injection

    • Create a new Request injection item (top-right button)

    • Set following attributes

      • “Identifier” - mandatory - Set to X_FORWARDED_USER for DXI REST service value.

      • “Description” - optional - Set to “Required field by DXI REST service for authentication”

      • “Type” - mandatory - Set to HttpRequestHeader

      • “Keyword” - mandatory - Set to X_FORWARDED_USER - this field will be available to DXI REST service after a successful authentication

    • “Keyword value separator” - mandatory - Set to “=”

      • “Request injection value template identifier” - mandatory - Set to LoginName

    • Save or update changes

  • Create DirX Access PEP

    • Navigate to Configuration→Policy Enforcement Pointes→Deployable Web

    • Create a new PEP or duplicate and existing configuration (for Tomcat 9),

    • Set following values:

      • “PEP Type” - mandatory - Set to Tomcat 9.0

      • “Identifier” - mandatory - Set to Tomcat 9.0 DXI REST services. This value will be used as a handler in Tomcat server configuration for connector and valve setup.

      • “Description” - optional - Set to Tomcat 9.0 PEP configuration for DXI REST services 8.10

    • Open Client settings

      • Use SSL/TLS - optional - Set to true to use SSL/TLS encrypted communication between DXA PEP and DXA server.

    • Open PEP settings

      • “Authority” - mandatory - This is a handler for current PEP and server configuration, and format is a string: domain:port, (e.g. my-company:8080).

      • “Common extensions to exclude” - optional - This is a list of web resources excluded from authentication process (e.g. gif, jpg, png, html, etc.).

      • “Other extensions to exclude” - optional - Extension of the above list. Add js and json values to this list.

      • “Authorization failed URL” - mandatory - This URL is used to redirect to a failed authentication. This page must exist to Tomcat server and must display the failed authentication message due to insufficient rights to use the DXA service (this is not and invalid or incorrect username or password message). E.g. /my-company/not_authorized_error.html.

      • “Request injection templated identifier” - mandatory - Add X_FORWARDED_USER for DXI REST services from the list (select from right tree).

If the identifier is not available in the list, then restart DXA services.
The tree may not work correctly with some web browsers (e.g. Mozilla Firefox).

  • Open Web PEP settings

  • Set following values:

    • “Enable HTTP cookie” - mandatory - Set to true.

    • “Cookie name” - mandatory - Set the cookie name, e.g. DXAIDMYCOMPANY

    • “Cookie domain” - mandatory - Set the cookie domain, e.g. .my-company.example.

    • “Enable URL rewriting” - mandatory - Set to true.

    • “Form authentication enabled” - optional - Set to true.

    • “Do process HTTP request parameters to extract custom data” - optional - Set to true.

    • “Set no-cache header” - optional - Set to true.

  • Open Web PEP deployments settings

  • Set following values:

    • “File system folder for PEP deployment” - mandatory - This is the path where DXA will deploy the PEP configuration and PEP implementation. These files must be copied (recommended approach) to the Tomcat with DXI REST services configuration: DXA_PEP_DEPLOYMENT_FOLDER (e.g. C:\Program Files\Tomcat90\My-Company BUI)

    • “File system folder for client keystore deployment” - optional/mandatory for SSL - This is the path where DXA will deploy the keystore for SSL communication between PEP and DXA server: DXA_PEP_DEPLOYMENT_FOLDER/conf (e.g. C:\Program Files\Tomcat90\My-Company BUI/conf).

    • “Update Apache Tomcat Server configuration” - mandatory - Set to true.

    • “Apache Tomcat version” - mandatory - Set to Tomcat90.

Is preferrable to manually copy the PEP configuration and PEP jar files to the DXI REST services deployment server.

  • Save or update changes

  • IMPORTANT: Deploy (manually copy) the PEP configuration.

  • RECOMMENDED: Restart DXA services.

Deploy DXA PEP to Apache Tomcat 9.0

These changes are for DXI REST services application server

  • Stop Apache Tomcat (service or application)

  • Backup Apache Tomcat conf folder

  • Backup Apache Tomcat lib folder

  • Copy to Apache Tomcat lib folder, the PEP jar files from location where DXA deployed the PEP implementation: DXA_PEP_DEPLOYMENT_FOLDER>\lib (e.g. c:\Program Files\Tomcat90\My-Company BUI\lib\)

Apache Tomcat lib folder, not to DXI REST services lib folder.

  • Copy to Apache Tomcat conf folder the PEP configuration files from location where DXA deployed the PEP configuration: DXA_PEP_DEPLOYMENT_FOLDER>\conf (e.g. c:\Program Files\Tomcat90\My-Company BUI\conf\)

  • Navigate to Apache Tomcat conf folder and open server.xml file.

  • Search for ClientId keyword and check and/or change values:

    • “ClientID” - This id must be the same with DXA PEP configuration.

    • “ClientKeystoreFilename” - Check if path to keystore is correct.

    • “ServerPrimaryHost” - DXA server host name, check if is correct.

    • “ServerPrimaryPort “- DXA server port, check if is correct.

    • “ServerPrimaryPortSSL” - DXA SSL server port, check if is correct.

  • Search for Connector keyword and check and/or change values:

  • “keystoreFile” - Check if path to keystore is correct.

  • Save changes to server.xml.

  • Don’t Apache Tomcat yet.

Configure DirX Identity REST Services with DXA PEP

The DXI REST services requires to enable security configuration for DXA PEP. This file is available in DXI REST services deployment folder:

dxi_install_path\restServices\DirXIdentityRestServices\DirXIdentityRestService-domainy\WEB-INF\authenticationSamples

  • Stop Apache Tomcat (service or application)

  • Navigate to DXI REST services deployment folder (e.g. dxi_install_path\restServices\DirXIdentityRestServices\DirXIdentityRestService-domainy\WEB-INF).

  • Backup security.xml.

  • Copy authenticationSamples\security-dirxaccess.xml file to WEB-INF folder and rename it to security.xml.

  • Open security.xml and check principalRequestHeader value, must be X_FORWADED_USER.

This value is set in DXA PEP configuration, to Request injection, the name from DXA PEP and from security.xml must be same.

  • Save security.xml changes

  • Backup security.properties.

  • Open security.properties and comment line:

  • auth.userDetails.valuePattern = ^CN=(.*?),".

  • Save security.properties changes.

  • Start Apache Tomcat (service or application).

Configure DXI Identity Business User Interface with DXA PEP

These settings are for communication between BUI and DXI REST services, DXA PEP configuration is available in server.xml in Apache Tomcat.

  • Open Business User Interface configuration file: *config.json*.

  • Search for dxaPepAuthServer section.

  • Set communication protocol between DXI REST services and BUI: http or https.

  • Set DXI REST services host name (e.g. dxi-server.my-company.example)

  • Set DXI REST services port (e.g. 8080)

  • Set DXI REST services domain (e.g. /DirXIdentityRestService)

  • Set DXI Logout path (e.g. http://dxi-server.my-company.example:8080/my-company/logoutAction)

  • Enable DXA PEP as authentication option

  • In Security→Authentication and DXA_PEP to available list.

    Position in authentication methods list is considered. If DXA_PEP is the last option, DXA PEP authentication method will be listed at the end of the available authentication options in the Business User Interface login page.

  • Reload Business User Interface application (refresh the page).