docs: add cloud guide for syncing IdP groups to database roles [DNM] by jubrad · Pull Request #37713 · MaterializeInc/materialize

jubrad · 2026-07-17T15:49:25Z

Motivation

Documents the new SCIM group provisioning and group-to-role mapping feature for Materialize Cloud (design: #35899). There are currently no user-facing docs for this feature.

Changes

Adds a new page under security/cloud/users-service-accounts/:

Prerequisites, including that an SSO connection must be configured first.
Creating a SCIM connection in the Console (Account Settings > Provisioning).
Selecting which IdP groups to sync (Okta Push Groups walkthrough), noting that only explicitly pushed groups are visible to Materialize.
Creating matching database roles (exact, case-sensitive name match, roles act as an allowlist).
Verifying sync via mz_role_members (grantor mz_jwt_sync) and mz_audit_events.
Sync semantics: applied at connection time, manual grants never revoked, unmatched groups skipped with a NOTICE.
Limitations: mz_/pg_-prefixed roles never mapped, no role auto-creation, not real time.
Managing groups via the Console or the Terraform provider (materialize_scim_config, materialize_scim_group, materialize_scim_group_users, materialize_scim_group_roles).

Also links the new page from the security index and the user/service accounts index, and adds Console/Okta screenshots.

The page is marked private preview with the contact-us enablement note.

Tips for reviewer

Rendered locally with Hugo, all images and links resolve.

Checklist

This PR has adequate test coverage / QA involvement has been duly considered. (trigger-ci for additional test/nightly runs)
This PR has an associated up-to-date design doc, is a design doc (template), or is sufficiently small to not require a design.
If this PR evolves an existing $T ⇔ Proto$T mapping (possibly in a backwards-incompatible way), then it is tagged with a T-proto label.
If this PR will require changes to cloud orchestration or tests, there is a companion cloud PR to account for those changes that is tagged with the release-blocker label (example).
If this PR includes major user-facing behavior changes, I have pinged the relevant PM to schedule a changelog post.

🤖 Generated with Claude Code

mtabebe

Just from a technical POV, this looks good to me. I had one slight nit but don't know that it should be corrected

mtabebe · 2026-07-20T14:26:08Z

+
+## Limitations
+
+* **Roles beginning with `mz_` or `pg_` are never mapped.** These prefixes are


There are other ones as well (e.g., current_user, session_user, user, public) I don't know how specific we want to get

We should list all of them in the docs. I'll make an update.

Good catch. Checked is_reserved_role_name in src/adapter/src/catalog.rs. Full set is: prefixes mz_, pg_, external_; the PUBLIC role; and the role-spec keywords current_user, current_role, session_user, user, none. Updated the Limitations section to list all of them (case-insensitive match).

jubrad · 2026-07-21T17:38:38Z

~~Waiting on https://github.com/MaterializeInc/cloud/pull/13021~~
[ merged ] this is ready to go.

kay-kim · 2026-07-22T20:00:24Z

+## Group sync
+
+As an **Organization admin**, you can provision groups from your identity
+provider via SCIM and map them to Materialize database roles, so that database


maybe include "existing" Materialize database roles?

kay-kim · 2026-07-22T20:36:29Z

+
+## Limitations
+
+* **Reserved role names are never mapped.** Groups whose names collide with


I would actually mention this point last.

kay-kim · 2026-07-22T20:46:56Z

+
+As an **Organization admin**, you can provision groups from your identity
+provider via SCIM and map them to Materialize database roles, so that database
+permissions are managed from your identity provider.


So ... it's not exactly permissions, yes? it's more the database role membership?

kay-kim · 2026-07-22T20:50:58Z

+* Groups you select in your IdP are provisioned into your Materialize
+  organization via [SCIM](https://scim.cloud/), along with their members.


Just trying to flesh out couple of things:
Let's say in my IdP, I have analysts group and someoneNewToMZ as a member.

Double checking that when someoneNewToMZ first log in, we'll still create the corresponding db role, yes?

If we don't set the Organization role for analysts group, what actually happens with someoneNewToMZ ? anything? or is just not being an OrgAdmin the main thing?

When someoneNewToMz signs in for the first time, assuming their coming from SSO, we will create their role, if they user's claim groups contains analysts then they will be assigned the analyst role.

Frontegg specifics... For roles we have Organization Admins and Organization Members. The only way to get superuser in cloud MZ is to have the role Organization Admins. It is possible, using the frontegg admin portal we provide to customers, to associate one of these roles with a group in a way that all users with that group will get that role assigned automatically. For instance, an upstream IDP group materialize_admin can sink to MZ using SCIM, and an admin user can set it so those people also get assigned the Organization Admins role and thus will be superuser. This was part was actually possible prior to this and we use it to manage some of our dog food environments.

Yup ... so, am trying to see if we could end up with users that have no org role by having someone who has not been manually invited to the MZ org but is in the sync'ed group's member list.
Is this possible? and if an admin user does not update the sync'ed analysts to have an organization role, then, someoneNewToMZ, on first signing in, will have their db role created, and be assigned analyst role but will not be associated with any Org role?

or by default, are people all Org members?

kay-kim · 2026-07-22T20:58:34Z

+Console under **Account** > **Account Settings** > **Groups**, marked with a
+SCIM badge. Groups pushed from your IdP are read-only in Materialize and must
+be managed from the IdP.
+


Wondering ... should we include a step here where people edit to set the organization role? Related to the above question about what happens if someone isn't either an Org Admin/Member ?

kay-kim · 2026-07-22T21:07:19Z

+This means you can manage who has access to what in Materialize from your IdP.
+When a team member joins, leaves, or changes teams, updating their group
+membership in the IdP updates their database permissions, with no manual
+`GRANT` or `REVOKE` statements required.


we might want to add a blurb w.r.t. its scope (that is, roles you grant manually aren't revoked via syncs.)

kay-kim · 2026-07-22T21:29:17Z

+Groups pushed from your IdP are managed in the IdP. You can also create and
+manage groups directly:
+
+* **Materialize Console**: Navigate to **Account** > **Account Settings** >


So ... manually created groups ... they won't sync, right? since they won't be in the Idp's token group claim?

kay-kim · 2026-07-23T13:17:29Z

+* Groups you select in your IdP are provisioned into your Materialize
+  organization via [SCIM](https://scim.cloud/), along with their members.


Yup ... so, am trying to see if we could end up with users that have no org role by having someone who has not been manually invited to the MZ org but is in the sync'ed group's member list.
Is this possible? and if an admin user does not update the sync'ed analysts to have an organization role, then, someoneNewToMZ, on first signing in, will have their db role created, and be assigned analyst role but will not be associated with any Org role?

kay-kim · 2026-07-23T13:27:12Z

+* Groups you select in your IdP are provisioned into your Materialize
+  organization via [SCIM](https://scim.cloud/), along with their members.


or by default, are people all Org members?

kay-kim · 2026-07-23T13:32:57Z

+
+Once pushed, the groups and their memberships appear in the Materialize
+Console under **Account** > **Account Settings** > **Groups**, marked with a
+SCIM badge. Groups pushed from your IdP are read-only in Materialize and must


oh, except for the Org admin/member thing, yes? It's just the members list?

Document the new SCIM group provisioning and group-to-role mapping feature for Materialize Cloud: creating a SCIM connection in the console, selecting which IdP groups to push, creating matching database roles, sync-at-connection semantics, and managing groups via the console or the Terraform provider. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

jubrad requested a review from mtabebe July 17, 2026 16:07

jubrad marked this pull request as ready for review July 17, 2026 17:41

jubrad requested a review from a team as a code owner July 17, 2026 17:41

jubrad changed the title ~~docs: add cloud guide for syncing IdP groups to database roles~~ docs: add cloud guide for syncing IdP groups to database roles [DNM] Jul 17, 2026

jubrad requested a review from kay-kim July 18, 2026 18:39

mtabebe approved these changes Jul 20, 2026

View reviewed changes

jubrad force-pushed the docs-cloud-group-sync branch 2 times, most recently from 2a4f918 to 1154473 Compare July 20, 2026 20:41

kay-kim reviewed Jul 22, 2026

View reviewed changes

jubrad force-pushed the docs-cloud-group-sync branch 5 times, most recently from 37d071f to ea7c08a Compare July 23, 2026 03:35

kay-kim reviewed Jul 23, 2026

View reviewed changes

jubrad force-pushed the docs-cloud-group-sync branch from ea7c08a to 365c530 Compare July 23, 2026 19:53

jubrad merged commit b3d6c7a into MaterializeInc:main Jul 23, 2026
10 checks passed


		## Limitations

		* Roles beginning with `mz_` or `pg_` are never mapped. These prefixes are


		## Limitations

		* Reserved role names are never mapped. Groups whose names collide with

		* Groups you select in your IdP are provisioned into your Materialize
		organization via [SCIM](https://scim.cloud/), along with their members.

Uh oh!

Conversation

jubrad commented Jul 17, 2026

Motivation

Changes

Tips for reviewer

Checklist

Uh oh!

mtabebe left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jubrad commented Jul 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jubrad commented Jul 21, 2026 •

edited

Loading