Skip to content

User Documentation

Jump to bottom Edit New page
julianzz98 edited this page Mar 9, 2022 · 2 revisions

About deegree security proxy (DSP)

The deegree security proxy (DSP) is lightweight security framework for protecting OGC Web Services against unauthorised access using the Spring Security framework.

Technical Requirements

The deegree security proxy requires Spring 3.2 with Spring Security 3.1 as a minimum and also requires Java SE 6 or higher. It can be installed on every Java EE 5 compliant web container such as Apache Tomcat 6.x. The deegree security proxy provides protection against unauthorised access for OGC Web Services such as WMS, WMTS, WCS, WFS, WPS, CSW served by deegree, GeoServer, MapServer, or any other blackbox system which is compliant to the OGC standards.

License

deegree security proxy is distributed under the GNU Affero General Public License, Version 3.0 (AGPL).

Permission is granted to copy and distribute this document and / or modify it under the terms of the GNU Free Documentation License, Version 1.3 or any later version, published by the Free Software Foundation; without immutable Sections with no front cover texts and no back cover texts. The license is available from http://www.gnu.org/licenses/fdl-1.3.

© Copyright 2014-2022 lat/lon - Gesellschaft für raumbezogene Informationssysteme mbH info@lat-lon.de http://www.lat-lon.de/ Im Ellig 1, 53343 Wachtberg, Germany

Features

Feature List

The following list gives an overview on the high-level features implemented by the DSP:

  1. deegree security proxy supporting authentication mechanism
  • The DSP supports several authentication mechanism.
  1. Support for Http-Basic authentication
  • The DSP supports HTTP BASIC authentication with username and password.
  1. Support for pre-authentication
  • The DSP supports pre-authentication scenarios where a user has been pre-authenticated in any other security provider and a security token has been added to the HTTP header.
  1. Support for WCS 1.0.0
  1. Support for POST KVP/XML encoding WCS 1.0.0
  • The DSP supports POST KVP/XML encoding for WCS 1.0.0.
  1. Support for WMS 1.3.0
  1. Configuration of available layers
  • The DSP supports the declaration of available/ non-available layers for WMS.
  1. Support for spatial restrictions on WMS Layers
  • The DSP supports spatial restrictions on WMS layers.
  1. Support for rewriting LegendURL value of GetCapabilities response
  • The DSP supports rewriting of LegendURL valued for WMS GetCapabilities responses.
  1. Support for WFS 1.1.0
  1. Support for CSW 2.0.2
  1. Support for WPS 1.0.0
  1. Support for WPS response manipulation on GetCapabilities operation
  • The DSP supports to apply response filter on “GetCapabilities” requests to eliminate not granted processes in the Capabilities document.
  1. Support for restriction on execute operation for WPS
  • The DSP supports to block requests on not granted processes in context of “Execute” requests.
  1. Support for request validation of WPS requests
  • The DSP supports request validation for WPS.
  1. Support for access restriction on DescribeProcess operation for WPS
  • The DSP supports to block request on DescribeProcess operation for not granted processes.
  1. Support for users, groups, roles, rights and resources stored in database
  • The DSP supports users, groups, roles, rights and resources stored in database.
  1. Support for unbounded number of OWS instances
  • The DSP supports to manage theoretically an unbounded number of OWS and unbounded number of user access roles per OWS. The number of supported background services depends on the hardware resources provided and influences the non-functional requirement for Performance.
  1. Write logs into database
  • The DSP supports writing of logs into a database.
  1. Content of logs for OWS requests
    * The DSP supports to log the following contents of OWS requests:
  • all requests: request user account IP address date and time of request type of request service request duration.
  1. Support for restrictions on service operations
  • The DSP supports restrictions on specific OGC services operations specified within the privileges for each user.
  1. Support for hiding service location
  • The DSP supports hiding of original service location for secured services.
  1. Logging of request duration
  • The DSP supports logging of duration of requests.
  1. Support for request validation
  • The DSP supports validation of incoming requests and only valid requests are forwarded to the remote OWS.

Implemented requirements (detailed overview)

  1. [OWS-Firewall_110] - Support of and Compliance to OGC Standards
  • The DSP supports the following services and service operations:
  • Services: * Web Map Service (WMS), Version 1.3.0
    • Service operations:
    • GetCapabilities
    • GetMap
    • GetFeatureInfo * Web Coverage Service (WCS), Version 1.0.0
    • Service operations:
    • GetCapabilities
    • DescribeCoverage
    • GetCoverage * Web Feature Service (WFS), Version 1.1.0
    • Service operations:
    • GetCapabilities
    • GetFeature
    • DescribeFeature * Catalog Service for Web (CSW), Version 2.0.2
    • Service operations:
    • GetCapabilities
    • GetFeature
    • DescribeFeature * Web Processing Service (WPS), Version 1.0.0
    • Service operations:
    • GetCapabilities
    • Execute
    • DescribeProcess
  1. [OWS-Firewall_011] - Support configurable error message
  • The DSP supports a configurable error message in XML format. The file is located in the file system of the host where the component is installed. The path to the file is configurable. The encoding is UTF-8 the mime type is for WCS 1.0.0 "application/vnd.ogc.se_xml" and compliant to ServiceExceptionReport as specified in appendix "A.6 Service exception schema" in  OpenGIS Web Coverage Service (WCS) Implementation Specification 1.0.0 (03-065r6).
  1. [OWS-Firewall_020] - Request Forwarding
  • The DSP supports to forward (pre-)authorized requests from outside to the internal (underlying) geodata servers.
  1. [OWS-Firewall_030] - Response Forwarding
  • The DSP supports to pass through all outgoing responses (as processed from the underlying geodata servers). This ensures that there is one and only one gate visible to the outside world.
  1. [OWS-Firewall_040] - User Management
  • The DSP supports to read from an existing access control database schema.
  1. [OWS-Firewall_050] - User Management Details
  • The DSP supports Users, groups, privileges, filters which are stored in a user management DB.
  1. [OWS-Firewall_054] - Domain type SpatialResponseFilter
  • The DSP supports a SpatialResponseFilter having a geometry defined as a WKT Polygon or Multipolygon.
  1. [OWS-Firewall_060] - User Database
  1. [OWS-Firewall_070] - Configuration interface
  • The DSP supports a REST interface for managing the service.
  1. [OWS-Firewall_080] - Filter Capability for WCS
  • The DSP supports user-specific filters for request and response processing. The filter are restricted to OGC WCS 1.0.0.
  1. [OWS-Firewall_081] - GetCapabilities Response Filter for WCS
  • The GetCapabilities response filter removes all coverages and operations that are not granted to the requesting user from the GetCapabilities response returned by the underlying WCS service.
  1. [OWS-Firewall_082] - GetCoverage Response Filter for WCS
  • The GetCoverage response filter applies a clipping mask as defined in the database as a MultiPolygon whenever a requested extend intersects with the clipping geometry by applying the 'NODATA' value stored in the image or '0' by default on all bands. The filter returns the geometry which is the result out of a difference operation between request bbox and clipping geometry in the HTTP response header as as WKT (Well Known Text) string with the element name "request_area" (the CRS shall epsg:4326).
  • The filter does not modify the geotiff header tags as provided by the geodataserver which has produced the image.
  1. [OWS-Firewall_090] - Filter Details for WCS
  • The DSP supports for WCS the following filter formats:
  • GetCoverage response filtering the following formats: GeoTiff Standard (compressed) 1bit, 8bit, 16bit, and 32bit.
  • GetCapabilities filtering: text/xml
  1. [OWS-Firewall_100] - Firewall Capacity
  • The DSP supports managing theoretically unbounded number of OWS and unbounded number of user access roles per OWS. The number of supported background services depends on the hardware resources and influences the non-functional requirement for Performance.
  1. [OWS-Firewall_110] - Interoperability with OGC-compliant SW
  • The DSP supports only OGC-compliant requests and background services.
  1. [OWS-Firewall_120] - Access denied exception
  • The DSP raises an exception if access to a resource is denied. The exception is in XML format and compliant OGC standards. Further requirements on format and encoding are supported for the list of OWS services as in [OWS-Firewall_110].
  1. [OWS-Firewall_121] - Support for pre-authentication
  • The DSP supports pre-authentication scenarios where a user has been pre-authenticated by the existing NGINX gateway server and the user can be identified by a HTTP header element 'access_token'.
  1. [OWS-Firewall_130] - OGC Compliance of Forwarded Requests
  • The DSP supports validation of incoming requests against the OWS service protocol XSD and furthermore the outgoing requests to the background services must be OGC-compliant and therefore validation against OWS service protocol XSD shall be enabled by configuration. Schema validation for both shall be independently enabled/disabled by configuration.
  1. [OWS-Firewall_140] - Logging
  • The DSP creates machine-readable and comprehensible log messages. The deegree security proxy has a enhanced logging mechanism based on a configurable Apache log4j 1.2 logging sub-system.
  • References:
  • http://logging.apache.org/log4j/1.2/
  1. [OWS-Firewall_150] - Configuration based logging mechanism
  1. [OWS-Firewall_151] - OWS ows_securityproxy_log table
  • The DSP logs the following properties to the ows_securityproxy_log table:
  • column ID - generated ID
  • column SERIAL_UUID - set by application
  • column LEVEL - log level set by application
  • column MESSAGE - comma separated list of
  • authenticated request (yes/no)
  • authorized (yes/no)
  • which filter applied
  • which request (OWS operation)
  • requested area (bounding box)
  • area after clipping (bounding box)
  • constraints:
  • ID and SERIAL_UUID are UNIQUE
  • Composite Primary Key consists out of ID and SERIAL_UUID
  1. [OWS-Firewall_152] - Add serial_uuid to HTTP header in response
  • The DSP creates a unique ID (GUID/UUID) with java.util.UUID at the time when the HTTP incoming request is received. And adds this UUID to the HTTP header with name serial_uuid when sending the response back to the requesting client/server.
  1. [OWS-Firewall_160] - Performance
  • The DSP was desinged to add less than 30% to the overall response time. The impact on the System Performance depends on hardware resources. The following terms are used:
  • response time - The time between the submission of a request and the completion of the response.
  • service time - The time between the initiation and completion of the response to a request.
  • think time - The time the user is not engaged in actual use of the processor.
  • wait time - The time between the submission of the request and initiation of the response.
  • latency - The time that one system component spends waiting for another component in order to complete the entire task. Latency can be defined as wasted time. In networking discussions, latency is defined as the travel time of a packet from source to destination.
  • throughput - The number of requests processed per unit of time.
  • concurrency - The ability to handle multiple requests simultaneously. Threads and processes are examples of concurrency mechanisms.
  • scalability - The ability of a system to provide throughput in proportion to, and limited only by, available hardware resources. A scalable system is one that can handle increasing numbers of requests without adversely affecting response time and throughput.
  • The goal is to tune the deegree security proxy component for response time (not for throughput!). Because response time equals service time plus wait time, the service time of the deegree security component is compared to the response time of a request send to the target service directly (without the deegree security proxy as an intermediary).
  1. [OWS-Firewall_170] - Support for high-availability
  • The DSP is designed to support high-availability 24/7.
  1. [OWS-Firewall_190] - Extensibility
  • The DSP has a modular and extendable design. The DSP supports a very straight forward way to extend the system. The systems architecture provideds hooks and extension points for expanding/enhancing the system with anticipated capabilities without having to make major changes to the whole system. Adding a OWS protocol security filter is be possible by adding an implementation (JAR artifact) and changing in the central system configuration.
  1. [OWS-Firewall_200] - Platform compatibility
  • The DSP is compatible with
  • OS: Ubuntu LTS 10.04, 12.04 (Ubuntu Server / 64bit)
  • Java SE: 6, 7, 8 (Oracle JVM, OpenJDK / 64 bit)
  • Java EE: 5, 6, 7 web profile (Apache Tomcat 6.0.35 or higher, 7.0.x, 8.0.x)

Using

The DSP supports the following usage scenarios:

Environment

US01: Setup and installation

The DSP can be setup and installed with Puppet or Docker in any OS (host or VM) which provides at least Java SE 6.

The test environment is a virtual machine with:

  • guest OS as specified in [OWS-Firewall_200] The virtual machine is set up with Puppet containing
  • a database as specified in [OWS-Firewall_060]
  • a JVM as specified in [OWS-Firewall_200]
  • a Servlet Container as specified in [OWS-Firewall_200]

Monitoring

US03: Simple Logging Facade for OWS

As a geodata provider I want to log all requests towards a OWS services so that I can retrieve from the log database the information who has accessed which operation of the OWS service.

Steps:

  • A client sends a OWS request towards the DSP which logs all access as specified in [OWS-Firewall_140] and [OWS-Firewall_150]
  • The incoming request is forwarded to the remote OWS as specified in [OWS-Firewall_020] and [OWS-Firewall_130]
  • The outgoing response is forwarded to the requesting client as specified in [OWS-Firewall_030] and [OWS-Firewall_130]
  • The requests are logged specified in [OWS-Firewall_151]

Simple Security Filter

US04: Simple Security Filter for OWS

As a geodata provider I want to protect all requests towards a OWS services so that restrict access to authenticated users.

Steps:

  • The DSP checks if a incoming request contains a valid access token as specified in [OWS-Firewall_121]
  • The incoming request is routed over the gateway server (intermediary)
  • The DSP evaluates the header attribute access_token and checks if the token is valid against the database table user_access_info
  • In case the token is valid * Then the incoming request is forwarded to the target OWS * The outgoing response is forwarded to the requesting client via the intermediary
  • In case the token is invalid * An error message as specified in [OWS-Firewall_011] and [OWS-Firewall_120] is returned

US05: Extended Security Filter on OWS requests

As a geodata provider I want to use a security filter for all incoming requests towards a OWS services so that defined privileges are evaluated at runtime.

Steps:

  • The DSP SecurityFilter evaluates the
  • accesstoken and username to retrieve a Privilege from the DB as defined in [OWS-Firewall_050]
  • serial_uuid is added to response and is written to log table as defined in [OWS-Firewall_152]
  • User-specific Privileges are retrieved from the User-Management DB as defined in [OWS-Firewall_040]

Protecting WCS

US06: Response Filter for WCS GetCoverage requests

As a geodata provider I want to use a clipping security filter for all GetCoverage responses received from WCS services so that the returned image can be manipulated depending on the defined graphical filter.

Steps:

  • The DSP SecurityFilter evaluates for
  • GetCoverage requests only
  • The response filter supports image formats in GetCoverage response as defined in [OWS-Firewall_090]
  • Then the clipping filter is applied as defined in [OWS-Firewall_082]
  • The manipulated image is returned to the requesting client.

Protecting WMS

US07: Simple Security Filter for WMS protocol

As a geodata provider I want to protect all requests towards a WMS 1.3.0 services so that only authenticated users can access the back-end service.

Steps:

  • A client sends a request towards a WMS and the DSP as the intermediary.
  • If a client sends a valid WMS request (GetCapabilities, GetMap, GetFeatureInfo) towards the DSP
  • then the DSP evaluates the authentication token and retrieves the privileges from the User-Management DB
  • and forwards the request to the target back-end service.
  • In case the authentication token is invalid or the request is invalid the DSP return an error message as defined in error message as specified in [OWS-Firewall_011] with a valid ServiceException as specified in the OGC WMS 1.3.0 spec.
  • ServiceException shall have code="InvalidRequest"
  • For all requests an entry in the system log table ows_system_log.ows_access_log is created

US09: Filter on layer level for GetMap requests

As a geodata provider I want to protect GetMap requests towards a WMS services so that restrict access to authenticated users.

Steps:

  • As in US07
  • Only granted layers can be accessed by authenticated users.

US10: Support security check on access time interval

As a geodata provider I want to protect all requests towards a WMS services so that restrict access to authenticated users.

Steps:

  • As in US07
  • Access is only granted when current time is inside subscription time.

US11: Filter on layer level for GetCapabilities response

As a geodata provider I want to protect GetCapabilites responses to filter operations and layers.

Steps:

  • As in US07
  • Optional operations of the response are filtered depending on column ogc_layer_service_operation_type_name.
  • Layers of the response are filtered depending on column service_layer_name.

US12: Clipping Filter for WMS GetMap requests

As a geodata provider I want to use a clipping security filter for all GetMap responses received from WMS 1.3.0 services so that the returned image can be manipulated depending on the defined graphical filter.

Steps:

  • The SecurityFilter evaluates for GetMap requests only
  • User-specific Privileges are retrieved from the User-Management DB as defined in [OWS-Firewall_060] and [OWS-Firewall_040]
  • The request is forwared to the remote WMS in case the user has granted privileges to access the target service
  • The response filter shall support image formats in GetMap response: png or jpeg
  • Then the clipping filter is applied: user_layer_limited_to-column
  • The manipulated image is returned to the requesting client.

Protecting WPS

US13: Simple Security Filter for WPS protocol

As a geodata provider I want to protect all requests towards a WPS 1.0.0 services so that only authenticated users can access the back-end service.

Steps:

  • If a client sends a valid WPS request (GetCapabilities, DescribeProcess, Execute) towards the DSP
  • then the DSP evaluates the authentication token and retrieves the privileges from the User-Management DB
  • and forwards the request to the target back-end service.
  • In case the authentication token is invalid or the request is invalid the DSP return an error message as defined in error message as specified in [OWS-Firewall_011] with a valid ServiceException as specified in the OGC WPS 1.0.0 spec.
  • ServiceException shall have code="InvalidRequest"
  • For all requests an entry in the system log table ows_system_log.ows_access_log is created

US14: Response filter for WPS GetCapabilities

As a geodata provider I want to filter a WPS GetCapabilites of the underlying back-end service responses so that the response document contains only the processes that have been granted to the requesting user.

Steps:

  • If a client sends a valid WPS request and
  • when a user with valid credentials (username+password or session_token) executes a GetCapabilities request against a WPS than
  • The section contains only elements where the user has granted permissions for
  • Processes are filtered depending on column ows_system_admin.user_access_info.service_layer_name.

US15: Restrict access to WPS DescribeProcess and Execute operations

As a geodata provider I want to restrict the access to the WPS operations DescribeProcess and Execute so that only those processes can be executed where the requesting user has privileges for.

Steps:

  • If a client sends a valid WPS request and
  • When a user with valid credentials (username+password or access_token) executes a DescribeProcess or Execute (optional HTTP GET method using KVP) operation against a WPS than
  • the request is forwarded only if the user has privileges for the requested process.
  • Permissions for a process are stored in the column ows_system_admin.user_access_info.service_layer_name.

US16: Support for HTTP POST method using XML encoding for WPS Execute operation

As a geodata provider I want to restrict the access to the WPS operation Execute so that only those processes can be executed where the requesting user has privileges for.

Steps:

  • If a client sends a valid WPS request and
  • When a user with valid credentials (username+password or access_token) executes the WPS Execute operation with HTTP POST method using XML than
  • the request is forwarded only if the user has privileges for the requested process.
  • Permissions for a process are stored in the column ows_system_admin.user_access_info.service_layer_name.

Protecting WFS

US17: Simple Security Filter for WFS

As a geodata provider I want to protect all requests towards a WFS 1.1.0 services so that only authenticated users can access the back-end service.

Steps:

  • If a client sends a valid WFS request (GetCapabilities, GetFeature, DescribeFeature) towards the DSP
  • then the DSP evaluates the authentication token and retrieves the privileges from the User-Management DB
  • and forwards the request to the target back-end service with session ID.
  • In case the authentication token is invalid or the request is invalid the DSP return an error message as defined in error message as specified in [OWS-Firewall_011] with a valid ServiceException as specified in the OGC WFS 1.1.0 spec.
  • ServiceException shall have code="InvalidRequest"
  • For all requests an entry in the system log table ows_system_log.ows_access_log is created

Client Integration with WAS

US18: DSP provides WAS Interface

As a geodata provider I want to use the DSP to authenticate users within client applications using a GDI NRW WAS-compliant interface (v1.1).

Steps:

  • When a user requests access to a protected resource within a client application such as a geoportal
  • The client can access the WAS-compliant interface of the DSP and the
  • supporting the operations are:
  • GetSession
  • CloseSession
  • DescribeUser
  • to authenticate a user either by
  • username/password or
  • token
  • in case the credentials are valid the DSP returns a session ID.

Building

System requirements

To build DSP you need:

  • Oracle or OpenJDK 1.6 or higher
  • Apache Maven 3.0.5 or higher

To run DSP you need:

  • Oracle or OpenJDK 1.6 or higher
  • A web container supporting Servlet API 2.5 or higher (for example Apache Tomcat 6.0.35 or higher)

Building from source

Clone the deegree-securityproxy repository:

% git clone https://github.com/lat-lon/deegree-securityproxy.git

Clone the j2ep repository:

% git clone https://github.com/lat-lon/j2ep.git

j2ep is reverse proxy which can be run within a webcontainer such as Apache Tomcat. deegree-securityproxy uses j2ep as a dependency.

Build order:

  1. Build j2ep: mvn clean install
  2. Build deegree-securityproxy: mvn clean install

Configuration

Before deploying there are several steps to take. First of all set up a database. Second set environment variables to configuration folder proxy_config. Third the configuration file must adopteded to the currently used environment.

Create configuration

The DSP is diveded into three parts. This means there are three artifacts required to install the DSP within in webcontainer:

  1. j2ep
  2. deegree-securityproxy
  3. configuration artifact

This configration artifact dsp-configuration-$VERSION-uat.zip contains all project specific configurations and other customization of DSP.

Set up database

Navigate to folder /$DSP_CONFIG/sql and execute the DDL script `create_table.sql on the `ows_system_log` schema (for Postgresql). This table is used to store the log messages. Alternativly it is possible to use any database (requires adjustment on the DDL script).

Set environment variables

The environment variable proxy_config must be set. The variable must point to the folder dsp-distribution-$VERSION/proxy_config . For example exporting the variable works by enter:

% export PROXY_CONFIG="$PATH/dsp-distribution-$VERSION/proxy_config"

in a command line interface (bash).

Adjust configuration files

In folder $PATH/dsp-distribution-$VERSION/proxy_config exists several configuration files.

  • clipping_failed_exception : Set the Exception text of the response body which is set in case of failed clipping.
  • config.properties : This is the main config file. Set paths to the exception files. Here you configure what http response code is given when authentication/authorization failed. The database connection is configured (driver, url, username, password). This must point to the ows_access_control database (customer database).
  • config xml : This is j2ep configuration. Set the url, which the proxy redirect to.
  • log4j.properties : Set the logging properties and change log level. The logging includes requests of the user and responses of the system. The logging is saved in a database (DB appender). It is nessacary that the logger points to the database ows_access_control. The general logging is written in a log file (file appender).
  • ogc_wcs_100_serviceexception : Set the Exception text of the response body which is set in case of the proxy denied to redirect the request.

Main config file (config.properties)

This is the main config file. In the following the properties are explained in detail:

  • The database connection is configured (driver, url, username, password). This must point to the ''ows_access_control'' database (customer database):
jdbc.driver=org.postgresql.Driver
jdbc.url=jdbc:postgresql://localhost:5432/ows_access_control
jdbc.username=postgres
jdbc.password=postgres
  • Set paths to the exception files. Here you configure what http response code is given when authentication/authorization failed:
common-exception-file-path=/path/to/exception/ogc_ows_200_serviceexception.xml
common-exception-status-code=400

wms_exception_file_path=/path/to/exception/ogc_wms_130_serviceexception.xml
wms_authentication_denied_status_code=401
wms_authorization_denied_status_code=403

wms_clipping_exception_file_path=/path/to/exception/wms_clipping_failed_exception.xml
wms_clipping_failed_status_code=500

wcs_exception_file_path=/path/to/exception/ogc_wcs_100_serviceexception.xml
wcs_authentication_denied_status_code=401
wcs_authorization_denied_status_code=403

wcs_clipping_exception_file_path=/path/to/exception/wcs_clipping_failed_exception.xml
wcs_clipping_failed_status_code=500

wps_exception_file_path=/path/to/exception/ogc_wps_100_serviceexception.xml
wps_authentication_denied_status_code=401
wps_authorization_denied_status_code=403
  • The DCP URLs in the Capabilities can be configured for POST and GET to replace the one from the original Capabilities document. If the configuration parameters are missing, the DCP URLs of the service are not replaced and the original DCP URLs are returned:
wms_dcp_url_get=http://deegree-securityproxy/services?
wms_dcp_url_post=http://deegree-securityproxy/services

wcs_dcp_url_get=http://deegree-securityproxy/services?
wcs_dcp_url_post=http://deegree-securityproxy/services

wps_dcp_url_get=http://deegree-securityproxy/services?
wps_dcp_url_post=http://deegree-securityproxy/services
  • Additional parameters can be configured as comma separated list. The values of this parameters are read from the database and passed as further parameters of the forwarded request to the server. The column name in the database and forwarded request parameter must have the same name:
additional_request_parameters=contract_id

  • KVP parameter: ''contract_id=''

  • The name of the header field that contains the token that is the result of a pre-authentication:

access_token_header_field_name=access_token

j2ep configuration (config.xml)

This is the j2ep configuration. Usually the proxy redirects to the service url from the database. The service url from the database is stored as header field in requests forwarded to the j2ep. In case the header field is missing or empty (e.g. if the service url field is empty) j2ep forwards to the url configured in this configuration file. Example config.xml:

```
<?xml version="1.0" encoding="UTF-8"?>
<config>
  <server className="net.sf.j2ep.servers.BaseServer" 
          domainName="devcloud.domain.com"
          path="/wcs/service"
          isRewriting="true">
    <rule className="net.sf.j2ep.rules.DirectoryRule" 
          isAppendTrailingSlash="false"
          directory="/wcs" />
  </server>
</config>
```

Exceptions mapping to OGC Service Excpetion Report

Exception files referenced in [#mainConfigFile main config file]:

  • ogc_ows_200_serviceexception.xml: Set the Exception text of the response body which is set in case the service type is missing or not supported.
  • ogc_wcs_100_serviceexception.xml: Set the Exception text of the response body to WCS 1.0.0 requests which is set in case of the proxy denied to redirect the request.
  • ogc_wms_130_serviceexception.xml: Set the Exception text of the response body to WMS 1.3.0 requests which is set in case of the proxy denied to redirect the request.
  • ogc_wps_100_serviceexception.xml: Set the Exception text of the response body to WPS 1.0.0 requests which is set in case of the proxy denied to redirect the request.
  • wcs_clipping_failed_exception.xml: Set the Exception text of the response body to WCS requests which is set in case of failed clipping.
  • wms_clipping_failed_exception.xml: Set the Exception text of the response body to WMS requests which is set in case of failed clipping.

Logging (log4j.properties)

Set the logging properties and change log level. The logging includes requests of the user and responses of the system. The logging is saved in a database (''DB appender''). It is nessacary that the logger points to the database ''ows_access_control''. The general logging is written in a log file (''file appender'').

Deployment

Deploy the created WAR file `deegree-securityproxy-webservice-$VERSION.war` to an application server for example Apache Tomcat.

Testing

Functional testing with soapUI

The DSP comes with scripts which can verify the correct behavior of the system.

Required Software

We have chosen SoapUI.org as the software solution for all functional test. It is possible to setup automatic test with different scenarios. SoapUI can execute as a command line tool and offers his own logs to get an overview about the current running results an well as the results about the whole test run. SoapUI is available under [SoapUI.org].

Setup

If you have done the download soapUI software file corresponding to your it-environment (operating system dependent), you can start the setup.

  • Fist make sure that the downloaded *.sh file is executable.
  • Execute the *.sh file.

Furthermore you have to download the PostgreSQL JDBC driver postgresql-9.3-1102.jdbc41.jar from PostgreSQL.org into :

<SOAPUI_DIR>/bin/ext/

More information are available under Getting started.

Test scenarios

Import SoapUI test script

Choose File » Import Project (or Strg+I), navigate and select the SoapUI test script from: :

dsp-testsuite/src/test/soapui/dsp-all-test-procedure-soapui-project.xml

Configure custom properties

The SoapUI test script is based on different custom properties which can be configured by Custom Properties.

All available properties:

  • JdbcUrl
  • JdbcUser
  • JdbcPassword
  • ServiceEndpointDSP
  • ServiceContextDSP
  • ServiceNameDSP
  • AccessTokenKey
  • AccessTokenValue

Structure of SoapUI test script

The SoapUI test script is divided into several TestSuite. The most relevant TestSuite is called dsp, which is divided into several TestCases:

  • WMS 1.1.1 - Execute functional test against WMS 1.1.1 (HTTP GET).
  • WMS 1.3.0 - Execute functional test against WMS 1.3.0 (HTTP GET).
  • WFS 1.1.0 - Execute functional test against WFS 1.1.0 (HTTP GET).
  • WFS 2.0.0 - Execute functional test against WFS 2.0.0 (HTTP GET).

Execute SoapUI test

To execute the whole TestSuite, please open the TestSuite with a double-click. A new windows will be opened, which contains a green button. After click on the green button, SoapUI run all selected TestCases. If you want to execute a single TestCase, please open a TestCase. A new window will be opened too.

Performance and Load Tests with soapUI and loadUI

Required Software

We have chosen LoadUI.org as the software solution for verifying performance. LoadUI is easy to use. It is possible to simulate stress to the software environment with different scenarios of stress which could be individually created. LoadUI offers his own logs to get an overview about the current running results an well as the results about the whole test run. LoadUI is available under [www.LoadUI.org].

See System requirements

Setup

Download the loadUI software corresponding for your operating system and you can start the setup.

  • Fist make sure that the downloaded *.sh file is executable.
  • Execute the *.sh file.
  • Follow the instructions which are given in a dialog.
  • Finished: Now you can start the program!

Make a test scenario

  • Start the program.
  • Choose Create a new project in the given dialog.
  • A GUI is the result for the new project.
  • Choose a SoapUIRunner under Point Runners on the left side in the menu Components per drag&drop.
  • Choose a Generator under Point Generators on the left side in the menu Components per drag&drop.
  • Connect your chosen Generator with the runner at the grey round connecting points with pressed mouse button and drag&drop until they are linked with a grey cable (SoapUIRunner upper grey point with Generators below grey point).
  • Additionally you can put Output as TableLog to the grey points below the TestRunner with the same procedure. The information, what the Runner will give as output, is given when you cross the mouse a second on the grey connecting point.

Configure your scenario

  • To add your soapUI Project: Open Project at soapUIRunner.
  • A dialog is mentioned. Here you easily browse on your harddisk to the chosen soapUI Test
  • Beware to have all settings of your soapUI file done by using the software soapUI for example to give the endpoint.
  • Furthermore you have to choose the TestSuite and TestCase to be executed which exclude all other TestCases / TestSuites.
  • The result is the added soapUI file shown in the middle of the TestRunner with all TestSteps that will be executed while performing the LoadUI Test.
  • To configure the requests:
  • First go to soapUIRunner: menu -> settings -> advanced. Choose your appreciate settings.
  • Second go Generator and choose the rate in count (number of request) and unit (given context for example minute)
  • To configure output you find the options in menu

Start the scenario

  • First set a time, request or failure limit for the scenario: This is done by set limit. If the limit is reached the scenario is stopped.
  • For finally start the execution of your scenario press the upper grey play button.
Add a custom footer
Add a custom sidebar
Clone this wiki locally