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>[/<dir>]
This creates a service account and writes its generated account credential to
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:
- 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
When you want to immediately create an access rule for the service account, you can use the
--permissionflag. 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 initcommand to the clipboard instead of to
--clipflag. 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 initcommand to a file instead of to
--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 initcommand to a script.
- Pipe the output of the
service initcommand one of the
secrethub service deploycommands. More on this below.
- 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.
- Provide a path to write the service config file to.
<generated-service-name>.secrethubin the working directory.
- Write the service account configuration to the clipboard instead of stdout. The clipboard is automatically cleared after 45 seconds.
- A description for the service.
- Write the service account configuration to a file instead of stdout.
- Set filemode for the written 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://22.214.171.124
- 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).