docs: add note about user CA rotation + desktop access #10126

zmb3 · 2022-02-03T15:35:21Z

In the future we'll move desktop access to a separate CA, but for
now Windows certs are generated with the user CA, so Active Directory
will need to be updated to trust the new certificate when a rotation
takes place.

zmb3 · 2022-02-07T20:58:00Z

docs/pages/setup/operations/ca-rotation.mdx

+  CA pin when adding nodes after rotation.
+</Admonition>
+
+<Admonition type="warning" title="Desktop Access">


Is it poor form to have two Adminitions back to back like this?

I've suggested moving the CA pinning warning since we use it twice in the page.

ptgott · 2022-02-07T21:20:12Z

docs/pages/desktop-access/getting-started.mdx

-  Started](../getting-started.mdx) guide.
+<Admonition type="note" title="User CA Rotation.">
+These steps will need to be repeated if Teleport's user certificate
+authority is [rotated](../setup/operations/ca-rotation.mdx).


So we can keep the reader's focus on this guide, I think we should remove the link here and provide any additional info we need from this link within this sentence. We can link to the page on CA rotation in a "Next steps" or "Further reading" section if it helps.

ptgott · 2022-02-07T21:24:15Z

docs/pages/setup/operations/ca-rotation.mdx

-Take a look at the [Certificates chapter](../../architecture/authentication.mdx#authentication-in-teleport) in the
-architecture document to learn how the certificate authority rotation works.
+Take a look at the
+[Certificates chapter](../../architecture/authentication.mdx#authentication-in-teleport)


Is reading this guide required before carrying on, or is this additional context? If it's additional context, I think we should put this in a "Next steps" or "Further reading" section to keep the reader's focus on this guide. If it's a prerequisite, maybe we should put it in the "Prerequisites" section.

I don't know, to be honest. This is a very old page that predates my employment at Teleport. On first glance, I don't see a problem moving this to a "further reading" section.

I guess getting such a thorough review is what I get for wrapping lines that aren't related to the actual change I'm making 😅

ptgott · 2022-02-07T21:31:16Z

docs/pages/setup/operations/ca-rotation.mdx


 This section will show you how to implement certificate rotation in practice.

-During manual and semi-automatic certificate authority rotation, Teleport generates a new certificate
-authority and issues certificates for auth servers, proxies, nodes and users.
+During manual and semi-automatic certificate authority rotation, Teleport


So we know what "manual" and "semi-automatic" mean in this sentence before we get to the relevant sections, I think we should add something like,

There are two kinds of CA rotation: - **Manual:** this is the definition. - **Semi-automatic:** this is the definition.

We can put this sentence below that one.

ptgott · 2022-02-07T21:35:31Z

docs/pages/setup/operations/ca-rotation.mdx

- `update_servers` Servers will reload and would start serving
-TLS and SSH certificates signed by the new certificate authority, but will still accept certificates
-issued by old certificate authority.
+- `init` - All components are notified of the rotation. A new certificate


Suggested change

- `init` - All components are notified of the rotation. A new certificate

- `init` All components are notified of the rotation. A new certificate

For consistency

ptgott · 2022-02-07T21:35:44Z

docs/pages/setup/operations/ca-rotation.mdx

+  authority is issued, but not used. It is necessary for remote trusted clusters
+  to fetch the new certificate authority, otherwise the new clients will reject
+  it.
+- `update_clients` - internal clients certs are updated and reloaded. Servers


Suggested change

- `update_clients` - internal clients certs are updated and reloaded. Servers

- `update_clients` Internal clients certs are updated and reloaded. Servers

ptgott · 2022-02-07T21:51:00Z

docs/pages/setup/operations/ca-rotation.mdx

-During the grace period, certificates issued both by old and new certificate authority work.
+This will trigger a rotation process for both hosts and users with a *grace
+period* of 48 hours. During the grace period, certificates issued both by old
+and new certificate authority work.


Suggested change

and new certificate authority work.

If we accept my previous suggestion, we'll need to remove this line.

ptgott · 2022-02-07T21:58:25Z

docs/pages/setup/operations/ca-rotation.mdx

-  rotation and come back only after the grace period has ended, they will be
-  forced to leave the cluster, i.e. users will no longer be allowed to SSH
-  into them.
+  Be careful when choosing a grace period when rotating host certificates. The


Since this is a long admonition, what would you think of removing this text from the Admonition component and making it regular body text, then wrapping the sentence, "Be careful when choosing a grace period when rotating host certificates." in a Notice component with the same type and title?

ptgott · 2022-02-07T21:59:36Z

docs/pages/setup/operations/ca-rotation.mdx

-  If you are using [CA Pinning](../admin/adding-nodes.mdx#untrusted-auth-servers) when adding new nodes, the CA pin will change after the rotation. Make sure you use the
-  *new* CA pin when adding nodes after rotation.
+  If you are using
+  [CA Pinning](../admin/adding-nodes.mdx#untrusted-auth-servers) when adding new


Is there a place we can put this warning so we only need to include it once in the page?

ptgott · 2022-02-07T22:03:44Z

docs/pages/setup/operations/ca-rotation.mdx

+
+<Admonition type="warning" title="Desktop Access">
+Teleport signs Windows Desktop certificates with the user certificate authority.
+If the user CA is rotated, the new certificate will need to be


Rather than add the link on "exported", which could break the user's focus, I should we should add a "Read more about exporting the Teleport CA" link at the bottom of this admonition box.

I am definitely not the expert, so I defer to you on the final decision, but in this case I think the link makes sense.

As a reader, I'm thinking "you're telling me I have to do this export thing, but I have no idea what that means or how to do it. Why make me search for it?"

ptgott · 2022-02-07T22:04:09Z

docs/pages/setup/operations/ca-rotation.mdx

+  CA pin when adding nodes after rotation.
+</Admonition>
+
+<Admonition type="warning" title="Desktop Access">


I've suggested moving the CA pinning warning since we use it twice in the page.

zmb3 · 2022-02-08T15:24:39Z

@ptgott after thinking on this, many of your comments should be applied to the docs for all recent releases, but the note about desktop access + cert rotation only applies to v8 and up.

I will open a separate PR to address the comments that are not related to desktop access. Once we get that merged and backported to all appropriate branches, I'll update this PR so that it contains only the desktop access change.

Sound reasonable?

ptgott · 2022-02-08T22:57:15Z

@zmb3 It does!

zmb3 · 2022-02-16T23:45:12Z

@ptgott I've applied most of your suggestions here in PR #10419.

ptgott · 2022-02-17T20:05:46Z

@zmb3 Thanks! So my comments here don't overlap too much with my comments in #10419, would you mind removing any changes from this PR that conflict with the other PR?

zmb3 · 2022-03-28T20:01:03Z

@ptgott I finally got back to this. Should be a much simpler review now that the rest of your comments have already been addressed and merged. PTAL

ptgott

Approved with small comments

docs/pages/desktop-access/getting-started.mdx

ptgott · 2022-03-30T19:33:10Z

docs/pages/setup/operations/ca-rotation.mdx

+use the *new* CA pin when adding nodes after rotation.
+
+<Admonition type="warning" title="Desktop Access">
+Teleport signes Windows Desktop services with the user certificate authority.


Suggested change

Teleport signes Windows Desktop services with the user certificate authority.

Teleport signs Windows Desktop services with the user certificate authority.

Also, should this be "Windows Desktop Service instances" (or "Windows Desktop Service nodes" or "Windows Desktop Service agents")?

It should be "Teleport signs Windows Desktop certificates with the..."

certificates, not services. Good catch!

ptgott · 2022-03-30T19:35:51Z

docs/pages/setup/operations/ca-rotation.mdx

+<Admonition type="warning" title="Desktop Access">
+Teleport signes Windows Desktop services with the user certificate authority.
+If the user CA is rotated, the new CA certificate will need to be exported and
+configured in group policy.


Should there be an article/possessive adjective before "group policy"?

No, I don't think so. "Group Policy" is standard terminology in Windows land.

In the future we'll move desktop access to a separate CA, but for now Windows certs are generated with the user CA, so Active Directory will need to be updated to trust the new certificate when a rotation takes place.

zmb3 added documentation desktop-access backport-required labels Feb 3, 2022

github-actions bot requested review from klizhentas, ptgott, xinding33 and r0mant February 3, 2022 15:35

zmb3 commented Feb 7, 2022

View reviewed changes

ptgott reviewed Feb 7, 2022

View reviewed changes

zmb3 mentioned this pull request Feb 16, 2022

docs: update CA rotation page #10419

Merged

zmb3 force-pushed the zmb3/cert-rotation-note branch from 17cd116 to 63358c5 Compare March 28, 2022 20:00

ptgott approved these changes Mar 30, 2022

View reviewed changes

docs: add note about user CA rotation + desktop access

5fd3b0b

In the future we'll move desktop access to a separate CA, but for now Windows certs are generated with the user CA, so Active Directory will need to be updated to trust the new certificate when a rotation takes place.

zmb3 force-pushed the zmb3/cert-rotation-note branch from 63358c5 to 5fd3b0b Compare March 30, 2022 19:51

zmb3 enabled auto-merge (rebase) March 30, 2022 19:51

r0mant approved these changes Mar 30, 2022

View reviewed changes

zmb3 merged commit f7fc461 into master Mar 30, 2022

zmb3 deleted the zmb3/cert-rotation-note branch March 30, 2022 19:57

This was referenced Mar 30, 2022

[v9] Backport "docs: add note about user CA rotation + desktop access" (#10126) #11586

Merged

[v8] Backport "docs: add note about user CA rotation + desktop access" (#10126) #11587

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: add note about user CA rotation + desktop access #10126

docs: add note about user CA rotation + desktop access #10126

zmb3 commented Feb 3, 2022

zmb3 Feb 7, 2022

ptgott Feb 7, 2022

ptgott Feb 7, 2022

ptgott Feb 7, 2022

zmb3 Feb 8, 2022

ptgott Feb 7, 2022

ptgott Feb 7, 2022

ptgott Feb 7, 2022

ptgott Feb 7, 2022

ptgott Feb 7, 2022

ptgott Feb 7, 2022

ptgott Feb 7, 2022

zmb3 Feb 8, 2022

ptgott Feb 7, 2022

zmb3 commented Feb 8, 2022

ptgott commented Feb 8, 2022

zmb3 commented Feb 16, 2022

ptgott commented Feb 17, 2022

zmb3 commented Mar 28, 2022

ptgott left a comment

ptgott Mar 30, 2022

ptgott Mar 30, 2022

zmb3 Mar 30, 2022

ptgott Mar 30, 2022

zmb3 Mar 30, 2022

ptgott Mar 30, 2022

	- `init` - All components are notified of the rotation. A new certificate
	- `init` All components are notified of the rotation. A new certificate

	- `update_clients` - internal clients certs are updated and reloaded. Servers
	- `update_clients` Internal clients certs are updated and reloaded. Servers

	Teleport signes Windows Desktop services with the user certificate authority.
	Teleport signs Windows Desktop services with the user certificate authority.

docs: add note about user CA rotation + desktop access #10126

docs: add note about user CA rotation + desktop access #10126

Conversation

zmb3 commented Feb 3, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

zmb3 commented Feb 8, 2022

ptgott commented Feb 8, 2022

zmb3 commented Feb 16, 2022

ptgott commented Feb 17, 2022

zmb3 commented Mar 28, 2022

ptgott left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment