Provisioning Users

This section explains how Rulebricks maps incoming SSO identities onto its internal authorization model, and how to configure that mapping from the Team → SSO tab. It is written for workspace administrators running a self-hosted or white-labeled Rulebricks deployment.

If you cannot provision an SSO application for Rulebricks — for example because Rulebricks lives inside a private network behind an existing identity-aware proxy — see Disabling Authentication for the token passthrough alternative.

What the SSO Team Tab Does

The SSO Team tab connects incoming identity claims from your IdP to four dimensions of Rulebricks authorization:

• Access — who is allowed to enter the application at all
• Tenants — which tenancy boundaries a user can see
• Roles — what permissions the user has once inside
• Profile — how the user's name and avatar are populated

Each dimension is configured independently. The full reference for every field lives in Claim Mapping.

How the SSO Model Works

Rulebricks uses a parent-child team model.

• The first admitted SSO user becomes the root workspace administrator.
• That user has no parent and is the single built-in administrator for the workspace.
• Every later admitted SSO user is adopted under that administrator as a child user.
• Child users receive:
  • a Rulebricks role
  • optional tenant assignments
  • optional profile mappings

This means the SSO layer does not create a separate authorization model. It resolves users into the same internal team structure that Rulebricks already uses everywhere else.

The One Administrator Rule

Rulebricks maintains exactly one built-in administrator per workspace:

• The first admitted user is the workspace administrator.
• The built-in Administrator role is not assignable through SSO role mapping.
• Later users can be assigned system roles like Developer or Editor, or custom roles created in Rulebricks.

This prevents claim mapping from accidentally creating multiple built-in administrators. If you need a class of trusted cross-tenant users, use the admin tenant value instead, which affects tenant visibility without granting administrator status.

What Happens When Mapping Fails

Rulebricks treats failed mapping safely by default.

Examples of failed mapping include:

• access rules block the user
• role mapping produces no valid role
• tenant mapping is enabled but no tenant claim is present
• the system cannot safely determine how the user should be adopted into the workspace

In these cases the user is denied access and sent to the access-unavailable screen.

There are two intentional exceptions:

• If a fallback role is enabled, an unmatched role resolves into that role instead of producing a denial.
• If the tenant claim refers to a tenant that does not exist yet, Rulebricks auto-creates the tenant.

Recommended Configuration Pattern

For most teams, a good configuration sequence is:

Access Levels at a Glance

Where to Next

• Claim Mapping — the full reference for the Access, Tenants, Roles, and Profile sections of the Team tab.
• Disabling Authentication — for deployments that cannot provision an SSO application for Rulebricks and instead want to delegate authentication to an upstream proxy.