diff --git a/docs/adrs/0002-public-endpoints.md b/docs/adrs/0002-public-endpoints.md new file mode 100644 index 0000000..d6689f2 --- /dev/null +++ b/docs/adrs/0002-public-endpoints.md @@ -0,0 +1,35 @@ +# Public endpoints for callbacks and docs + +Date: 2023-09-14 + +## Status + +Accepted + +## Context + +To prevent misuse, access to the API has been restricted using Aptible IP filtering. This does not work +for callbacks from providers as the IPs may change for Twilio and Mailgun. Also, it is desirable +to have the API docs be publicly available without restriction. + +Callback endpoints are secured using signature verification with a shared secret from the provider. + +Note: CfA has purchased Twilio Security Edition that supports a static list of IPs from which callbacks originate. As we had already implemented +signature verification, we have not availed ourselves of this feature. We do not have a similar facility with Mailgun. + +## Decision + +We will listen on a separate port for callbacks and docs. This will not be secured with IP filtering. +The specific port can be chosen using the configuration variable `server.trustedPort`. The callbacks and docs will be +made available under the path `/public/`. + +| Port Use | Security | +|-|-| +| Messaging API | IP Filtering & BasicAuth shared password | +| Messaging Provider Callbacks & API Documentation | Public w/ Provider Signature varification | + + +## Consequences + +Aptible supports at most one default endpoint per app. Additional endpoints will need custom domains. +For our staging environment, we have created a custom domain named https://staging.messaging.cfa-platforms.org/ using the AWS Route 53 service.