docs: add details on not saving token to system key manager (#698)

* docs: add details on not saving token to system key manager in getting started; use tabs to clean up the getting started flow

* Add more information

Co-authored-by: Jeff Mitchell <jeffrey.mitchell@gmail.com>
This commit is contained in:
Jeff MalnickandJeff Mitchell authored and GitHub committed 2020-10-15 15:30:06 -07:00
1 parent d25a39b4d7
commit 685b7c1e63
1 file changed
+43 -1
@@ -20,7 +20,8 @@ Boundary uses a predictable login name (`admin`) and password (`password`) in
dev mode. These can be overridden, or randomly generated, with flags to
`boundary dev`.
From the CLI:
<Tabs>
<Tab heading="CLI">
```
$ boundary authenticate password \
@@ -29,6 +30,39 @@ $ boundary authenticate password \
-auth-method-id=ampw_1234567890
```
If you are on Unix-like operating system (other than macOS/Darwin), you may get
an error indicating that the token could not be stored, as the freedesktop.org
Secret Service implementation is not always available. On these systems, you can
work around this by installing `dbus-x11` and `gnome-keyring` using your package
manager, then creating and unlocking the default keyring with the following,
substituting in a password of your choice for "foorbar" (but ending with `\n`).
You can also avoid putting the password on the command line by running the
`gnome-keyring-daemon` commands directly and entering in the password, followed
by a newline (return) and an EOF (`Ctrl+D`).
- `eval "$(printf 'foobar\n' | gnome-keyring-daemon --unlock)"`
- `eval "$(printf 'foobar\n' | gnome-keyring-daemon --start)"`
This would have to be run in each shell.
If you're unable to install these packages, or don't want to, you can tell the
Boundary authenticate command to not save the token to the operating system's
key manager by setting `-token-name=none` flag or `BOUNDARY_TOKEN_NAME=none` env
variable when running `boundary authentiate`. You'll be responsible for setting
the token in subsequent commands via `-token` flag or `BOUNDARY_TOKEN` env
variable. An easy way to do this would be to use the `-format=json` flag along
with `jq` to pull the token value out of the response and place it wherever you
wish, then create a command alias for `boundary` that sources that value into
the environment or the `-token` flag.
~> Token storage on *nix systems has been more problematic than we expected.
We're exploring alternatives. See the discussion on [this GitHub
issue](https://github.com/hashicorp/boundary/issues/697#issuecomment-709448942)
to track it and voice your thoughts.
</Tab>
<Tab heading="Admin Console">
To authenticate to the Admin UI, open
[http://127.0.0.1:9200](http://127.0.0.1:9200) in a browser and enter the login
name and password:
@@ -40,6 +74,10 @@ name and password:
/>
</video>
</Tab>
<Tab heading="Terraform">
You can also use these overrides to configure the [Terraform provider for
Boundary](https://github.com/hashicorp/terraform-provider-boundary):
@@ -55,6 +93,10 @@ provider "boundary" {
Note in the example above we're setting `base_url` to `http` and not `https` as
the Boundary server does not use TLS in development mode.
</Tab>
</Tabs>
## Next Steps
See [connecting to your first target](/docs/getting-started/connect-to-target) for how