Configure a permission for Bridge

Confirm the Bridge deployment

Use Britive Bridge 3.0.0 or later for a colocated broker. For a broker on another host, use Bridge 3.0.2 or later and enable server.checkout_api_tokens.enabled. Follow Connect an external broker to create a scoped checkout token and configure the HTTPS API connection.

Confirm that bsh receives the API address and a credential:

• BSH_BRIDGE_BROKER_API_URL selects the API address. The host fallback is BRIDGE_BROKER_API_URL. Colocated brokers use the private loopback API. External brokers use Bridge’s public HTTPS API.
• BSH_BRIDGE_BROKER_API_TOKEN supplies the credential directly or through a secret reference. A protected file is also supported through BSH_BRIDGE_BROKER_API_TOKEN_FILE or the host fallback BRIDGE_BROKER_API_TOKEN_FILE.

When the API URL is configured and no token source is supplied, bsh checks /data/keys/bridge-broker-api.token for the colocated broker’s credential.

The broker token authorizes checkout management. Configure the current broker API settings for bsh; it does not use the older BRIDGE_API_URL and BRIDGE_CLUSTER_TOKEN settings.

Keep the target transport configured separately. The broker API registers the Bridge session; the target transport performs the account, credential, or group operation.

Set the public Bridge URL

Use the public HTTPS origin that users can reach, for example https://bridge.example.com.

On a broker within a Bridge deployment, bsh uses BRIDGE_SERVER_TELEMETRY_REVIEW_BASE_URL when BSH_BRIDGE_URL is unset or empty. To override the host value for a permission, set:

BSH_BRIDGE_URL=https://bridge.example.com

The --bridge-url flag overrides both environment variables. A bare hostname receives an https:// prefix, and trailing slashes are removed.

The public URL and broker API URL serve different connections. The public URL must be reachable by users. The broker API URL must be reachable by the broker.

Map the session values

Configure the permission’s variable mappings:

1. Map user.username to BSH_USER_EMAIL.
2. Map profile.transactionId to BSH_TRANSACTION_ID for both checkout and checkin.
3. Set BSH_SESSION_DURATION to the permitted session lifetime. For example, 1h is one hour, and 3600 is 3,600 seconds.

If the permission takes its duration from profile.timeout, map that value to BSH_SESSION_DURATION. Do not use the script execution timeout as the session lifetime.

When the platform supplies the user’s Bridge login password, map it to BSH_BRIDGE_AUTH_PASSWORD. bsh selects bridge_credentials authentication unless LDAP password passthrough is enabled. For details about authentication choices, see the Bridge settings.

Set the Bridge login identity

If the user’s Bridge login differs from their email, map that login to BSH_BRIDGE_USERNAME. For example, a user with the email will@example.com and Bridge login will needs:

BSH_USER_EMAIL=will@example.com
BSH_BRIDGE_USERNAME=will

Supply the requesting user’s own Bridge login for each checkout. Use bsh version 0.2.0 or later for this override. Keep the identity settings consistent during checkout and checkin.

Enable Bridge mode in both scripts

For the SSH key example, use this checkout script:

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

Use this checkin script:

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

The transaction ID must be available in both operations. Checkin ends the Bridge checkout before it removes access on the target.

Set session controls

Set controls as permission variables. For example, these settings allow browser access and disable native client access:

BSH_BROWSER_ENABLED=true
BSH_NATIVE_ENABLED=false

Use controls supported by the selected protocol. Both connection paths cannot be disabled. Some protocols provide only one path, such as browser access for Kubernetes exec.

Recording follows Bridge’s default when BSH_BRIDGE_RECORD_SESSION is unset. Set it to false only when the permission is intended to disable recording.

For a nondefault native listener port, set BSH_BRIDGE_NATIVE_PORT. Keep it separate from BSH_TARGET_PORT, which describes the target service, and BSH_TRANSPORT_PORT, which describes the provisioning connection.