Brokers

Prev Next

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 permissions 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 the 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 a startup calls a bootstrap endpoint (REST API/HTTPS endpoint) to register itself with 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.

Installing and Configuring Broker

To install and configure brokers on different OS systems, see Installing and Configuring Broker.

Configuring broker-config.yml file

Configure the broker using a YAML file, e.g., 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

Note:

If the script name contains spaces, add double quotes for that parameter. For example, if the script name used in the BRITIVE_PERMISSION_SCRIPT parameter has spaces, use "<BRITIVE_PERMISSION_SCRIPT>".

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

      • connection_type: Can be one of Legacy, Forwarding, or Tunneling. The default is Tunneling.

  • resource_types:

    • <resource_type>: Name of the resource type. For example, ssh is 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 it 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"]
      }
    }
']