user guide xml gatewayopensource.corisecio.com/.../user_guide_xml_gateway.pdf · 2013. 4. 19. ·...

CORISECIO GmbH - Uhlandstr. 9 - 64927 Darmstadt - Germany - www.corisecio.com

Open XML Gateway

User Guide

Conventions

Typographic representation:

Screen text and KEYPAD

Texts appearing on the screen, key pads like e.g. system messages, menu titles, - texts, or

buttons are displayed as follows:

Example: Enter your name in the User field and click OK.

Files and folders

File and folder structures are marked as follows:

Example: Download the file doSpellingSuggestion.xml from the folder Examples.

Entries

User entries are displayed as follows:

Example: Enter login here.

Quotation

Quotations and references are displayed as follows:

Example: Further information can be found in chapter “Overview” on the following pages.

Weblinks

Web addresses and links are displayed as follows:

Example: http://www.corisecio.com


3

1 INTRODUCTION .............................................................................. 5

2 SYSTEM REQUIREMENTS .............................................................. 6

3 INSTALLATION ...................................... .......................................... 7

4 ADMINISTRATION .................................... ....................................... 8

4.1 Login ......................................................................................................................................... 8

4.2 Home ......................................................................................................................................... 9

4.3 Express .................................................................................................................................... 9

4.4 Advanced ................................................................................................................................. 9

4.5 Express mode ....................................................................................................................... 10

4.5.1 Level ..................................................................................................................................... 10

4.5.2 Config ................................................................................................................................... 11

4.5.2.1 Security Level Low................................................................................................................. 11

4.5.2.2 Security Level Medium .......................................................................................................... 11

4.5.2.3 Security Level High ................................................................................................................ 11

4.6 Advanced mode ................................................................................................................... 12

4.6.1 Entity .................................................................................................................................... 12

4.6.1.1 Consumer................................................................................................................................ 12

4.6.1.1.1 New ..................................................................................................................................... 12

4.6.1.1.2 Edit ...................................................................................................................................... 14

4.6.1.1.3 Delete .................................................................................................................................. 14

4.6.1.2 Provider ................................................................................................................................... 15

4.6.2 Policy ................................................................................................................................... 16

4.6.2.1 Activate Policy ........................................................................................................................ 17


4

4.6.2.2 Listener .................................................................................................................................... 17

4.6.2.3 Request ................................................................................................................................... 17

4.6.2.3.1 Applying new functions to the policy .............................................................................. 18

4.6.2.3.2 Removing Policy functions............................................................................................... 18

4.6.2.3.3 Changing the order in the Policy ..................................................................................... 18

4.6.2.3.4 Configuring the functions in the policy ........................................................................... 18

4.6.2.3.5 Displaying a description text for a function .................................................................... 18

4.6.2.3.6 Accepting the changes ..................................................................................................... 18

4.6.2.4 Response ................................................................................................................................ 19

4.6.2.5 Error ......................................................................................................................................... 19

4.6.3 Logging ................................................................................................................................ 20

4.6.4 Admin ................................................................................................................................... 21

4.6.4.1 Change Password ................................................................................................................. 21

4.6.4.2 External Access ..................................................................................................................... 21

4.6.4.2.1 API Keypair ............................................................................................................................. 21

4.6.4.2.2 WSDL-User Keypair .............................................................................................................. 21

4.6.4.2.3 Keypair Download .................................................................................................................. 22

5 LOG FILES ......................................... ............................................ 23

6 HELP & SUPPORT..................................... .................................... 24


5

1 Introduction

The CORISECIO Open XML Gateway provides companies the possibility to cost-effectively

and simply protect their Web Services. Nowadays, more and more applications communicate

via the internet and local networks because of the increased spreading of architectures like

SOA and Cloud Computing. Because of the network-based approach applications and data

are increasingly exposed to business critical threats. This e.g. includes, besides various se-

curity vulnerabilities, themes like data theft, XML-DOS or Multi-Layer attacks. These weak

points need to be protected efficiently.

CORISECIO – Open XML Gateway provides the following features:

• Policy-based SOAP messages processing

• Filtering, authentication and authorization for Web Services

• The gateway may be used as stand-alone component

• Enables use of cryptography for Web Services


6

2 System requirements

The statements regarding processor, working memory and hard disk storage may only be

seen as values for orientation as the requirement for system resources mainly depends on

the Open XML Gateway use. Reliable statements are only available by testing in your sys-

tem environment.

Processor Intel Pentium IV 2,4 GHz or more

Working storage 1024 MB or more

Free hard disk stor-

age

10 GB or more (amongst others for Logging)

Operating system • CentOS 6.0

Software • Java Software Development Kit 1.6

• Java Cryptography Extension (JCE) Unlimited Stren gth

Jurisdiction Policy

• Apache Tomcat 6.0.32


7

3 Installation

In the following deploying the Open XML Gateway in an Application Server is described. If

you are using the preconfigured Virtual Appliance, you may skip this chapter.

The Open XML Gateway is operated as Web application on the Application Server. If re-

quired, please kindly see your Application Server’s documentation.

For deploying in the Apache Tomcat rename the War-File so that the filename corresponds

with the required deployment path. Maintain the file extension. Copy the file to the Tomcat

webapps directory. If necessary, restart the Tomcat.

After deploying test the installation by starting the web application.

Enter the following text at your browser’s address line:

http://<hostname>:<port>/<filename without extension>

Example: If you have renamed the war file openxmlgateway.war and if your tomcat installa-

tion is running under localhost:8080, then the address to be entered is:

http://localhost:8080/openxmlgateway

You will be shown the Open XML Gateway login page.


8

4 Administration

The configuration is done completely via the Open XML Gateway web interface.

4.1 Login

First you will have to login at the Open XML Gateway web interface. The password is prede-

fined as follows:

Password: secRT

Enter the password and click Ok. At correct entry the Open XML Gateway administration

page shows up.

The password may be changed after login to the system (see chapter 4.6.4.).

If you are logging-in for the first time, the data store will automatically be created in the Open

XML Gateway directory. Here the Open XML Gateway configuration is saved.


9

4.2 Home

After login the Open XML Gateway start page is displayed. On the home page an over-

view of the menu items Express and Advanced as well as the services status is shown.

Here you may start and stop the service.

4.3 Express

By using the Express button you may switch the Open XML Gateway to the Express mode.

4.4 Advanced

By using the Advanced button you may switch the Open XML Gateway to the Advanced

mode.


10

4.5 Express mode

In the Express mode all configuration steps are executed automatically.

4.5.1 Level

Under the menu item Level the solution’s security level can be set. At installation the security

level “Low ” is preset.

The following Security Levels are available:

• Low : At Security Level Low all messages incoming on Port 80 are checked against

an XML scheme for correctness and XXE attacks and forwarded to the configured

target address.

• Medium : At Security Level Medium the message sender has to authenticate using

SSL v3 (Client authentication). All incoming messages on Port 443 are tested against

an XML scheme for correctness as well as for XXE attacks and SQL/X-Query injec-

tions and forwarded to the configured target address. Also the XML well-formedness

is ensured.


11

• High : At Security Level High the same features apply as at Security Level Medium.

Additionally, messages are tested for WSDL scanning attacks and Replay attacks.

Also requests are. Additionally a SAML Token is added to the request and it is en-

crypted and signed. The response delivered from the target system is decrypted and

the signature is verified.

Select the required Security Level and click Apply.

4.5.2 Config

Using Config you may configure the behavior of the solution. The provided parameters are

dependent on the selected security level.

4.5.2.1 Security Level Low

At Security Level Low the following configuration parameters are available:

• URL: Enter the XML scheme file URL, the messages will be validated against. If not

defined otherwise, all SOAP messages will be accepted. Also, you may define a file

here. The format to be used is file:///E:/directory/file.xsd.

• Endpoint : Enter the target address formatted like host:port, e.g. localhost:4711.

4.5.2.2 Security Level Medium

At Security Level Medium the following configuration parameters are available:





• SSL Key Password : Here you define the password for the Consumer Keypair, used

for the SSL Client authentication.

• SSL Key Generate : Here you generate the Consumer’s SSL Keypair.

• SSL Key Download : Here you may download the Consumer’s root certificate and the

keypair.

4.5.2.3 Security Level High

At Security Level High the following configuration parameters are available:


12





• SSL Key Password : Here you define the password for the Consumer’s Keypair,

used for the SSL Client authentication.

• SSL Key Generate : Here you generate the Consumer’s SSL Keypair.

• SSL Key Download : Here you may download the Consumer’s root certificate and the

keypair.

• Provider Certificate : Here you may download the provider certificate.

4.6 Advanced mode

In the Advanced mode you may detailed define the Open XML Gateway performance and

configuration.

4.6.1 Entity

Under Entity you may configure the Consumer and the Provider. Consumer are authorized

clients, the provider is the identity used for signing and SAML tokens.

4.6.1.1 Consumer

4.6.1.1.1 New

After clicking this link the form for generating consumers shows up:


13

Permitted entry values are:

Field Description Acceptance criteria

Name ID of the user to be created 4-50 characters accordant to the reg-

ular expression ([-]|[_]|[.]|[a-z]|[0-9])+,

unambiguously (no commas)

Keystore

Password

User password; an entry is possible

by clicking …

0-100 characters

Address Consumer address 0-60 characters

Description Consumer description 0-60 characters

When clicking the button, the data is sent and the new consumer created and a key pair is

generated if the acceptance criteria are fulfilled.


14

4.6.1.1.2 Edit

By clicking Edit you may edit the selected user’s properties. The name cannot be edited. The

acceptance criteria are the same as at creating a consumer.

4.6.1.1.3 Delete

Via this link the selected consumers are deleted. The data is completely removed from the

database, issued certificates are revoked.


15

4.6.1.2 Provider

Here you may change the provider information.

Permitted entry values are

Field Description Acceptance criteria

Name ID of the provider to be created 4-50 characters accordant the regular

expression ([-]|[_]|[.]|[a-z]|[0-9])+, un-

ambiguously (no commas)

Keystore

Password

Provider password; entry by clicking

… is possible

0-100 characters

Endpoint Hostname and Port, requests are for-

warded to.

Format: hostname:port

Trusted SSL The optional SSL provider certificate

is required if the endpoint is using an

Valid SSL certificate.


16

SSL connection.

After having created resp. modified the provider, click Activate Policy .

4.6.2 Policy

With the Policy Editor, XML Gateway provides an option to arrange and configure security

functions available via adapters in a process logic. Thus, security functions may be realized

by the Workflow Engine without programming effort. To open the Policy Editor, click the

menu item Policy.

With the Policy Editor you may configure how incoming requests and the corresponding re-

plies will be tested resp. secured.

When clicking the symbol, the Editor appears and the current configuration is shown.

The entire sequence is displayed graphically. You will see areas for configuring the Listener ,

under Request the request processing, the response processing (Response ) and the error

handling (Error ).

On the Policy Editor main page there are buttons to be used for starting the configuration

pages.


17

4.6.2.1 Activate Policy

This button is placed on the left side of the page. Clicking it results in persistent saving the

current configuration and activating and starting (or restarting) it. After successful start you

will be lead to the Advanced Mode overview page, displaying the Services status.

Please pay special attention to the fact that, without clicking Activate Policy on the Policy

Editor main page, all unsaved configuration changes are discarded, especially when leaving

the Policy Editor. When restarting the Policy Editor, it will be preset with the currently saved

setting.

4.6.2.2 Listener

Select Listener and click the Select button, to configure the Listener for the service. You will

be forwarded to another page, where the available Listeners are displayed as selection list

(the current configuration is selected by default).

Select the Listener from the list. Then click the Configure button.

You will be forwarded to the Listener configuration page.

According to selection you have several options – from the simple stating of a TCP/IP port to

configuring an SSL client authentication. Please kindly consult your product’s Modeling Ref-

erences regarding the varied configuration options.

Accept the required configuration by clicking Apply . You will be returned to Entry Point

Configuration .

Click the Apply button on the bottom of the page to accept the changes and to return to the

Policy Editor main page. The changes are accepted for the current session, but they are not

persistent and do not affect the service (to achieve this, please click Activate Policy on the

Policy Editor main page).

4.6.2.3 Request

Select Request and click the Select button, to configure the request processing.

You will be forwarded to the Request Configuration page.

On the left side you will see the currently configured Policy (Request Configuration list) and

on the right side all available functions.


18

4.6.2.3.1 Applying new functions to the policy

Click the function in the list of available functions (Functions ) and click on the arrow point-

ing to the left. The function is added to the Policy at the end.

4.6.2.3.2 Removing Policy functions

Click the function in the Request Configuration list and then click the arrow pointing to the

right. The function is removed from the Policy.

4.6.2.3.3 Changing the order in the Policy

In the Request Configuration list click the function, the position of which in the process

order you would like to change. Then click the buttons resp. . Normally, the process

order is essential for the correct message processing.

4.6.2.3.4 Configuring the functions in the policy

In the Request Configuration list click the function you would like to configure and then

Configure .

A specific configuration page for the function appears.

Please consult your product’s Modeling References to learn more about the configuration

options.

Accept the changes on the configuration pages with Apply . You will be returned to the page

for the Request Configuration .

4.6.2.3.5 Displaying a description text for a function

In the Functions list, click the function you would like to learn more about. Then click the

Display Information button below the Functions list. In the Description text field fur-

ther information for the function are shown.

Alternatively you may consult the Modeling References.

4.6.2.3.6 Accepting the changes

Click the Apply button on the bottom of the page to accept the configuration changes.

Please kindly bear in mind, that the changes do not apply immediately, but after having been

confirmed again on the Policy Editor main page (see Fehler! Verweisquelle konnte nicht

gefunden werden. ).


19

4.6.2.4 Response

Select Response and click the Select button, to configure the process steps for the re-

sponse.

The functionality of page appearing then is mainly the same as of the Request Configura-

tion page (see paragraph 4.6.2.3). The difference is, that here the policy for processing the

response is configured here.

4.6.2.5 Error

Select Error and click the Select button, to configure the error page, which is sent if errors

occur during processing. You will be forwarded to a page where you may configure the error

text. Entry of HTML tags is possible here.

Accept the changes by clicking Apply .


20

4.6.3 Logging

Under Logging the recorded SOAP messages are shown.

In the fields From and To enter the required period of time and click Refresh . Under Log

Messages all logged messages are shown. The status shows the log reason, if it is an error

(red), a normally processed message (green) or a message, where a warning occurred dur-

ing processing (orange). Date is the log date, Message ID an internal Id and Source the

sender’s address.

Click an entry to have the details displayed. A description of the log-cause can be seen un-

der Message Details and under Message the message can be viewed.

By clicking a bar in the timeline you may focus the log entry view on this period of time.


21

4.6.4 Admin

4.6.4.1 Change Password

Using Change Password changes the entry data for the Open XML Gateway.

4.6.4.2 External Access

Here you may configure the API, used for accessing the Open XML Gateway functions from

external applications.

4.6.4.2.1 API Keypair

As for an external accessing the Open XML Gateway an encrypted connection is required,

the API Keypair has to be used for encryption.

4.6.4.2.2 WSDL-User Keypair

For authenticating and authorizing the access to the WSDL API the WSDL-User Keypair is required.


22

4.6.4.2.3 Keypair Download

SOAP messages sent to the WSDL API, first have to be signed with the private WSDL-User

key and then have to be encrypted with the WSDL-API Public Key. The Open XML Gate-

way responses are signed with the private key from the WSDL-API Keypair generated pre-

viously. The signature may be validated with the WSDL-API Public Key . The responses are

encrypted using the public WSDL-User key.


23

5 Log files

The Open XML Gateway Log Files are located in the folder log of the web application’s

directory structure. In this folder there is a file named connector.[YYYY]-[MM]-[TT].log.

Here [YYYY] means the year, [MM] the month and [TT] the day, the log file was created at.

To open the log file, you will have to close the application first.


24

6 Help & Support

You have a problem or a question? Our Support Team will support you fast and professional-

ly.

Please kindly have the version information of your CORISECIO solution available. You can

find the data required by the Support Team in the Security Administration (RCP) under

Help > About via the button Plug-In Details . On the client systems you can obtain these

data via the appropriate About dialogs of the CORISECIO Runtime Components.

Please kindly state your CORISECIO customer name and your customer ID at each inquiry

which you may receive from us if necessary.

[email protected]

user guide xml gatewayopensource.corisecio.com/.../user_guide_xml_gateway.pdf · 2013. 4. 19. ·...

Documents