When you create your own instance of Crossfeed, you can customize many aspects of how it looks. The
dev.env.example file contains a full list of all customizable variables.
To deploy Crossfeed for the first time in a fresh AWS environment, you need to do a couple of things:
- Set up a custom domain for the frontend and create an ACM certificate for it
- Set up authentication mechanism (Cognito or login.gov) Generate a login.gov RSA key
- Set initial SSM variables
- Configure User Agent and request signing
- Configure other environment variables
Pick a custom domain for your frontend and create an ACM certificate for your domain. Then, set the
frontend_cert_arn variables in
Choose between using Cognito or login.gov. login.gov can only be used if you are a government agency, so you'll most likely just want to use Cognito.
You can perform these Cognito setup steps after the user pools have been created after you first run Terraform (mentioned below).
backend/env.yml, set the following variables:
USE_COGNITO: 1 REACT_APP_USER_POOL_ID: us-east-1_uxiY8DOum
frontend/prod.env, make sure the following environment variables are set:
REACT_APP_USE_COGNITO=1 REACT_APP_USER_POOL_ID=us-east-1_uxiY8DOum REACT_APP_USER_POOL_CLIENT_ID=1qf4cii9v0t9hn1hnr54f2ao0j
frontend/prod.env, remove the lines that set the
REACT_APP_USE_COGNITO environment variables. Both variables must be unset for login.gov authentication to be used!
Run the following to generate a login.gov RSA key (preferably in a non-git directory outside of crossfeed!):
openssl genrsa -out private.pem 2048 openssl req -newkey rsa:2048 -nodes -days 3650 -out csr.pem openssl x509 -req -in csr.pem -out cert.pem -signkey private.pem npm install -g pem-jwk pem-jwk private.pem > private.jwk
Visit the Login.gov sandbox dashboard to create a login.gov application, providing
cert.pem as the public certificate. Copy the contents of
private.jwk to use as your
LOGIN_GOV_JWT_KEY, which is stored in SSM in the next step.
First, make sure you set the following SSM variables manually through the AWS Console (replace
prod as needed). Make sure these variables are set as "SecureString":
cd infrastructure. Then, create a new bucket on S3 that can be used to store terraform state; make sure the bucket is private, bucket versioning is enabled, and server-side encryption is enabled. Then run
cp stage.config .env and change the variables in
.env to use this bucket name.
Make sure you configure the default AWS profile using
aws configure , or set the
AWS_PROFILE environment variable in
You must also create a service-linked role for Amazon ES (this only needs to be created once per AWS account):
aws iam create-service-linked-role --aws-service-name es.amazonaws.com
npm i -g dotenv-cli make init make plan make apply
Crossfeed's workers, when performing requets, can optionally send a User Agent identifying the requestor as Crossfeed
Signature header to verify that Crossfeed is performing the request.
To do this, you can set the
WORKER_SIGNATURE_PUBLIC_KEY, and the
WORKER_SIGNATURE_PRIVATE_KEY parameters in your env file:
WORKER_USER_AGENT="Crossfeed (Test request from Crossfeed Staging Environment, for development use only. For more information, see https://github.com/cisagov/crossfeed)" WORKER_SIGNATURE_PUBLIC_KEY="public key, can have newlines" WORKER_SIGNATURE_PRIVATE_KEY="private key, can have newlines"
Note that when deploying Crossfeed to AWS, the worker signature public and private keys should also be set as SSM secrets (such as
The public and private key values can be generated by running:
ssh-keygen -m PEM -t rsa -f test_key ssh-keygen -f test_key.pub -m 'PEM' -e > test_key.pem
The public key is the value of
test_key.pem and the private key is the value of
One can then verify that requests are coming from Crossfeed by providing you with the following parts of the request:
- Value of the
- Value of the
- Request method
- Request URL
You can call the
SignRequests.verify_signature method (found in
backend/worker/mitmproxy_sign_requests.py) to verify a signature with
the above four parts of a request. Crossfeed will later have an admin UI that allows admins to run this check directly from the web interface.
The full list of configurable environment variables are provided in
.env (used in local development),
backend/env.yml. Additionally, more settings from the Terraform end are stored in