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.
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
To create a new service account for an application, you can use the
service init command:
secrethub service init [options] <namespace>/<repo>
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):
- Through the command-line flag
--credential. Be sure to avoid having the credential end up in the command history or process lists.
- Through the environment variable
- Through a
credentialfile in the configuration directory. The configuration directory defaults to
$HOME/.secrethuband can be configured with the
To help you supply the credential in one of those ways, the
service init command offers a few possibilities:
- By default, the
service initcommand 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
--clipflag, 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
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
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.
- The service account is attached to this repository.
- Write the service account credential to the clipboard instead of stdout. The clipboard is automatically cleared after 45 seconds.
- A description for the service.
- Write the service account credential to a file instead of stdout.
- Set filemode for the written credential file. Defaults to
0440(read only) and is ignored without the
- Create an access rule giving the service account permission on a directory.
Accepted permissions are
--permission <permission>to give permission on the root of the repo and
--permission <subdirectory>:<permission>to give permission on a subdirectory.
To list all service accounts attached to a repository, you can use the
service ls command:
secrethub service ls [options] <namespace>/<repo>
service ls command prints out the details of all services in tabular format.
- The repository to list service accounts for.
- Only print service IDs.
- Show timestamps formatted to RFC3339 instead of human readable durations.
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
secrethub service init company/repo \ --description "Example service deployed using SSH" \ --permission read \ | ssh user@host "mkdir .secrethub && cat > .secrethub/credential"
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://188.8.131.52
- Hostname, optional connection protocol and port of the host (
[http[s]//]<host>[:<port>]). This defaults to https and port 5986.
- Authentication type (
cert). Defaults to
- The username used for logging in when authentication type is basic. Is asked if not supplied.
- The password used for logging in when authentication type is basic. Is asked if not supplied.
- Path to client certificate used for certificate authentication.
- Path to client key used for certificate authentication.
- Path to CA certificate used to verify server TLS certificate.
- Do not verify server TLS certificate (insecure).
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