BBj User Authentication

BBj allows the administrator to require user authentication for all users of a particular BBjServices installation.

To enable or disable user authentication, use the Enterprise Manager configuration dialog and follow these steps:

Log in to Enterprise Manager on the server to be configured.
Navigate to BBjServices > Settings.
Check or uncheck the box labeled User Authentication.
Click [Save] in the upper left of the screen.

User authentication provides a dialog (or a prompt in the non-GUI environment) in which the user supplies a valid BBjServices username and password pair. An empty password is legal, although not advised. BBjServices fills in the user field with this value if a –u command line option specified.

After a successful login, BBjServices checks out a license to that valid username and returns that username via INFO(3,2). Sets the !DSUDDB key in the STBL.

Set a user password pair in the config.bbx file with the following line:

SET !DSUDDB=user=username,passwd=trogdor

Token-Based Authentication (JWT)

In addition to standard username and password credentials, BBj supports authentication using JSON Web Tokens (JWT). When using token-based authentication, the user provides a generated JWT token in place of the username. The password field is ignored during authentication processing, but it must still be provided as a non-empty string value (e.g., a dummy value like "nopassword" or "x").

Generating JWT Tokens

JWT tokens can be generated programmatically within a BBj application or administratively using the Enterprise Manager.

1. Programmatically via BBjAdminFactory

To generate a JWT auth token inside a BBj program using a user/password combination, call the getAuthToken method on BBjAdminFactory:

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

Additional overloaded getAuthToken() methods are available on BBjAdminFactory to allow setting custom token durations and adding custom payload data. For full details on available parameters, refer to the BBjAdminFactory API Documentation.

2. Via Enterprise Manager

Administrators can also manually generate tokens through the Enterprise Manager graphical interface:

Navigate to Security > Authentication Tokens.
Click the Add button.
Specify the target username for whom the token is being created.
Enter your password to validate that you have permission to create a token for that user.
(Optional) Configure additional payload attributes and specify the duration/expiration for the token.

Using JWT Tokens in Configuration

Once a JWT token is generated, it can be passed in place of the username in configuration settings or code. For example, in a config.bbx file or runtime STBL setting:

SET !DSUDDB=user=<JWT_TOKEN>,passwd=unused

Why Choose Token-Based Authentication Over Username/Password?

Opting for token-based authentication rather than embedding raw usernames and passwords into application code or configuration files provides several significant security and architectural advantages:

Credential Protection: Avoids hardcoding plaintext database or service passwords inside configuration files (such as config.bbx) or source code scripts, preventing credential leakage through repository check-ins or unauthorized file access.
Time-Limited Access & Expiration: Tokens can be configured with strict expiration times (duration), ensuring that even if a token is exposed, it automatically invalidates after a set window.
Scoped & Granular Permissions: Tokens can carry specific metadata/payloads allowing fine-grained authorization control without exposing master account credentials.
Simplified Revocation & Auditing: Tokens can be revoked or rotated independently without changing the underlying account's primary authentication password.

Additionally, configure the text in the dialog or prompt by entering the following lines in the config file with the desired dialog/prompt following the = sign:

SET userAuthentication.prompt.title=Login Required
SET userAuthentication.prompt.user=User:
SET userAuthentication.prompt.rememberUsername=Remember Username
SET userAuthentication.prompt.password=Password:
SET userAuthentication.prompt.button=Login
SET userAuthentication.prompt.cancel=Cancel
SET userAuthentication.prompt.attributes=

Note:

The attributes value is currently defined only for the DWC client, with values taken from the Attributes column on the dwc-login component page. For example:

SET userAuthentication.prompt.attributes=rememberme=false

When logging in, the user may press the Enter instead of clicking the button. To suppress the display of the button, use the following line in the config file:

set userAuthentication.prompt.button=

When a new BBj session is started via an SCALL or newBBjSession(), a user authentication dialog is displayed only if a –u is specified.

When user authentication is not enabled, RHOSTS (and optionally including IDENTD) authentication is performed.

CSS

The visual appearance of BUI controls is defined using CSS (cascading style sheets) rules. Easily change the default colors, border, and other settings by customizing these rules, all without changing any application code. See CSS API for a high-level overview of BUI CSS.

If User Authentication is selected in Enterprise Manager (see BBj Services - Settings), the user is prompted for a user name and password before being handed off to the application. By default, the login dialog looks like this:

Those five text values ("Login Required", "User:", "Password:", "Login", and "Cancel") can be customized through defined STBL values, either at runtime or in the config.bbx file. The styles can be customized with the following CSS style names:

.BBjUserAuthentication

.BBjUserAuthentication-title

.BBjUserAuthentication-panel

.BBjUserAuthentication-topPanel

.BBjUserAuthentication-userLabel

.BBjUserAuthentication-user

.BBjUserAuthentication-rememberUsername

.BBjUserAuthentication-passwordLabel

.BBjUserAuthentication-password

.BBjUserAuthentication-rememberUsername

.BBjUserAuthentication-buttonPanel

.BBjUserAuthentication-button

.BBjUserAuthentication-loginButton

.BBjUserAuthentication-cancelButton

And here's how it looks with a few very minor CSS tweaks:

Sample CSS

.BBjUserAuthentication
{
}
.BBjUserAuthentication-title
{
  background: blue !important;
  border-color: blue !important;
}
.BBjUserAuthentication .dialogMiddleCenter
{
  border-color: blue !important;
}
.BBjUserAuthentication-panel
{
  background: #f0f0f0 !important;
}
.BBjUserAuthentication-topPanel
{
}
.BBjUserAuthentication-userLabel
{
}
.BBjUserAuthentication-user
{
}
.BBjUserAuthentication-passwordLabel
{
}
.BBjUserAuthentication-password
{
}
.BBjUserAuthentication-buttonPanel
{
}
.BBjUserAuthentication-loginButton
{
}
.BBjUserAuthentication-cancelButton
{
}

Version History

BBj 20.12: added the rememberUsername property