From b8b60686ace214743f39b56ca69ee2ffba944f30 Mon Sep 17 00:00:00 2001 From: Jacob Bednarz Date: Tue, 17 Nov 2020 12:52:33 +1100 Subject: [PATCH] Extend documentation (#28) Add documentation on how/what short lived tokens are --- README.md | 182 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 182 insertions(+) diff --git a/README.md b/README.md index ff427ab..c83657b 100644 --- a/README.md +++ b/README.md @@ -25,6 +25,79 @@ $ brew tap jacobbednarz/cf-vault $ brew cask install jacobbednarz/cf-vault/cf-vault ``` +## Getting started + +1. First step is to generate a new API key or API token. Either will work + however there are some subtle differences to take into consideration before + choosing your path. + + - API tokens **are not** supported by all services yet. Regardless of whether + you are using the short lived credentials or long lived token, it may not + work for all services and you may need to have a backup profile defined + using an API key to cover all scenarios . + - API keys **are** supported everywhere however they cannot be scoped. API + keys have the permission and scopes that your user account has. This can be + dangerous so be sure to tread carefully as it may have unintended consequences. + + While it is possible (and better practice of [principle of least privilege]), + to use an API token with only permissions to create a new API token, this + isn't really viable for all use cases yet. The recommended approach is to use + the API key for the profile and rely on a custom policy to scope the short + lived credential. This allows the best of both worlds where if you need to + use a service that doesn't support API tokens, you don't need to create a new + profile. + + To create a new API token: + + ``` + > https://dash.cloudflare.com/ + > My Profile + > API Tokens + > Create API token + ``` + + To retrieve your API key: + + ``` + > https://dash.cloudflare.com/ + > My Profile + > API Tokens + > Global API Key + ``` + +1. If you're using an API key, you can skip to the next step. Otherwise, + navigate through the UI and configure what permissions and resources you'd + like to assign to the token. If you're looking to use an API token to + generate short lived API tokens, you should only need the single predefined + "Create API tokens" permission. See the section below on generating the desired + TOML output for instructions on how to do automatically convert policies from + API responses. + + Note: Be sure to note down the API token **before** closing/navigating away + from the UI as you won't be able to retrieve it again. + +1. Once you have your API key or API token value, you can start using `cf-vault` + by creating a profile. A profile is the collection of configuration that + tells `cf-vault` how you intend to interact with the Cloudflare credentials. + You need to start by calling `cf-vault add + [your-profile-name]` where `[your-profile-name]` is a label for what the + credential/use of the profile is. Some examples: + + - `cf-vault add write-everything` + - `cf-vault add read-only` + - `cf-vault add super-scary-access-everything` + - `cf-vault add api-token-to-create-other-tokens` + + There is no limit on how many profiles you have if you prefer to have + specific profiles for your use cases. + +1. Now that you have created a profile, you can use it with `cf-vault exec + [your-profile-name]`. + +If you do not wish to use the short lived credentials functionality, +that's totally fine and you can do so by omitting the `session_duration` value +and instead the long lived credentials you've setup will be used. + ## Usage `cf-vault` allows you to manage your Cloudflare credentials in a safe place and @@ -55,3 +128,112 @@ $ exit $ env | grep -i cloudflare # => no results ``` + +## Generating token policies + +While TOML is more readable, its not always straight forward to generate the +desired output. Instead, you can use the Cloudflare dashboard to build the +policy you'd like and then covert that to TOML using some tooling to avoid +manually building your policy (though you can if you understand the syntax!). + +1. Using `cf-vault add` create your profile following the prompts. +1. Create the token you'd like to use on the command line using the Cloudflare + dashboard. +1. Make the API call to fetch the token you've just created. See + https://api.cloudflare.com/#user-api-tokens-token-details or + https://api.cloudflare.com/#user-api-tokens-list-tokens to fetch all tokens. +1. Write the contents of the single `result` JSON payload to a local file. For + the example, I'll use `example_token.json` for the documentation. +1. Run the following command using `docker` which will pull the `go-toml` tool + for coverting JSON -> TOML. Remember to replace `example_token.json` with + your filename. + + ``` + docker run -v $PWD:/workdir pelletier/go-toml jsontoml /workdir/example_token.json + ``` + +1. Paste the generated `policy` into your configuration file. You will need to + adjust the structure slightly to match the hierarchy. For instance, if I have + the following profile: + + ```toml + [profiles] + + [profiles.doco-example] + auth_type = "api_token" + email = "me@example.com" + session_duration = "15m" + ``` + + and my policy output: + + ```toml + [[policies]] + effect = "allow" + + [[policies.permission_groups]] + id = "eb258a38ea634c86a0c89da6b27cb6b6" + name = "Access: Apps and Policies Read" + + [[policies.permission_groups]] + id = "517b21aee92c4d89936c976ba6e4be55" + name = "Zone Settings Read" + + [[policies.permission_groups]] + id = "c8fed203ed3043cba015a93ad1616f1f" + name = "Zone Read" + + # .. snip + ``` + + The policy needs to be updated to prepend `profiles.doco-example` to the + section keys. + + ```toml + [[profiles.doco-example.policies]] + effect = "allow" + + [[profiles.doco-example.policies.permission_groups]] + id = "eb258a38ea634c86a0c89da6b27cb6b6" + name = "Access: Apps and Policies Read" + + [[profiles.doco-example.policies.permission_groups]] + id = "517b21aee92c4d89936c976ba6e4be55" + name = "Zone Settings Read" + + [[profiles.doco-example.policies.permission_groups]] + id = "c8fed203ed3043cba015a93ad1616f1f" + name = "Zone Read" + + # .. snip + ``` + + Making the complete configuration look like: + +```toml + [profiles] + + [profiles.doco-example] + auth_type = "api_token" + email = "me@example.com" + session_duration = "15m" + + [[policies]] + effect = "allow" + + [[policies.permission_groups]] + id = "eb258a38ea634c86a0c89da6b27cb6b6" + name = "Access: Apps and Policies Read" + + [[policies.permission_groups]] + id = "517b21aee92c4d89936c976ba6e4be55" + name = "Zone Settings Read" + + [[policies.permission_groups]] + id = "c8fed203ed3043cba015a93ad1616f1f" + name = "Zone Read" + + # .. snip + ``` + +[principle of least privilege]: https://en.wikipedia.org/wiki/Principle_of_least_privilege