Using the Proxy Server


The LDAP authentication feature became part of StreamBase Server itself. See Using LDAP Authentication.

When you need to enable secure access to a StreamBase Server from a client application, you can use the StreamBase sbproxy server. For example, you might want to allow access only from certain network domains, to prevent unauthorized persons from reading from or writing to streams or performing administrative commands, or to grant or deny specific actions to different people. The proxy server can be configured to identify trusted entities and to enforce authorized rights and restrictions.

Running StreamBase in secure mode requires no Client library changes to the client or the application being run by the sbd server: security is a deployment option, implemented entirely in the runtime environment (which is why it is not available in StreamBase Studio).

Your organization's security requirements and deployment environment will determine the options that you will choose from. To implement your choices, we suggest following the guidelines in this topic and related topics as follows:

  1. To understand the basic concepts, read Overview of Proxy-Based Security in this topic.

  2. To understand the options you will need to choose from, read Options in this topic.

  3. For information about non-StreamBase components that are used with proxy-based security, read External Components in this topic.

  4. To configure the sbproxy server on the deployment system, follow the instructions in Configuring the Proxy Server.

Running the Proxy Server explains how to run the sbproxy server on the configured deployment system.

Overview of Proxy-Based Security

The StreamBase proxy server, sbproxy, is configured using the security section of the sbd server's sbconf configuration file. When the <security> element exists, sbd runs in secure mode: it listens for connections only on localhost, so connections from remote computers cannot be made. In this way all communications between clients and the sbd go through the sbproxy server.

When proxy-based security is enabled, client/server connections occur over either one-way or two-way Secure Socket Layer (SSL) connections, providing encrypted communications.

The following diagram shows the runtime components involved in StreamBase authentication with one-way SSL connection:

In the preceding figure, when the client attempts to connect to the StreamBase systems, the connection occurs through the proxy server, not the sbd server. An X.509 certificate is configured with the proxy server, and is used to authenticate the signature submitted by the client. Usernames and passwords can be authenticated either in the sbconf file or through one or more optional LDAP servers.

The next diagram shows a detail of a similar system with a two-way SSL connection, where both the StreamBase client and proxy server have a certificate:

With certificates on both sides, authentication can be more secure, and the certificates authenticate not only the client signature, but usernames and passwords as well.

Note that the certificates and LDAP servers are external resources, not supplied by StreamBase. You must install them separately, as discussed in External Components.


This section describes the options available for your proxy-based security.

SSL Connections

All communications between the client and the StreamBase sbproxy server occur over Secure Socket Layer (SSL) connections. Your configuration of certificates and the sbconf file will be based on one of these SSL options:

One-way SSL

A single, signed X.509 certificate and keystore are configured on the StreamBase system's proxy server. The proxy server accepts the client. User names and passwords can be stored in either an LDAP server or in the sbconf file.

This is a reasonable option for your organization if a single certificate on the sbd's host system provides adequate security for your deployment.

Two-way SSL

Requires X.509 certificates and keystores on the sbproxy server and on each participating remote client. Usernames and passwords are not entered by users, but provided through the certificates.

Consider this option if your organization requires the maximum level of security.


For StreamBase clients that communicate over SSL, in URIs use the sbs: protocol, not sb:.


The sbproxy server can be configured to work with one or more LDAP servers to authenticate users and to help control user activities. The LDAP servers can be located remotely from the sbproxy and client systems.

When accessing an LDAP server, the sbproxy must identify itself using one of these methods:

  • The sbproxy can pass its credentials, stored in the sbconf file, to the LDAP server for authentication.

  • The LDAP server can have its own client certificate on the sbproxy's host system, to authenticate sbproxy requests.

Controlling User Activities

Once users have accessed the running client (for example, after entering a name and password), you may want to limit what they can do. Of course, you may decide not to impose any such restrictions beyond authentication. In this case, any client user can use any available functions.

If you want to limit the activities of users, you will begin by defining roles, which are associated with specific actions. You can then authorize different users to perform different operations by assign users to roles. Authorization involves these constructs:


An action is a fixed set of commands that can be performed on a StreamBase Server. There are two pre-defined actions, which cannot be changed:


Applies to these commands:

shutdown, shutdownsecondary, suspend, resume, restart, getOperatorProperty, setOperatorProperty, addContainer, removeContainer, checkpoint, loadcheckpoint, listConnections, typecheck

Status applies to these commands:

status, describe, list

These commands also imply Status:

Enqueue stream-name, Dequeue stream-name

A role is a collection of one or more actions. You can define multiple roles to create different groupings of actions.


Also known as principals, users can be assigned roles.

By mapping roles to actions, and then assigning users to roles, you can achieve fine-grained control over user activities. You can use either of these methods:

Control user activities in the sbconf file only

You can define actions and roles and assign them to users, all in the sbconf file.

This option can be useful for small-scale deployments and debugging. For larger, production environments, maintaining the list of users in the sbconf file may be inefficient: consider the next option instead.

Control user activities in the sbconf file and LDAP server

If you are using LDAP, you can define actions and roles in the sbconf file, and then assign them to users in the LDAP server.

Consider this option if you want to manage user authorization independently of the sbproxy server configuration.

External Components

This section describes the non-StreamBase components that work with proxy-based security. Certificates and Keystores are required; LDAP servers are optional.

X.509 Certificates and Keystores

The StreamBase X.509 certificates provide encrypted communications and, optionally, client authorization.

There are many tools and commands that can be used create X.509 certificates, and there are several file formats that store them. You can use any method that creates valid X.509 certificates that are signed by a recognized certificate authority (CA), but generally the following steps apply:

  1. Create a PKCS#10 format Certificate Signing Request (CSR) that contains the user's identity information and the encryption. Specify:

    • A key signing algorithm, such as DSA or RSA.

    • The size of the key: a multiple of 64 that is between 512 and 1024.

  2. Obtain a signed certificate from a CA.

  3. Create a keystore for each certificate, using the keytool utility (included in the Oracle Java JDK). A keystore is a protected file that contains the certificate and keys needed to access it. The keystore must have a password.

LDAP Servers

Install the LDAP servers that you require in your deployment system. Use any LDAP server you choose (for example, openldap); StreamBase does not supply one.


If you configure multiple LDAP servers, they must all contain identical information. The sbproxy can access any of the LDAP servers, sending requests in round-robin fashion.

Cipher Suites

SSL encryption requires a cipher suite. By default, the StreamBase proxy server will automatically use an appropriate cipher suite among those that are included with the JVM used by StreamBase. However, if you install different cipher suites or need to restrict the set of cipher suites used, you can enumerate the cipher suites in the sbconf file.

SSL Proxy for C++ and .NET Clients

C++ and by extension .NET StreamBase clients do not possess native SSL capability. However, you can configure them to use 1-way SSL authentication by installing the third-party utility sTunnel, which allows any non-SSL-capable StreamBase client to perform 1-way SSL with sbproxy, in the following configuration:

sbc <-- (non-SSL) --> sTunnel <-- (SSL) --> sbproxy <-- (non-SSL) --> sbd

That is, sTunnel serves as an SSL encryption wrapper between a remote client and server.

You can download sTunnel in StreamBase Studio and install it by doing as follows:

  1. Click FileStreamBase Component Exchange

  2. In the search box, type ssl

  3. Select SSL Proxy for C++ and .NET StreamBase Clients

  4. Follow the instructions in the README that StreamBase Studio then displays for setting up and running stunnel.

Related Topics