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
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 3
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 4
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 security 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 5
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 system environment. Processor Working storage Free hard disk storage Intel Pentium IV 2,4 GHz or more 1024 MB or more 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 Strength Jurisdiction Policy Apache Tomcat 6.0.32 6
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 required, 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 installation 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. 7
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 predefined 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. 8
4.2 Home After login the Open XML Gateway start page is displayed. On the home page an overview 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. 9
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 injections and forwarded to the configured target address. Also the XML well-formedness is ensured. 10
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 encrypted 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: 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. 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: 11
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. 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: 12
Permitted entry values are: Field Description Acceptance criteria Name ID of the user to be created 4-50 characters accordant to the regular 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. 13
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. 14
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])+, unambiguously (no commas) Keystore Password Provider password; entry by clicking is possible 0-100 characters Endpoint Hostname and Port, requests are forwarded to. Format: hostname:port Trusted SSL The optional SSL provider certificate is required if the endpoint is using an Valid SSL certificate. 15
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 replies 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. 16
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 References 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. 17
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 pointing 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 further 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.). 18
4.6.2.4 Response Select Response and click the Select button, to configure the process steps for the response. The functionality of page appearing then is mainly the same as of the Request Configuration 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. 19
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 during 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 under 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. 20
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. 21
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 Gateway responses are signed with the private key from the WSDL-API Keypair generated previously. The signature may be validated with the WSDL-API Public Key. The responses are encrypted using the public WSDL-User key. 22
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. 23
6 Help & Support You have a problem or a question? Our Support Team will support you fast and professionally. 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. support@corisecio.com 24