LAMP-app-gateway

The app gateway server component for logging and push notifications.

Environment

Name	Required	Description
API_KEYS	✔️	Secret. Comma-separated list of
APNS_BUNDLE_ID	✔️	The Apple app's bundle id (the reverse-dns style identifier) is used as the topic for push notifications.
APNS_IS_PRODUCTION		Set to true if production APNs endpoints should be used. Else, false or not set.
APNS_KEY_FILE_BASE64	✔️	Secret. This is a base64-encoded .p8 key. See details below reguarding it's generation and encoding.
APNS_KEY_ID	✔️
APNS_TEAM_ID	✔️
AWS_DYNAMO_OTP_REGION	✔️	The region in which the one-time passwords dynamo table lives.
AWS_DYNAMO_OTP_TABLE_NAME	✔️	The name of the one-time passwords dynamo table.
AWS_SES_EMAIL_ADDR_REPLY_TO	✔️	The email address that should be automatically configured for replys to dispatch email messages. Usually a no-reply@ address.
AWS_SES_EMAIL_ADDR_SENDER	✔️	The email address the end-user will see as the "From" address in their email client. Eg. dev-sender@mail.dev.lamp.digital. Note that this domain must be verified in AWS's SES.
AWS_SES_REGION	✔️	The region in which our SES resources are configured and the SES API requests should be directed.
AWS_SES_TEMPLATE_SUFFIX	✔️	The suffix of email template strings. Each ECS service is only authorized to use templates that end in a specific suffix. That suffix should be match the SES template suffixes configured in terraform.
AWS_SMS_CONFIG_SET_NAME	✔️	The name of the AWS End-User Messaging configuration set (rules) that should be used when dispatching SMS messages.
AWS_SMS_ORIGINATION_IDENTITY	✔️	The ID of the End-User Messaging phone pool that should be used in dispatching SMS messages to end users.
AWS_SMS_REGION	✔️	The region in which out End-User Messaging resources are configured and the End-User API requests should be directed.
FIREBASE_SERVICE_ACCOUNT_JSON_BASE64	✔️	Secret. A base64 encoded service account key. These keys start as json in cleartext and must be base64 encoded before setting. To generate the service account json file, follow
SENTRY_DSN		The unique URL provided by Sentry used to route error events to the correct account. Leave empty to disable error event reporting to Sentry.
SENTRY_ENV		The environment string that should be reported to Sentry for aggregation. Leave empty if Sentry error reporting is disabled.

Note

Variables ending in _BASE64 are values that must be base64 encoded prior to being set in the environment or parameter store secrets. Typically these environment variables are files, such as google's serivce accounts or apns' certificate bundles.

To encode a file:

# OSX
openssl base64 -A -in input_file | pbcopy

# Linux
base64 -w 0 input_file | xclip -selection clipboard

To encode a value:

# OSX
printf %s "input_value" | openssl base64 -A | pbcopy

# Linux
echo -n "input_value" | base64 -w 0 | xclip -selection clipboard

Warning

there are several variants of base-64 encoding out there. base64 uses the one defined in RFC 4648. When decoding in node, use Buffer.from(base64String, 'base64').toString('utf8');. Beware of functions that encode or decode base-64 using alterative character sets or padding. See this mdn article for more.

Adding a new API Key

To generate a new API key, use tr -dc A-Za-z0-9 </dev/urandom | head -c 64; echo. Append it to the list with a comma, without spaces.

Setting Firebase Variables

To configure the Firebase Admin application in our non-google environment, we must set credentials manually rather than relying on Google's "Application Default Credentials" look-up chain. Our application has a service account for each environment:

• dev: LAMP-notif-dev
• staging: LAMP-notif-stg
• prod: LAMP-notif-prod

Each of these service accounts should be grantend the "Service Account Token Creator" and "Firebase Admin SDK Administrator Service Agent" roles on the "LAMP Platform" resource.

To (re)configure the keys to each of these service accounts, follow these steps:

1. Determine the email address of the environment's service account (see above)
2. Find the service account by email in the "IAM & Admin / Service accounts" console. Under the "Actions" column, selct "Manage keys" from the three-dot pull down menu.
3. Create a new "JSON" key for the service account using the "Add key" dropdown. This will automatically download the file to your computer.
4. In a terminal, navigate to the downloaded key. Once there, base64 encode the file to your clipboard. See instructions above about doing this on the command line.
5. Set the appropriate FIREBASE_SERVICE_ACCOUNT_JSON_BASE64 secret in AWS's Parameter Store "/env/{env}/gateway/FIREBASE_SERVICE_ACCOUNT_JSON_BASE64. Be sure to save the new parameter. Note that the new key will not be used until the next full deployment of the gateway's ECS service. Either using the ECS console or triggering a new deploy from github.
6. Back on the command line, shred <downloaded-key-file> and rm <downloaded-key-file>
7. Force a new deployment in the ECS console to pick up the new service account key.
8. Once confirmed the key is up and working, delete the old key.

Warning

Do not delete the old key, if any, until the service is restarted and confirmed working. Once a container is running, it will continue to use the same service account key until it is restarted or redeployed.

Setting Apple Push Notification Service (APNs) Variables

To (re)configure keys for the Apple Push Notification Service (APNs):

1. In the developer account portal, select "Keys" under the "Certificates, IDs & Profiles" section. It should bring you here
2. Click the + button next to the Keys table header. This should take you to a "Register a New Key" form. Fill it in as follows: - Key Name: <appname> App Gateway <env> <date: YYYYMMdd> -- note no special characters permitted, use spaces - Key Usage Description: APNS Key in the <env> App Gateway - Check the 'Enable' box next to "Apple Push Notifications service (APNs)
   • Click the conifgure button, select "Production" if this is the prod environment's key and "Sandbox" for all others
   • Key Restriction should be "Team Scoped (All Topics)"
   • Save - Click "Continue" button - Click "Register" button
3. Download the key
4. In a terminal, navigate to the downloaded key. Once there, base64 encode the file to your clipboard. See instructions above about doing this on the command line.
5. Set the appropriate APNS_KEY_ID secret in AWS's Parameter Store "/env/{env}/gateway/APNS_KEY_ID. This is not a secret, but it is useful to have it co-located in the secrets with the corresponding encoded keys as they must change together. Note that APNS_TEAM_ID is unchanging and set in the LAMP-infra configuration of the environment.
6. Set the appropriate APNS_KEY_FILE_BASE64 secret in AWS's Parameter Store "/env/{env}/gateway/APNS_KEY_FILE_BASE64. Be sure to save the new parameter.
7. Back on the command line, shred <downloaded-key-file> and rm <downloaded-key-file>
8. Force a new deployment in the ECS console to pick up the new service account key.
9. Once confirmed the key is up and working, delete the old key.

Note that the new key and key id will not be used until the next full deployment of the gateway's ECS service. Either using the ECS console or triggering a new deploy from github.