docs: add self signed certs guide by GavinFrazar · Pull Request #16182 · gravitational/teleport

GavinFrazar · 2022-09-06T21:40:03Z

This PR adds a guide for using self-signed certs with Teleport. It includes a prominent warning about why you should never use self-signed certs in production, and info about how to use teleport, tctl, and tsh with a proxy that uses self-signed certs.

For using teleport I included info about passing --insecure for helm and for systemd daemon.

The PR also consolidates copies of the same snippet regarding TLS certificate setup into a single include file:
tls-certificate-setup.mdx

GavinFrazar · 2022-09-06T21:44:04Z

I also moved the info on how to setup certs into an include file and included that in the self-signed certs guide

Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>

… want it

certs -> certificates proxy -> Proxy Service

ryanclark · 2022-10-04T08:26:22Z

+- The Teleport config file `auth_servers` setting is set to the Proxy Service endpoint:
+  - `auth_servers: ["tele.example.com:443"]` or
+  - `auth_servers: ["tele.example.com:3080"]`


We recently added config v3 which has either auth_server or proxy_server (#15761)

teleport/docs/pages/reference/config.mdx

Lines 142 to 158 in bd0ae38

# Only use one of auth_server or proxy_server.

#

# When you have either the application service or database service enabled,

# only tunneling through the proxy is supported, so you should specify proxy_server.

# All other services support both tunneling through the proxy and directly connecting

# to the auth server, so you can specify either auth_server or proxy_server.

# Auth Server address and port to connect to. If you enable the Teleport

# Auth Server to run in High Availability configuration, the address should

# point to a Load Balancer.

# If adding a node located behind NAT, specify `proxy_servers` instead

auth_server: 10.1.0.5:3025

# Proxy Server address and port to connect to. If you enable the Teleport

# Proxy Server to run in High Availability configuration, the address should

# point to a Load Balancer.

proxy_server: teleport-proxy.example.com:443

Can you update this to match please?

Note, we didn't backport this, so when backporting for v10 you should still mention auth_servers.

Sure. On that note, are we planning to update the teleport start cli to have separate --proxy-server and --auth-server?

alexfornuto · 2022-10-04T15:52:19Z

I disabled auto-merge and reassigned back to @GavinFrazar to address the latest review.

ryanclark · 2022-10-05T16:53:26Z

@GavinFrazar did you mean to assign this PR to me?

GavinFrazar · 2022-10-05T22:24:50Z

@GavinFrazar did you mean to assign this PR to me?

I reassigned after addressing your feedback, since I've seen that a few times in other PRs I thought maybe it was just the norm lol.

GavinFrazar · 2022-10-11T02:13:14Z

@ryanclark just waiting on your approval, was there something else you wanted addressed still?

github-actions · 2022-10-11T18:03:36Z

@GavinFrazar See the table below for backport results.

Branch	Result
branch/v11	Failed

* Add slug for self signed certs * Add self-signed certs guide * Move tls cert setup into an include snippet * Update tsh section on self signed certs * Fix indentation * Remove extra slash before heading * Update docs/config.json Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com> * Update docs/pages/management/admin.mdx Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com> * Update docs/pages/includes/tls-certificate-setup.mdx Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com> * Update docs/pages/management/admin/self-signed-certs.mdx Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com> * Update docs/pages/management/admin/self-signed-certs.mdx Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com> * Update docs/pages/management/admin/self-signed-certs.mdx Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com> * Update docs/pages/management/admin/self-signed-certs.mdx Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com> * Fix formatting of github suggestion commit * Change link title to avoid abbreviation * Update intro to explain the purpose of the guide and why anyone would want it * Make 'proxy' and 'certs' consistent throughout the guide: certs -> certificates proxy -> Proxy Service * Move motivation for guide out of warning and into intro * Simplify the warning notice * Change headings * Capitalize helm and simplify label * Update Helm info to include inline instructions * Simplify systemd label * Update systemd tab * Update slug certs -> certificates * Fix include snippet yaml example * Change prereqs to omit cloud tab and instruct user to check for self-signed certs config * Update docs/pages/management/admin/self-signed-certs.mdx Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com> * Update docs/pages/management/admin/self-signed-certs.mdx Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com> * Update docs/pages/management/admin/self-signed-certs.mdx Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com> * Apply suggestions from code review Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com> * Update docs/pages/management/admin/self-signed-certs.mdx Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com> * Get specific about problem caused by insecure TLS * Remove 'how to setup tls certs' section in favor of a link at the bottom * Add examples for tsh and tctl, and clean up tctl wording * Remove link to systemd guide * Add more detail to systemd instructions * Change wording around instructions for teleport * Rearrange links * Remove reference to deleted acme.mdx * Remove v2 config reference to auth_servers * Remove list syntax for proxy_server Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>

* docs: add self signed certs guide (#16182) * Add slug for self signed certs * Add self-signed certs guide * Move tls cert setup into an include snippet * Update tsh section on self signed certs * Fix indentation * Remove extra slash before heading * Update docs/config.json Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com> * Update docs/pages/management/admin.mdx Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com> * Update docs/pages/includes/tls-certificate-setup.mdx Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com> * Update docs/pages/management/admin/self-signed-certs.mdx Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com> * Update docs/pages/management/admin/self-signed-certs.mdx Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com> * Update docs/pages/management/admin/self-signed-certs.mdx Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com> * Update docs/pages/management/admin/self-signed-certs.mdx Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com> * Fix formatting of github suggestion commit * Change link title to avoid abbreviation * Update intro to explain the purpose of the guide and why anyone would want it * Make 'proxy' and 'certs' consistent throughout the guide: certs -> certificates proxy -> Proxy Service * Move motivation for guide out of warning and into intro * Simplify the warning notice * Change headings * Capitalize helm and simplify label * Update Helm info to include inline instructions * Simplify systemd label * Update systemd tab * Update slug certs -> certificates * Fix include snippet yaml example * Change prereqs to omit cloud tab and instruct user to check for self-signed certs config * Update docs/pages/management/admin/self-signed-certs.mdx Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com> * Update docs/pages/management/admin/self-signed-certs.mdx Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com> * Update docs/pages/management/admin/self-signed-certs.mdx Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com> * Apply suggestions from code review Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com> * Update docs/pages/management/admin/self-signed-certs.mdx Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com> * Get specific about problem caused by insecure TLS * Remove 'how to setup tls certs' section in favor of a link at the bottom * Add examples for tsh and tctl, and clean up tctl wording * Remove link to systemd guide * Add more detail to systemd instructions * Change wording around instructions for teleport * Rearrange links * Remove reference to deleted acme.mdx * Remove v2 config reference to auth_servers * Remove list syntax for proxy_server Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com> * Delete orphaned include Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>

GavinFrazar added 4 commits September 6, 2022 14:28

Add slug for self signed certs

912b454

Add self-signed certs guide

3d62efd

Move tls cert setup into an include snippet

524084f

Update tsh section on self signed certs

ead4b5f

GavinFrazar requested a review from ptgott September 6, 2022 21:40

GavinFrazar marked this pull request as ready for review September 6, 2022 21:40

GavinFrazar added the backport/branch/v10 label Sep 6, 2022

github-actions Bot requested review from alexfornuto, r0mant, sagesyr, xinding33 and zmb3 September 6, 2022 21:40

github-actions Bot added the documentation label Sep 6, 2022

GavinFrazar added 2 commits September 6, 2022 14:50

Fix indentation

a98850b

Remove extra slash before heading

bf66bb0

ptgott reviewed Sep 13, 2022

View reviewed changes

GavinFrazar and others added 13 commits September 13, 2022 13:18

Update docs/config.json

a592df7

Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>

Update docs/pages/management/admin.mdx

607d0c7

Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>

Update docs/pages/includes/tls-certificate-setup.mdx

cf9728e

Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>

Update docs/pages/management/admin/self-signed-certs.mdx

02ff3c8

Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>

Update docs/pages/management/admin/self-signed-certs.mdx

dd25237

Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>

Update docs/pages/management/admin/self-signed-certs.mdx

c78c5ad

Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>

Update docs/pages/management/admin/self-signed-certs.mdx

ce075f7

Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>

Fix formatting of github suggestion commit

4f30d02

Change link title to avoid abbreviation

c1194d4

Update intro to explain the purpose of the guide and why anyone would…

3385e9f

… want it

Make 'proxy' and 'certs' consistent throughout the guide:

166edd0

certs -> certificates proxy -> Proxy Service

Move motivation for guide out of warning and into intro

ad9f8dd

Simplify the warning notice

85a2a65

ryanclark reviewed Oct 4, 2022

View reviewed changes

alexfornuto disabled auto-merge October 4, 2022 15:11

alexfornuto assigned GavinFrazar and unassigned ptgott Oct 4, 2022

GavinFrazar assigned ryanclark and unassigned GavinFrazar Oct 4, 2022

GavinFrazar added 2 commits October 4, 2022 16:29

Remove v2 config reference to auth_servers

3730890

Merge branch 'master' into gavinfrazar/self_signed_certs

bfc1d12

ryanclark reviewed Oct 5, 2022

View reviewed changes

Comment thread docs/pages/management/admin/self-signed-certs.mdx Outdated

Remove list syntax for proxy_server

7ab4e7b

GavinFrazar added the backport/branch/v11 label Oct 11, 2022

ryanclark approved these changes Oct 11, 2022

View reviewed changes

github-actions Bot removed request for alexfornuto, r0mant, sagesyr, xinding33 and zmb3 October 11, 2022 09:18

GavinFrazar removed the backport/branch/v10 label Oct 11, 2022

Merge branch 'master' into gavinfrazar/self_signed_certs

78c4f75

GavinFrazar enabled auto-merge (squash) October 11, 2022 17:53

GavinFrazar merged commit 1c3c06e into master Oct 11, 2022

GavinFrazar deleted the gavinfrazar/self_signed_certs branch October 11, 2022 18:19

GavinFrazar mentioned this pull request Oct 11, 2022

[v11] Add self signed certs guide #17299

Merged

	# Only use one of auth_server or proxy_server.
	#
	# When you have either the application service or database service enabled,
	# only tunneling through the proxy is supported, so you should specify proxy_server.
	# All other services support both tunneling through the proxy and directly connecting
	# to the auth server, so you can specify either auth_server or proxy_server.

	# Auth Server address and port to connect to. If you enable the Teleport
	# Auth Server to run in High Availability configuration, the address should
	# point to a Load Balancer.
	# If adding a node located behind NAT, specify `proxy_servers` instead
	auth_server: 10.1.0.5:3025

	# Proxy Server address and port to connect to. If you enable the Teleport
	# Proxy Server to run in High Availability configuration, the address should
	# point to a Load Balancer.
	proxy_server: teleport-proxy.example.com:443

Conversation

GavinFrazar commented Sep 6, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

GavinFrazar commented Sep 6, 2022

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ryanclark Oct 4, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

GavinFrazar Oct 4, 2022

Choose a reason for hiding this comment

Uh oh!

ryanclark Oct 5, 2022

Choose a reason for hiding this comment

Uh oh!

alexfornuto commented Oct 4, 2022

Uh oh!

Uh oh!

ryanclark commented Oct 5, 2022

Uh oh!

GavinFrazar commented Oct 5, 2022

Uh oh!

GavinFrazar commented Oct 11, 2022

Uh oh!

github-actions Bot commented Oct 11, 2022

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

GavinFrazar commented Sep 6, 2022 •

edited

Loading

ryanclark Oct 4, 2022 •

edited

Loading