Configuring Windows Service with Authentication

Contents

Configuring One Service for Authentication
Error Conditions
Configuring Two or More Services for Authentication

This topic describes how to configure the Windows registry to allow StreamBase Server, when run as a Windows service, to make use of the StreamBase authentication system. The instructions on this page apply to you only if:

You have enabled the StreamBase authentication system, as described in Using StreamBase Server Simple Authentication.
You have enabled StreamBase Server to run as a Windows service, as described in Running StreamBase Server as a Windows Service.

The steps on this page supplement the setup described on those two pages, and does not replace that setup in any way. You must still configure both features independently, and then turn to this page to bind those features together.

Configuring One Service for Authentication

When StreamBase Server runs as a Windows service, it uses the access control provided by the StreamBaseAdminClient API to determine when the server is ready to accept connections, and when to allow server shutdown commands. If you enable the StreamBase authentication system, you must also configure at least one StreamBase user name with the SBAdmin role, and you must specify that user name and password in the registry.

Follow these steps:

Use the sbuseradmin command to create a StreamBase user with the SBAdmin role. For instructions, see Using StreamBase Server Simple Authentication and the sbuseradmin reference page.

For example, create the StreamBase user sbservicerunner with password n0tw3llkn0wn with a command like the following:
```
sbuseradmin -a -n sbservicerunner -p n0tw3llkn0wn -r SBAdmin
```
Notes
- TIBCO recommends, but does not require, that you create a unique user name for Windows service control. That is, do not reuse a user name you create for a person to use.
- Remember that the StreamBase authentication system is independent of the Windows NTLM authentication system, or any other authentication system on your network. You can re-use the same user name as an existing Windows login name, but that does not mean you thereby participate in the Windows authentication system for StreamBase access.
- The password you provide is stored in the Windows registry in clear text, and might appear in clear text in Event Log error messages. Therefore, use a unique, throwaway password that is not the same as any other administrative password on your network.
Open regedit or another registry editor, and navigate to the StreamBase Server sub-key for your StreamBase release, as described in Placeholder Sub-Keys.

Open the sbd64.n.m sub-key for the 64-bit StreamBase Server. (If a sub-key for your StreamBase Server instance does not exist for your installation, create it.)

If you are adding authentication to a server with an alternate service name (as described in Setting Up Multiple StreamBase Services), create an empty sub-key with the same name as your alternate service.

In the sub-key folder that matches your StreamBase Server's service name, add the following string (REG_SZ) keys. The key names are case sensitive and must be spelled exactly as shown:

Registry key to add	Contents	Example
`sbWindowsServiceUserName`	The user name you created with the sbuseradmin command.	sbservicerunner
`sbWindowsServicePassword`	The password you gave to the user name with the sbuseradmin command.	n0tw3llkn0wn

For example:

Important! As part of the initial steps to enable StreamBase authentication (described in Enabling Authentication), you generated and edited a server configuration file. In that file, you changed the <authentication> element's enabled parameter to true.

In the same section of the server configuration file, you must also change the filepath parameter to specify a full, absolute path to the sbpasswd file. The default configuration file specifies this path by means of an environment variable, but that variable is not available when running the server as a service.

For example, use a setting like the following example:
```
<param name="filepath" value="C:/TIBCO/sb-cep/7.6/etc/sbpasswd" />
```

Error Conditions

If StreamBase authentication is enabled (that is, if the <authentication> element's enabled parameter is set to true in the server configuration file), the server fails to start if either of the sbWindowsService* registry keys is not present. In this case, the server writes an entry to the Windows Event Log before exiting.

If the sbWindowsService* registry keys are present, but their contents do not match an entry in the sbpasswd file, then the server starts but cannot respond to connection attempts. The following events trigger this error condition:

The user name in sbWindowsServiceUserName is not found in the sbpasswd file.
The user name is found, but the password in sbWindowsServicePassword does not match the password placed in the sbpasswd file.
The user name is found, but it does not have SBAdmin privileges.

In these cases, the server writes a warning in the Windows Event Log every 30 seconds for the next four minutes. The warning states that the server at a particular StreamBase URI is not yet responding. The StreamBase URI contains the service user name and password that it is attempting to use. The Windows Service Control Manager eventually condemns the server as unresponsive, but leaves the server running. In this case, you must use the Windows Task Manager to kill the server process.

Configuring Two or More Services for Authentication

You can have more than one StreamBase Server instance configured to run as a Windows service on the same machine, as described in Setting Up Multiple StreamBase Services. In this case, you must configure the sbWindowsService* registry keys for each service instance.