diff --git a/README.md b/README.md index fed87c0..ae9aec8 100644 --- a/README.md +++ b/README.md @@ -5,11 +5,28 @@ Purpose: Manage gpg keys for: # Key Management -Roles: - -* New User: new key to be added; can be a new employee being added for first time, existing employee getting access to a new repo, key rotation, etc -* Existing User: user who already has access to the appropriate project +* Role: New User: new key to be added; can be a new employee being added for first time, existing employee getting access to a new repo, key rotation, etc +* Role: Existing User: user who already has access to the appropriate project * Definition: List of all users: [verify/.sops.yaml](verify/.sops.yaml) +* Keys Repository: This Git Repository (`communication-keys`), manages public keys and configuration in Project Repositories +* Project Repository: Git Repository for each Project which contains SOPS-Encrypted secrets, e.g. for GitOps Deployments using Helm Files + + +# Playbook for Configuring Access for New Users + +## Overview: + +1. In the Keys Repo (`communication-keys`): + 1. New User creates,adds GPG Key + 1. Existing User configures groups + 1. Existing User configures verification SOPS Config + 1. New User installs SOPS + 1. New User verifies SOPS installation using verification SOPS Config + 1. **Status**: New User has working key, working sops installation. Caveat: No access to secrets in other repos yet +1. In the Project Repo + 1. Existing User adds New User Key to SOPS Config, Secrets Files + 1. New User verifies access + 1. **Status**: New User has access to SOPS-encrypted secrets within Project Repo ## 1a. Onboarding: [New User]: create and add a gpg key 1. Clone this repository @@ -20,38 +37,26 @@ Roles: - CAVEAT: step 14 is not necessary, as it is specific to a GitHub account 1. add ONLY the _PUBLIC_ part of your gpg key!!! to your branch - file format: `@netgo.de.gpg.pub` + - **Example**: `max.musterman@netgo.de.gpg.pub` 1. git: commit the new file, push -1. open a MergeRequest -1. Hand-Off: Assign the MR to an Existing User in your Team to have your key added. +1. gitlab: open a MergeRequest +1. **Hand-Off**: Assign the MR to an Existing User in your Team to have your key added. - Hint: Look up all Existing Users in the comments at: [verify/.sops.yaml](verify/.sops.yaml) ## 1b. Onboarding: [Existing User|New User]: Add new user to groups -Determine the groups to which access is needed, e.g. a specific repository. - -If uncertain, ask a Team Member for help! +**Prerequisite**: Determine the groups to which access is needed, e.g. a specific repository. If uncertain, ask a Team Member for help! -Technical Instructions - please forgive the complexity - -Access for each repo is tracked using the `./groups/` directory; each sub-directory represents a "group" (Note: some "groups" are also "roles", e.g. `admin`) - -Most of the groups correspond directly to git repository names, aka "project name" +**Technical Instructions** - please forgive the complexity Create a symlink from the group-directory back to the keyfile -```shell -cd groups/ -ln -s ../../ -``` -Example: - -Add "Max Musterman" to the group for `devnso-adp-argocd`: -```shell -# navigate to group-directory for devnos -cd groups/devnso-adp-argocd -# symlink to pubkey for New User -ln -s ../../max.musterman@netgo.de.gpg.pub -``` +1. `cd groups/` + - **Example**: `cd groups/devnso-adp-argocd` + - Explanation: Access for each repo is tracked using the `./groups/` directory; each sub-directory represents a "group" (Note: some "groups" are also "roles", e.g. `admin`) + - Explanation: Most of the groups correspond directly to git repository names, aka "project name" +1. `ln -s ../../` + - **Example**: `ln -s ../../max.musterman@netgo.de.gpg.pub` ## 2. Onboarding: [Existing User]: Configure sops config @@ -61,53 +66,96 @@ For verification purposes, this repo also contains a _sample_ `.sops.yaml` to wh ### Update Verification SOPS Config -Follow the interactive prompts: -```shell -./verify/usr_confirm_keycfg.sh -``` - -Now the sample secrets file _in this repo_ has been updated, and the New User should be able to decrypt it! +1. Checkout the New User's branch titled `add_pubkey_[firstname]-[lastname]`. + - CLI: e.g. `git branch add_pubkey_Max-Musterman` +1. Run `./verify/usr_confirm_keycfg.sh` +1. git: commit the new file, push +1. **Status**: New User has working SOPS Configuration +1. **Hand-Off**: Proceed to next steps; Instruct New User to verify access to secrets ### Update Project SOPS Config -The following commands explain how to update the `.sops.yaml` for a repository: - -#### Prerequisite +The following commands explain how to update the `.sops.yaml` for a repository. + +Note: For a worked-through example, see next section. + +1. **Prerequisite** + 1. Obtain Project Repo + - CLI:: `git clone ` +1. **Create Branch** + - CLI: `git checkout -b add_pubkey_[firstname]-[lastname] origin/main` +1. **Configure Project Repo for New User** + 1. List available groups: + - CLI: `${PATH_TO_COMMUNICATION_KEYS_REPO}/bin/update_sops.sh --list_groups` + - Reminder: Group Name usually corresponds to Repository Name + 1. Update sops config AND all secrets files: + - CLI: `${PATH_TO_COMMUNICATION_KEYS_REPO}/bin/update_sops.sh -g $(find . -name secrets.yaml)` +1. **Commit the changes, Create Change Request (PR/MR)** + 1. git: commit the changes to `.sops.yaml` and secrets files (`secrets.yaml`) files + - CLI: `git add .sops.yaml $(find . -name secrets.yaml)` + - **CAVEAT**: check for other changes with `git status` ! The files do not always follow consistent conventions. + - CLI: `git commit -m "adds . to sops config"` + 1. git: push branch + - CLI: `git push -u origin add_pubkey_[firstname]-[lastname]` + 1. gitlab: open a MergeRequest, Review, Merge +1. **Status**: New User has access to SOPS-Encrypted Secrets within Project Repo +1. **Hand-Off**: Proceed to next steps; Instruct New User to verify access to secrets + +#### Example + +**Prerequisite** +Obtain Repo ```shell # E.g. update sops config for DevNSO % git clone git@git.dev-at.de:cloud-solutions/nso/devnso-adp-argocd.git % cd devnso-adp-argocd/ ``` +**Create Branch** + +```shell +## OPINIONATED GIT - use preferred method +git checkout -b add_pubkey_max-musterman origin/main +``` -#### Commands +**Configure Project Repo for New User** + + ```shell # List available groups +# Output: % ${PATH_TO_COMMUNICATION_KEYS_REPO}/bin/update_sops.sh --list_groups # INFO: listing groups admin automation devnso-adp-argocd -# For a given group, update sops config -% ${PATH_TO_COMMUNICATION_KEYS_REPO}/bin/update_sops.sh -g devnso-adp-argocd +# For a given group, update sops config AND all secrets files - New Users cannot add themselves! +# Output: +% ${PATH_TO_COMMUNICATION_KEYS_REPO}/bin/update_sops.sh -g devnso-adp-argocd $(find . -name secrets.yaml) # RUN: generate SOPS config -# WARN: no secrets file passed in, make sure to call 'sops updatekeys' on secrets files +# RUN: gpg --import *.gpg.pub +# RUN: sops updatekeys ./loki/loki/secrets.yaml +... +# SUCCESS: all users with keys in this dir should have functional keys +``` -# [OPTIONAL] For a given group, update sops config AND specified secrets file -% ${PATH_TO_COMMUNICATION_KEYS_REPO}/bin/update_sops.sh -g devnso-adp-argocd -s ./adp-api-devs/adp-api-devs/secrets.yaml +**Commit the changes, Create Change Request (PR/MR)** +```shell +# git: commit the changes to `.sops.yaml` and secrets files (`secrets.yaml`) files +% git add .sops.yaml $(find . -name secrets.yaml) +# **CAVEAT**: check for other changes with `git status` ! The files do not always follow consistent conventions. +# output: +% git status +... +no changes added to commit (use "git add" and/or "git commit -a") -# commit the changes to any .sops.yaml or secrets files, e.g. with -## OPINIONATED GIT - use preferred method -% git add -p -# 1. review changes to the .sops.yaml -# 2. press 'y' to accept the changes -y -% git commit -m "adds . to sops config" -% git push +% git commit -m "adds max.musterman to sops config" + +git push -u origin add_pubkey_max-musterman ``` -At this point, the New User has been configured and can grant themselves access to any of the secrets files in this project. +Now proceed to with the remaining steps, i.e. gitlab: open a MergeRequest, Review, Merge ## 3. Onboarding: [New User] Configure SOPS @@ -116,30 +164,18 @@ SOPS is used for encrypting secrets, e.g. credentials for various systems ## Install -### 1. Install Sops - -https://github.com/getsops/sops - -Note: -* MacOS: If desired, one can also use brew to install sops: `brew install sops`; although this is not officially maintained, [the formula is essentially the same as the official installation instructions](https://github.com/Homebrew/homebrew-core/blob/4496ce5131bc09e7065fa0aa8fb96366a3df6477/Formula/s/sops.rb) - -### 2. Configure - -Add the following to your `~/.bashrc` or `~/.zshrc` - but _not_ to your `~/.profile` as it must be set per session: - -```shell -# Enable interactive passphrase prompt for SOPS -export GPG_TTY=$(tty) -``` - -### 3. Verify - -Run the following command to verify local SOPS installation _and_ key configuration: - -```shell -# Follow the interactive prompts: -./verify/usr_confirm_keycfg.sh -``` +1. **Install Sops** + 1. https://github.com/getsops/sops + - Note: + * MacOS: If desired, one can also use brew to install sops: `brew install sops`; although this is not officially maintained, [the formula is essentially the same as the official installation instructions](https://github.com/Homebrew/homebrew-core/blob/4496ce5131bc09e7065fa0aa8fb96366a3df6477/Formula/s/sops.rb) +1. **Configure Sops** + * Add the following to your `~/.bashrc` or `~/.zshrc` - but _not_ to your `~/.profile` as it must be set per session: + ```shell + # Enable interactive passphrase prompt for SOPS + export GPG_TTY=$(tty) + ``` +1. **Verify SOPS Installation and Key Configuration** + 1. `./verify/usr_confirm_keycfg.sh` ## Usage @@ -154,7 +190,9 @@ Note: The `GPG_TTY` is necessary to have the password prompt appear. src: https: Note: `secrets.yaml` is just an example; the file can have any name -## 4. Offboarding: [Existing User]: Archive Expired Keys (EOL) +# Playbook for Removing Expired Keys + +## Offboarding: [Existing User]: Archive Expired Keys (EOL) To mark a key as expired: 1. move it to the `archive/` dir @@ -180,7 +218,7 @@ find groups/ -name ${keyname} # For each group, update sops config in that repo # Example: % cd devnso-adp-argocd -% ${PATH_TO_COMMUNICATION_KEYS_REPO}/bin/update_sops.sh -g devnso-adp-argocd +% ${PATH_TO_COMMUNICATION_KEYS_REPO}/bin/update_sops.sh -g devnso-adp-argocd $(find . -name secrets.yaml) # now git commit, push, etc ```