Authentication Sample

Contents

This Sample's Files
Running the Authentication Sample
Importing This Sample into StreamBase Studio
Sample Location

This sample demonstrates the use of StreamBase authentication. That is, optionally limiting access to certain StreamBase commands, such as sbadmin shutdown, to users who can provide authentication credentials associated with one of the StreamBase roles.

Note that the authentication credentials that you define for use with StreamBase commands have no connection with system-level accounts. They are independent of each other. While you could use the same user-name and password combinations for StreamBase and a system-level account, it is not necessary.

Unlike the samples that focus on StreamBase operators, where the *.sbapp file contains specific data processing features, the Authentication sample is focused on configuration steps. It allows you to observe what happens at runtime when different types of StreamBase commands are attempted.

For more information, see the Using StreamBase Server Simple Authentication topic in the Administration Guide.

This Sample's Files

The Authentication sample consists of:

A StreamBase application, authentication.sbapp.
Scripts to add and remove authentication credentials (users). The adduser.* script uses an sbuseradmin command to add users to the sbpasswd file. The deleteuser.* script removes users from the sbpasswd file.
A feed simulation that provides test data, order_simulation.sbfs.
A comma-separated data file, orders.csv.
The authentication.sbconf configuration file for the StreamBase Server process that will host the authentication.sbapp StreamBase application.

Note

While you can examine authentication.sbapp in StreamBase Studio, note that the point of this sample is not the application diagram itself. The point of this sample is to notice how once authentication is enabled, users must provide valid credentials in order to run StreamBase administration commands such as sbd, sbfeedsim, sbc dequeue, and sbadmin shutdown.

The installed sample contains a customized StreamBase Server configuration file, authentication.sbconf, which includes the following <authentication> section:

<authentication>
    <param name="enabled" value="true"/>
    <param name="type" value="sb-password-file"/>
    <param name="filepath" value="./sbpasswd"/>
</authentication>

This configuration enables authentication for all StreamBase Server administration functions. (In the default configuration file, authentication is disabled.) The file that contains the StreamBase authentication information (user name, password, and roles) is sbpasswd in the sample's directory.

For production applications, an empty password file is installed at streambase-install-dir/etc. On UNIX, this file is protected by access rights. You must use a privileged account such as root that has access rights to this file to add, remove, or update StreamBase users.

Running the Authentication Sample

You can and should open this sample's application files in StreamBase Studio to study how the applications are assembled. However, this sample is designed to be run in UNIX terminal windows or Windows command prompt windows. On Windows, be sure to use the StreamBase Command Prompt from the Start menu as described in the Test/Debug Guide, not a standard command prompt.

To run this sample:

Open three terminal windows on UNIX, or three StreamBase Command Prompts on Windows. In each window, navigate to the directory where the sample is installed, or to your workspace copy of the sample, as described above.

On UNIX, run adduser.sh. On Windows, run adduser.bat. These scripts add the following user, password, and roles values to the sbpasswd file:

User	Password	Roles
sbmanager	sbmanager	SBAdmin
sbdev	sbdev	SBDeveloper
sbtest	sbtest	SBUser

On UNIX and Windows, in window 1, start StreamBase Server with this command:
```
sbd -f authentication.sbconf authentication.sbapp
```
On Windows in window 2, dequeue from the output stream ExpressOrders with the following command
```
sbc -u sb://localhost:10000;user=sbtest;password=sbtest dequeue ExpressOrders
```
On UNIX in window 2, enclose the URI string in quotes so that the semicolon is not interpreted as a delimiter:
```
sbc -u "sb://localhost:10000;user=sbtest;password=sbtest" dequeue ExpressOrders
```
Because authentication is enabled, you are able to execute this sbc dequeue command with the specified sbtest credentials.
On Windows in window 3, run sbfeedsim to enqueue tuples:
```
sbfeedsim -u sb://localhost:10000;user=sbtest;password=sbtest order_simulation.sbfs
```
On UNIX in windows 3, use quotes around the URI argument:
```
sbfeedsim -u "sb://localhost:10000;user=sbtest;password=sbtest" order_simulation.sbfs
```
In window 2, look for the following tuples:

SB-1202,Network Management Corp,Desk Top Model 204,DT204,15,300,4500,true
SB-1204,Logical Design,Server Model 100,SV100,3,5000,15000,true
SB-1205,Mirage,Desk Top Model 204,DT204,5,300,1500,true
SB-1208,Royal Club,Desk Top Model 204,DT204,3,300,900,true
SB-1209,Core Security,Server Model 100,SV100,4,5000,20000,true
SB-1210,O'Reilly System,Desk Top Model 204,DT204,20,300,6000,true
Next, try to shut down the server without credentials. In window 3, type:
```
sbadmin shutdown
```
Without credentials, the server refuses the shutdown request:
```
sbadmin: sb://localhost:10000/: Authentication failure. 
    Method: status, role: SB User, user:
```
Now try to shut down the server with the credentials for the sbtest user:
```
sbadmin -u sb://localhost:10000;user=sbtest;password=sbtest shutdown
```
Server shutdown is restricted to users with the SBAdmin role, so this command also fails:
```
sbadmin: sb://localhost:10000/: Authentication failure. 
    Method: shutdown, role: SBAdmin, user: sbtest
```
Finally, shut down the server with the credentials for an administrative user:
```
sbadmin -u sb://localhost:10000;user=sbmanager;password=sbmanager shutdown
```
This time, the command succeeds. Look for a StreamBaseServer shut down message in window 1.
Delete the StreamBase users from the sbpasswd file using one of the following scripts:
- deleteuser.bat (Windows)
- ./deleteuser.sh (UNIX)

Importing This Sample into StreamBase Studio

In StreamBase Studio, import this sample with the following steps:

From the top menu, click File → Load StreamBase Sample.
Select this application from the Applications list.
Click OK.

StreamBase Studio creates a project for each sample.

Sample Location

When you load the sample into StreamBase Studio, Studio copies the sample project's files to your Studio workspace, which is normally part of your home directory, with full access rights.

Important

Load this sample in StreamBase Studio, and thereafter use the Studio workspace copy of the sample to run and test it, even when running from the command prompt.

Using the workspace copy of the sample avoids the permission problems that can occur when trying to work with the initially installed location of the sample. The default workspace location for this sample is:

studio-workspace/sample_authentication

See Default Installation Directories for the location of studio-workspace on your system.

In the default TIBCO StreamBase installation, this sample's files are initially installed in:

streambase-install-dir/sample/authentication

See Default Installation Directories for the location of streambase-install-dir on your system. This location may require administrator privileges for write access, depending on your platform.