From cb34acd0b6f2d841a3e8d15e34117347f2190848 Mon Sep 17 00:00:00 2001 From: Jay Conrod Date: Tue, 27 Aug 2024 07:30:21 -0700 Subject: [PATCH] README: document noninteractive flow + minor tweaks (#42) - Squashed "One-time setup" and "Installation" headings. - Expanded Use section, removed "Each day". - Add "Use in a non-interactie environment" section. - Moved "Building" section up, renamed "Building from source", added instructions for Bazel and Go dev builds. --- README.md | 92 +++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 69 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index 2fd7da0..c0a9ab3 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,20 @@ # engflow_auth -This repository provides `engflow_auth`, a [Bazel credential helper](https://blog.engflow.com/2023/10/20/secure-builds-with-credential-helpers/) that helps you automatically obtain and securely store EngFlow authentication tokens. +This repository provides `engflow_auth`, a [Bazel credential helper](https://blog.engflow.com/2023/10/20/secure-builds-with-credential-helpers/) that helps you automatically obtain and securely store EngFlow authentication credentials. ## Installation -### One-time setup - 1. Download the appropriate binary from the latest [release - page](https://github.com/EngFlow/auth/releases/latest) + page](https://github.com/EngFlow/auth/releases/latest). 1. Copy the downloaded binary to a directory on the system `$PATH` and mark as - executable (if necessary) -1. Configure `.bazelrc`: In the `.bazelrc` file of either your project or user, - add a `build` flag that sets `--credential_helper` for your cluster. For + executable (if necessary). On macOS, you may also need to remove the quarantine flag. + + ```bash + chmod +x engflow_auth + [ "$(uname)" != Darwin ] || xattr -d com.apple.quarantine engflow_auth + ``` + +1. In the `.bazelrc` file of either your project or user, add a line that sets `--credential_helper` for your cluster. For instance: ``` @@ -19,16 +22,70 @@ This repository provides `engflow_auth`, a [Bazel credential helper](https://blo ``` would configure the credential helper correctly when `--config=engflow` is - passed to a bazel invocation. See [Bazel's config + passed to a bazel invocation. You may remove existing `--tls_client_certificate`, `--tls_client_key`, and `--remote_header` flags for this cluster. See [Bazel's config documentation](https://bazel.build/run/bazelrc) for more info on bazelrc files, and [EngFlow setup documentation](https://docs.engflow.com/re/client/bazel-first-time.html#4-set-up-bazelrc) - for EngFlow-specific setup and tips. + for EngFlow-specific setup instructions. + +## Use + +1. Run `engflow_auth login [CLUSTER URL]` to obtain a credential. This prints a URL to visit in your browser. +1. Visit the URL to complete the process, logging in if necessary. `engflow_auth` will download and store a credential in on your system's encrypted keyring. + +This process needs to be repeated after the credential expires, typically every 90 days. + +## Use in a non-interactive environment (CI) + +You can use `engflow_auth` to authenticate when no web browser is available, for example, on a continuous integration and testing server. + +1. You may wish to create a service account with your authentication provider, then log into your EngFlow cluster with that account. The credential created here will let Bazel authenticate as this account. +1. On a machine with a web browser, complete the login process as described above: + + ```bash + engflow_auth login [CLUSTER URL] + ``` + +1. Export the credential to stdout using the command below: + + ```bash + engflow_auth export [CLUSTER URL] + ``` + +1. Save this credential as a secret, accessible in the non-interactive environment. For example, if you're using GitHub Actions, you can save this as a GitHub secret, then grant access in workflows that need it. +1. At the beginning of a job, retrieve the secret and import it on stdin using the command below. The `-store=file` flag may be necessary to store the credential as an unencrypted file instead of your encrypted keyring. Non-interactive environments typically don't have an encrypted keyring. + + ```bash + engflow_auth import -store=file <<<"${ENGFLOW_CRED}" + ``` + +1. At the end of a job, remove the credential using the command below. + + ```bash + engflow_auth logout [CLUSTER URL] + ``` -### Use +For an example, see this repository's own configuration. [main.yml](/blob/main/.github/workflows/main.yml) grants access to the secret. [login.sh](/blob/main/infra/login.sh) obtains and imports a credential. [logout.sh](/blob/main/infra/logout.sh) removes it. -Each day, run `engflow_auth login [CLUSTER URL]` to obtain an auth credential; -the application will emit a URL to visit to complete the login process. +## Build from source + +To build `engflow_auth` with Bazel, clone this repository then run: + +```bash +bazel build //cmd/engflow_auth +``` + +To build and install `engflow_auth` with Go: + +```bash +go install github.com/EngFlow/auth/cmd/engflow_auth@latest +``` + +To build release artifacts: + +```bash +bazel build --config=release //:release_artifacts +``` ## Reporting Issues @@ -43,17 +100,6 @@ For usability bugs and feature requests, please contact us through your DSE or via our [existing support channels](https://docs.engflow.com/support/get-day-to-day-support.howto.html). -## Building - -The CLI can be built via either the Go toolchain or Bazel; released binaries are -built via Bazel. - -To build release binaries, run: - -``` -bazel build --config=release //:release_artifacts -``` - ## Contributing We are not accepting pull requests from external contributors at this time due