Reorg and refine info across Authorization, Authentication docs; create 'User and Role Management' doc

[mikeCRL]

Mike Lewis (mikeCRL) commented:

Follow up from PR: Align, reorganize, update, and reframe CREATE USER, CREATE ROLE, and related content on users/roles #9913. Bringing in @knz feedback and recommendations.

the current structure of the doc around authorization mistakenly conflate managing the set of users and roles, which is primarily an authentication matter, and managing privileges and role membership, which is the true authorization matter.

Additionally the page on user/role management (and authentication) should introduce and define the term "authentication principal", which is used in Enterprise deployments and which we will increasingly use in later versions of CockroachDB.

---

v20.2/authorization.md #9913 (comment)

Be consistent that:

• creating and removing users and roles are related to authentication, not authorization
• the term "access policy" is related to both authentication and authorization, so it's confusing to see it here
  (Note: Already removed)

What is related to authorization is the mapping of roles to SQL privileges, and the use of role membership to group users that share privileges.

The term "RBAC" was originally introduced inside documentation because of a product-level fad that the term would help drive sell—i.e. it is not a technical thing and does not have explanatory power. (The fact that no other database uses "RBAC" to structure its reference docs on authorization should be a strong hint.) We made a mistake to use it in the reference documentation - it should have been segregated to the "major release notes" and perhaps the main feature/comparison page. I think it's time to correct this mistake.

v20/authorization.md section on Users and Roles #9913 (comment)

This section and the next section belong to a separate page "User and role management" which is a separate concern from authentication and authorization.

The "authorization" page should be limited to the actual authorization matters:

• which SQL privileges exist
• how they can be granted and revoked
• how to group users in roles in practice to achieve various use cases

v20.2/authentication.md examples, 2 instances of $ cockroach sql --certs-dir=certs --user=jpointsman #9913 (comment)

the ability to use --certs-dir in the client commands is unfortunate (and we're considering removing it) because it hides which forms of TLS validation is being used.

The proper way to explain security is to show pg connection URLs, and explain the various sslmode values.

For example, would a user know, by looking at this command, whether the client command performs server certificate validation or not? (No: they can't.)

Re. additional example $ cockroach sql --user=jpointsman #9913 (comment)

also would work with a connection URL with sslmode=disable.

v20.2/create-role.md #9913 (comment) & v20.2/create-user.md #9913 (comment)

I would use 2 separate hyperlinks here (in the intro): authorization for privilege management and role membership, and user/role management for creating/dropping roles

v20.2/create-role.md #9913 (comment) & v20.2/create-user.md #9913 (comment)

The list of possible role options should be part of the authorization page, and referred to here. I think it's confusing to explain this in the "create role" page when really it's an authorization matter and users can inherit these options via role membership.

v20.2/schema-design-overview.md #9913 (comment) & v20.2/show-grants.md (2 places #9913 (comment) #9913 (comment))

The hyperlinks should point to separate pages for user/role management and authorization.

Jira Issue: DOC-1033