doc/user: rework access control documentation (MaterializeInc#21609)

ggevay · Sep 12, 2023 · 4f1062c · 4f1062c
1 parent 43d51c6
commit 4f1062c
Show file tree

Hide file tree

Showing 9 changed files with 503 additions and 184 deletions.
diff --git a/doc/user/content/invite-users.md b/doc/user/content/invite-users.md
diff --git a/doc/user/content/manage/access-control/_index.md b/doc/user/content/manage/access-control/_index.md
diff --git a/doc/user/content/manage/access-control/invite-users.md b/doc/user/content/manage/access-control/invite-users.md
@@ -0,0 +1,40 @@
+---
+title: "Invite users"
+description: "Invite new users to a Materialize organization."
+aliases:
+  - /invite-users/
+---
+
+As an **administrator** of a Materialize organization, you can invite new users
+via the Materialize console. Depending on the level of access each user should
+have, you can assign them `Organization Admin` or `Organization Member`
+privileges.
+
+These privileges primarily determine a user's access level to the console, but
+also have implications in the default access level to the database. More
+granular permissions within the database must be handled separately using
+[role-based access control (RBAC)](/manage/access-control/#role-based-access-control-rbac).
+
+## Step 1. Invite a new user
+
+1. [Log in to the Materialize console](https://console.materialize.com/).
+
+1. Navigate to **Account** > **Account Settings** > **Users**.
+
+1. Click **Invite User** and fill in the user information.
+
+1. Select *Organization Admin* or *Organization Member* depending on what level of console access the user needs:
+
+    - `Organization Admin`: can perform adminstration tasks in the console, like
+      inviting new users, editing account and security information, or managing
+      billing. Admins have _superuser_ privileges in the database.
+
+    - `Organization Member`: can login to the console and has restricted access
+      to the database, depending  on the privileges defined via
+      [role-based access control (RBAC)](/manage/access-control/#role-based-access-control-rbac).
+
+2. Click the **Invite** button at the bottom right section of the screen.
+
+   Materialize will email the user with a verification link. The user will
+   verify their email and create a password for their account. The user will
+   then be able to login to the Materialize console.
diff --git a/doc/user/content/manage/access-control/manage-privileges.md b/doc/user/content/manage/access-control/manage-privileges.md
@@ -3,7 +3,7 @@ title: "Manage privileges"
 description: "Assign and manage role privileges in Materialize"
 menu:
   main:
-    parent: access-control
+    parent: rbac
     weight: 20
 ---
 

diff --git a/doc/user/content/manage/access-control/manage-roles.md b/doc/user/content/manage/access-control/manage-roles.md
@@ -3,7 +3,7 @@ title: "Manage roles"
 description: "Create and manage roles in Materialize"
 menu:
   main:
-    parent: access-control
+    parent: rbac
     weight: 15
 ---
 

diff --git a/doc/user/content/manage/access-control/rbac.md b/doc/user/content/manage/access-control/rbac.md
@@ -0,0 +1,111 @@
+---
+title: "Role-based access control (RBAC)"
+description: "Manage roles, privileges, and other access control options in Materialize"
+menu:
+  main:
+    parent: access-control
+    weight: 10
+---
+
+[//]: # "NOTE(morsapaes) This page will be rewritten as a follow-up."
+
+This page introduces role-based access management (RBAC) in Materialize. RBAC
+allows you to apply granular privileges to your Materialize objects and clusters. Organizations
+using RBAC can manage user roles and privileges to ensure there is not
+unauthorized or improper access to sensitive objects.
+
+In Materialize, RBAC allows organization administrators to:
+
+* Determine which users have read or write privileges for specific objects
+
+* Control how users interact with clusters by giving them different levels of access to
+resources
+
+* Prevent accidental operations from unauthorized users
+
+* Isolate access to user-facing data from internal organization data
+
+Materialize object access is also dependent on cluster privileges.
+Roles that need access to an object that use compute resources must also have
+the same level of access to the cluster. Materialize objects that use compute
+resources are:
+
+* Replicas
+* Sources
+* Sinks
+* Indexes
+* Materialized views
+
+The next sections go over the concepts of authorization and authentication and
+the objects within Materialize.
+
+## RBAC structure
+
+RBAC in practice is a group of roles with assigned privileges.
+You can assign specific users to roles or assign privileges to users to inherit
+from other roles.
+
+### Roles
+
+A role is a collection of privileges you can apply to users. Roles make it
+easier to assign or revoke privileges on Materialize objects. You can group
+users into specified roles with different levels of privileges and adjust those
+privileges to ensure they have the correct level of access to objects.
+
+### Role attributes
+
+Role attributes are actions available to any role you create. Attributes are
+independent of any other object in Materialize and apply to the entire
+organization. You can edit these actions when you create the role:
+
+| Name              | Description                                                                 |
+|-------------------|-----------------------------------------------------------------------------|
+| `INHERIT`         | **Read-only.** Can inherit privileges of other roles.                       |
+
+PostgreSQL uses role attributes to determine if a role is allowed to execute certain statements. In
+Materialize these have all been replaced by system privileges.
+
+### Privileges
+
+Privileges are the actions or operations a role is allowed to perform on a
+specific object. After you create a role, you can grant it the following
+object-specific privileges in Materialize:
+
+| Privilege       | Description                                                                                    | `psql` |
+|-----------------|------------------------------------------------------------------------------------------------|--------|
+| `SELECT`        | Allows selecting rows from an object.                                                          | `r`    |
+| `INSERT`        | Allows inserting into an object.                                                               | `a`    |
+| `UPDATE`        | Allows updating an object (requires `SELECT`).                                                 | `w`    |
+| `DELETE`        | Allows deleting from an object (requires `SELECT`).                                            | `d`    |
+| `CREATE`        | Allows creating a new object within another object.                                            | `C`    |
+| `USAGE`         | Allows using an object or looking up members of an object.                                     | `U`    |
+| `CREATEROLE`    | Allows creating, altering, deleting roles and the ability to grant and revoke role membership. | `R`    |
+| `CREATEDB`      | Allows creating databases.                                                                     | `B`    |
+| `CREATECLUSTER` | Allows creating clusters.                                                                      | `N`    |
+
+
+Note that the system catalog uses the abbreviation of the privilege name.
+
+Objects in Materialize have different levels of privileges available to them.
+Materialize supports the following object type privileges:
+
+| Object Type          | Privileges                                |
+|----------------------|-------------------------------------------|
+| `SYSTEM`             | `CREATEROLE`, `CREATEDB`, `CREATECLUSTER` |
+| `DATABASE`           | `USAGE`, `CREATE`                         |
+| `SCHEMA`             | `USAGE`, `CREATE`                         |
+| `TABLE`              | `INSERT`, `SELECT`, `UPDATE`, `DELETE`    |
+| `VIEW`               | `SELECT`                                  |
+| `MATERIALIZED  VIEW` | `SELECT`                                  |
+| `TYPE`               | `USAGE`                                   |
+| `SOURCE`             | `SELECT`                                  |
+| `CONNECTION`         | `USAGE`                                   |
+| `SECRET`             | `USAGE`                                   |
+| `CLUSTER`            | `USAGE`, `CREATE`                         |
+
+### Inheritance
+
+Inheritance in RBAC allows you to create roles that inherit privileges from
+other roles. Inheritance only applies to role privileges. Role attributes are
+not inherited. Inheriting privileges allows you to minimize the number of roles
+you have to manage.
diff --git a/doc/user/content/manage/access-control/sso.md b/doc/user/content/manage/access-control/sso.md
@@ -0,0 +1,63 @@
+---
+title: "Single sign-on (SSO)"
+description: "Configure single sign-on (SSO) using SAML or Open ID Connect as an additional layer of account security."
+aliases:
+  - /manage/sso/
+---
+
+As an **administrator** of a Materialize organization, you can configure single
+sign-on (SSO) as an additional layer of account security using your existing
+[SAML](https://auth0.com/blog/how-saml-authentication-works/)- or
+[OpenID Connect](https://auth0.com/intro-to-iam/what-is-openid-connect-oidc)-based
+identity provider. This ensures that all users can securely log in to the
+Materialize console using the same authentication scheme and credentials across
+all systems in your organization.
+
+{{< note >}}
+Single sign-on in Materialize only supports authentication into the Materialize
+console. Permissions within the database are handled separately using
+[role-based access control](/manage/access-control/).
+{{</ note >}}
+
+## Before you begin
+
+To make Materialize metadata available to Datadog, you must configure and run the following additional services:
+
+* You must have an existing SAML- or OpenID Connect-based identity provider.
+* Only users assigned the `OrganizationAdmin` role can view and modify SSO settings.
+
+## Configure authentication
+
+* [Log in to the Materialize console](https://console.materialize.com/).
+
+* Navigate to **Account** > **Account Settings** > **SSO**.
+
+{{< tabs >}}
+{{< tab "OpenID Connect" >}}
+
+* Click **Add New** and choose the `OpenID Connect` connection type.
+
+* Add the issuer URL, client ID, and secret key provided by your identity provider.
+
+{{< /tab >}}
+{{< tab "SAML" >}}
+
+* Click **Add New** and choose the `SAML` connection type.
+
+* Add the SSO endpoint and public certificate provided by your identity provider.
+
+{{< /tab >}}
+{{< /tabs >}}
+
+* Optionally, add the SSO domain provided by your identity provider. Click **Proceed**.
+
+* Select `Organization Admin` or `Organization Member`, depending on the level
+  of console access the user needs:
+
+    - `Organization Admin`: can perform adminstration tasks in the console, like
+      inviting new users, editing account and security information, or managing
+      billing. Admins have _superuser_ privileges in the database.
+
+    - `Organization Member`: can login to the console and has restricted access
+      to the database, depending  on the privileges defined via
+      [role-based access control (RBAC)](/manage/access-control/#role-based-access-control-rbac).
diff --git a/doc/user/content/manage/sso.md b/doc/user/content/manage/sso.md
diff --git a/doc/user/content/releases/v0.60.md b/doc/user/content/releases/v0.60.md
@@ -62,7 +62,7 @@ flag. The flag was raised in v0.60 -— so mentioning it here."
 * Improve and extend the base implementation of **Role-based
   access control** (RBAC):
 
-  * Restrict granting and revoking [system privileges](/manage/access-control/#privileges)
+  * Restrict granting and revoking [system privileges](/manage/access-control/manage-privileges/)
     to _superuser_ users with admin privileges.
 
   It's important to note that role-based access control (RBAC) is **disabled by