Back: README.md
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 AppRoles to policies that manage what the service can do.
Configuring OIDC is out of scope for the Vault Sync Tool. The tool assumes there is another process (manual or automated) that maps end users to the roles included in their token.
It is extremely important that roles are correctly mapped.
A group is a collection of policies aimed at solving a class of access. This allows for the syncing of a specific group of policies (like apps or system) by themselves.
The 'group' here is not a Vault group which is a separate thing.
| Group | Definition | Examples | Typical Usage |
|---|---|---|---|
| system | Policies that provide broad access to Vault. | system/admin-super | Admin users; Generic access |
| apps | Policies required by an individual application for its own use. | 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 (developers, operations, security, auditors, management) |
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 '/' if that group is sync'ed.
This repo includes a generic configuration in ./config. If you have specific needs, you can copy this folder to another repository and make your changes there.
If required, copy (or mount) your configuration to the config folder before you run the tool.
This is a key value object. Each of the root keys will be described in a separate section.
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.
| 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 |
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.
Creates: Nothing. See Type: AppActorPolicies.
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.
| 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. |
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.
| 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. |
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.
| 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
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.