Skip to content
Integrations
Infrastructure
Access Broker Deployment
Britive Script Helper (bsh)
Configure an SSH permission

Configure an SSH permission

Use bsh in your permission scripts to issue a generated SSH key for a Linux account during and remove the key at . The broker connects to the target over SSH using a separate administrative account.

For another operation using bsh, select a supported combination from the protocol and method reference. The permission still needs matching checkout and checkin scripts.

Before you begin

Prepare the following:

  • A registered Britive with bsh installed.
  • A Linux target reachable from the broker over SSH.
  • An administrative SSH account that can manage users, home directories, and authorized keys. A non-root account needs passwordless sudo for the operations the method performs.
  • The administrative account’s private key, readable by the broker’s operating-system user.
  • A known_hosts file containing the target’s verified SSH host key.
  • An existing resource type permission in Britive and access to edit its scripts and variable mappings.

Use a test target for the first checkout. The checkout creates the target account if it does not exist and installs an SSH key.

Configure the permission

Map the checkout identity

In the permission’s variable mappings:

  1. Map the platform’s user.username value to BSH_USER_EMAIL.
  2. Map profile.transactionId to BSH_TRANSACTION_ID.
  3. Ensure the same values are available during checkin.

For example, a checkout for jane.doe@example.com derives the target account name janedoe. Set BSH_USERNAME to select an existing naming convention explicitly.

Keep the identity and username settings the same for checkout and checkin. SSH key cleanup matches the user email on the target account. Checkin removes all keys that bsh manages for that email, including keys from overlapping checkouts.

Set the target and administrative connection

Configure these permission variables with values for your environment:

BSH_TRANSPORT=ssh
BSH_TARGET_HOST=linux.example.com
BSH_TARGET_PORT=22
BSH_TRANSPORT_USER=britive-broker
BSH_TRANSPORT_KEY_FILE=/etc/britive/keys/provisioning_ed25519
BSH_KNOWN_HOSTS=/etc/britive/known_hosts
BSH_TRANSPORT_SUDO=true

The paths refer to files on the broker host or inside its container. The broker user must be able to read them.

BSH_TRANSPORT_SUDO lets the administrative connection run provisioning commands through sudo -n. It does not grant sudo access to the user checking out the permission. To grant that access, set the separate BSH_SUDO parameter.

If the administrative connection already runs as root, leave BSH_TRANSPORT_SUDO unset or set it to false.

An external value reference can supply any of these values. For example, BSH_TRANSPORT_KEY=aws-sm://prod/linux-admin-key?region=us-east-1 fetches the private key at invocation time.

Add the checkout and checkin scripts

Set the permission’s checkout script to:

checkout.sh
#!/bin/sh
exec bsh checkout ssh --method ephemeral-key

Set its checkin script to:

checkin.sh
#!/bin/sh
exec bsh checkin ssh --method ephemeral-key

exec preserves the command’s exit status and output as the script result. Keep stdout free of status messages. Checkout uses stdout for the credential payload, and checkin produces no stdout payload.

Use the same protocol, method, mode, target, and identity settings for both scripts.

Check configuration and connectivity

Run these commands in the broker’s execution environment with the permission variables set:

bsh probe ssh --method ephemeral-key
bsh doctor --protocol ssh --method ephemeral-key

probe reports the selected transport, core configuration checks, and derived target account. It does not connect to the target or prove that the administrative account can perform every provisioning operation. Resolving a reference can contact an external store.

doctor attempts the configured SSH connection and reports the remote identity and sudo setting. Resolve failures before enabling the permission for users.

Verify

  1. Request the permission through Britive using the test user.
  2. Confirm that checkout returns a JSON payload containing the target username, private key, and connection details.
  3. Connect to the test target with the issued key.
  4. Check the permission back in through Britive.
  5. Confirm that a new connection using the issued key is rejected.

By default, checkin removes the generated key and its sudo grant but retains the account and home directory. Set BSH_DELETE_USER=true to delete the account. Set BSH_REMOVE_HOME=true only when its files must also be removed.

Removing a key prevents new key-based logins. It does not guarantee that an already-open direct SSH session is disconnected. For access through a managed Bridge session, use Configure a permission for Bridge.

Return a raw key when required

If the consuming permission expects only a private key instead of JSON, set BSH_FORMAT=raw or use:

checkout.sh
#!/bin/sh
exec bsh checkout ssh --method ephemeral-key --format raw

Raw output contains the credential without a JSON wrapper or a trailing newline. Use JSON for methods that do not issue a single credential, such as group membership or role grants.

Last updated on
Install bshConfigure a permission for Bridge