Two-Factor Authentication in BBj


BBj 23.00 introduced support for two-factor authentication in the Enterprise Manager, Admin API, and BBj applications.

Two-factor authentication (2FA) is a security process requiring users to provide two different authentication factors to access a system or application. TOTP, or Time-Based One-Time Password, is one method of implementing 2FA.

In a TOTP-based 2FA system, the user's account uses a secret key known only to the user and the system. The system generates a one-time password (OTP) based on this secret key and the current time. The user must then provide this OTP in addition to their regular password to authenticate themselves.

There are several reasons why 2FA with TOTP is important for security:

  1. Protection against password breaches: Passwords can be stolen through various means, such as phishing attacks or data breaches. By requiring a second authentication factor, such as a TOTP-based OTP, the system can ensure that even if a user's password is compromised, their account remains secure.
  2. Defense against account takeover: If an attacker gains access to a user's password, they may attempt to take over the account. With 2FA, even if the attacker has the password, they still need the second authentication factor to access the account, making it more difficult for them to succeed.

Overall, 2FA with TOTP is an effective security measure that can help protect user accounts from unauthorized access and mitigate the impact of password breaches.

2FA in the Enterprise Manager and BBj

When 2FA is enabled, users experience an additional prompt to enter the 2FA code after providing a valid user and password as shown in Figure 1 and Figure 2.

Enterprise Manager Login Flow

Figure 1. Enterprise User Log In Dialog

After providing the username and password, if and only if they are valid, the user will be presented with another dialog where they’ll provide the 2FA code. The 2FA code may be provided by an authenticator app such as the Google Authenticator App or via email sent by BBj. See the Configuration section below for more information.

Figure 2. Enterprise Two-Factor Authorization Code Dialog

BBjApplication Login Flow

When BBj’s “User Authentication” setting is enabled (see BBjServices->Settings in the Enterprise Manager), BBj application login flow is the same as that when using the Enterprise Manager, shown in Figure 3 and Figure 4. Developers may also utilize the Admin API to manage user authentication and 2FA code validation. See the Using 2FA in BBj Programs section below for more information.

Figure 3. BBjApplication User Log In Dialog

Figure 4. BBjApplication Two-Factor Authorization Code Dialog


The BBj Enterprise Manager provides an interface for enabling and configuring 2FA. There are a few steps that need to be followed when choosing to enable 2FA.

1. Create an Email Service to send email notifications

A BBj email service uses SMTP to send email using the configuration provided for the service. Please consult your email service provider or system administrator for the necessary information. The example below in Figure 5 shows how someone might configure their email service to send email through Namecheap’s SMTP service. Make sure to test your email service after configuration using the 'Send Test Message' button:

Figure 5. Email Services Configuration Example

2. Update user accounts so that each account that will use 2FA has a valid email address associated with it.

Providing an email address for each user account, as shown in Figure 6, allows BBjServices to send an email to those users with the information necessary to configure their 2FA. The email message will include instructions for completing the configuration (QR code, authenticator app key, etc.).

Figure 6. Providing an Email to be Associated with the User Account

3. Choose the preferred 2FA method (TOTP authentication app or email).

The current options available include the use of an authenticator app or an email 2-step code, as seen in Figure 7. For more information about the Google Authenticator app, see the Google Authenticator App section below.

When using the Email 2-Step Code option, when the user attempts to log in, if their username and password are valid, they will be sent an email message containing the 2-factor authentication code. This code will be valid for the amount of time specified in the Code Validity field.

Figure 7. Two-Factor Authentication Methods in Dropdown Menu

4. Enable 2FA for the desired users.

Administrators have the ability to enable 2FA for all users or a subset of users. In the example below in Figure 8, only the admin user has 2FA enabled.

Once you save the changes, make sure to click the 'Verify Configuration' button to ensure everything will function properly. Keep in mind that once 2FA is enabled, users for which it is enabled will need to provide the 2FA code during login.

The Email User Instructions button will send out setup instructions for each user for which 2FA is enabled. The email will include a QR code and setup key to use if using the authenticator method.

Figure 8. Two-Factor Authentication Settings Enabled for Admin Users Only

Google Authenticator App

Google Authenticator is a two-factor authentication (2FA) app developed by Google that enhances the security of online accounts by adding an additional layer of protection beyond just a password. It is commonly used to secure various online services, such as email accounts, social media platforms, and financial websites.

Here's how Google Authenticator works and what it's used for:

  1. Installation and Setup: Users need to install the Google Authenticator app on their smartphone or tablet. Once installed, they can associate it with their online accounts that support two-factor authentication.
  2. Generating Time-Based One-Time Passwords (TOTPs): When setting up 2FA with Google Authenticator, the user pairs the app with their online account. This involves scanning a QR code provided by the service or manually entering a secret key. This key is used to synchronize the app's internal clock with the server's clock.
  3. Time-Sensitive Codes: Once the synchronization is done, the app generates time-based one-time passwords (TOTPs). These passwords are six-digit numeric codes that change every 30 seconds. The code is generated based on the current time, the secret key, and a cryptographic algorithm. Because the password changes frequently, even if an attacker somehow obtains one code, it would be useless within a short time.
  4. Authentication Process: When logging into a supported online service, the user is required to provide not only their regular password but also the currently displayed TOTP code from the Google Authenticator app. This means that even if someone knows the user's password, they would still need access to the user's physical device to generate the correct TOTP.
  5. Enhanced Security: The use of two-factor authentication significantly improves account security. Even if a malicious actor manages to obtain or guess a user's password, they would also need physical access to the user's device to gain access to the account.

In summary, Google Authenticator is a mobile app that generates time-based one-time passwords (TOTPs) to provide an additional layer of security, known as two-factor authentication (2FA), for online accounts. It's used to prevent unauthorized access to accounts by requiring users to provide a constantly changing code along with their regular password during the login process. This helps protect accounts from various cyber threats, such as phishing, password breaches, and unauthorized access.

Using 2FA in BBj Programs

Some developers rely on BBj authentication to manage user log ins. However, many developers handle authentication at the application level. The Admin API provides a means of utilizing the BBj security features including 2FA without enabling it globally at the BBjServices level.

The following is a simple BBj program that prompts the user to enter a username and password. If they are valid and 2FA is enabled, the user will be prompted to enter the 2FA code. If 2FA is not enabled for the user, they will proceed without the need for a 2FA code:

    addr! ="localhost")
    port = 2002
    ssl = 0

    print "Enter Username:"
    input username$

    print "Enter Password:"
    input password$

    api! = BBjAdminFactory.getBBjAdmin(addr!, port, ssl, username$, password$, err=authFailed)
    goto success

    rem 'Check the error message to see if it's related to 2FA
    if (new String(errmes(-1)).indexOf("2-factor authentication") > 0) then
        rem 'It was 2FA related so prompt for the Code
        print "Enter the 2FA code:"
        input code$

        rem 'Try again with the 2FA code.
        api! = BBjAdminFactory.getBBjAdminWith2FA(addr!, 2002, ssl, username$, password$, code$, err=beginAuth)
        rem 'It was not a 2FA-related error so simply print the error and start over
        print errmes(-1)
        goto beginAuth

    print "Successfully logged in!"
    goto beginAuth