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>

Credential

Service accounts are given their own credential, which they use to access SecretHub.

To give your service (e.g. your application or CI pipeline) access to SecretHub, you can supply the credential 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.

To help you supply the credential in one of those ways, the service init command offers a few possibilities:

• By default, the service init command prints the credential on stdout. You can pipe the output of the command in a script. Below, you’ll find examples for SSH and Winrm.
• To supply the credential in a graphical user interface, such as your CI pipelines environment variables, you can use the --clip flag, which copies the services credential to your clipboard and clears the clipboard again after 45 seconds.
• To supply the credential in a file, you can use the --file and --file-mode flags.

Permission

To give the service account access to secrets, you’ll set up access rules. You can set access rules using secrethub acl set. You can find the service ID (the account-name to use in acl set), by running service ls.

As a shorthand alternative, you can use the --permission flag on this service init command to immediately set an access rule when creating the service account.

Arguments

<namespace>/<repo> (string)

The service account is attached to this repository.

Flags

-c, --clip (boolean)

Write the service account credential 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 credential to a file instead of stdout.

--file-mode

Set filemode for the written credential 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).

Revocation

To remove a service account and revoke its access to all secrets, you can use the repo revoke command:

secrethub repo revoke company/repo s-2A3bf0sd4K5p

For further reference, see the documentation for repo revoke.