# Access control (Role-based)

How to configure and manage role-based database access control (RBAC) in Materialize.




> For the complete documentation index, see [llms.txt](https://preview.materialize.com/materialize/40269/llms.txt).


> **Note:** Initially, only the `mz_system` user (which has superuser/administrator
> privileges) is available to manage roles.


<a name="role-based-access-control-rbac" ></a>

## Role-based access control

In Materialize, role-based access control (RBAC) governs access to objects
through privileges granted to [database
roles](https://preview.materialize.com/materialize/40269/markdown-docs/security/self-managed/access-control/manage-roles/index.md).

## Enabling RBAC

> **Warning:** If RBAC is not enabled, all users have <red>**superuser**</red> privileges.


By default, role-based access control (RBAC) checks are not enabled (i.e.,
enforced) when using [authentication](https://preview.materialize.com/materialize/40269/markdown-docs/security/self-managed/authentication/index.md#configuring-authentication-type). To
enable RBAC, set the system parameter `enable_rbac_checks` to `'on'` or `True`.
You can enable the parameter in one of the following ways:

- For [local installations using
  Kind/Minikube](https://preview.materialize.com/materialize/40269/markdown-docs/self-managed-deployments/installation/index.md#installation-guides), set `spec.enableRbac:
  true` option when instantiating the Materialize object.

- For [Cloud deployments using Materialize's
  Terraforms](https://preview.materialize.com/materialize/40269/markdown-docs/self-managed-deployments/installation/index.md#installation-guides), set
  `enable_rbac_checks` in the environment CR via the `environmentdExtraArgs`
  flag option.

- After the Materialize instance is running, run the following command as
  `mz_system` user:

  ```mzsql
  ALTER SYSTEM SET enable_rbac_checks = 'on';
  ```

If more than one method is used, the `ALTER SYSTEM` command will take precedence
over the Kubernetes configuration.

To view the current value for `enable_rbac_checks`, run the following `SHOW`
command:

```mzsql
SHOW enable_rbac_checks;
```

> **Important:** If RBAC is not enabled, all users have <red>**superuser**</red> privileges.

## Roles and privileges

In Materialize, you can create both:
- Individual user or service account roles; i.e., roles associated with a
  specific user or service account.
- Functional roles, not associated with any single user or service
  account, but typically used to define a set of shared
  privileges that can be granted to other user/service/functional roles.

Initially, only the `mz_system` user is available.

To create additional users or service accounts, login as the `mz_system` user,
using the `external_login_password_mz_system` password, and use [`CREATE ROLE
... WITH LOGIN PASSWORD ...`](https://preview.materialize.com/materialize/40269/markdown-docs/sql/create-role/index.md):

```mzsql
CREATE ROLE <user> WITH LOGIN PASSWORD '<password>';
```

> **Note:** If you are using [OIDC authentication (SSO)](https://preview.materialize.com/materialize/40269/markdown-docs/self-managed-deployments/sso/oidc/index.md), user
> roles are **automatically created** when a user first signs in. You do not need
> to manually create roles for OIDC users. See
> [Auto-provisioning roles](https://preview.materialize.com/materialize/40269/markdown-docs/self-managed-deployments/sso/oidc/index.md#auto-provisioning-roles) for
> details.


To create functional roles, login as the `mz_system` user,
using the `external_login_password_mz_system` password, and use [`CREATE ROLE`](https://preview.materialize.com/materialize/40269/markdown-docs/sql/create-role/index.md):

```mzsql
CREATE ROLE <role>;
```

### Managing privileges

Once a role is created, you can:

- [Manage its current
  privileges](https://preview.materialize.com/materialize/40269/markdown-docs/security/self-managed/access-control/manage-roles/index.md#manage-current-privileges-for-a-role)
  (i.e., privileges on existing objects):
  - By granting privileges for a role or revoking privileges from a role.
  - By granting other roles to the role or revoking roles from the role.
    *Recommended for user account/service account roles.*
- [Manage its future
  privileges](https://preview.materialize.com/materialize/40269/markdown-docs/security/self-managed/access-control/manage-roles/index.md#manage-future-privileges-for-a-role)
  (i.e., privileges on objects created in the future):
  - By defining default privileges for objects. With default privileges in
   place, a role is automatically granted/revoked privileges as new objects are
   created by **others** (When an object is created, the creator is granted all
   [applicable privileges](https://preview.materialize.com/materialize/40269/markdown-docs/security/appendix/appendix-privileges/index.md) for that
   object automatically).

> **Disambiguation:** - Use `GRANT|REVOKE ...` to modify privileges on **existing** objects. - Use `ALTER DEFAULT PRIVILEGES` to ensure that privileges are automatically granted or revoked when **new objects** of a certain type are created by others. Then, as needed, you can use `GRANT|REVOKE <privilege>` to adjust those privileges. 


### Initial privileges

All roles in Materialize are automatically members of
[`PUBLIC`](https://preview.materialize.com/materialize/40269/markdown-docs/security/appendix/appendix-built-in-roles/index.md#public-role). As
such, every role includes inherited privileges from `PUBLIC`.

By default, the `PUBLIC` role has the following privileges:


**Baseline privileges via PUBLIC role:**

| Privilege | Description | On database object(s) |
| --- | --- | --- |
| <code>USAGE</code> | Permission to use or reference an object. | <ul> <li>All <code>*.public</code> schemas (e.g., <code>materialize.public</code>);</li> <li><code>materialize</code> database; and</li> <li><code>quickstart</code> cluster.</li> </ul>  |


**Default privileges on future objects set up for PUBLIC:**

| Object(s) | Object owner | Default Privilege | Granted to | Description |
| --- | --- | --- | --- | --- |
| <a href="https://preview.materialize.com/materialize/40269/markdown-docs/sql/types/index.md" ><code>TYPE</code></a> | <code>PUBLIC</code> | <code>USAGE</code> | <code>PUBLIC</code> | When a <a href="https://preview.materialize.com/materialize/40269/markdown-docs/sql/types/index.md" >data type</a> is created (regardless of the owner), all roles are granted the <code>USAGE</code> privilege. However, to use a data type, the role must also have <code>USAGE</code> privilege on the schema containing the type. |

Default privileges apply only to objects created after these privileges are
defined. They do not affect objects that were created before the default
privileges were set.

In addition, all roles have:
- `USAGE` on all built-in types and [all system catalog
schemas](https://preview.materialize.com/materialize/40269/markdown-docs/sql/system-catalog/index.md).
- `SELECT` on [system catalog objects](https://preview.materialize.com/materialize/40269/markdown-docs/sql/system-catalog/index.md).
- All [applicable privileges](https://preview.materialize.com/materialize/40269/markdown-docs/security/appendix/appendix-privileges/index.md) for
  an object they create; for example, the creator of a schema gets `CREATE` and
  `USAGE`; the creator of a table gets `SELECT`, `INSERT`, `UPDATE`, and
  `DELETE`.

You can modify the privileges of your organization's `PUBLIC` role as well as
the modify default privileges for `PUBLIC`.

## Privilege inheritance and modular access control

In Materialize, when you grant a role to another role (user role/service account
role/independent role), the target role inherits privileges through the granted
role.

In general, to grant a user or service account privileges, create roles with the
desired privileges and grant these roles to the user or service account role.
Although you can grant privileges directly to the user or service account role,
using separate, reusable roles is recommended for better access management.

With privilege inheritance, you can compose more complex roles by
combining existing roles, enabling modular access control. However:

- Inheritance only applies to role privileges; role attributes and parameters
  are not inherited.
- When you revoke a role from another role (user role/service account
role/independent role), the target role is no longer a member of the revoked
role nor inherits the revoked role's privileges. **However**, privileges are
cumulative: if the target role inherits the same privilege(s) from another role,
the target role still has the privilege(s) through the other role.

## Best practices



### Follow the principle of least privilege

Role-based access control in Materialize should follow the principle of
least privilege. Grant only the minimum access necessary for users and
service accounts to perform their duties.



### Restrict the granting of `CREATEROLE` privilege


{{% include-headless "/headless/rbac-sm/createrole-consideration" %}}



### Use Reusable Roles for Privilege Assignment


{{% include-headless "/headless/rbac-sm/use-resusable-roles" %}}

See also [Manage database roles](https://preview.materialize.com/materialize/40269/markdown-docs/security/self-managed/access-control/manage-roles/index.md).



### Audit for unused roles and privileges.


{{% include-headless "/headless/rbac-sm/audit-remove-roles" %}}

See also [Show roles in
system](https://preview.materialize.com/materialize/40269/markdown-docs/security/self-managed/access-control/manage-roles/index.md#show-roles-in-system)
and [Drop a
role](https://preview.materialize.com/materialize/40269/markdown-docs/security/self-managed/access-control/manage-roles/index.md#drop-a-role) for
more information.




## Pages in this section

- [Manage database roles](https://preview.materialize.com/materialize/40269/markdown-docs/security/self-managed/access-control/manage-roles/index.md): Create and manage database roles and privileges in Materialize