Custom Domain Service Broker

A Cloud Foundry service broker that provides a custom domain service. Traffic is encrypted using an SSL certificate generated by Let's Encrypt.

For the CDN version of this broker: https://github.com/18F/cf-cdn-service-broker

Let's Encrypt V1 End of Life

The Let's Encrypt V1 endpoint is reaching end of life in June of 2020. In November of 2019, Let's Encrypt shutdown the creation of new users via the V1 API. https://community.letsencrypt.org/t/end-of-life-plan-for-acmev1/88430

In response to disabling new user creation, this broker has been changed to use an existing user's credentials. This is implemented in LoadRandomUser in models/models.go. The pool of user ids to select from is configured via an environment variable USER_ID_POOL. This environment variable is injected via bosh from credhub. The envar is configured in bosh/manifest.yml and the value is set in credhub as /bosh/domain-broker/user-id-pool. These values should be set as a comma separated list in double quotes.

LoadRandomUser will select a user from the pool, use the Let's Encrypt reg and key and create a new user entry in the broker database. Effectively, the user is the same in the eyes of Let's Encrypt but a different user in the broker database. This maintains the one user to one domain relationship in the broker database.

The random selection of users from a pool aims to minimize the impact of the following rate limits:

• • 300 Pending Authorizations per account
• • Failed Validation limit of 5 failures per account, per hostname, per hour.

Deployment

Automated

The easiest/recommended way to deploy the broker is via the Concourse pipeline.

1. Create a ci/credentials.yml file, and fill in the templated values from the pipeline.

2. Deploy the pipeline.

   fly -t lite set-pipeline -n -c ci/pipeline.yml -p deploy-domains-broker -l ci/credentials.yml

Updating ALBs

On startup, the broker automatically detects ALBs based on their name. To pick up changes, simply restart the broker.

Usage

1. Target the space your application is running in.

   $ cf target -o <org> -s <space>

2. Add your domain to your Cloud Foundry organization:

   $ cf create-domain <org> my.domain.gov
   ```
   

3. Create a service instance.

   $ cf create-service custom-domain custom-domain my-domain -c '{"domains": ["my.domain.gov"]}'
   
   Create in progress. Use 'cf services' or 'cf service my-domain' to check operation status.

   If you have more than one domain you can pass them as a list to the domains parameter, just keep in mind that the broker will wait until all domains are CNAME'd:

   $ cf create-service cdn-route cdn-route my-cdn-route -c '{"domains": ["my.domain.gov","www.my.domain.gov"]}'
   
   Create in progress. Use 'cf services' or 'cf service my-domain' to check operation status.

4. Get the DNS instructions. (note that the target of the CNAME will probably be different for you)

   $ cf service my-domain
   
   Last Operation
   Status: create in progress
   Message: Provisioning in progress; CNAME domain "my.domain.gov" to "production-domains-0-792003535.us-gov-west-1.elb.amazonaws.com"

5. Create/update your DNS configuration.

6. Wait up to 30 minutes for the CloudFront distribution to be provisioned and the DNS changes to propagate.

7. Visit my.domain.gov, and see that you have a valid certificate (i.e. that visiting your site in a modern browser doesn't give you a certificate warning).

8. Add your domain to a Cloud Foundry application:

   $ cf map-route <app> my.domain.gov

Debugging

By default, Cloud Controller will expire asynchronous service instances that have been pending for over one week. If your instance expires, run a dummy update to restore it to the pending state so that Cloud Controller will continue to check for updates:

cf update-service my-domain -c '{"timestamp": 20161001}'

Tests

go test -v $(go list ./... | grep -v /vendor/)

Contributing

See CONTRIBUTING for additional information.

Public domain

This project is in the worldwide public domain. As stated in CONTRIBUTING:

This project is in the public domain within the United States, and copyright and related rights in the work worldwide are waived through the CC0 1.0 Universal public domain dedication.

All contributions to this project will be released under the CC0 dedication. By submitting a pull request, you are agreeing to comply with this waiver of copyright interest.