Beyondtrust Secrets Actions

This project integrates with BeyondTrust Password Safe and provides two core actions for secret management: get_secret and create_secret. The get_secret action is used to retrieve existing secrets, while the create_secret action allows the creation of new secrets. Detailed descriptions and usage examples for each action are provided in the following sections.

🚧 New changes in 2.0.0

Warning

Breaking changes

Instead of a single unified operation for handling secrets, this release splits the functionality into two distinct operations:

get_secret – Retrieves a secret from Secrets Safe
(BeyondTrust/secrets-safe-action/get_secret)
create_secret – Creates a secret in Secrets Safe
(BeyondTrust/secrets-safe-action/create_secret)

If you are upgrading from version 1.x, you must update your GitHub Actions workflows to use these new operation names.
Workflows that relied on the previous combined behavior will no longer work unless they are updated to use either get_secret or create_secret.

Get Secrets Action

This action retrieves ASCII secrets from BeyondTrust Secrets Safe and makes them available in the GitHub action workflow. The secrets are requested using either a Secrets Safe path or a path to a managed account which is composed of a managed system and account. The action output returns the secrets with an ID specified in the action request. This allows immediate retrieval and usage of secrets from your BeyondTrust Secrets Safe instance. Retrieved secrets are masked on the GitHub runner used to retrieve the secret. This helps reduce the chance that secrets are printed or logged by accident.

Warning: It is important that security-minded engineers review workflow composition before changes are run with access to secrets.

Prerequisites

The Secrets Safe action supports retrieval of secrets from BeyondInsight/Password Safe versions 23.1 or greater.

For this extension to retrieve a secret the Secrets Safe instance must be preconfigured with the secret in question and must be authorized to read it.

Runners must use a Linux operating system. Additionally, self-hosted runners will need Docker installed.

Inputs

`api_key`

Optional: The API Key configured in BeyondInsight for your application. If not set, then client credentials must be provided.

`client_id`

Required: API OAuth Client ID.

`client_secret`

Required: API OAuth Client Secret.

`api_url`

Required: BeyondTrust Password Safe API URL.

https://example.com:443/BeyondTrust/api/public/v3

`api_version`

Optional: The recommended version is 3.1. If no version is specified, the default API version 3.0 will be used

`secret_path`

Required: Path of the secret to retrieve.

[
  {
    "path": "folder1/folder2/title",
    "output_id": "title"
  },
  {
    "path": "folder1/folder2/title2",
    "output_id": "title2"
  }
]

`managed_account_path`

Required: Path of the Managed account to retrieve.

[
  {
    "path": "system/account",
    "output_id": "account"
  },
  {
    "path": "system/account2",
    "output_id": "account2"
  }
]

`certificate`

Content of the certificate (cert.pem) for use when authenticating with an API key using a Client Certificate.

`certificate_key`

Certificate private key (key.pem). For use when authenticating with an API key

`verify_ca`

Indicates whether to verify the certificate authority on the Secrets Safe instance. Defaults to true if not specified.

VERIFY_CA: true

Warning: false is insecure, instructs the Secrets Safe custom action not to verify the certificate authority.

`log_level`

Level of logging verbosity. Default INFO.

Levels: CRITICAL, FATAL, ERROR, WARNING, WARN, INFO, DEBUG, NOTSET

`decrypt`

Optional: When set to true, the decrypted password field is returned. When set to false, the password field is omitted. This option applies only to secret retrieval type. Defaults to true if not specified.

Outputs

`output_id`

The action stores the retrieved secrets in output variables defined by the end user. The <output_id> must be a unique identifier within the outputs object. The <output_id> must start with a letter or _ and contain only alphanumeric characters, -, or _. See secret_path and managed_account_path.

Example usage

uses: BeyondTrust/secrets-safe-action/get_secret@bd174328f6b88a6cd795049a9dbe2a81c8669342 # v2.0.0
env:
  API_URL: ${{vars.API_URL}}
  VERIFY_CA: ${{vars.VERIFY_CA}}
  CLIENT_ID: ${{secrets.CLIENT_ID}}
  CLIENT_SECRET: ${{secrets.CLIENT_SECRET}}
  CERTIFICATE: ${{secrets.CERTIFICATE}}
  CERTIFICATE_KEY: ${{secrets.CERTIFICATE_KEY}}
  API_VERSION: ${{vars.API_VERSION}}
with:
  SECRET_PATH: '{"path": "folder1/folder2/title", "output_id": "title"}'
  MANAGED_ACCOUNT_PATH: '{"path": "system/account", "output_id": "account"}'

Create Secrets Action

This action creates new secrets in BeyondTrust Secrets Safe. The action supports creating different types of secrets including credentials (username/password), text secrets, and file-based secrets. Created secrets are stored in specified folders within your Secrets Safe instance.

Authentication

The action supports two authentication methods:

API Key Authentication: Using an API key with optional client certificates
OAuth Client Credentials: Using client ID and client secret

Prerequisites

Appropriate permissions to create secrets in the target folder
Target parent folder must exist in Secrets Safe
Runners must use a Linux operating system with Docker installed

Create Secret Inputs

Authentication Inputs

`api_key`

Optional: The API Key configured in BeyondInsight for your application. If not set, then client credentials must be provided.

`client_id`

Optional: The API OAuth Client ID configured in BeyondInsight for your application.

`client_secret`

Optional: The API OAuth Client Secret configured in BeyondInsight for your application.

`api_url`

Required: The API URL for the Secrets Safe instance.

https://example.com:443/BeyondTrust/api/public/v3

`api_version`

Optional: The recommended version is 3.1. If no version is specified, the default API version 3.0 will be used.

`verify_ca`

Optional: Indicates whether to verify the certificate authority on the Secrets Safe instance. Defaults to true.

`certificate`

Optional: Content of the certificate (cert.pem) for use when authenticating with an API key using a Client Certificate.

`certificate_key`

Optional: Certificate private key (key.pem) for use when authenticating with an API key using a Client Certificate.

Secret Configuration Inputs

`secret_title`

Required: Title of the secret to be created. Must be unique within the parent folder.

`parent_folder_name`

Required: Name of the parent folder where the secret will be created. The folder must exist in Secrets Safe.

`secret_description`

Optional: Description of the secret for documentation purposes.

Secret Content Inputs

For Credential Secrets:

`username`

Optional: Username for credential type secrets.

`password`

Optional: Password for credential type secrets.

For Text Secrets:

`text`

Optional: Text content for text type secrets.

For File Secrets:

`file_content`

Optional: File content for file type secrets (base64 encoded or plain text).

`file_name`

Optional: File name for file type secrets.

Advanced Configuration Inputs

`owner_id`

Optional: ID of the owner for the secret.

`owner_type`

Optional: Type of the owner (User or Group).

`owners`

Optional: List of owners for the secret in JSON format.

[{"user_id": 123, "owner_id": 123}]

`password_rule_id`

Optional: Password rule ID for credential secrets to enforce password policies.

`notes`

Optional: Additional notes for the secret.

`urls`

Optional: URLs associated with the secret in JSON format.

[{"url": "https://example.com"}]

`log_level`

Optional: Level of logging verbosity. Default: INFO Levels: CRITICAL, FATAL, ERROR, WARNING, WARN, INFO, DEBUG, NOTSET

Create Secret Examples

Example 1: Create Credential Secret

- name: Create credential secret
  id: credential_secret
  uses: BeyondTrust/secrets-safe-action/create_secret@bd174328f6b88a6cd795049a9dbe2a81c8669342 # v2.0.0
  env:   
    API_URL: ${{vars.API_URL}}
    CLIENT_ID: ${{secrets.CLIENT_ID}}
    CLIENT_SECRET: ${{secrets.CLIENT_SECRET}}
    VERIFY_CA: ${{vars.VERIFY_CA}}
    LOG_LEVEL: ${{vars.LOG_LEVEL}}
    API_VERSION: "3.1"
  with:
    SECRET_TITLE: "Secret Title"
    PARENT_FOLDER_NAME: "Parent folder name"
    SECRET_DESCRIPTION: ""
    USERNAME: "username"
    PASSWORD: "p4ssw0rd!#"
    TEXT: ""
    FILE_NAME: ""
    FILE_CONTENT: ""
    OWNER_ID: "1"
    OWNER_TYPE: "User"
    NOTES: ""
    OWNERS: '[{"owner_id": 1}]'

Example 2: Create Text Secret

- name: Create Text secret
  id: text_secret
  uses: BeyondTrust/secrets-safe-action/create_secret@bd174328f6b88a6cd795049a9dbe2a81c8669342 # v2.0.0
  env:   
    API_URL: ${{vars.API_URL}}
    CLIENT_ID: ${{secrets.CLIENT_ID}}
    CLIENT_SECRET: ${{secrets.CLIENT_SECRET}}
    VERIFY_CA: ${{vars.VERIFY_CA}}
    LOG_LEVEL: ${{vars.LOG_LEVEL}}
    API_VERSION: "3.1"
  with:
    SECRET_TITLE: "Secret Title"
    PARENT_FOLDER_NAME: "Parent folder name"
    SECRET_DESCRIPTION: ""
    USERNAME: ""
    PASSWORD: ""
    TEXT: "Doc_S3guro!21"
    FILE_NAME: ""
    FILE_CONTENT: ""
    OWNER_ID: "1"
    OWNER_TYPE: "User"
    NOTES: ""
    OWNERS: '[{"owner_id": 1}]'

Example 3: Create File Secret

- name: Create File secret
  id: file_secret
  uses: BeyondTrust/secrets-safe-action/create_secret@bd174328f6b88a6cd795049a9dbe2a81c8669342 # v2.0.0
  env:   
    API_URL: ${{vars.API_URL}}
    CLIENT_ID: ${{secrets.CLIENT_ID}}
    CLIENT_SECRET: ${{secrets.CLIENT_SECRET}}
    VERIFY_CA: ${{vars.VERIFY_CA}}
    LOG_LEVEL: ${{vars.LOG_LEVEL}}
    API_VERSION: "3.1"
  with:
    SECRET_TITLE: "Secret Title"
    PARENT_FOLDER_NAME: "Parent folder name"
    SECRET_DESCRIPTION: ""
    USERNAME: ""
    PASSWORD: ""
    TEXT: ""
    FILE_NAME: "secret.txt"
    FILE_CONTENT: "Doc4!Pass789"
    OWNER_ID: "1"
    OWNER_TYPE: "User"
    NOTES: ""
    OWNERS: '[{"owner_id": 1}]'

Extracting Client Secret

Download the pfx certificate from Secrets Safe and extract the certificate and the key to be pasted into a GitHub secret.

openssl pkcs12 -in client_certificate.pfx -nocerts -out ps_key.pem -nodes

openssl pkcs12 -in client_certificate.pfx -clcerts -nokeys -out ps_cert.pem

Copy the text from the ps_key.pem to a secret.

-----BEGIN PRIVATE KEY-----
...
-----END PRIVATE KEY-----

Copy the text from the ps_cert.pem to a secret.

-----BEGIN CERTIFICATE----- 
... 
-----END CERTIFICATE-----

Get Help

Contact BeyondTrust support

Name		Name	Last commit message	Last commit date
Latest commit History 55 Commits
.github		.github
create_secret		create_secret
get_secret		get_secret
images		images
.coveragerc		.coveragerc
.flake8		.flake8
.gitignore		.gitignore
.isort.cfg		.isort.cfg
.pre-commit-config.yaml		.pre-commit-config.yaml
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
version.txt		version.txt

License

BeyondTrust/secrets-safe-action

Folders and files

Latest commit

History

Repository files navigation

Beyondtrust Secrets Actions

🚧 New changes in 2.0.0

Get Secrets Action

Prerequisites

Inputs

api_key

client_id

client_secret

api_url

api_version

secret_path

managed_account_path

certificate

certificate_key

verify_ca

log_level

decrypt

Outputs

output_id

Example usage

Create Secrets Action

Authentication

Prerequisites

Create Secret Inputs

Authentication Inputs

api_key

client_id

client_secret

api_url

api_version

verify_ca

certificate

certificate_key

Secret Configuration Inputs

secret_title

parent_folder_name

secret_description

Secret Content Inputs

For Credential Secrets:

username

password

For Text Secrets:

text

For File Secrets:

file_content

file_name

Advanced Configuration Inputs

owner_id

owner_type

owners

password_rule_id

notes

urls

log_level

Create Secret Examples

Example 1: Create Credential Secret

Example 2: Create Text Secret

Example 3: Create File Secret

Extracting Client Secret

Get Help

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 5

Packages 0

Uh oh!

`api_key`

`client_id`

`client_secret`

`api_url`

`api_version`

`secret_path`

`managed_account_path`

`certificate`

`certificate_key`

`verify_ca`

`log_level`

`decrypt`

`output_id`

`api_key`

`client_id`

`client_secret`

`api_url`

`api_version`

`verify_ca`

`certificate`

`certificate_key`

`secret_title`

`parent_folder_name`

`secret_description`

`username`

`password`

`text`

`file_content`

`file_name`

`owner_id`

`owner_type`

`owners`

`password_rule_id`

`notes`

`urls`

`log_level`

Packages