Break-Glass Feature

NOTE:

The Break-Glass feature is driven by PAM and may require additional licensing. Contact your Imprivata Customer Support for more information.

TIP:

This document is meant only for System Administrators.

Break-Glass is an emergency credential-access utility for Imprivata Privileged Access Security products. It provides offline, last-resort access to secrets stored in the Vault when the primary server is unreachable due to an outage or network failure.

The utility runs as a standalone command-line application on a System Administrator's workstation. An authorized operator manually imports the encrypted artifact from the server and stores it locally. During an emergency, the administrator decrypts and searches the local replica using a passphrase with no network connection to the server.

IMPORTANT:

The Break-Glass client cannot get secrets that have a Personal Secret Scope, these are Personal secrets that must remain private for the user.

Requirements

To configure and use the Break-Glass binary, System Administrators must have the following access and configurations:

  • API Access: The workstation must be able to reach the server over HTTPS to perform the initial and periodic artifact import.

  • Passphrase: The passphrase is set by the system administrator or client operator when configuring the CLI. It is not stored on the workstation and must be known only by the authorized operator.

    IMPORTANT: The System Administrator is  the sole accountable owner of the protection and safekeeping of the passphrase. System Administrators must store it following their own security protocols for passwords and secrets.

  • Operator Access: Limit access to the Break-Glass API key and passphrase to a very small, accountable group.

  • Decryption Key: The passphrase or key must not reside on the same host as the encrypted artifact.

  • Permission: If the process is handled by an Internal User who does not have a System Administrator role, the user needs a role with the following additional permissions:

    • BREAK_GLASS

  • Output Directory: The feature stores local files in fixed XDG-based locations. Ensure the operator account can create and access the required local Break-Glass directories.

Download the break-glass Binary

To download the break-glass binary:

  1. Log in to the Imprivata Community Portal.

  2. Navigate to Product Downloads > Privileged Access.

  3. Select Imprivata PAM Break-Glass Client from the drop-down.

  4. Select the platform.

    Wait for the download to complete.

  5. Execute the break-glass binary.

NOTE:

If you do not have a PAM license, the Community Portal will not display the break-glass client download option. Contact your Imprivata partner for more information on PAM licensing.

Install break-glass

The break-glass binary does not include an installer. If the binary is not already on PATH, add it.

  1. Make the binary executable with the following command:

    chmod +x break-glass

  2. Move the binary to /usr/local/bin:

    mv break-glass /usr/local/bin/break-glass

  3. Verify the installation:

    break-glass version

  1. Place break-glass.exe in a directory that is on PATH.

  2. Verify the installation:

    break-glass version

Break-Glass Configuration

System Administrators configure the Break-Glass with the following steps:

The server-side API endpoint that generates the encrypted artifact for the Break-Glass feature requires the caller to have the BREAK_GLASS permission. Assign this permission to a Role before you create the API Key. To create the role:

  1. Log in to your Privileged Access Security server as a System Administrator.

  2. Go to User Management > Roles.

  3. Click Add New Role.

  4. Enter a role name and an optional description.
    For example: Break-Glass Operator | Custom role for the use the break-glass feature

  5. Select the BREAK_GLASS Permission for the role.

  6. Save the role.

BEST PRACTICE:

Do not use the BREAK_GLASS permission for any other role, nor combine the permission with other permissions. The BREAK_GLASS permission is highly privileged.

NOTE:

The BREAK_GLASS permission has no sub-permissions and is not hierarchical. Assigning it grants only artifact generation access.

The API Key is required to use and generate calls to the PAS API. Create one API key for the dedicated Break-Glass role and restrict access to only the authorized operators who are accountable for emergency access.

To create the API Key:

  1. Navigate to System Administration > API Keys.

  2. Click +Add.

  3. Fill in the key details:

    1. Name: for example, break-glass-workstation-01

    2. Expiration: set an appropriate rotation period.
      Ensure to set a reminder to renew the API Key for the role.

  4. Select the Custom Role you created in Step 1.

  5. Click Create API Key.

  6. Copy the API Key Secret immediately and safekeep it!

    IMPORTANT:

    The secret is shown only once.

After you verify the correct installation of the Break-Glass binary, continue to intialize the client.

  1. Run the following command to initialize the client:

    break-glass init

    This command walks you through configuring the appliance connection, choosing a passphrase, and generating a local key pair and API key.

  2. Pull the latest encrypted secrets artifact from the appliance.

    break-glass secrets pull

  3. Search the decrypted secrets.

    break-glass secrets view --search alice --search-by username

  4. Export the decrypted secrets to a file, if needed.

    break-glass secrets export ./secrets.json

    IMPORTANT:

    This command writes raw secrets to disk. Ensure to run only if strictly necessary.

Break-Glass stores its local files following the XDG base directory spec. The most relevant paths:

  • Configuration: $XDG_CONFIG_HOME/break-glass/config.yml

  • Pulled Secrets Artifact: $XDG_DATA_HOME/break-glass/artifacts/artifact.enc.json

  • Audit Log: $XDG_STATE_HOME/break-glass/logs/audit.jsonl

Run the following command to manually request the encrypted artifact from your PAS server and store it locally:

break-glass secrets pull [--insecure] [--passphrase-file]

This command downloads the latest encrypted secrets artifact from your PAS appliance. The artifact is encrypted and requires your passphrase to decrypt. After pulling, you can use break-glass secrets view or break-glass secrets export to access the secrets.

The --passphrase-file flag reads the passphrase from a file, instead of prompting for it interactively. This enables you to schedule automated or scheduled operations to pull artifacts without user interaction.

To use the --passphrase-file flag:

  1. Create a plain text file containing your passphrase:

  2. Set appropriate permissions on the file to restrict access.

    IMPORTANT:

    Remember the System Administrator is the sole responsible for the safety or storage of the passphrase.

  3. Pass the file path to the --passphrase-file flag:

    break-glass secrets pull --passphrase-file /path/to/passphrase.txt

How to Use the Break-Glass Feature

Use the Break-Glass feature when your VPAM server is unreachable due to maintenance or emergencies. the purpose of the Break-Glass feature is to use it even when you have no network connection.

Consider the following available commands in the break-glass CLI:

Command Description
api-key edit View or update the stored API key.
config edit Edit the local configuration interactively.
config set <field> <value> Setbase_urldirectly.
init [--force] Initialize the local client (config, passphrase, key pair, API key). Must run before any other command.
key-pair rotate Generate or replace the local key pair. Invalidates any pulled artifact.
secrets export <path> Decrypt and export the stored artifact to a JSON file.
secrets pull [--insecure] [--passphrase-file] Pull the latest encrypted secrets artifact from the appliance.
secrets view [--search --search-by] [--reveal] Decrypt and display the stored artifact.
version Print the client version.