Skip to main content

BlockID Legacy Authentication Broker

Overview​

A BlockID Authentication Broker is installed on a client environment to allow the BlockID Admin Console (running in the cloud) to communicate within a client’s environment. All connections made by the broker are outbound and there is no need for any inbound connectivity into the company's network. The BlockID Authentication Broker is a lightweight JAVA application that provides a mechanism, communicates outbound only, and handles the flow of encrypted traffic between the Credential Provider (on Windows), Network Device Enrollment Service (NDES), Active Directory (AD), and the 1Kosmos cloud.

BlockID Authentication Broker is a proxy enabled, supports proxy authentication, and uses a proxy to connect to the 1Kosmos cloud.

Prerequisites:​

You will need the following resources and privileges to complete this installation:

  1. OS - Linux (supports only Linux), RHEL 7 and above
  2. JAVA - Java SE version 8, or OpenJDK version 17.02 LTS
  3. RAM - 2 GB (Minimum)
  4. Two Virtual CPUs

Permissions:​

  1. Permissions to the installation folder and install the BlockID Authentication Broker application on the Linux server.
  2. Outbound internet access and permission to communicate with the tenant URL on TCP ports 80 and 443.
  3. Proxy URL in case the enterprise requires that the BlockID Authentication Broker communicate outbound through a proxy.
  4. Non-authenticated proxy connection.
  5. Authentication credentials for non-proxy connection.
Note:

The BlockID Authentication Broker Installation (.zip) file is named as blockIdSetup-<version number>.zip. To get the BlockID Authentication Broker installation file, please contact your 1Kosmos representative.

Enable Authentication Broker module and obtain websocket URL from the BlockID Admin Console:​

  1. Login to your BlockID Admin Console, navigate to *Administration Console > Auth Configuration > Authentication Modules*.
  2. From the All Authentication Modules section, click on the Add this Module + icon for the Authentication Broker module. The Authentication Broker module is displayed in the Enabled Authentication Modules section.
  3. Click on the Edit & Configure this Module pencil icon for that module.
  4. In the Authentication Broker screen, click Enable.
    • Copy the URL generated for the broker websocket and save it.

Installation Steps:​

  1. Place and unzip the BlockID Authentication Broker Installation file within a particular folder on the Linux server. This will create the following folders and files within the main folder where the installation file is placed:

    • Folders:

      • Conf: This folder contains the configuration files in the <configurations_filename>.yml format. For example, default.yml.
      • Libs: This folder contains the required libraries to run the broker.
      • Logs: This folder contains the default.log file with all the logs.
      • Pid: The broker uses this folder during runtime.

    • Files:

      • startClient.bsh: This is a script file to start the broker.
      • stopClient.bsh: This is a script file to stop the Broker.

  2. On the Linux server:

    • To start the BlockID Authentication Broker:
      • Run ./startClient.bsh to start the broker. The -P regulates the port on which the broker will be running. By default, the port is 8081, you can specify this while running ./startClient.bsh.

  3. Open the web browser, enter the Broker Server FQDN URL that is http://<BROKER_SERVER_HOSTNAME>:8081 in the Address bar, and press Enter. The Configure Websocket Client application screen is displayed. This is the enterprise screen to configure the Broker.

  4. In the Configure Websocket Client application screen, it is mandatory to fill in details in all the fields given in the following tabs.

    • In the LDAP or AD Configurations tab:
      • In the BlockID Broker Core Config section:
      • In the LDAP or AD Configuration section, enter your AD configuration details.
    • In the SCEP Configuration tab, enter your SCEP and NDES server configuration details.
    • Click Submit.

  5. To verify that the BlockID Authentication Broker has started successfully:

    • Run the tail -f logs/default.log command. You will get the default connection logs that show the connection has been established to the broker, the broker has started up successfully, and the broker can communicate with the tenant.
      • For example, you will get the following logs: isHealthyProxy checking host: <YOUR_TENANT_URL> using proxyUrl: <YOUR_PROXY_URL>MessageHandlerTask PINGMessageHandlerTask PONG received from server

  6. To establish a successful connection between the BlockID Authentication Broker and the tenant, you need to perform the following tasks in the BlockID Admin Console:

    • Navigate to *Administration Console > Auth Configuration > Authentication Scheme*.
      • Click on the Edit button for the default authentication scheme.
      • Select Modules: select broker.
      • Select Criteria: select Required.
      • Click Save.
    • Navigate to *Administration Console > Enterprise Configuration > SCEP Configuration*, enable the Simple Certificate Enrollment Protocol Broker option and click Save & Apply. The BlockID Authentication Broker has successfully been installed and configured on your server.

  7. Follow the below steps to install and configure the second broker:

    • You will require a different server to install a second broker. Perform the BlockID Authentication Broker installation steps.
    • Perform the AD/LDAP configurations in the Configure Websocket Client application screen of your broker.
    • Note that, there is no need to perform any configurations in the BlockID Admin Console.

Test the Broker Connection:​

  1. In your browser, enter your tenant’s URL for the BlockID Admin Console.
  2. In the login screen, enter your AD username and password details. The BlockID Authentication Broker will authenticate your details against your AD and grant access to the BlockID Admin Console upon successful authentication.

Troubleshooting Steps:​

  1. If BlockID Authentication Broker is not connected and you are not receiving the PING and PONG messages in the default.log file in the logs folder, then perform the following steps:
    • Check the broker URL is entered correctly in the broker configuration.
    • Check whether the proxy is preventing the broker from communicating with the tenant.
      • Check the Proxy logs and allow the broker to communicate with the tenant.
    • During authentication, if the user is not getting authenticated successfully in the BlockID Admin Console:
      • In the broker logs, check if the broker can connect to Active Directory (AD).
    • Check if the broker can connect to CA and NDES servers properly.
  2. To check whether the broker is running or not:
    • Navigate to the Broker Configuration screen and refresh the screen to check whether it has got stopped or not.
    • Check the broker logs:
      • Run tail -f logs/default.log
    • The broker is a java application, hence, to check whether any JAVA process is running on the Unix machine:
      • Run ps -ef | grep java This will show you all the java processes that are running on the Unix machine.

BlockID Legacy Authentication Broker User Guide​

The BlockID Authentication Broker is a lightweight JAVA application that provides a mechanism, communicates outbound only, and handles the flow of encrypted traffic between the Credential Provider (on Windows), Network Device Enrollment Service (NDES), Active Directory (AD), and the 1Kosmos cloud.

This document describes the following fundamental concepts supported by the BlockID Authentication Broker:

  1. Multiple Broker Support
  2. Broker Legacy AD Password Reset Support

Multiple Broker Support​

1Kosmos provides multiple brokers setup for BlockID Admin Console. To achieve this, install each broker on a separate Linux/Unix machine, and in each broker configuration, add the same broker auth module’s WebSocket URL and AD/LDAP details of BlockID Admin Console.

When a BlockID Admin Console is connected to multiple brokers, it will detect if a broker is brought off-line and automatically route requests to the other connected brokers. Also, additional brokers can be added to the system to provide additional performance and availability.

The BlockID Admin Console will randomly select any broker and establish a connection with it at a time (until that broker stops working) out of the number of linked brokers. This allows the BlockID Admin Console to provide a high level of performance and uptime that cannot be achieved when just a single broker is providing service.

The BlockID Admin Console will detect if a broker is brought off-line or stopped and automatically route the requests to the other linked brokers. Also, additional brokers can be added to the system to provide additional performance and availability.

tip

To Install and configure more than one broker for best performance and availability, they should all be on separate Linux/Unix machines.

To configure multiple brokers support for the BlockID Admin Console:

  1. BlockID Admin Console configurations:

    • Login to the BlockID Admin Console.
    • Navigate to Administration Console > Auth Configuration > Authentication Modules.
    • From the Enabled Authentication Modules section, click on the Edit & Configure this Module pencil icon for the enabled authentication broker module.
    • Copy the websocket URL generated for the broker and save it.

  2. Broker configurations:

    • On the Linux/Unix server, start the BlockID Authentication Broker.
    • Open the web browser, enter the Broker Server FQDN URL that is http://<BROKER_SERVER_HOSTNAME>:<port> in the Address bar, and press Enter. The Configure Websocket Client application screen is displayed. This is the enterprise screen to configure the broker.
    • In the Configure Websocket Client application screen:
      • Navigate to LDAP or AD Configurations > BlockID Broker Core Config > Broker WebSocket, enter the same websocket URL copied from the BlockID Admin console.
      • Navigate to LDAP or AD Configurations > LDAP or AD Configuration, enter the similar AD configuration details added within the other brokers LDAP section.
      • Click Submit.
Info:

Note that, multiple brokers should include the same WebSocket configurations to provide support to the same BlockID Admin Console.

Broker Legacy AD Password Reset Support​

This feature allows the user to reset his/her password. For example, the BlockID mobile app has a reset credentials feature, that would use the password reset if the broker was configured for the authentication. The BlockID Admin console also has a password reset feature. The broker searches for the user using the config parameters and if the searched user is found, the broker binds it as the administrative user to the configured directory and modifies the password of the user.

Note:

Active Directory password resets always require an SSL/TLS connection from the broker to the AD server. LDAP directories may or may not require SSL/TLS depending on how they are configured.

To reset the password, perform the following steps:

  1. From the BlockID app:
    • Open the BlockID mobile app, click RESET AD CREDENTIALS.
      • Update password for below userid: It shows the username of the persona.
      • New Password: Enter the new password.
      • Confirm Password: Enter the new password again.
      • Click Reset Ad Credentials. This will reset the password for the selected persona within the application.
  2. From the BlockID Admin Console:
    • Login to BlockID Admin Console.
    • From the top right corner, click on the User Account list (third list) and click Profile.
    • Click on the Password Management tab.
    • In the Password Management tab:
      • Password: Enter the new password.
      • Confirm Password: Enter the new password again.
      • Click Update Password. This will update the password for the selected user profile within the application.

Upgrading BlockID Authentication Broker​

In order to ensure this is seamless, download the latest broker, and perform the following steps for the upgrade. The following steps will assist you in manually installing the broker for LDAP/AD connectivity.

Note:

The expected duration of the activity is approximately 20-30 minutes.

Linux Virtual Machine (VM) Server Requirements​

  1. OS - Linux (supports only Linux), RHEL 7 and above
  2. JAVA:
    • OpenJDK version 17.02 LTS or higher
    • Oracle Java SE 8 or higher
  3. RAM - 2 GB (Minimum)
  4. Two Virtual CPUs
  5. Port for you broker interface
  6. Web proxy should allow outbound WebSocket connections

Steps to be performed:​

  1. Log in to the Linux machine with the userid that was used for the broker installation.
  2. Before you begin, ensure that the broker you are trying to upgrade is stopped. To stop the BlockID Authentication broker:
    • Run the ./stopClient.bsh command.
  3. Please take a backup of the entire broker folder within the server. Our standard installation instructions ask for the broker to be installed within the /opt/1kosmos/broker directory.
  4. Download and copy the BlockID Authentication Broker Installation .zip file to the Linux machine from the location provided to you.
  5. Unzip the BlockID Authentication Broker Installation file within a designated folder on the Linux server. You will be prompted to choose which files to replace.
    • Select YES for all files other than default.yml.
    • If you have made changes to the start or stop scripts, select NO for those prompts.
  6. Start the BlockID Authentication broker:
    • Run ./startClient.bsh -consoleDns <tenantname> -community <communityname> -licenseKey <licensekey> -tenantTag <tag> -p <port> -t <time-in-seconds> command.
  7. Navigate to the logs folder and tail the latest broker log:
    • Run tail -f logs/default_<dateandtime>.log command.
  8. Repeat the steps across all of your brokers.

Test the broker connection​

  1. Login to the BlockID Admin Console as an administrator.
    • Navigate to Administration Console > Auth Configuration > Authentication Modules.
    • From the Enabled Authentication Modules section, click on Authentication Broker.
  2. Check and confirm the indicator in green next to the newly upgraded broker.
  3. Log out from the BlockID Admin Console and log in again as a regular user. The My Profile screen is displayed for the user.