@@ -15,6 +15,9 @@ following reasons:
1515- The image doesn't come with any ca-certificates
1616- You're using an internal certificate authority
1717
18+ Coder workspaces may also fail to build if the TLS certificate used by Coder is
19+ not present in the image, or if there is some issue with the certificate.
20+
1821## Adding certificates for Coder
1922
2023To add certificates to your image and have them recognized by Coder:
@@ -38,3 +41,53 @@ within the workspace will use the certificates when making requests.
3841The specific process to add system-level certificates depends on the Linux
3942distribution that you're using, but it is typically done by adding your
4043certificates to your system's trusted CA repository.
44+
45+ ## TLS Certificate Requirements
46+
47+ Since the publication of RFC 2818 in 2000, the ` commonName ` field has been
48+ [ considered deprecated] ( https://groups.google.com/a/chromium.org/g/security-dev/c/IGT2fLJrAeo/m/csf_1Rh1AwAJ ) .
49+
50+ The Go programming language, which Coder uses, recently began enforcing this and
51+ ignoring the ` commonName ` field (source) in favor of the Subject Alternative
52+ Name (SAN) field.
53+
54+ This essentially means that SSL certificates are required to use
55+ ` Subject Alternative Name ` instead of ` commonName ` . If you attempt to use a
56+ certificate having ` commonName ` with Coder, you may see the following error:
57+
58+ ``` shell
59+ x509: certificate relies on legacy Common Name field, use SANs instead
60+ ```
61+
62+ Certificates may specify both fields for interoperability with existing software
63+ that requires the ` commonName ` field.
64+
65+ If you see this error when building a workspace or performing other operations
66+ with Coder workspaces, you may be running into the aforementioned issue. To verify
67+ that this is the case, you can inspect the certificate of your Coder deployment
68+ with the following command:
69+
70+ ``` shell
71+ openssl s_client -connect coder.domain.tld:443 < /dev/null 2> /dev/null \|
72+ sed -ne ' /-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' \|
73+ openssl x509 -text -noout \|
74+ grep -A1 ' Subject Alternative Name'
75+ ```
76+
77+ If your certificate has SANs specified, the expected output for the above command
78+ would be similar to the following:
79+
80+ ``` shell
81+ X509v3 Subject Alternative Name:
82+ DNS:* .coder.domain.tld, DNS:coder.domain.tld, DNS:domain.tld
83+ ```
84+
85+ Otherwise, a blank output is expected.
86+
87+ To fix the issue, a new TLS certificate is required that does not rely solely on
88+ the ` commmonName ` field. In the above example, this would equate to adding the
89+ following arguments to the ` openssl ` invocation to generate the certificate:
90+
91+ ``` shell
92+ -addext " subjectAltName = DNS:domain-name.com"
93+ ```
0 commit comments