--- title: "Brokers" slug: "brokers" updated: 2026-07-20T08:21:11Z published: 2026-07-20T08:21:21Z canonical: "docs.britive.com/brokers" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.britive.com/llms.txt > Use this file to discover all available pages before exploring further. # Brokers The Britive broker is a long-running agent installed in your environment. It connects outbound to the Britive platform, subscribes to a message queue, and executes resource actions (permission checkout/check-in, scans, and credential rotations) against your on-premises resources using scripts you control. 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 file system 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 - Broker version 2.0 and below: Install and configure the broker on different OS systems; see [Broker version 2.0 and below](/v1/docs/brokers#installing-and-configuring-broker). This broker will be deprecated in the next few weeks; you are encouraged to use the latest broker version 3.0.1. - Broker version 3.0.1 and upwards: Britive has built a native executable for each platform (OS and hardware architecture); see [Broker version 3.0.1 and upwards](/v1/docs/broker-3-0-1). ## *broker-config.yml* file Configure the broker using a YAML file, e.g., *broker-config.yml*. Here is a configuration file template: ```ConfigurationFileTemplate # Uncomment and modify as needed # # This config file is optional. All settings can be provided via environment # variables. When both are present, environment variables take precedence. # # Environment variable overrides: # #   Config-level: #     BRITIVE_BROKER_CONFIG_VERSION                  - config.version #     BRITIVE_BROKER_EXECUTION_ENVIRONMENT           - config.execution_environment #     BRITIVE_BROKER_CA_CERTIFICATE_PATH             - config.ca_certificate_path #     BRITIVE_BROKER_CACHE_PATH                      - config.cache_path #     BRITIVE_BROKER_MAX_CONCURRENT_SCANS            - config.max_concurrent_scans #     BRITIVE_BROKER_MAX_CONCURRENT_ROTATES          - config.max_concurrent_rotates # #   Bootstrap: #     BRITIVE_BROKER_BOOTSTRAP_PORT                  - config.bootstrap.port #     BRITIVE_BROKER_BOOTSTRAP_EXECUTION_ENVIRONMENT - config.bootstrap.execution_environment #     BRITIVE_BROKER_BOOTSTRAP_SCRIPTS_PATH          - config.bootstrap.scripts_path #     BRITIVE_BROKER_TENANT_SUBDOMAIN                - config.bootstrap.tenant_subdomain #     BRITIVE_BROKER_AUTH_TOKEN                       - config.bootstrap.authentication_token #     BRITIVE_BROKER_AUTH_TOKEN_GENERATOR             - config.bootstrap.authentication_token_generator #     BRITIVE_BROKER_NAME_GENERATOR                  - config.bootstrap.broker_name_generator #     BRITIVE_BROKER_RESOURCES_GENERATOR             - config.bootstrap.resources_generator # #   HTTP Proxy: #     BRITIVE_BROKER_HTTP_PROXY_HOST                 - config.http_proxy.host #     BRITIVE_BROKER_HTTP_PROXY_PORT                 - config.http_proxy.port #     BRITIVE_BROKER_HTTP_PROXY_USERNAME             - config.http_proxy.username #     BRITIVE_BROKER_HTTP_PROXY_PASSWORD             - config.http_proxy.password #     BRITIVE_BROKER_HTTP_PROXY_CONNECTION_TYPE      - config.http_proxy.connection_type # #   Notes: #     - BRITIVE_BROKER_AUTH_TOKEN and BRITIVE_BROKER_AUTH_TOKEN_GENERATOR are #       mutually exclusive. If both are set, AUTH_TOKEN wins. #     - resource_types cannot be configured via environment variables. #       When running without a config file, resource_types is unset and the #       broker operates in open/demo mode (all resource types and actions #       accepted). To restrict to specific resource types, provide a config #       file with at least the resource_types section defined. # config: #  version: 1 | 2 #  execution_environment: /bin/sh -c "sudo -E " # optional. execute all bootstrap or resource action scripts using this command. Will be overwritten by the #  ca_certificate_path:   # optional: additional CA certificate(s) to trust for establishing TLS connections. #  cache_path: ${britive.broker.action.command.cache} # default to ./cache if not provided #  max_concurrent_scans: 5 # default 1 #  max_concurrent_rotates: 10 # default 1 #  bootstrap: #    execution_environment: /bin/sh -c "sudo -E " # 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:    # do not define resource_types if want to support all scans, rotates, and permissions (checkin, checkout) actions on any resource for demo purposes. #  UbuntuEC2: #    scans: #      ScanTemplate: #        source: local | remote #        execution_environment: /bin/sh -c "sudo -E " # optional #        script: /opt/britive-broker/scripts/ec2-ubuntu-scan.sh  # required if source is 'local' #        file_extension: ps1 | bat | sh | etc...   #optional  only used to append to filename of the remote scripts downloaded from Britive platform #    rotates: #      secretTemplate1: #        source: local | remote #        execution_environment: /bin/sh -c "sudo -E " # optional #        script: /opt/britive-broker/scripts/ec2-ubuntu-rotate.sh  # required if source is 'local' #        file_extension: ps1 | bat | sh | etc...   #optional  only used to append to filename of the remote scripts downloaded from Britive platform #      secretTemplate2: #        source: local | remote #        execution_environment: /bin/sh -c "sudo -E " # optional #        script: /opt/britive-broker/scripts/ec2-ubuntu-rotate.sh  # required if source is 'local' #        file_extension: ps1 | bat | sh | etc...   #optional  only used to append to filename of the remote scripts downloaded from Britive platform #    permissions: #      ssh_key: #        execution_environment: /bin/sh -c "sudo -E " # optional #        max_supported_version: local | any | # 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_SCRIPT_PLACEHOLDER parameter has spaces, use . ```yaml resource_types:  demo-resource:    checkout this now:      max_supported_version: any      execution_environment: powershell.exe -File ""      file_extension: ps1 ``` > [!NOTE] > Notes: > > - and is used for *config.version=1*. > - is used in the *execution_environment* in *config.bootstrap* section of *broker-config.yml*. > - is used in the *resource_types* section of the *broker-config.yml* > - is used for *config.version=2* for all *execution_environment* settings. ### Environment variable overrides Every **config** setting (except the **proxy** and **resource_types**) can be supplied or overridden by an environment variable, which takes precedence over the file. The config file itself is optional if all required values arrive via environment variables. **BRITIVE_BROKER_AUTH_TOKEN** and **BRITIVE_BROKER_AUTH_TOKEN_GENERATOR** are mutually exclusive; if both are set, the token **BRITIVE_BROKER_AUTH_TOKEN** takes precedence. ### Configurable parameters Here is a line-by-line description of each configurable parameter: - **config**: Configurable properties of a broker file. - **version**: - **1:** Allows resource check-in and checkout - **2**: Allows resource scanning and secret rotation along with resource check-in and checkout. - **execution_environment**: (Optional) /bin/sh -c *sudo -E * Execute all bootstrap or resource action scripts using this command. ** is replaced with the actual path of the script that will be executed. - **ca_certificate_path**: (Optional): Additional CA certificate(s) to trust for establishing TLS connections. - **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 **. The default is */cache* - **max_concurrent_scans**: 5. Default is 1. - **max_concurrent_rotates**: 10. Default is 1, - **bootstrap**: - **execution_environment**: (Optional) */bin/sh -c "sudo -E * Execute all bootstrap or resource action scripts using this command. is replaced with the actual path of the script that will be executed. - **scripts_path**: The directory/folder containing the bootstrap scripts. The default path is *./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](/v1/docs/brokers#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](/v1/docs/brokers#creating-resources). - **http_proxy**: (Optional) Proxy server to connect to the Britive platform. - **host**: Hostname of the proxy server. - **port:** The port of the proxy server. - **username**: Username to authenticate to the proxy server. If this or the **password** is not specified, the authorization type is None. - **password**: Password to authenticate to the proxy server. If this or the **username** is not specified, the authorization type is None. - **connection_type**: Not configurable, must be set to *Tunneling*. - **resource_types:** Which scans, rotations, and permissions this broker serves and the scripts that implement them. If omitted, the broker runs in open/demo mode and accepts all resource types; always define it for production. - ****: Name of the resource type. For example, *ssh* is the name of the resource type in the sample file. - **scans**: - **ScanTemplate**: Must be same as the ** - **source**: local | remote - **execution_environment**: (Optional) /bin/sh -c "sudo -E " - **script**: This is required only if the source is defined as **local**. /opt/britive-broker/scripts/ec2-ubuntu-scan.sh. - **file_extension**: (Optiona) ps1 | bat | sh | etc... Only used to append to the filename of the remote scripts downloaded from the Britive platform - **rotates**: *secretTemplate1* and *secretTemplate2* need to match the rotate template name configured for the resource type defined in the Britive platform. - **secretTemplate1**: - **source**: local | remote - **execution_environment**: (Optional) */bin/sh -c "sudo -E "* - **script**: This is required only if the **source** is defined as local. */opt/britive-broker/scripts/ec2-ubuntu-rotate.sh* - **file_extension**: (Optional) ps1 | bat | sh | etc... Only used to append to the filename of the remote scripts downloaded from the Britive platform - **secretTemplate2**: - **source**: local | remote - **execution_environment**: (Optional) */bin/sh -c "sudo -E "* - **script**: This is required only if the **source** is defined as **local**. */opt/britive-broker/scripts/ec2-ubuntu-rotate.sh* - **file_extension**: (Optional) ps1 | bat | sh | etc... Only used to append to the filename of the remote scripts downloaded from the Britive platform - **permissions**: The resource type permission to provide JIT access. For example, *ssh_key* is the permission name. - **ssh_key**: - **execution_environment**: /bin/sh -c "sudo -E " - **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. - **: 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 *.* 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 .* Here is an example of a basic *broker-name-generator.sh* as configured above. ```shell #!/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. ```shell #!/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"]      }    } '] ```