-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
feat: integrate documentation with NR Broker (#71)
* feat: integrate documentation with NR Broker * fix: improve instructions and catch error with no approles
- Loading branch information
Showing
19 changed files
with
1,316 additions
and
1,167 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -14,3 +14,4 @@ VAULT_UNSEAL_KEY | |
| /intention.json | ||
| /config/envconsul/env.hcl | ||
| /config/config.json | ||
| /setenv/* | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,128 @@ | ||
| # Vault Sync Tool - Configuration | ||
|
|
||
| This document is aimed at Vault Administrators looking to alter the policies and access the Vault Sync Tool configures. | ||
|
|
||
| For users, the Vault Sync Tool maps client roles coming from OIDC to internal groups with policies that manage what the group can do. For services, it maps App Roles to policies that manage what the service can do. | ||
|
|
||
| ## Defined Groups | ||
|
|
||
| The 'group' here refers to a grouping of policies and not a Vault group. This allows for the syncing of a specific group of policies (like apps or system) by themselves. A group is a collection of policies aimed at solving a class of access. | ||
|
|
||
| | Group | Definition | Examples | Typical Usage | | ||
| | --- | --- | --- | --- | | ||
| | system | Policies that provide broad access of Vault or a specific part. | system/admin-super | Admin users | | ||
| | apps | Policies that an individual application needs for itself. | apps/fidq/prod-kv-read | Applications or developers of an application | | ||
| | groups | Policies for a group of end users (humans) | groups/appdelivery-user | A group of end users (application delivery, DBA, etc) | | ||
|
|
||
| ### Policy Naming Pattern | ||
|
|
||
| The tool uses a naming pattern that Vault admins need to be aware of. The pattern for policy names is a simple 'group/name' pattern. | ||
|
|
||
| **Warning:** The tool will delete policies not generated by the tool starting with '<group>/' if that group is sync'ed. | ||
|
|
||
| ## Configuration Folder | ||
|
|
||
| This repo includes a generic configuration in [./config](./config/). If you have specific needs, you can copy this folder to another repository and make your changes there. | ||
|
|
||
| ## File: config.json | ||
|
|
||
| This is a key value object. Each of the root keys will be described in a separate section. | ||
|
|
||
| ### Key: db | ||
|
|
||
| **Creates:** Databases | ||
|
|
||
| This is an array of database names along with their type. Applications configured in the 'apps' key first need a database defined here to use it. There is no defined list of types as new types of databases may come along. | ||
|
|
||
| #### Database Configuration Contents | ||
|
|
||
| | Property | Type | Req | Description | | ||
| | --- | --- | --- | --- | | ||
| | name | String | Required | The lowercase name of the database. Alphanumeric and dashes only. | | ||
| | type | String | Required | The type (lowercase name) of the database. Alphanumeric only.Examples: postgresql, oracle, mysql, mariadb, orientdb | | ||
|
|
||
| ### Key: kv | ||
|
|
||
| **Creates:** Policies | ||
|
|
||
| This is simply an array of the paths to the kv roots. Only root level paths are tested (no slashes, please!). This drives creations of admin policies for these kv secret engines. | ||
|
|
||
| ### Key: appActorDefaults | ||
|
|
||
| **Creates:** Nothing. See Type: AppActorPolicies. | ||
|
|
||
| ### Key: groups | ||
|
|
||
| **Creates:** Policies & external groups | ||
|
|
||
| This is an array of team configurations. This drives creation of policies for team groups access to team kv secret access. It also is used to generate external groups to link the groups with the client roles in the OIDC used to connect. | ||
|
|
||
| The Vault Sync Tool also reads all teams from NR Broker that are setup to "use" Vault in addition to the groups here. | ||
|
|
||
| #### Groups Configuration Contents | ||
|
|
||
| | Property | Type | Req | Description | | ||
| | --- | --- | --- | --- | | ||
| | kv | String | Optional | The name of the kv root for this team's kv secret engine | | ||
| | name | String | Required | The... uh... name of the name? Used to create the external group. | | ||
| | policies | String[] | Required | An array of policies to attach. Other properties like kv will attach policies as well. It is preferred that this only be for one-off grants. Patterns should be added as extension of the team configuration. | | ||
|
|
||
| ## Application Configuration | ||
|
|
||
| The only implement source from applications and their configuration is retrieves the information from NR Broker. | ||
|
|
||
| When on boarding an application: | ||
|
|
||
| * Confirm the service is in Broker | ||
| * Confirm instances that link to the service to environments have been added | ||
|
|
||
| The vault configuration from NR Broker drives creation of policies for access to application secrets. Both users (especially developers) and the application itself will use these policies. | ||
|
|
||
| ### Vault Configuration Contents | ||
|
|
||
| | Property | Type | Req | Description | | ||
| | --- | --- | --- | --- | | ||
| | actor | AppActorPolicies | Optional | Per-environment overrides of policies for each type of actor. See: AppActorPolicies | | ||
| | approle | AppRole | Optional | Enables creating an approle for the application. Sets the policies and parameters applied to the approle. | | ||
| | db | String[] | Optional | An array of database names (see db key) that this application uses.| | ||
| | enabled | Boolean | Required | If this is enabled or not | | ||
| | policyOptions | Object | Optional | Options that alter the content of policies. Only has kvReadProject which controls if an application kv policies should be able to read project kv secrets. | | ||
|
|
||
| ### Type: AppRole | ||
|
|
||
| **Creates:** Approles that use the policies generated for apps | ||
|
|
||
| Each application can have an approle created for each environment it is configured for. This approles are created on the mount point /auth/vs_apps_approle. | ||
|
|
||
| #### Approle Configuration Contents | ||
|
|
||
| | Property | Type | Req | Description | | ||
| | --- | --- | --- | --- | | ||
| | enabled | Boolean | Required | If this is enabled or not | | ||
| | secret_id_ttl, etc | * | Optional | See Vault documentation. Every approle parameter can be specified except for role_name and policies. | | ||
|
|
||
| If you do not set a parameter, the default is usually used. The following have been given non-standard defaults: | ||
|
|
||
| * token_max_ttl - 768h | ||
| * token_period - 48h | ||
| * secret_id_num_uses - 1 | ||
|
|
||
| ### Type: AppActorPolicies | ||
|
|
||
| Defines the policy each application actor gets per environment. An application actor is something that uses application secrets like a developer or the application's approle. | ||
|
|
||
| It is best illustrated with an example. | ||
|
|
||
| ``` | ||
| { | ||
| "approle": { | ||
| ... | ||
| }, | ||
| "developer": { | ||
| "dev": ["project-kv-read", "project-kv-write", "app-db-readwrite"], | ||
| "test": ["project-kv-read", "app-db-read"] | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| The developer actor is granted policies based on the environment. The policy is named based on the filename (minus any suffix like hcl.tpl) rather than the name of the policy in Vault. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,52 @@ | ||
| # Vault Sync Tool - Development | ||
|
|
||
| Back: [README.md](README.md) | ||
|
|
||
| This document is aimed at developers looking to setup the Vault Sync Tool to run or make modifications to it. | ||
|
|
||
| See: [Oclif CLI](https://oclif.io) | ||
|
|
||
| ## Requirements | ||
|
|
||
| * Podman | ||
| * Node.js | ||
|
|
||
| ## Supported NPM commands | ||
|
|
||
| * npm run lint - lint source code | ||
| * npm run test - Run unit tests | ||
| * npm run prepack - Build and update CLI README | ||
|
|
||
| ## Build with Podman | ||
|
|
||
| ``` | ||
| podman build . -t vsync | ||
| ``` | ||
|
|
||
| ## Hashicorp Vault Setup for local testing | ||
|
|
||
| ### With NR Broker | ||
|
|
||
| NR Broker's local setup will start a Vault container and run a setup script. No further setup should be required. | ||
|
|
||
| This is currently the only practical way to run the Vault Sync Tool because NR Broker is the only implemented data source for applications. | ||
|
|
||
| ### Without NR Broker | ||
|
|
||
| The following will start up Vault in Podman. The Vault Sync Tool defaults to localhost:8200 for the address and myroot for the token. | ||
|
|
||
| `podman run --rm -e 'VAULT_DEV_ROOT_TOKEN_ID=myroot' -e 'VAULT_DEV_LISTEN_ADDRESS=0.0.0.0:8200' --name=dev-vault -p 8200:8200 vault` | ||
|
|
||
| You will need to ensure the expected auth and kv mounts exist in Vault. | ||
|
|
||
| ``` | ||
| source setenv-local.sh | ||
| vault auth enable oidc | ||
| vault auth enable -path=vs_apps_approle approle | ||
| vault secrets enable -path=apps -version=2 kv | ||
| vault secrets enable -path=groups -version=2 kv | ||
| ``` | ||
|
|
||
| ## Running with Broker | ||
|
|
||
| See: [Running Vault Sync Tool](https://bcgov-nr.github.io/nr-broker/#/development?id=running-vault-sync-tool) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.