Brokers

The broker is deployable at the user's end in a remote environment. It is a deployable package with a broker configuration template (broker-config-template.yml) that can be referenced to create a broker-config.yml file. The configuration file (broker-config.yml) contains the information to bootstrap/register the broker to the Britive platform under a broker pool (i.e., the tenant subdomain and the authentication token associated with the pool). It also lists the resources and permissions a broker can manage. 

One broker can manage multiple resources, or one can exclusively manage only one. These details are specified in a configuration file. Every broker gets automatically re-bootstrapped/reconnected to the Britive platform after every 24 hours.

A broker is configured to execute OS-specific scripts (e.g., bash scripts for Linux, PowerShell scripts for Windows) when acquiring access (checkout) or revoking access (check-in) to resource permission on behalf of the end user. The broker can be configured to run scripts locally stored in a filesystem the broker has access to, or a broker can be configured to run scripts passed in the request message to acquire or revoke access to resource permission from the Britive platform. 

Broker functioning

A broker at startup calls a bootstrap endpoint (REST API/HTTPS endpoint) to register itself to the Britive platform under a broker pool. This registration process informs the Britive platform that the broker is up and running and what resource permissions the broker supports. The bootstrap endpoint responds to the broker with the AWS IoT MQTT broker connection information. Based on the returned connection information, the broker connects to the MQTT broker and subscribes to request messages sent to an MQTT topic by the Britive platform to acquire or revoke access to resource permissions.

Prerequisites

• A broker can run on any OS that can run Java Virtual Machine (JVM)/Java Development Kit (JDK). 
• Britive supports Windows services and Linux OS that supports the systemd services for running broker as a service.
• Broker service installers are provided for Microsoft Windows MSI and Linux OS Debian packages.  
• A broker can run on any modern CPU with a RAM requirement of 100MB.

Downloading and installing the broker

1. Log in to Britive.
2. Click on Admin->Brokers and Broker Pools->Brokers.
3. Click on the Download Brokers button.
4. Expand the package type to view available installer(s), and click on the required installer to download the package. 
5. Install the broker using the downloaded package. If you are upgrading/updating Access Broker, see Upgrading Access Broker.
   • deb (Debian-based Linux):
     1. Install the Debian package as the root user, the broker is installed at /opt/britive-broker. 
        ShellShell

        ‘dpkg -i <path to the debian package downloaded>’

     2. Start systemd service britive-brokeras root like so: 
        ShellShell

        systemctl start britive-broker

        
        
     3. Note: The britive-broker Debian package has a dependency on the Debian package openjdk-21-jre-headless.  If openjdk-21-jre-headlessis package is not installed on the Debian system, run the following command to install it: 
        ShellShell

        ‘apt-get install openjdk-21-jre-headless’

     4. jar:
        1. Run the downloaded JAR file on the command line or terminal window. You must have Java installed on your system, and the environment should be configured to run this file.
     5. msi: 
        1. Run the .msi installer and follow the install wizard to install the broker as a service.
     6. tar: Locate the downloaded file and click to unzip the file. 
     7. zip: Unzip and extract the files from the downloaded file.
6. Add and configure broker-config.yml. For more details about the configuration file, see the Configure broker-config.yml file. 
7. A list of brokers is updated on Britive after users download and install the broker package on their system.
8. Start the Britive Broker service.

Upgrading Access Broker

• Linux systems: Uninstall the debian or rpm package for the broker and install the new version. Ensure /opt/britive-broker/conf/broker-config.yml and /opt/britive-broker/conf/logback.xml have not been modified after the upgrade.
• Microsoft Windows: Manually make a backup of the broker-config.yml. Run the latest MSI installer and restore the backed-up broker-config.yml after installing/upgrading the broker with the latest MSI installer. Another workaround is to modify the broker-config.yml file (e.g. / add a comment)  and save the file before running the latest MSA installer to upgrade the broker.

Configuring broker-config.yml file

Configure the broker using a YAML file, eg. broker-config.yml. Here is a configuration file template:

# Uncomment and modify as needed
config:
#  cache_path: ${britive.broker.action.command.cache} # default to ./cache if not provided
#  bootstrap:
#    execution_environment: /bin/sh -c "sudo -E <BRITIVE_BOOTSTRAP_SCRIPT>" # optional
#    scripts_path: ${britive.broker.scripts.path}  # default to ./bootstrap if not provided
#    tenant_subdomain: ${britive.broker.tenant.subdomain}  # required
#    authentication_token_generator: ${britive.broker.authentication.token.script}  # one of authentication_token or authentication_token_generator is required
#    authentication_token: ${britive.broker.authentication.token}  # one of authentication_token or authentication_token_generator is required
#    broker_name_generator: ${britive.broker.name.script} # optional, defaults to running command hostname
#    resources_generator: ${britive.broker.resources.script} # optional
#  http_proxy:  # optional, if not specified do not use http proxy for connecting
#    host: localhost      # required
#    port: 8080           # required
#    username: userA      # optional: if this or password not specified authorization type is None
#    password: passwordA  # optional: if this or username not specified authorization type is None
#    connection_type: [Legacy | Forwarding | Tunneling]   # optional defaults to Tunneling if not specified

# The resource types supported by this broker
resource_types:
#  ssh:
#    new_key:
#      execution_environment: /bin/sh -c "sudo -E <BRITIVE_PERMISSION_SCRIPT>" # optional
#      max_supported_version: local | any | <version#> # required
#      checkout_script: ${ssh.new.key.checkout.script}  # required if max_supported_version is 'local'
#      checkin_script: ${ssh.new.key.checkin.script} # required if max_supported_version is 'local'
#      file_extension: ps1 | bat | sh | etc...   #optional  only used to append to filename of the remote scripts downloaded from Britive platform

resource_types:
  demo-resource:
    checkout this now:
      max_supported_version: any
      execution_environment: powershell.exe -File "<BRITIVE_PERMISSION_SCRIPT>"
      file_extension: ps1

Here is a line-by-line description of each configurable parameter:

• config: Configurable properties of a broker file.
  • cache_path: The directory/folder to save permission action scripts downloaded from the Britive platform when max_supported_version of the resource_types is any or <version#>. The default is <Broker install directory>/cache
  • bootstrap:
    • execution_environment: Full command to execute the locally defined bootstrap scripts defined by configuration properties authentication_token_generator, broker_name_generator, and resources_generator by the broker.
    • scripts_path: The directory/folder containing the bootstrap scripts. The default path is <broker install directory>./bootstrap.
    • tenant_subdomain: ${britive.broker.tenant.subdomain} # required. Do not use the entire FQDN for the subdomain. For example, for https://super-customer.test.aws.britive-corp.com, use super-customer.test.aws as a tenant subdomain.
    • authentication_token_generator: The bootstrap script to execute to dynamically generate/get the authentication token to authenticate to the broker bootstrap endpoint for a specific agent pool.
    • authentication_token: The authentication token used to authenticate to the broker bootstrap endpoint for a specific agent pool.
    • broker_name_generator: The bootstrap script to execute to dynamically generate/get the broker name to register when calling the broker bootstrap endpoint to register the broker. For more information about customizing a broker name, see Customizing Broker Name.
    • resources_generator: The bootstrap script to execute to dynamically generate/get the resources the broker will support when registering the agent via the broker bootstrap endpoint. For more information about configuring the resource generator script, see Creating Resources.
  • http_proxy: (Optional) Proxy server to connect to the Britive platform.
    • host: Hostname of the proxy server 
    • port: Port of the proxy server.
    • username: Username to authenticate to the proxy server.
    • password: Password to authenticate to the proxy server.
    • connnection_type: Can be one of Legacy, Forwarding, or Tunneling. The default is Tunneling.
• resource_types:
  • <resource_type>: Name of the resource type. For example, sshis the name of the resource type in the sample file.
    • <permission_name>: The resource type permission to provide JIT access. For example, new_key is the permission name.
      • execution_environment: /bin/sh -c "sudo -E <BRITIVE_PERMISSION_SCRIPT>"
      • max_supported_version: The maximum supported version of the permission script. Use one of the following versions: 
        • local: Use scripts specified in checkout_script and checkin_script.
        • any: Download and use any version specified in the resource permission request.
        • <version#>: Only download and use the version specified in the resource permission request if it is equal to or less than the max_supported_version.
      • checkout_script: Full path to the local script to execute to check out access to the resource permission. Valid only if max_supported_version is configured for the local version.
      • checkin_script: Full path to the local script to execute to check-in access to the resource permission. Valid only if max_supported_version is configured for the local version.
      • file_extension: The filename extension to use when saving the resource permission scripts downloaded from the Britive platform to a file if max_supported_version is configured for any or a <version #>.  The file is stored in the directory/folder config.cache_path.

Customizing Broker Name

The broker name generator script allows customers to customize the name of the broker displayed in the UI when displaying the list of brokers in the broker pool. If the script name is not specified, it defaults to using the Operating System’s hostname command to get the hostname of the machine/virtual machine the broker is running on and use that as the broker name. 

To configure the broker name generator script add the broker_name_generator attribute with the value set to the filename of the broker name generator script in the broker-config.yml file.

Note: The broker configuration assumes the broker_name_generator script is located in the default scripts_path location. For example: /opt/britive-broker/bootstrap on Linux or C:\Program Files (x86)\Britive Inc\Britive Broker\bootstrap’ on MS Windows.  To use a PowerShell script on MS Windows, you need to uncomment the execution_environment from the configuration file and set it to powershell.exe -File <BRITIVE_BOOTSTRAP_SCRIPT>.

Here is an example of a basic broker-name-generator.sh as configured above. 

#!/bin/bash
hostname -f

It could be as simple as this example or could be as complex as a script creating a broker name that uniquely identifies the running broker instance.

Creating Resources

The resource generator script allows customers to create resources for the first time when the broker bootstraps. Here is a sample code for the resource-generator.sh script.

#!/bin/bash
echo ['
    {
      "name": "linux-server-instance-1",
      "type": "Server-resource-type",
      "labels": {
        "Resource-Type": ["Server-resource-type"]
      }
    },
	{
      "name": "db-server-instance-2",
      "type": "db-resource-type",
      "labels": {
        "Resource-Type": ["db-resource-type"]
      }
    }
']