UNIX Remote Host Validation

Description

On UNIX, remote connections to BBjServices are validated via either by /etc/hosts.equiv or by the .rhosts file.

Using the /etc/hosts.equiv file, the system administrator can configure global settings for the machines that will be trusted by the BBjServices machine. If a machine should be globally trusted so that users on that machine are allowed to use BBjServices as the same account on the BBjServices machine, then add the line "+<machine>" to the /etc/hosts.equiv file. After adding this line, no .rhosts manipulation is necessary.

NOTE: BBj DS services performed a DNS lookup on every entry in the .rhosts and /etc/hosts.equiv files. Depending on system configuration, the DNS lookups can take an excessive amount of time, causing the connection attempt to time out and cause either a !ERROR=72 or a !ERROR=12 (depending on whether the client or server timed out first).


In order for remote users to connect using .rhosts, follow the steps listed below::

STEP 1) If BBjServices will be running as root, ensure that every remote user has an account on the machine.

STEP 2) If BBjServices will be running as root, modify each remote user's .rhosts file. If BBjServices will be running as any other user other than root, modify this user's .rhosts file.

The .rhosts file is found in the user's home directory. The .rhosts file(s) should include all remote machines and users that are connecting to BBjServices.

For example:

tiger csmith <==== machine tiger, remote user csmith will be allowed to connect

rider + <==== machine rider, all remote users from this box will be allowed to connect

STEP 3) Set the .rhosts file permissions to 644.

STEP 4) Ensure that the .rhosts file for each user is owned by that user. For example, the .rhosts file for root must be owned by root and the .rhosts file for the user BBj must be owned by the user BBj.

Filesystem User/Password and Token-Based Authentication

In a multi-tier BBj environment, user authentication occurs when an application attempts to open a file on a remote BBj Filesystem Server. By default, BBj uses .rhosts authentication. However, another option is to use simple user/password or token-based authentication. Enabling password authentication on the BBj Filesystem Server switches the server to require explicit credentials (either a username/password pair or a JWT token) instead of relying on .rhosts to authenticate incoming remote connections. The administrator must enable this on the Filesystem server, and developers must include code in the application to provide the necessary credentials when accessing files on a remote BBj Filesystem Server.

Enable Password/Token Authentication on the Server

Using the Enterprise Manager, navigate to BBjServices > Servers > Filesystem and enable Password Auth for the Filesystem server.

Add BBj Application Code

When a Filesystem Server is configured to use password authentication, clients (and other remote BBjServices) connecting to that server must supply authentication credentials. This is accomplished using the !DSUDDB Global String (STBL):

Option A: Standard Username and Password Authentication

Pass the traditional username and password pair via the !DSUDDB STBL variable:

dummy$ = STBL("!DSUDDB", "user=jdoe,passwd=mypassword")

Option B: JWT Token-Based Authentication

Alternatively, BBj supports JSON Web Tokens (JWT) in place of standard user credentials. To authenticate using a token, pass the JWT token in place of the username. While the password parameter is ignored during token validation, it must still be supplied as a non-empty string value:

dummy$ = STBL("!DSUDDB", "user=" + token$ + ",passwd=unused")

Generating a JWT Token:

  • Programmatically: Generate a token within BBj code using BBjAdminFactory:

    token$ = BBjAdminFactory.getAuthToken("admin", "admin123")

Additional getAuthToken() methods are available on BBjAdminFactory to configure token duration and payload data. See the BBjAdminFactory API Documentation for more details.

  • Enterprise Manager: Generate tokens via Security > Authentication Tokens > Add. Provide the target user and your admin password to validate issuance. Custom payload and expiration duration can also be specified.

Once set (using either username/password or JWT token), subsequent file OPEN calls will use the specified credentials to connect to the remote Filesystem Server when data server syntax is used:

OPEN(chan)"//path/to/my/file.dat"

Why Opt for Token-Based Authentication Over User/Password?

Using token-based authentication instead of raw username and password credentials in application code or configuration files provides several key advantages:

  • Security against Hardcoded Passwords: Prevents storing sensitive primary user account passwords in plaintext scripts, STBL calls, or configuration files, mitigating risk from source control leaks.

  • Controlled Lifetime: Tokens can be issued with explicit expiration times (duration), minimizing the window of vulnerability if a token is intercepted or logged.

  • Granular Access & Auditability: Tokens can include specific payload data tailored to particular operations and can be revoked individually without requiring account password changes.