feat: mvp of github account link (#278)

* feat: mvp of github account link
* docs: improve and fix

docs/_sidebar.md

@@ -19,8 +19,9 @@
 
 * Development
 ** [Development](/development.md)
-** [MongoDB](/dev_mongodb.md)
 ** [Document Site](/dev_docsite.md)
+** [MongoDB](/dev_mongodb.md)
+** [Vault](/dev_vault.md)
 
 * Maintenance
 ** [Adding Internal Users](/operations_internal_user.md)

docs/dev_env_vars.md

@@ -8,6 +8,7 @@ A suggested deployment strategy is to use [envconsul](https://github.com/hashico
 
 | Env Var | Default | Secret | Description |
 | --- | --- | --- | --- |
+| BROKER_URL |  |  | The external URL that this instance is running on. Used to create redirect urls. |
 | HOSTNAME |  |  | The hostname of the server this instance is running on. Used in logs. The instance with a hostname ending in '-0' is the primary node. It will cause issues if there is no primary node or there are multiple primary nodes'. |
 
 ## Audit file logging
@@ -129,6 +130,24 @@ The Redis environment variables used to setup the connection.
 | REDIS_USER | '' | Yes | The Redis user |
 | REDIS_PASSWORD | '' | Yes | The Redis password |
 
+## User Alias Services
+
+### GitHub
+
+| Env Var | Default | Secret | Description |
+| --- | --- | --- | --- |
+| GITHUB_OAUTH_CLIENT_ID |  |  | The client id of the GitHub OAuth App |
+| GITHUB_OAUTH_CLIENT_SECRET |  |  |  The client secret of the GitHub OAuth App |
+
+## Sync Services
+
+### GitHub
+
+| Env Var | Default | Secret | Description |
+| --- | --- | --- | --- |
+| GITHUB_SYNC_CLIENT_ID |  |  | The client id of the GitHub App |
+| GITHUB_SYNC_PRIVATE_KEY |  |  | The private key of the GitHub App |
+
 ## Temporary
 
 | Env Var | Default | Secret | Description |

docs/dev_vault.md

@@ -0,0 +1,35 @@
+# Hashicorp Vault
+
+## Local Development
+
+### Connecting to the local
+
+Link: http://localhost:8200/ui/vault/auth?with=token
+
+### Configure local Vault
+
+```bash
+# Configure the local Vault with basic setup
+$ ./scripts/vault-setup.sh
+```
+
+The setup script can be rerun to reset the local database. You may need to reindex the redis cache by calling the api `/v1/graph/reindex-cache`.
+
+## Vault Policies
+
+The local setup script inputs some basic policy configuration. These policies should not be used in production. It is suggested that a separate tool be used to keep your policies up-to-date.
+
+See: [Vault Sync Tool](https://github.com/bcgov-nr/vault-sync-app)
+
+### Vault Sync Tool
+
+The [Vault Sync Tool](https://github.com/bcgov-nr/vault-sync-app) configures HashiCorp Vault using NR Broker as a data source for applications and groups. NR Broker does not require the Vault Sync Tool to run for any of its own operations.
+
+#### Running
+
+The following will start the tool in monitoring mode to update the local Vault.
+
+```
+source ./scripts/setenv-curl-local.sh
+podman run --rm -e=VAULT_ADDR=http://$(podman inspect -f "{{.NetworkSettings.IPAddress}}" broker-vault):8200 -e=VAULT_TOKEN=$VAULT_TOKEN -e=BROKER_API_URL=http://host.containers.internal:3000/ -e=BROKER_TOKEN=$BROKER_JWT ghcr.io/bcgov-nr/vault-sync-app:v2.1.0
+```

docs/development.md

@@ -84,20 +84,18 @@ See: [MongoDB Development](./dev_mongodb.md)
 ### Setup Vault
 
 ```bash
-# Start up local vault
+# Start up local Vault
 $ podman run -p 8200:8200 --cap-add=IPC_LOCK -e 'VAULT_DEV_ROOT_TOKEN_ID=myroot' -d --name=broker-vault hashicorp/vault
 ```
 
-Once started, you must run the vault setup script to bootstrap it. MongoDB must be running and setup before running this.
+Once started, you must run the Vault setup script to bootstrap it. MongoDB must be running and setup before running this.
 
 ```bash
-# Configure the local vault with basic setup
+# Configure the local Vault with basic setup
 $ ./scripts/vault-setup.sh
 ```
 
-#### Github secret sync
-
-To setup a Github App to test secret syncing, set the values GITHUB_CLIENT_ID and GITHUB_PRIVATE_KEY at the Vault path `apps/prod/vault/vsync`.
+See: [Vault Development](./dev_vault.md)
 
 ## Running Locally
 
@@ -132,16 +130,6 @@ $ envconsul -config=env-prod.hcl npm run start:dev
 
 If Kinesis and AWS access is not setup then some APIs will return a 503 (service unavailable).
 
-## Running Vault Sync Tool
-
-The [Vault Sync Tool](https://github.com/bcgov-nr/vault-sync-app) configures HashiCorp Vault using NR Broker as a data source for applications and groups. NR Broker does not require the Vault Sync Tool to run for any of its own operations.
-
-The following will start the tool in monitoring mode to update the local Vault.
-
-```
-source ./scripts/setenv-curl-local.sh
-podman run --rm -e=VAULT_ADDR=http://$(podman inspect -f "{{.NetworkSettings.IPAddress}}" broker-vault):8200 -e=VAULT_TOKEN=$VAULT_TOKEN -e=BROKER_API_URL=http://host.containers.internal:3000/ -e=BROKER_TOKEN=$BROKER_JWT ghcr.io/bcgov-nr/vault-sync-app:v2.1.0
-
 ### Local MongoDB Disconnects
 
 The connection to MongoDB may time out if your machine goes to sleep. The easiest way to recover is to stop the backend, restart the containers and rerun the vault setup. The provided restart script will do the container and setup steps for you.
@@ -193,6 +181,39 @@ The dockerfile can be built locally by running the following.
 podman build . -t nr-broker
 ```
 
+## Setup Sync Services
+
+Broker can be setup to sync secrets from Vault to other locations. This helps reduce secrets sprawl by ensuring Vault remains the source of truth for your secrets.
+
+### GitHub Sync
+
+GitHub sync requires a GitHub app. It is recommended that the GitHub app be registered under a GitHub organization in production. A GitHub app registered under a personal account can be used for testing. The app requires the following permissions:
+
+* Read and Write: Manage Actions repository secrets.
+
+The app must also be installed in an organization with access to your service repositories.
+
+See:
+
+* https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app
+* https://docs.github.com/en/apps/using-github-apps/installing-your-own-github-app
+
+To locally setup a GitHub App syncing, set the values GITHUB_SYNC_CLIENT_ID and GITHUB_SYNC_PRIVATE_KEY at the Vault path `apps/prod/vault/vsync`.
+
+## Setup User Alias services
+
+Broker can be setup to allow users to alias their identity in other identity providers to their account.
+
+### GitHub Alias
+
+GitHub user alias requires a GitHub OAuth app. It is recommended that the GitHub OAuth app be registered under a GitHub organization in production. A GitHub OAuth app registered under a personal account can be used for testing.
+
+See:
+
+* https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app
+
+To locally setup a GitHub App syncing, set the values GITHUB_OAUTH_CLIENT_ID and GITHUB_OAUTH_CLIENT_SECRET at the Vault path `apps/prod/vault/vsync`.
+
 ## Province of British Columbia Palette and Font
 
 The UI defaults to Material's indigo-pink styling. The Angular build configuration 'bcgov' can be combined with an environment configuration to create a build using the BC Government Colour palette and font.