diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md new file mode 100644 index 0000000..be8deed --- /dev/null +++ b/DEPLOYMENT.md @@ -0,0 +1,127 @@ +# DEPLOYMENT + +# Running the prod image (local build): +1) Build the prod image: +``` +docker build -t astral:latest . +``` +2) Run the prod image: +``` +docker run -p 3000:3000 astral:latest +``` + +A dockerhub image will be available soon! + +# Dependencies +Astral depends on Vault, Postges, AppRegistry, and an oidc +provider. These dependencies are supplied and configured in the +devcontainer, but in production will need to be specified in the +configuration. + +Each dependency has a group of configuration params. + +# Configuration +Astral is configured in `config/astral.yml` -- all availble +configuration options are listed in the `shared` section. +Configuration values can be supplied in this file in the shared or +environmental override sections. Per-environment settings in the +config file (development, test, production) will override the shared +values for that type. + +Configuration values can also be supplied as process +environment variables with the same names (but +UPPER_CASE). Environment vars will override any values in the config +file. + +Database-specific configuration is found in `config/database.yml`, for +which environment var overrides are setup to use the `DB_` prefix. We +recommend PostgreSQL for all deployments of Astral, but any +Rails-supported database (sqlite, mysql, Oracle, etc) can be used. + +## Vault Token and Root Certificate +Astral operates with wide but not complete permissions in Vault. These +can be seen in `app/lib/clients/vault/policy.rb` in the +`create_astral_policy` section. + +An initial bootstrap token is rotated to an `astral` token having only +this policy -- but the initial token needs the ability to create the +policy and the auth token. + +The root certificate path and PKI mount point are specified in the +`vault_root_ca_ref` and related configuration params. A self-signed +root cert can be created by Astral (`vault_create_root: true`), but +you will most likely want to point to a trusted root. + +## Database encryption +The Astral database can be encrypted, if needed, but requires a bit of setup +and careful retention of a master key. Note that there are potential performance impacts. + +The database stores metadata about secrets (ownership and group info) but no actual secrets. + +1. First, create encryption keys for the database: +``` +rails db:encryption:init +``` +Copy the output to your clipboard. + +2. Next, create a `credentials.yml.enc` file: +``` +EDITOR=vi rails credentials:edit +``` +Paste the db encryption key data into this file, save, and exit. + +NB, the credentials file is encrypted and is decoded by a key placed in +`config/master.key`. Be sure to save this file, perhaps in a vault secret. + +3. Finally, set the following Astral configuration to 'true': +``` + db_encryption: true +``` + +## SSL/mTLS connections +Astral should be run as an SSL service and set to communicate with Vault via mTLS. + +To run Astral with SSL in production, provide the necessary +environment (ASTRAL_SSL_CERT, ASTRAL_SSL_KEY) to the container +environment, and use the `bin/ssl.sh` startup command. Eg: +``` +docker run -p 3000:3000 \ +-e ASTRAL_SSL_CERT=/certs/cert.pem \ +-e ASTRAL_SSL_KEY=/certs/key.key \ +-v certs:/certs:cached \ +astral:latest bin/ssl.sh +``` + +To use mTLS with Vault, set the following values in `config/astral.yml` (or environment) to +encrypt Astral-to-Vault : +``` + vault_ssl_cert: + vault_ssl_client_cert: + vault_ssl_client_key: +``` + +A self-signed server cert for Vault and Astral can +be generated with the following command. Initial placeholder certs +are already provided -- these should not be used in production. +``` +rake configure:ssl +``` + +More likely, you will want to generate certs from your trusted root or +intermediate and mount them into the container certs volume. + + +## OIDC configuration +Astral endpoints expect a `Bearer` JWT which carries the subject and +group claims of the client identity. The identity provider is external +to Astral, and could be a service such as Auth0 or a self-hosted +solution. Your Vault backend should be configured to use the same OIDC +provider. + +# Decoding JWT with signing key +To decode a JWT using a preshared signing key, set the +`jwt_signing_key` parameter in your configuration. + +# Decoding JWKS based tokens +To decode JWKS-based tokens, set the astral.yml `jwks_url` parameter to the +jwks endpoint of your auth provider. diff --git a/README.md b/README.md index 6b65340..149f3e3 100644 --- a/README.md +++ b/README.md @@ -12,13 +12,19 @@ Some features of Astral: 1) Authenticate requests for cerficates or secrets using a third party trusted source (JWT with signing key, eg) 2) For certificates: - a) Authorize the request using a Domain Ownership registry, where domain owner + 1) Authorize the request using a Domain Ownership registry, where domain owner or authorized groups must match the identity of the requesting client - b) When authorized, obtain a certificate for the common name + 2) When authorized, obtain a certificate for the common name 3) For secrets: - a) Create secrets with a policy for reading - b) Read only when the requesting client identity has the policy. -4) Log all transactions in audit infrastructure (ELK, etc). + 1) Create, read, update, and delete secrets with an arbitrary subpath. + 2) Create secrets with read-only groups for consuming. + 2) Owner/producer has full control. +4) Log all transactions in audit table. + +# Running in production + +See our [deployment guide](DEPLOYMENT.md) for configuration and deployment information. + # Running in development @@ -53,85 +59,6 @@ curl http://localhost:3000/secrets/some/path \ rails test ``` -# Running the prod image (local build): -1) Build the prod image: -``` -docker build -t astral:latest . -``` -2) Run the prod image: -``` -docker run -p 3000:3000 astral:latest -``` - -# Configuration -Astral is configured in `config/astral.yml` -- available configuration -options are listed in the `shared` section. Note that -configuration values can be supplied in this file or as process -environment variables with the same names (but -UPPER_CASE). Environment vars will override any values in the config -file. Per-environment settings in the config file(development, test, -production) will override the shared values for that type. - -Database-specific configuration is found in `config/database.yml`, for -which environment var overrides are setup to use `DB_` prefix. - -## Database encryption -The local database can be encrypted, if needed, but requires a bit of setup -and careful retention of a master key. Note that there are performance impacts. - -1. First, create encryption keys for the database: -``` -rails db:encryption:init -``` -Copy the output to your clipboard. - -2. Next, create a `credentials.yml.enc` file: -``` -EDITOR=vi rails credentials:edit -``` -Paste the db encryption key data into this file, save, and exit. - -NB, the credentials file is decoded by a key placed in -`config/master.key`. Be sure to save this file (it is .gitignored)! - -3. Finally, set the following Astral configuration to 'true': -``` - db_encryption: true -``` - -## mTLS connections -Astral can be run as an SSL service and can communicate with Vault via SSL. -Just set the following values in `config/astral.yml` (or environment) to -encrypt Astral-to-Vault : -``` - vault_ssl_cert: - vault_ssl_client_cert: - vault_ssl_client_key: -``` - -A self-signed server cert for Vault, Astral, and the OIDC provider can be -generated with the following command, and initial placeholder certs are already provided. -``` -rake configure:ssl -``` - -To use Vault SSL in the devcontainer, edit -`.devcontainer/docker-compose.yml` so that the `app` service has -`VAULT_ADDRESS` of `https://vault:8443`. Client certs can also be -configured -- in which case Vault needs to supplied with a CA for -peer verification. - -To use Astral with SSL in production, provide the necessary -environment (ASTRAL_SSL_CERT, ASTRAL_SSL_KEY) to the container -environment, and use the `bin/ssl.sh` startup command. Eg: -``` -docker run -p 3000:3000 \ --e ASTRAL_SSL_CERT=/certs/cert.pem \ --e ASTRAL_SSL_KEY=/certs/key.key \ --v certs:/certs:cached \ -astral:latest bin/ssl.sh -``` - ## OIDC configuration The OIDC modules allow the assignment of a policy to an OIDC user, by mapping that user's email address to a policy we create. They work as