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 accountservice 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):
- 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
SECRETHUB_CREDENTIAL
. - Through a
credential
file in the configuration directory. The configuration directory defaults to$HOME/.secrethub
and can be configured with the--config-dir
flag orSECRETHUB_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 onstdout
. 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
andadmin
. 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
orcert
). Defaults tobasic
. -
--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
.