Access Keys:
Skip to content (Access Key - 0)
WELCOME TO KAAZING.ORG LOGIN | REGISTER
Kaazing.com | FAQ | Jobs | Forum | Wiki
 
This document is also packaged with the Kaazing Gateway demo bundle, which is available here

Administrator's Guide

Kaazing Gateway 8.12 (Battlestar) Release

February 2009

This guide contains the following sections:

Configuring the Kaazing Gateway Server

After you have installed Kaazing Gateway Server as described in the Getting Started Guide, you can configure the gateway by modifying the settings in the configuration file $KAAZING_HOME/conf/gateway-config.xml. The individual configuration elements are explained in the following section.

Description of the gateway-config.xml Configuration Elements

The configuration file gateway-config.xml defines the following configuration elements contained in the top-level gateway-config element:

gateway-config

Required? Required; only one

This is the root-level element for gateway configuration. gateway-config contains the following elements:

Element Description
management The element for gateway management configuration (see management)
session The element for associating a session with one or more services (see session)
security

The element for configuring gateway security (see security)
service The element for configuring a service running on the Kaazing Gateway Server (see service)

The following is an example gateway-config element:

<?xml version="1.0" encoding="UTF-8" ?>

<gateway-config
  xmlns="http://xmlns.kaazing.org/gateway-config/battlestar">
  .
  .
  .
</gateway-config>

Note:
Kaazing Gateway Server configuration files must use the namespace
http://xmlns.kaazing.org/gateway-config/battlestar

management

Required? Optional; zero or one

This is the element for gateway management configuration. management contains the following elements:

Element Description
accept The protocol, network interface (possibly internal), and the port number on which the management agent accepts connections
realm-name The name of the security realm used for authentication
auth-constraint

The user roles that are authorized to perform management operations (see auth-constraint)

auth-constraint

Required? Optional; zero or more

This is the element for configuring the user roles that are authorized to access management features. auth-constraint contains the following element:

Element Description
require-role The name of the user role to be included in the auth-constraint or * to indicate any valid user

The following is an example management element:

<management>
  <!-- specify protocol, network interface (possibly internal) and port -->
  <accept>jmx://localhost:2020/</accept>
  
  <!-- secure the management using a security realm -->
  <realm-name>demo</realm-name>
  
  <auth-constraint>
    <require-role>ADMINISTRATOR</require-role>
  </auth-constraint>
</management>

session

Required? Optional; zero or more

This is the element that associates a session with one or more services by matching the domain of each service's accept URL. session contains the following elements:

Element Description
service-domain

The domain associated with a service accept URL

Note:

  • To specify a session that spans across multiple hosts, use a wild card and a domain. For example, *.test.local
  • To specify a session that spans across multiple ports on one domain, use the hostname. For example, localhost
authentication-scheme The method used for authentication
realm-name The name of the security realm used for authentication
encryption-key-alias The alias for the session cookie encryption key that protects the value of the session token used by the gateway server to identify authenticated users
inactivity-timeout The length of time (in seconds) that the session cookie is active

The following is an example session element:

<session>
  <!-- associate service realms automatically -->
  <service-domain>localhost</service-domain>
  
  <!-- HTTP authentication configuration -->
  <authentication-scheme>Basic</authentication-scheme>
  <realm-name>demo</realm-name>
  
  <!-- Session cookie configuration -->
  <encryption-key-alias>session</encryption-key-alias>
  <inactivity-timeout>1800</inactivity-timeout>
</session>

security

Required? Optional; only one

This is the element for configuring gateway security. security contains the following elements:

Element Description
keystore

The keystore contains the encryption keys for secure communications with the Kaazing Gateway Server (see keystore)
truststore

The truststore contains digital certificates for certificate authorities trusted by Kaazing Gateway Server (see truststore)
realm

The realm associates an authenticated user with a set of authorized roles (see realm)

keystore

Required? Optional; only one

This is the element for configuring the keystore that contains encryption keys for secure communications with the Kaazing Gateway Server. keystore contains the following elements:

Element Description
type

The format of the keystore file
file The location of the keystore file (absolute path or path relative to the gateway-config.xml file)
password-file The name of the file that contains the password to unlock the keystore file

truststore

Required? Optional; only one

This is the element for configuring the truststore that contains digital certificates for certificate authorities trusted by Kaazing Gateway Server. truststore contains the following elements:

Element Description
type

The format of the keystore file
file The location of the truststore file (absolute path or path relative to the gateway-config.xml file)

realm

Required? Optional; zero or more

This is the element that associates an authenticated user with a set of authorized roles. realm contains the following elements:

Element Description
name

The name of the realm
description The description of the realm
login-module The login module communicates with a user database to validate user's credentials and to determine a set of authorized roles (see login-module)
login-module

Required? Required; one or more

This is the element that configures the login module, which communicates with a user database to validate user's credentials and to determine a set of authorized roles. login-module contains the following elements:

Element Description
type

The type of login module: file or ldap
success

The behavior of the login module at the time it validates the user's credentials. Possible options are:

  • required-
  • requisite
  • sufficient
  • optional

The success status options are defined in the javax.security.auth.login.Configuration class. Authentication succeeds if all required and requisite login modules succeed, or if a sufficient or optional login module succeeds.
options

The configuration options specific to the type of login module (see examples below):

The following is an example of a file-based login-module element:

<login-module>
  <type>file</type>
  <success>required</success>
  <options>
    <file>jaas-config.xml</file>
  </options>
</login-module>

The following is an example of an LDAP-based login-module element:

<login-module>
  <type>ldap</type>
  <success>required</success>
  <options>
    <userProvider>ldap://ldap-svr/ou=people,dc=example,dc=com</userProvider>
    <userFilter>(&amp;(uid={USERNAME})(objectClass=inetOrgPerson))</userFilter>
    <authzIdentity>{EMPLOYEENUMBER}</authzIdentity>
  </options>
</login-module>

The following is an example of a security element:

<security>
  <keystore>
   <type>JCEKS</type>
   <file>keystore.db</file>
   <password-file>keystore.pw</password-file>
  </keystore>

  <truststore>
    <file>truststore.db</file>
  </truststore>
    
  <realm>
    <name>demo</name>
    <description>Kaazing Gateway Demo</description>
    <login-module>
      <type>file</type>
      <success>required</success>
      <options>
        <file>jaas-config.xml</file>
      </options>
    </login-module>
  </realm>
</security>

service

Required? Optional; zero or more

This is the element for configuring a service running on the Kaazing Gateway Server. Each service contains the following elements:

Element Description
accept

The URL on which the service accepts connections
type

The type of service--one of the following:
properties The service type-specific properties

auth-constraint

The user roles that are authorized to perform operations (see auth-constraint)
cross-site-constraint The cross-origin sites (and their methods and custom headers) allowed to access the service. (see cross-site-constraint)

broadcast

This type of service is used to broadcast information from a backend service.The broadcast service has the following properties:

  • accept--the URL of the broadcast service that a backend service connects to

The following is an example of a service element of type broadcast:

<service>
  <accept>sse://localhost:8003/sse</accept>
  <type>broadcast</type>

  <properties>
    <accept>udp://localhost:50505</accept>
  </properties>
</service>

directory

This type of service is used to expose directories or files hosted on the gateway.The directory service has the following properties:

  • directory--the path to the directory to be exposed on the gateway
  • welcome-file--the path to the file to be exposed on the gateway

The following is an example of a service element of type directory:

<service>
  <accept>https://localhost:8000/</accept>

  <type>directory</type>
  <properties>
    <directory>/</directory>
    <welcome-file>index.html</welcome-file>
  </properties>
</service>

proxy

This type of service is used to proxy connections to a backend service.The proxy service has the following properties:

  • connect--the URL of a backend service that the proxy service connects to

The following is an example of a service element of type proxy:

<service>
  <!-- ws:// scheme refers to WebSocket -->
  <accept>ws://localhost:8001/activemq</accept>

  <!-- wss:// scheme refers to WebSocket (secure) -->
  <accept>wss://localhost:9001/activemq</accept>
  
  <type>proxy</type>
  <properties>
    <connect>tcp://localhost:61613</connect>
  </properties>
</service>

session

This type of service is used to prevent sessions from timing out.

Note:
Communication with the session service should be always be configured to use HTTPS..

The session service does not have any additional properties. The following is an example of a service element of type session:

<service>
  <accept>https://localhost:9000/session</accept>
  
  <type>session</type>
  
  <auth-constraint>
    <require-role>AUTHORIZED</require-role>
  </auth-constraint>
</service>

auth-constraint

Required? Optional; zero or more

This is the element for configuring the user roles that are authorized to access the service. auth-constraint contains the following element:

Element Description
require-role The name of the user role to be included in the auth-constraint or * to indicate any valid user

The following is an example of a proxy service element with an auth-constraint:

<service>
  <accept>ws://localhost:8001/activemq</accept>

  <type>proxy</type>
  <properties>
    <connect>tcp://localhost:61613</connect>
  </properties>

  <auth-constraint>
    <require-role>AUTHORIZED</require-role>
  </auth-constraint>
</service>

cross-site-constraint

Required? Optional; zero or more

This is the element for configuring how a cross-origin site is allowed to access the service. cross-site-constraint contains the following elements:

Element Description
allow-origin The protocol scheme, fully qualified host name, and port number of the cross-origin site that is allowed to access this service. Specify the value * if you want to allow access to all cross-site origin sites. Specifying * may be for appropriate for services that restrict HTTP methods or custom headers, but not the origin of the request.
allow-methods A comma-separated list of methods that can be invoked by the cross-origin site
allow-headers A comma-separated list of custom header names that can be sent by the cross-origin site when it accesses the service

The following is an example of a proxy service element with a cross-site-constraint, allowing access to the backend service to the site http://localhost:8000. Access to backend services is denied by default and cross-site-constraints allow you to "white-list" cross-origin sites.

<service>
  <!-- ws:// scheme refers to WebSocket -->
  <accept>ws://localhost:8001/activemq</accept>
  
  <type>proxy</type>
  <properties>
    <connect>tcp://localhost:61613</connect>
  </properties>

  <auth-constraint>
    <require-role>AUTHORIZED</require-role>
  </auth-constraint>
  
  <cross-site-constraint>
    <allow-origin>http://localhost:8000</allow-origin>
  </cross-site-constraint>
</service>

network

Required? Optional; zero or one

This is the element for network configuration. network contains the following elements:

Element Description
address-mapping Mapping configuration for externally visible addresses on a firewall or a load-balancing router to a local internal address where the Kaazing Gateway Server is listening (see address-mapping)

address-mapping

Required? Optional; zero or more

This is the element for configuring address mapping of externally visible addresses on a firewall or a load-balancing router to a local internal address where the Kaazing Gateway Server is listening. Refer to configuring network address mapping for more information. address-mapping contains the following elements:

Element Description
internal-address The local address where the Kaazing Gateway Server is listening
external-address The address of a firewall or a load-balancing router as observed by the devices on the external network, such as a Web browser

The following is an example network element:

<network>
  <address-mapping>
    <internal-address>gateway.dmz.net:8000</internal-address>
    <external-address>www.server.com:80</external-address>
    <external-address>stock.server.com:80</external-address>
    <external-address>chat.server.com:80</external-address>
  </address-mapping>

  <address-mapping>
    <internal-address>10.0.0.1:8000</internal-address>
    <external-address>www.server.com:80</external-address>
    <external-address>stock.server.com:80</external-address>
    <external-address>chat.server.com:80</external-address>
  </address-mapping>
</network>

Securing the Kaazing Gateway Server

This section covers the following topics:

Security Overview

For successful, secure communication between the browser and the server, we need to consider both wire traffic encryption as well as authentication and authorization. For wire traffic encryption, TLS (Transport Layer Security, formerly known as SSL) support is required to prevent unwanted eavesdropping, man-in-the-middle attacks, and packet sniffing. HTTP over TLS is called HTTPS. An HTTPS connection is established after a successful TLS handshake (using public and private key certificates).

Authentication is the mechanism by which systems identify their users and check whether the user really is who he represents himself to be. To start the authentication process, the Web server issues a challenge using the HTTP 401 Authorization Required code. The client then responds by providing the requested authentication information if it can.

Authorization is the mechanism by which a system determines what level of access a particular user has. For example, a Web page can have viewer, moderator, and administrator privileges. Access rights are typically stored in the policy store that is associated with the application.

Technically, HTTPS is not a separate protocol, but it is HTTP running on top of a TLS connection. Commonly, HTTPS uses a different port (HTTPS's default port is 443 and HTTP's default port is 80) In the following diagram, you can see that HTTP runs directly on top of TCP and that HTTPS runs on top of TLS, which in turn runs on top of TCP. The same is true for secure WebSocket connectivity; the WebSocket protocol runs on top of TCP (like HTTP), and the secure WebSocket protocol runs on top of TLS, which in turn runs on TCP. WebSocket's default port is 81 and Secure WebSocket uses port 815 by default.

HTTP and HTTPS, WS and WSS

Kaazing Gateway supports communication over HTTPS and WSS (WebSocket Secure). On top of that, Individual gateway services can be configured to have authorization constraints. To better understand how the security parameters, specified in the gateway-config.xml file, work together, let's take a detailed look at what is involved in the secure communication between the browser and the Kaazing Gateway Server.

Suppose that a browser requests content from the URL https://localhost:9000/ and that the service for this URL has been configured to have a security constraint on it as follows (in gateway-config.xml):

<service>
  <accept>https://localhost:9000/</accept>
  
  <type>directory</type>
  <properties>
    <directory>/</directory>
    <welcome-file>index.html</welcome-file>
  </properties>
  
  <auth-constraint>
    <require-role>AUTHORIZED</require-role>
  </auth-constraint>
</service>

The following is a detailed overview of what happens under-the-hood:

  1. Since the URL that is accessed is an HTTPS URL, a TLS handshake takes place in which public and private key for localhost are used to establish a shared secret used to encrypt and decrypt data. After the secure connection has been set up, the browser sends the HTTP request to the server.
  2. The server looks up the service that is registered for the requested URL and then checks if the service has security constraints applied to it. Since the authorization constraint is present, the server tries to identify the end user so that it can enforce the constraint.

  3. The server checks if either an authorization header or a session cookie was sent with the request, but the browser will not have sent those yet, since this is the first request.

  4. The server parses the URL that the browser is trying to access and extracts the host name. In this case, that is localhost.

  5. The server consults the configuration parameters that were supplied at server startup (in the file gateway-config.xml) and looks for a session element that contains the localhost service domain to look up the authentication scheme. For example:

    <session>
        <!-- associate service realms automatically -->
        <service-domain>localhost</service-domain>
        
        <!-- HTTP authentication configuration -->
        <authentication-scheme>Basic</authentication-scheme>
        <realm-name>demo</realm-name>
        
        <!-- Session cookie configuration -->
        <encryption-key-alias>session</encryption-key-alias>
        <inactivity-timeout>1800</inactivity-timeout>
    </session>

  1. The server sends back a response, challenging the user to supply login credentials. The server uses the authentication scheme specified in the session element (authentication-scheme).

  2. The browser responds by providing the requested authentication information by re-requesting the original URL, but this time with the appropriate authorization header information. For example, joe/welcome).

  3. The server looks up the service that is registered for the requested URL and then checks if the service has security constraints applied to it. Since the authorization constraint is present, the server tries to identify the end user so that it can enforce the constraint.

  4. The server now finds the authorization header and decodes it to extract the supplied login credentials.

  5. The server parses the URL that the browser is trying to access and extracts the host name. In this case, that is localhost.

  6. The server looks for a session element that contains the localhost service domain to look up the realm name. For example:

<!-- HTTP authentication configuration -->
<authentication-scheme>Basic</authentication-scheme>
<realm-name>demo</realm-name>

  1. The realm-name value is used to look up the realm information for the request. The realm element is part of the security element in the gateway-config.xml file. For example (realm information in bold text):

<security>
  <keystore>
   <type>JCEKS</type>
   <file>keystore.db</file>
    <password-file>keystore.pw</password-file>
  </keystore>
    
  <realm>
    <name>demo</name>
    <description>Kaazing Gateway Demo</description>
    
    <login-module>
      <type>file</type>
      <success>required</success>
      <options>
        <file>jaas-config.xml</file>
      </options>
    </login-module>
  </realm>
</security>

  1. The server checks the realm information to see which login module is associated with it and passes the encoded user's login credential values to it.

  2. The realm login modules are used to authenticate the end user's login credentials and establish the list of authorized roles that the user has. For example, AUTHORIZED.

    Since this realm uses a file-based login module, the server will consult the jaas-config.xml file specified as follows:

<?xml version="1.0" encoding="UTF-8" ?>
<jaas-config xmlns="http://xmlns.kaazing.org/jaas-config/battlestar" >
  <user>
    <name>joe</name>
    <password>welcome</password>
    <require-role>AUTHORIZED</require-role>
  </user>
  <role>
    <name>AUTHORIZED</name>
    <description>Authorized users</description>
  </role>
</jaas-config>

  1. In this case, joe is successfully authenticated, so the server proceeds to construct a cookie to send along with the HTTP response. Inactivity timeout information, as well as domain, name, user name and password information is stored in the cookie and to protect this information, the cookie is encrypted using a secret key stored in the keystore under the encryption key alias (session).

  2. The server verifies that joe has been granted all the roles required by the authorization constraint for this request and continues to service the request, sending back the data and the cookie in the response. If joe had not been fully authorized, an additional challenge would have been sent to the browser.

  3. When the cookie is present, subsequent requests follow the steps above and behave as if the authentication header was present, but instead the session cookie contains an encrypted version of the authorization header plus session expiration information.

The following sections describe how to configure the different aspects of security for the Kaazing Gateway Server.

Configuring Wire Traffic Encryption

Configuring wire traffic encryption using TLS (Transport Layer Security, a.k.a. SSL) is a multi-step process:

  1. Create and sign key pair
  2. Configure the server to locate the keystore
  3. Configure the server to use TLS

Create and Sign a Key Pair

To create and sign a private and public key pair that can be used in a production WebSocket server environment (for TLS), perform the following steps:

  1. Locate the the Java keytool utility, which is part of your Java installation and can be found in the Java bin directory. For example, C:\Program Files\Java\jdk1.6.0_06\bin.

  2. Create a key pair (private and public) by running the keytool utility as shown in the following example:

    keytool -genkeypair -keystore C:\kaazing-gateway\conf\keystore.db -storetype JCEKS -storepass welcome -alias example -keyalg RSA -dname "CN=example.server.com, OU=Example, O=Example, L=Mountain View, ST=California, C=US"

    Notes:

  • By default the self-signed certificate that you just created will be valid for 90 days. When you purchase the trusted certificate from the certificate authority its validity will be determined by the terms of your purchase.

  • For testing purposes, you can use the self-signed certificate that you just created.
Note:
Firefox 3 does not, by default, accept self-signed certificates. Your users must create an exception for each port used by your application, including secondary ports used by WebSocket.

  1. Create a certificate-signing request:

    keytool -certreq -keystore C:\kaazing-gateway\conf\keystore.db -storetype JCEKS -storepass welcome -alias example -file example.csr

  2. Send the certificate to the digital certificate authority (for example, Verisign). The authority will return a trusted certificate containing the public key.

  3. Import the trusted certificate:

keytool -importcert -keystore C:\kaazing-gateway\conf\keystore.db -storetype JCEKS -storepass welcome -trustcacerts -alias example -file example.cer

Configure the server to locate the keystore

Perform the following steps to configure the server to locate the keystore:

  1. Open the configuration file $KAAZING_HOME/conf/gateway-config.xml in a text editor.

  2. Add the following section (in bold text) to the <security> section of the gateway-config.xml file:

<security>
  <keystore>
    <type>JCEKS</type>
    <file>keystore.db</file>
    <password-file>keystore.pw</password-file>
  </keystore>

Configure the server to use TLS

Perform the following steps to configure the server to use TLS:

  1. Open the configuration file $KAAZING_HOME/conf/gateway-config.xml in a text editor.

  2. Specify secure URLs in the accept elements for the services you want to set up to use TLS (HTTPS or WSS) as shown in bold in the following example:

<service>
  <accept>https://localhost:9000/</accept>

  <type>directory</type>
  <properties>
    <directory>/</directory>
    <welcome-file>index.html</welcome-file>
  </properties>

  <auth-constraint>
    <require-role>AUTHORIZED</require-role>
  </auth-constraint>
</service>

Configuring authentication

Perform the following steps to configure authentication:

  1. Open the configuration file $KAAZING_HOME/conf/gateway-config.xml in a text editor.

  2. Add a realm element in the security section of the gateway-config.xml file. You specify the login module in the realm section. Specify file if you want to use the jaas-config.xml that is part of the Kaazing Gateway Server. Specify ldap if you want to use an external LDAP login module. See the description of the security element for examples of the file- and ldap-based login modules.

  3. If you're using the file-based login module, open the file $KAAZING_HOME/conf/jaas-config.xml and make sure the right users and roles are defined for your application. For example:

<jaas-config xmlns="http://xmlns.kaazing.org/jaas-config/battlestar" >
  <user>
    <name>joe</name>
    <password>welcome</password>
    <require-role>AUTHORIZED</require-role>
  </user>
  <role>
    <name>AUTHORIZED</name>
    <description>Authorized users</description>
  </role>
</jaas-config>

Configuring Authorization

Perform the following steps to configure authorization:

  1. Using the Java keytool utility, located in your Java installation's bin directory, create a session cookie encryption key:

    keytool -genseckey -keystore C:\kaazing-gateway\conf\keystore.db -storetype JCEKS -storepass welcome -alias session

  2. Open the configuration file $KAAZING_HOME/conf/gateway-config.xml in a text editor.

  3. Create a session element:

Notes:

  • The session element is specific only to services, because the service domain implicitly matches the accept URLs of the services.
  • The encryption-key-alias refers to the session cookie encryption key (session in this example) that was defined earlier. This key is used to protect the value of the session token used by the gateway server to identify authenticated users.
  1. Define auth-constraints for the services you want to configure authorization for. The following example shows that users who want to access to the Stomp service must be members of the AUTHORIZED role.

!-- Proxy to STOMP server (secure) -->
<service>
  <!-- wss:// scheme refers to WebSocket (secure) -->
  <accept>wss://test.local:9001/activemq</accept>
  
  <type>proxy</type>
  <properties>
    <connect>tcp://localhost:61613</connect>
  </properties>
  
  <auth-constraint>
    <require-role>AUTHORIZED</require-role>
  </auth-constraint>
</service>

Configuring Gateway Management Security

Gateway management is secured by an explicitly specified security realm name. The realm-name element refers to one of the named realms inside the security element. To secure gateway management, perform the following steps:

  1. Open the configuration file $KAAZING_HOME/conf/gateway-config.xml in a text editor.

  2. Add a realm-name and a security constraint as follows

<management>
  <!-- specify protocol, network interface and port -->
  <accept>jmx://localhost:2020/</accept>
  
  <!-- secure the management using a security realm -->
  <realm-name>demo</realm-name>
  
  <auth-constraint>
    <require-role>ADMINISTRATOR</require-role>
  </auth-constraint>
</management>

Monitoring the Kaazing Gateway Server

You can monitor the Kaazing Gateway Server using the Java's built in Java Management and Monitoring Console (JConsole). The Java Management and Monitoring Console is used to monitor the JVM (Java Virtual Machine) or management beans for running applications, as long as these MBeans conform to the JMX specification.

To monitor the gateway, perform the following steps:

  1. To monitor the Kaazing Gateway Server, install and run the gateway demo bundle as described in the Getting Started Guide. Ensure that the Kaazing Gateway Server, Apache ActiveMQ, and the stock.start script are running.
  2. Navigate to the Kaazing demos home page at http://localhost:8000/demo/index.htmland click the Stock Trading Matrix Demo.
  3. Click Connect at least once to establish a session.
  4. Open a command prompt and navigate to your Java bin directory. For example, C:\Program Files\Java\jdk1.6.0_06\bin on Windows.
  5. Launch the Java Management and Monitoring Console by running JConsole.

Start JConsole

  1. Select the process com.kaazing.gateway.Main.
  2. The Java Management and Monitoring Console opens and displays information about the Kaazing Gateway Server process.

JConsole Monitoring

  1. Click the MBeans tab
  2. Expand com.kaazing.console > service and expand the top Apache ActiveMQ service node.
  3. Expand sessions and click one of the session IDs. The session data exposed by the MBeans displays.

Jconsole Session information

  1. To close a specific session, select a session ID and expand Operation and then click close() on the operation invocation page. Alternatively, you can click suspendWrite(), which suspends the session by keeping it on hold until it is resumed. To resume the session click resumeWrite().

Jconsole close session

  1. Next, expand the bottom Apache ActiveMQ service node and click summary. Aggregate information about the number of sessions displays.
  2. Expand summary > Notifications and click one of the session IDs. The session data exposed by the MBeans displays.
  3. To subscribe to notifications in the console, click Subscribe. When a new connection is established, a new row with session information displays in the console (on the Notification buffer page).

Jconsole sessions

Configuring Network Address Mapping

When a firewall or load-balancing router front-ends a Kaazing Gateway Server, DNS will resolve to the public IP address of that device. The device is configured to forward requests to the Kaazing Gateway Server on the internal network.

In an example scenario, a firewall connected directly to the Internet has the IP address 65.43.2.1 and the public DNS name www.server.com. The Kaazing Gateway Server is running on gateway.dmz.net with IP address 10.0.0.1. The firewall forwards network traffic to the Kaazing Gateway Server, which has to serve HTTP requests for www.server.com on port 80. In this scenario, the Kaazing Gateway Server has to serve requests for www.server.com. These requests must be routed through the firewall to the gateway’s internal IP address (10.0.0.1) on port 8000.

By default, the Kaazing Gateway Server resolves the local interface address (10.0.0.1) by looking up the DNS name www.server.com , but in this case that would resolve to 65.43.2.1, which does not represent any local network interface, resulting in a failure to serve requests for www.server.com.

You use the network configuration address-mapping element to override the gateway's default behavior. In this example scenario, you map the internal address gateway.dmz.net:8000 to the external address of the firewall, which is www.server.com:80 as follows:

<network>
  <address-mapping>
    <internal-address>gateway.dmz.net:8000</internal-address>
    <external-address>www.server.com:80</external-address>
  </address-mapping>
</network>

This signals the Kaazing Gateway Server to listen on the internal address gateway.dmz.net:8000 to serve requests originally sent to the external address www.server.com:80.Alternatively, the IP address can be used in the configuration parameters as shown in the following example:

<network>
  <address-mapping>
    <internal-address>10.0.0.1:8000</internal-address>
    <external-address>www.server.com:80</external-address>
  </address-mapping>
</network>

Configuring Apache HTTP Server to Integrate with Kaazing Gateway Server

It is common for Web applications that use the Kaazing Gateway to require integration with static or dynamic content served by an Apache HTTP Server. These Web applications may include static content from HTML files as well as dynamic content from, for example, PHP or JSP files. The Web application can be served up by an Apache HTTP Server or by an Apache HTTP Server that front-ends a Web application server, which handles the Web application’s business logic.

An HTML page that is part of such a Web application may contain an embedded backend service that is hosted on a different server. For example, you may want to embed an XMPP-based chat service into your main application and then click a link in the main application to open a specific chat room in the embedded chat application. The communication between the main application and the embedded service is performed using HTML 5 postMessage. PostMessage handles the sending and receiving of information between the main application and the embedded service iframe, as shown in the following image.

postMessage architecture

Some browsers, like Firefox 3.0+, Internet Explorer 8.0+, and Opera 9.62+ support HTML 5 postMessage natively, and the Kaazing Gateway Client Libraries provide an emulation of postMessage for the rest of the browsers. The postMessage emulation is achieved with additional iframes and fragment identifier messaging, which uses a special URL syntax for inter-iframe communication.

No additional configuration is required if the gateway serves both the main application and the service, but if the main page is served by an Apache HTTP Server, that server must be configured to support the postMessage emulation.

Note: The Kaazing Client Libraries use a secondary iframe and postMessage as the foundation for Cross-Site XMLHttpRequest, which is used to emulate HTML 5 Server-Sent Events and WebSockets.

Let’s take a look at an example. As shown in the following image, the page example.html is served up by an Apache HTTP Server that is listening on port 80 at http://www.server.com. The parent application contains a child iframe that embeds a service accessed through the Kaazing Gateway Server, which is listening on port 80 at http://www.gateway.com.

Apache inegration overview 1

In this network topology, the Apache HTTP Server is located as a peer to the Kaazing Gateway Server. In a typical scenario, the two servers will be on separate domains as shown here (http://www.server.com and http://www.gateway.com), but the servers can also reside on the same domain and listen on different ports.

In this case, the postMessage emulation requires two additional iframes: one for each direction of communication between the main application and the service.The iframe that receives messages sent to the main application has the URL http://www.server.com/?.kr=xsp. Without additional configuration, the Apache HTTP Server does not understand how to provide an appropriate response, causing the postMessage emulation to fail.

When the Apache HTTP Server is configured to interpret and forward requests to the Kaazing Gateway Server, communication flows as expected and postMessage emulation is achieved for the browsers that do not support it natively, as shown in the following image.

Apache inegration overview 2

To configure the Apache HTTP Server to integrate with the Kaazing Gateway Server, perform the following steps:

  1. Open your Apache HTTP Server configuration file.
  2. Ensure mod_proxy, mod_proxy_http, and mod_rewrite are enabled. Refer to the Apache HTTP Server documentation for more information on how to configure this.
  3. Add the following directives (shown in bold text) to the VirtualHost directive that you want to configure, replacing the example server name with your server name:

<VirtualHost *:80>
  .
  .
  .
  RewriteEngine on
  RewriteCond %{QUERY_STRING} ^\.kr=.*$
  RewriteRule / http://www.gateway.com/ [QSA,P]

  <Proxy http://www.gateway.com/ >
    Allow from all
  </Proxy>
  .
  .
  .
</VirtualHost>

This causes any request with syntax http://www.server.com/?.kr=xyz to be forwarded to the Kaazing Gateway Server. The [QSA]flag causes the original query string to be automatically appended to the rewritten request and the [P]flag causes the rewrite engine to hand off the rewritten request to mod_proxy.

Note:Using a wildcard for the value of the .kr query parameter in the RewriteCond directive will ensure that you don’t need to change your configuration in the future.

  1. Save the Apache HTTP Server configuration file and restart the Apache HTTP Server.
  2. To verify that the Apache HTTP Server is now configured correctly, open a browser and navigate to the proxied URL, for example http://www.server.com/?.kr=xsp, and verify that the text PostMessageParentBridge is displayed.

Configuring Java Servlets to Integrate with Kaazing Gateway Server

There is yet another way to configure your application to find the Kaazing Gateway postMessage resources if you are serving HTML resources from a Java Servlet container, such as a Java Enterprise Edition server or Apache Tomcat. To do this, you can use the Servlet Filter feature standardized in the Java Servlet specification, version 2.3 or later. By combining freely-available open source tools, you can establish a Servlet Filter that rewrites the appropriate postMessage URLs and directs them to the Kaazing Gateway Server as shown in the following image.

Servlet Container Architecture

Configuring Java Servlets to integrate with the Kaazing Gateway Server is a two-step process. These steps apply some modifications to an existing Web application before WAR archival and deployment to the Servlet container.

Download UrlRewriteFilter and Its Dependencies

First, download the UrlRewriteFilter project and its dependencies. To do so, perform the following steps:

  1. Navigate to the UrlRewriteFilter project.at http://code.google.com/p/urlrewritefilter.
  2. In the Featured Downloads section, download the binary release archive urlrewritefilter-3.2.0.zip (or later).
  3. From the downloaded archive file, extract the urlrewrite.xml file into your Web application's /WEB-INF directory. This file will be used to configure the rewrite rules.
  4. From the downloaded archive file, extract the urlrewrite-3.2.0.jar file into your Web application's /WEB-INF/lib directory. This contains the code for the rewrite actions.

The UrlRewriteFilter project has two dependencies: Apache Commons HttpClient and Apache Commons Codec. To include the Java libraries from these Apache projects in your existing Web application, perform the following steps:

Apache Commons HTTPClient

  1. Navigate to the Apache HTTPClient project download page at http://hc.apache.org/downloads.cgi.
  2. Scroll to Commons HttpClient and download the binary release archive commons-httpclient-3.1.zip (or later).
  3. From the downloaded archive file, extract the commons-httpclient-3.1.jar and copy it to your Web application's /WEB-INF/lib directory.

Apache Commons Codec

  1. Navigate to the Apache Commons Codec project download page at http://commons.apache.org/downloads/download_codec.cgi.
  2. Download the binary release archive commons-codec-1.3.zip (or later).
  3. From the downloaded archive file, extract the commons-codec-1.3.jar and copy it to your Web application's /WEB-INF/lib directory.

Configure UrlRewriteFilter

Next, the Web application's web.xml file and the previously downloaded urlrewrite.xml file must be modified to enable the rewrite rules. To do so, perform the following steps:

  1. Modify the web.xml file for your Web application to include a reference to a new Servlet Filter as shown in the following example. The new <filter> may be added anywhere among the existing <filter> elements.

    <filter>
      <filter-name>UrlRewriteFilter</filter-name>
      <filter-class>org.tuckey.web.filters.urlrewrite.UrlRewriteFilter</filter-class>
    </filter>

  2. Declare a new <filter-mapping> element above any existing <filter-mapping> elements in your application and after all <filter> elements, as shown in the following example.

    <filter-mapping>
      <filter-name>UrlRewriteFilter</filter-name>
      <url-pattern>/*</url-pattern>
    </filter-mapping>

  3. Modify the urlrewrite.xml file to include a new rule as shown in the following example. Change the hostname and port from localhost:8000 to the actual address and port of your Kaazing Gateway Server.

    <rule>
      <name>Kaazing Gateway Proxy</name>
      <condition type="query-string" operator="equal">^\.kr=.*$</condition>
      <from>/.*</from>
      <to type="proxy" last="true">http://localhost:8000/?%{query-string}</to>
    </rule>

  4. Package and deploy your modified Web application that now contains the rewrite filter.
  5. Restart your Servlet container if necessary.
  6. To verify that the Servlet Container is now configured correctly, open a browser and navigate to the proxied URL, for example http://www.server.com/?.kr=xsp, and verify that the text PostMessageParentBridge is displayed.

Using Path-Prefix Request Proxying to Integrate with Kaazing Gateway Server

If your server topology uses an HTTP front-end other than Apache HTTP Server or Java Servlets, then it may not be able to send requests based on a query string, and instead be limited to proxying requests using a path prefix. To support path-prefix request proxying, the postMessage emulation must construct a URL of the form http://www.server.com/path-prefix?.kr=xsp.

By default, the postMessage emulation constructs a URL of the form http://www.server.com/?.kr=xsp, but this can be customized to include a user-defined path prefix. To do this, you must specify the following meta tag in the <head> section of the main application HTML page:

<meta name="kaazing:postMessagePrefix" content="/path-prefix" >

In this example, the user-defined path prefix is /path-prefix. This causes the request for http://www.server.com/path-prefix?.kr=xsp to be sent to the Web server during postMessage emulation initialization, and the Web server can then proxy the request to the Kaazing Gateway Server at http://www.gateway.com/?.kr=xsp.

Configuring Sun Java System Web Server to Use Path-Prefix Request Proxying

Sun Java System Web Server--formerly known as Sun ONE Web Server, Netscape Enterprise Server, and iPlanet Enterprise Server--is a server that does not support proxying requests using a query string. Instead, it relies on proxying requests using a path prefix. The Sun Java System Web Server Reverse Proxy add-on is required to enable path-prefix request proxying.

To configure Sun Java System Web Server to use path-prefix request proxying, you must perform the following steps:

  1. Download and Install the Reverse Proxy add-on for Sun Java System Web Server. When the add-on is installed, a $SERVER_HOME/plugins/passthrough directory is created.
  2. Navigate to the directory $SERVER_HOME/https-virtual-server/config, where virtual-server is the host and domain of the URLs serviced by your Sun Java System Web Server. For example, /opt/SUNWwbsrv/https-www.server.com/config services URLs such as http://www.server.com/.
  3. Edit the magnus.conf file to initialize the Reverse Proxy add-on's passthrough plugin during Sun Java System Web Server startup. For the value of the shlib attribute, specify the name of the passthrough plugin's shared library as shown in the following example:

    Init fn="load-modules" shlib="/opt/SUNWsbsvr/plugins/passthrough/libpassthrough.so"

  4. Edit the obj.conf file to associate the URL path with the KaazingGatewayProxy Object handler by adding a line to the <Object name="default"> section, as shown in the following example:

    NameTrans fn="assign-name" from="/path-prefix" name="KaazingGatewayProxy"

    Notes:

  5. Continue editing the file obj.conf to define the behavior of the KaazingGatewayProxy Object handler so that requests can be proxied to the Kaazing Gateway Server. Add a new <Object> section with the name KaazingGatewayProxy. For the value of the servers attribute, specify the URL of the Kaazing Gateway Server. Set the rewrite-host attribute to true, otherwise Kaazing Gateway Server will refuse to service the request. A complete KaazingGatewayProxy <Object> section is shown in the following example:

    <Object name="KaazingGatewayProxy" >
      Service fn="service-passthrough" servers="http://www.gateway.com"
      rewrite-host="true"
    </Object>

  6. Save the configuration files and restart the Sun Java System Web Server.
  7. To verify that the Sun Java System Web Server is now configured correctly, open a browser and navigate to the proxied URL, for example http://www.server.com/path-prefix?.kr=xsp, and verify that the text PostMessageParentBridge is displayed.

Troubleshooting

The following are some things that can go wrong during the Kaazing Gateway installation:

Port Conflicts

The most common problem occurs when another web server or process is already using the default port 8000. This is the default HTTP port that the Kaazing Gateway Server attempts to bind to at startup. To change this, perform the following steps:

  1. Open the file $KAAZING_HOME/conf/gateway-config.xml and search for instances of 8000.
  2. Change them to a port number that is not in use, and greater than 1024, as ports less than or equal to 1024 require superuser access to bind to under UNIX.
  3. Restart the Kaazing Gateway Server
  4. Access the Kaazing Gateway at http://localhost:<new-port-number>/ in your browser. For example: http://localhost:8884/

Localhost Not Configured

It can happen that “localhost” is not found when you try to access the Kaazing Gateway Server. This can happen if your browser is configured to use a proxy server. If this is the case, make sure your proxy configuration bypasses the proxy to access “localhost.”

Adaptavist Theme Builder (3.2.1) Powered by Atlassian Confluence 2.9, the Enterprise Wiki.
Free theme builder license