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.

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

Consider reorganizing the 'Authorization Policy' page #1375

Open
kenjenkins opened this issue Apr 26, 2024 · 0 comments
Open

Consider reorganizing the 'Authorization Policy' page #1375

kenjenkins opened this issue Apr 26, 2024 · 0 comments

Comments

@kenjenkins
Copy link
Contributor

Page: https://www.pomerium.com/docs/capabilities/authorization

I think the overall structure of this page could be improved to enhance its clarity. Some suggestions:

  • Many of the sections describe Enterprise-only features. Would it make sense to group them together, and put the features common to both open source and Enterprise first? I think a single Enterprise callout would be more effective than four separate callouts mixed in throughout the page.

  • I don't understand how the first three sub-sections ("Namespaces", "Routes", and "Continuous verification") fit together.

    • Maybe we could move the part about continuous verification up to the top as part of the introduction?
    • The Namespaces and Routes sections are very brief, to the point that they may not be helpful. I think we should either flesh these out more, or perhaps remove them altogether.
  • The "Policy Overrides" section describes part of the Enterprise Console "Policy Builder" UI, so I think this should be combined with that section.

    • And we should probably remove "Pomerium Core" from the phrase "Pomerium Core and Enterprise offer the following options".
  • I believe Rego policy is intended as an Enterprise-only feature, so I think this should be grouped with the other Enterprise features (or if not, then the Enterprise callout should be moved up to the top of this section).

  • I like that we've added detailed information about the Rego policy inputs and outputs, but I wonder if it would be better to move this into its own page (e.g. Capabilities > Rego Policy — with the ENT tag). It might help to keep this page focused on the main concepts.

    • Also, the line "you can write policies in Rego with the PPL builder" does not make sense. As the nested callout states, "A policy can only support PPL or Rego. Once one is set, the other tab is disabled."
  • Finally, I think any discussion of Enterprise policies is incomplete without explaining the difference between "enforced" and "optional" policies:
    Screen Shot 2024-04-25 at 5 16 05 PM

    I still find these terms confusing, and I don't know that we clearly define them anywhere.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant