We offer cities the ability to host their OpenCounter via a CNAME, which is essentially a customized URL, usually at subdomain of the City's website. For example, Boston's site can be found at https://permits.boston.gov, and Orlando's is at https://business.cityoforlando.net.
Using a CNAME gives applicants the understanding that OpenCounter is an official service offered by, validated, and supported by the City. Cities can choose CNAMEs for 3 sites:
Landing Page / Table of Contents (e.g. business.slcgov.com)
Zoning Portal (e.g. zoning.slcgov.com)
Business Portal (e.g. permits.slcgov.com)
In order to ensure the security of your applicants' information, CNAME URLs must support HTTPS access.
If you'd like to offer the site under a CNAME, the following steps are taken:
1. The City provides OpenCounter with the list of CNAME subdomains they would like to configure, and which portals each subdomain points to.
- permits.cityname.gov -> Business Portal
- zoning.cityname.gov -> Zoning Portal
- zoning.city-other-site.com -> Zoning Portal
- opencounter.cityname.gov -> Table of Contents (Index of all available portals)
2. OpenCounter provides the City with a Certificate Signing Request (CSR) for each subdomain. These are needed in the next step.
3. City purchases an SSL certificate for each of the desired subdomains (e.g. https://permits.cityname.gov) and sends us the certificate file(s) by uploading them to Basecamp.
- If you have an existing wildcard certificate for your City's website, we recommend generating the SSL certificate(s) as a SAN (Subject Alternative Name) certificate.
- Otherwise, we recommend using a single subdomain certificate for each subdomain. (If you use an existing wildcard certificate without SAN, you will need to provide sensitive security information as we upload the wildcard certificate to our hosting provider.)
- The basic level certificate provides sufficient security for OpenCounter. We recommend using an EV (Extended Validation) certificate, but while domain and organizational validations are nice, they are not necessary.
- In the process of purchasing a certificate, you may be asked to select a webserver to create the certificate for. If this occurs, select Nginx (Heroku), or, if Nginx is not an option, select Apache 2.x.
- If you are given an option of what certificate format to use, select X.509.
4. OpenCounter installs the City's SSL certificate on the hosting platform.
5. OpenCounter sends City the SSL URL generated by the hosting platform.
6. City creates a CNAME record (on their Domain Name System (DNS)) for the desired subdomain (e.g. permits.cityname.gov) and points the CNAME record to the provided URL.
- Ensure that you add the CNAME record to both your external/public-facing DNS, as well as your internal DNS (i.e. the City network).
7. OpenCounter adds the City's subdomain URL to the list of supported domains.
8. OpenCounter adds the City's subdomain URL to backend configuration.
After setup, if you cannot access the CNAME domain on a computer or phone connected to the City's network / internet, but you can connect from home or from a phone using a cellular connection (WiFi turned off), that means the DNS record has not been added to the internal DNS. To fix this, ensure that the DNS record is added to the City's internal DNS system.
CNAME vs Redirect / URL Forwarding
Redirects and URL forwarding send a user who types in a web address to a web address at a different domain. CNAME records keep the URL consistent. Using a CNAME gives applicants the impression that OpenCounter is an official service offered by and supported by the City.
Additionally, CNAME records work at the DNS level, whereas redirects only work if the user is on a web browser. If OpenCounter begins offering public APIs, we will be able serve those APIs through your CNAME, but would not be able to do so with a redirect.
Let's take the example of Anchorage, Alaska.
The user clicks on a link to startup.muni.org, or types it in and presses enter. In the browser, they notice the URL has changed to anchorage.opencounter.com. This can cause some confusion, and the user might wonder why the link they clicked isn't the same as the page they're on. This can reduce confidence, and make the user feel like a third party is interfering with a continuous experience offered by the Municipality of Anchorage.
The user clicks on a link to startup.muni.org, or types it in and presses enter. They notice no change in the domain, as it remains startup.muni.org. This implies that this is an official service of the Municipality.