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 a 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.

To download and install the broker, follow these steps:

1. Login 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. 
   • 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 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 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.

Configure 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: _tenant_
      #    authentication_token_generator: ${britive.broker.authentication.token.script}  # optional
    authentication_token: _pooltoken_
    broker_name_generator: broker-name-generator.sh
#    resources_generator: ${britive.broker.resources.script}
#  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:
      max_supported_version: local
      execution_environment: /bin/sh -c "sudo -E <BRITIVE_PERMISSION_SCRIPT>"
      checkout_script: /opt/britive-agent/scripts/ssh-access-key-checkout.sh
      checkin_script: /opt/britive-agent/scripts/ssh-access-key-checkin.sh
  file_upload_type:
    file_upload_permission:
      max_supported_version: any
  inline-resource-type:
    inline-resource-permission:
      max_supported_version: any
      execution_environment: python3 <BRITIVE_PERMISSION_SCRIPT>
      file_extension: py

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.
    • authentication_token: The authentication token used to authenticate to the broker bootstrap endpoint for a specific agent pool.
    • 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.
    • 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.
    • 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.
  • 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 isthe permission name.
      • execution_environment:
      • 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.