Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Improve access graph documentation #49314

Merged
merged 4 commits into from
Nov 25, 2024
Merged

Improve access graph documentation #49314

merged 4 commits into from
Nov 25, 2024

Conversation

tigrato
Copy link
Contributor

@tigrato tigrato commented Nov 21, 2024 •
edited
Loading

This PR introduces a recommendation for users to enable Okta/Entra synchronization to improve the user experience when working with Crown Jewels. Ephemeral, highly privileged users created by the SSO connector can generate excessive activity, making Crown Jewels difficult to use.

Additionally, the PR includes examples of the new ssh_keys view when utilizing the Policy SSH Keys scan functionality.

@tigrato
Improve access graph documentation
a07bd29 
This PR introduces a recommendation for users to enable Okta/Entra synchronization to improve the user experience when working with Crown Jewels. Ephemeral, highly privileged users created by the SSO connector can generate excessive activity, rendering Crown Jewels difficult to use.

Additionally, the PR includes examples of the new `ssh_keys` view when utilizing the Policy SSH Keys scan functionality.

Signed-off-by: Tiago Silva <[email protected]>
@tigrato tigrato added the no-changelog Indicates that a PR does not require a changelog entry label Nov 21, 2024
@github-actions GitHub Actions
Copy link

🤖 Vercel preview here: https://docs-2xfrsnuzd-goteleport.vercel.app/docs

@tigrato tigrato force-pushed the tigrato/improve-access-graph-docs branch from 2f6f622 to a07bd29 Compare November 21, 2024 14:28
@github-actions GitHub Actions
Copy link

🤖 Vercel preview here: https://docs-210e8pqxs-goteleport.vercel.app/docs

ptgott
ptgott reviewed Nov 21, 2024
View reviewed changes
docs/pages/admin-guides/teleport-policy/crown-jewels.mdx Outdated

For an improved experience, we recommend using Crown Jewels in conjunction with Teleport local users or integrating with
[Okta](../../enroll-resources/application-access/okta/okta.mdx) or [Microsoft Entra ID](./integrations/entra-id.mdx).
This setup helps mitigate the spam generated by highly privileged ephemeral users created by Teleport Auth Connectors.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What does "spam" mean in this case? To me, this sounds a little judgmental towards a Teleport feature, which seems out of place in documentation.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Spam refers to an excessive number of entries. When a user with access to all resources logs in using a standard connector, it generates N access path changes, where N is the number of resources they have access to.

docs/pages/admin-guides/teleport-policy/integrations/ssh-keys-scan.mdx Outdated
@@ -152,6 +152,30 @@ Insecure paths are also visible in a user's access paths. To view them, click on
from the context menu. This will show the Teleport permissions granted to the user, the resources they can access,
and any detected insecure paths.

**Access Graph: Dedicated `ssh_keys` SQL View**
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If this is a section heading, I would use header syntax (#+) instead of bold text.

docs/pages/admin-guides/teleport-policy/integrations/ssh-keys-scan.mdx Outdated Show resolved Hide resolved
@tigrato tigrato requested a review from ptgott November 21, 2024 22:13
ptgott
ptgott approved these changes Nov 21, 2024
View reviewed changes
docs/pages/admin-guides/teleport-policy/crown-jewels.mdx Outdated
@@ -16,7 +16,8 @@ Crown Jewels, and how to see permission changes for these resources.

For an improved experience, we recommend using Crown Jewels in conjunction with Teleport local users or integrating with
[Okta](../../enroll-resources/application-access/okta/okta.mdx) or [Microsoft Entra ID](./integrations/entra-id.mdx).
This setup helps mitigate the spam generated by highly privileged ephemeral users created by Teleport Auth Connectors.
This setup helps minimize the number of access path change entries generated when highly privileged ephemeral users
log in via Teleport Auth Connectors..
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
log in via Teleport Auth Connectors..
log in via Teleport authentication connectors.

To use the convention we use elsewhere in the docs

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are we being overly pedantic here?

The product literally calls them Auth Connectors:

image

docs/pages/admin-guides/teleport-policy/integrations/ssh-keys-scan.mdx Outdated Show resolved Hide resolved
@github-actions GitHub Actions
Copy link

🤖 Vercel preview here: https://docs-5pq78tfjb-goteleport.vercel.app/docs

@github-actions GitHub Actions
Copy link

🤖 Vercel preview here: https://docs-d7ml5j91w-goteleport.vercel.app/docs

@github-actions GitHub Actions
Copy link

🤖 Vercel preview here: https://docs-bzany97mu-goteleport.vercel.app/docs

r0mant
r0mant approved these changes Nov 22, 2024
View reviewed changes
docs/pages/admin-guides/teleport-policy/crown-jewels.mdx
Comment on lines +19 to +20
This setup helps minimize the number of access path change entries generated when highly privileged ephemeral users
log in via Teleport Auth Connectors.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
This setup helps minimize the number of access path change entries generated when highly privileged ephemeral users
log in via Teleport Auth Connectors.
This setup helps minimize the number of access path change entries generated when ephemeral SSO users
marked as Crown Jewels log in via Teleport Auth Connectors.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

They don't need to be Crown Jewels. Actually the issue is much worse if the resources are Crown Jewels because it generates one event per resource they have access to

@tigrato tigrato force-pushed the tigrato/improve-access-graph-docs branch from 0b96bdf to 9a6a869 Compare November 25, 2024 09:33
@tigrato tigrato force-pushed the tigrato/improve-access-graph-docs branch from 9a6a869 to 5535e59 Compare November 25, 2024 09:43
@github-actions GitHub Actions
Copy link

🤖 Vercel preview here: https://docs-3icfcfail-goteleport.vercel.app/docs

@tigrato tigrato added this pull request to the merge queue Nov 25, 2024
@github-actions GitHub Actions
Copy link

🤖 Vercel preview here: https://docs-4hqg9ez3l-goteleport.vercel.app/docs

Merged via the queue into master with commit 4102fa5 Nov 25, 2024
41 checks passed
@tigrato tigrato deleted the tigrato/improve-access-graph-docs branch November 25, 2024 10:04
@public-teleport-github-review-bot
Copy link

@tigrato See the table below for backport results.

Branch Result
branch/v15 Failed
branch/v16 Create PR
branch/v17 Create PR

This was referenced Nov 25, 2024
Merged
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@ptgott ptgott ptgott approved these changes

@r0mant r0mant r0mant approved these changes

@zmb3 zmb3 Awaiting requested review from zmb3

Assignees
No one assigned
Labels
backport/branch/v15 backport/branch/v16 backport/branch/v17 documentation no-changelog Indicates that a PR does not require a changelog entry size/sm
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
4 participants
@tigrato @r0mant @zmb3 @ptgott