Repository navigation
[CLO-538] Add access control docs and rewrite MFA guide for WorkOS - #972
Conversation
Add a new Access Control section covering members, groups, policies, single sign-on (SAML/OIDC), and service accounts. Rewrite the MFA setup guide to match the new WorkOS-based flow and refresh the screenshots. Point the introduction at the new section and reorder the cloud sidebar to fit it in.
Docs build
|
PR Summary by QodoAdd Access Control docs and update WorkOS MFA guide
AI Description
Diagram
High-Level Assessment
Files changed (21)
|
Docs build
|
Code Review by Qodo🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0)
Great, no issues found!Qodo reviewed your code and found no material issues that require reviewTo customize comments, go to the Qodo configuration screen, or learn more in the docs. |
Deploying documentation with
|
| Latest commit: |
653546e
|
| Status: | ⚡️ Build in progress... |
stktung
left a comment
stktung
left a comment
There was a problem hiding this comment.
Review of the new access control docs and the WorkOS MFA rewrite. The structure and
writing read well, and the sidebar ordering is coherent (introduction 1 → getting-started 2
→ access-control 3 → ops 4 → tutorials 5 → networking 6 → automation 7 → integrations 8 →
guides 9, no collisions). I also checked that none of the eight deleted enable-mfa-*.png
images are still referenced anywhere — they are not.
Two inline findings below, plus one stale line just outside the diff that I have raised as a
separate general comment. The Terraform/Pulumi one needs a product answer before we pick the
right fix.
| ### Access control | ||
|
|
||
| Each organization has its own access control, which includes the list of users who have access to the organization, groups, roles, policies, and identity providers. | ||
| Each organization has its own access control, covering the members who can access the organization, the groups, roles, and policies that govern what they can do, single sign-on through your own identity provider, and service accounts for automation. |
There was a problem hiding this comment.
This sentence mentions roles, but the new Access Control section doesn't document a role concept — the pages cover members/invitations, groups, policies, SSO, and service accounts, and there's no roles page or Roles UI described anywhere in docs/cloud/access-control/. As written it sends readers looking for something the docs never explain.
Suggest dropping the term:
| Each organization has its own access control, covering the members who can access the organization, the groups, roles, and policies that govern what they can do, single sign-on through your own identity provider, and service accounts for automation. | |
| Each organization has its own access control, covering the members who can access the organization, the groups and policies that govern what they can do, single sign-on through your own identity provider, and service accounts for automation. |
If roles are still a real part of the product, then the opposite fix applies — the new section needs a roles page to link to.
| Service accounts are the recommended identity for infrastructure automation. | ||
| Configure the [Terraform](../automation/terraform.md) or | ||
| [Pulumi](../automation/pulumi.md) provider with a service account's credentials | ||
| so that plans and applies run under an identity that is not tied to a single | ||
| person. See the [Automations](../automation/README.md) section for provider | ||
| setup. |
There was a problem hiding this comment.
This recommends configuring the Terraform and Pulumi providers with service account credentials, but neither provider's setup docs support that path today:
docs/cloud/automation/terraform.md:64— "The Kurrent Cloud provider must be configured with an access token."docs/cloud/automation/pulumi.md:36—eventstorecloud:tokenis "a valid refresh token for an Kurrent Cloud account with admin access".
Neither mentions a client ID/secret. So a reader who follows this section lands on provider setup that only documents user tokens.
Question before we pick a fix: do the providers already accept service account credentials (client credentials grant)? If they do, the provider docs are the stale ones and should be updated instead of this page. If they don't, I'd narrow the claim here so we're not promising something unsupported:
| Service accounts are the recommended identity for infrastructure automation. | |
| Configure the [Terraform](../automation/terraform.md) or | |
| [Pulumi](../automation/pulumi.md) provider with a service account's credentials | |
| so that plans and applies run under an identity that is not tied to a single | |
| person. See the [Automations](../automation/README.md) section for provider | |
| setup. | |
| Service accounts are well suited to infrastructure automation, where plans and | |
| applies should run under an identity that is not tied to a single person. Note | |
| that the [Terraform](../automation/terraform.md) and | |
| [Pulumi](../automation/pulumi.md) providers are currently configured with a | |
| token rather than with service account credentials — see the | |
| [Automations](../automation/README.md) section for each provider's setup. |
|
One stale line just outside this PR's diff, in the same section the access-control rewrite touches —
Same dead "roles" concept as line 62, six lines above it. It pre-dates this PR, but since the PR is what establishes the new members/groups/policies terminology, it'd be odd to leave the old wording sitting directly above the rewritten paragraph. Suggested wording:
(Posting this as a general comment rather than inline because the line isn't part of the diff, so GitHub won't anchor a review comment to it.) |
…th for Terraform - introduction.md: replace "users and roles" with members/groups wording; drop "roles" from the access control overview since the docs don't document a role concept - service-accounts.md: state provider support accurately — Terraform supports service account credentials from v3.1.0, Pulumi is still token-configured - terraform.md: document client_id/client_secret (ESC_CLIENT_ID / ESC_CLIENT_SECRET) provider options and add a section on authenticating as a service account
Add a new Access Control section covering members, groups, policies, single sign-on (SAML/OIDC), and service accounts. Rewrite the MFA setup guide to match the new WorkOS-based flow and refresh the screenshots. Point the introduction at the new section and reorder the cloud sidebar to fit it in.