Manage Service Accounts

To allow applications to access secrets without human intervention, SecretHub supports service accounts. A service account is a non-human account that is tied to a repository. Similar to users, service accounts can be granted access rights to directories within their repository.

While users are identified by their username, service accounts are identified by names starting with s- followed by 12 random alphanumeric characters (e.g. s-2A3bf0sd4K5p).

All Commands

To manage service accounts, you can use the following commands:

• service init - create a new non-human service account
• service ls - list service accounts
• Deploy a service credential using SSH
• service deploy winrm - deploy a service credential to a Windows machine using WinRM

Init

To create a new service account for an application, you can use the service init command:

secrethub service init [options] <namespace>/<repo>[/<dir>] 

This creates a service account and writes its generated account credential to stdout. The printed account credential needs to be deployed to the application’s system, to give that application access to SecretHub.

Eventually, the account credential must be provided to the service’s SecretHub client in one of the following ways, listed by order of precedence:

1. Through the command-line flag --credential. Be sure to avoid having the credential end up in the command history or process lists.
2. Through the environment variable SECRETHUB_CREDENTIAL.
3. Through a credential file in the configuration directory. The configuration directory defaults to $HOME/.secrethub and can be configured with the --config-dir flag or SECRETHUB_CONFIG_DIR environment variable.

When you want to immediately create an access rule for the service account, you can use the --permission flag. This automatically creates an access rule on the path argument you provide, granting access rights to the account.

There are a few different ways to deploy an account credential. Depending on your stack and use case, you may choose to use one of the deployment mechanisms described below:

• Write the output of the service init command to the clipboard instead of to stdout with the --clip flag. This can be useful for services with a graphical user interface that allow for pasting in environment variables. As with secrets, the credential will be cleared after 45 seconds.
• Write the output of the service init command to a file instead of to stdout with --file and --file-mode. Then manually copy the file to the service machine and make sure to remove the file afterwards.
• Pipe the output of the service init command to a script.
• Pipe the output of the service init command one of the secrethub service deploy commands. More on this below.

Arguments

<namespace>/<repo>[/<dir>] (string)

The service account is attached to the repository in this path and when used together with --permission, an access rule is created on the directory in this path.

<out> (string) (optional)

Provide a path to write the service config file to. Defaults <generated-service-name>.secrethub in the working directory.

Flags

-c, --clip (boolean)

Write the service account configuration to the clipboard instead of stdout. The clipboard is automatically cleared after 45 seconds.

--description (string)

A description for the service.

--file (string)

Write the service account configuration to a file instead of stdout.

--file-mode

Set filemode for the written file. Defaults to 0440 (read only) and is ignored without the --file flag.

--permission (string)

Create an access rule giving the service account permission on a directory. Accepted permissions are read, write and admin. Use --permission <permission> to give permission on the root of the repo and --permission <subdirectory>:<permission> to give permission on a subdirectory.

List

To list all service accounts attached to a repository, you can use the service ls command:

secrethub service ls [options] <namespace>/<repo> 

The service ls command prints out the details of all services in tabular format.

Arguments

<namespace>/<repo> (string)

The repository to list service accounts for.

Flags

-q, --quiet (boolean)

Only print service IDs.

-T, --timestamp (boolean)

Show timestamps formatted to RFC3339 instead of human readable durations.

Deploy SSH

To deploy service accounts automatically to machines using SSH, you can pipe the service init output to the ssh command that creates the $HOME/.secrethub directory and writes stdin to the credential file:

secrethub service init company/repo \
    --description "Example service deployed using SSH" \
    --permission read \
    | ssh user@host "mkdir .secrethub && cat > .secrethub/credential"

Deploy Winrm

To help you deploy service accounts automatically to Windows machines, we’ve implemented the service deploy winrm command:

secrethub service deploy winrm [options] <resource-uri>

This reads an account credential from stdin and deploys it to a running instance using WinRM. The instance needs to be reachable, have WinRM enabled, and have PowerShell installed. The account credential is automatically placed in the $HOME/.secrethub/credential file in the home directory of the authenticating user.

An example would look something like this:

secrethub service init alice/myrepo/windows-server \
    --description "Example windows service" \
    --permission read \
    | secrethub service deploy winrm https://100.199.216.186

Arguments

<resource-uri> (string)

Hostname, optional connection protocol and port of the host ([http[s]//]<host>[:<port>]). This defaults to https and port 5986.

Flags

--auth-type (string)

Authentication type (basic or cert). Defaults to basic.

--username (string)

The username used for logging in when authentication type is basic. Is asked if not supplied.

--password (string)

The password used for logging in when authentication type is basic. Is asked if not supplied.

--client-cert (string)

Path to client certificate used for certificate authentication.

--client-key (string)

Path to client key used for certificate authentication.

--ca-cert (string)

Path to CA certificate used to verify server TLS certificate.

--insecure-no-verify-cert (boolean)

Do not verify server TLS certificate (insecure).