Document database access control (#495)

docs/infra/database-access-control.md

@@ -0,0 +1,24 @@
+# Database Access Control
+
+## Manage `postgres` master user password with AWS Secrets Manager
+
+The master user password is managed by Amazon RDS and Secrets Manager. Managing RDS master user passwords with Secrets Manager provides the following security benefits:
+
+* RDS rotates database credentials regularly, without requiring application changes.
+* Secrets Manager secures database credentials from human access and plain text view. The master password is not even in the terraform state file.
+
+For more information about the benefits, see [Benefits of managing master user passwords with Secrets Manager](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/rds-secrets-manager.html#rds-secrets-manager-benefits).
+
+## Database roles and permissions
+
+The database roles are created by the master user `postgres` when the Role Manager lambda function runs. The following roles are created:
+
+* **migrator** — The `migrator` role is the role the database migration task assumes. Database migrations are run as part of the deploy workflow before the new container image is deployed to the service. The `migrator` role has permissions to create tables in the `app` schema.
+* **app** — The `app` role is the role the application service assumes. The `app` role has read/write permissions in the `app` schema.
+
+## Database connections
+
+The database authenticates connections with [IAM database authentication](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.html) (except when connecting as the `postgres` master user). The security benefits of this approach include:
+
+* The system leverages IAM to centrally manage access to the database
+* There are no long lived user database credentials that need to be stored as database authentication tokens are generated by IAM and have a lifetime of 15 minutes