Skip to content

docs: document RBAC space roles and correct noun/verb defaults #47

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
luisina-santos merged 1 commit into from
Aug 19, 2026
Merged

docs: document RBAC space roles and correct noun/verb defaults #47

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 32 additions & 6 deletions docs/connector.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,11 +18,30 @@ sidebarTitle: "Atlassian Confluence"
| Groups | <Icon icon="square-check" iconType="solid" color="#c937ae"/> | <Icon icon="square-check" iconType="solid" color="#c937ae"/> |
| Spaces | <Icon icon="square-check" iconType="solid" color="#c937ae"/> | |
| Space permissions | <Icon icon="square-check" iconType="solid" color="#c937ae"/> | <Icon icon="square-check" iconType="solid" color="#c937ae"/> |
| Space Roles (opt-in) | <Icon icon="square-check" iconType="solid" color="#c937ae"/> | |
| Space Role Assignments (opt-in) | <Icon icon="square-check" iconType="solid" color="#c937ae"/> | <Icon icon="square-check" iconType="solid" color="#c937ae"/> |

<Tip>
To limit sync times, a limited list of Spaces entitlements and their associated grants are synced. See the [Spaces entitlements synced by default](/baton/confluence#spaces-entitlements-synced-by-default) section of this page for more information.
</Tip>

## RBAC space roles

The Confluence connector supports two modes for syncing space access:

- **Granular space permissions** (default): Syncs individual noun-verb permission pairs (for example, `read-space`, `administer-space`) per space. This is the default behavior.
- **RBAC space roles**: Syncs Confluence's built-in space roles and their assignments instead of granular permissions. Enable this mode by setting the `--use-rbac` flag (or `BATON_USE_RBAC=true`).

@github-actions github-actions Bot Aug 7, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Suggestion: "built-in space roles" understates the scope — GetSpaceRoles returns custom roles too (see the comment at pkg/connector/space_role_assignments.go:39: "4 defaults + 10 custom"). Suggest "built-in and custom space roles".


The connector uses one mode or the other — not both. When RBAC mode is enabled, granular space permissions are not synced, and the Space Roles and Space Role Assignments resource types become active.

@github-actions github-actions Bot Aug 7, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Suggestion: The two resource types aren't gated the same way. spaceRoleBuilder is registered unconditionally (pkg/connector/connector.go:165) and its List runs regardless of useRbac (pkg/connector/space_roles.go:24-31) — Space Roles are gated only by the OptInRequired annotation (pkg/connector/helpers.go:25-30), not by --use-rbac. Only Space Role Assignments are --use-rbac-gated, via the ChildResourceType annotation added in spaces.go:224-228. Consider saying both types require C1-side opt-in and that --use-rbac is what enables role assignment sync and disables granular permissions.


<Warning>
**RBAC mode requires that Space Roles are enabled and entitled on your Confluence instance.** If the RBAC endpoints are unavailable (for example, because a trial or beta grant has expired), the connector's `Validate` step fails with the message:

`RBAC data endpoints are unavailable (space-roles returned 404) — this can happen when a trial or beta grant for RBAC has expired`

If you see this error, either disable `--use-rbac` or contact Atlassian to ensure Space Roles are enabled on your instance.
</Warning>

## Gather Confluence credentials

Configuring the connector requires you to pass in credentials generated in Confluence. Gather these credentials before you move on.
Expand Down Expand Up @@ -187,6 +206,9 @@ stringData:

# Optional: include to skip syncing personal spaces and their permissions
BATON_SKIP_PERSONAL_SPACES: true

# Optional: include to use RBAC space roles instead of granular permissions
# BATON_USE_RBAC: true
Comment on lines +210 to +211

@github-actions github-actions Bot Aug 7, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Suggestion: The comment reads "Optional: include to use RBAC..." but the key itself is commented out, unlike the other optional entries above (BATON_PROVISIONING, BATON_SKIP_PERSONAL_SPACES), which are live. Copy-pasting this block silently leaves RBAC off. Suggest matching the surrounding style.

Suggested change
# Optional: include to use RBAC space roles instead of granular permissions
# BATON_USE_RBAC: true
# Optional: include to use RBAC space roles instead of granular permissions
BATON_USE_RBAC: true

```

See the connector's README or run `--help` to see all available configuration flags and environment variables.
Expand Down Expand Up @@ -241,13 +263,13 @@ spec:

## Spaces entitlements synced by default

Each Confluence Space has its own set of permissions and allowed actions, which can result in a very large set of entitlement and grant access information in each Space. In order to reduce sync times, the Confluence connector only syncs a limited set of Spaces entitlements.

By default, the Confluence connector syncs entitlements formed by valid pairs of the following targets (nouns) and operators (verbs), such as `administer-space` or `read-space`.
Each Confluence Space has its own set of permissions and allowed actions, which can result in a very large set of entitlement and grant access information in each Space.

Default targets (nouns): `space`
The Confluence connector syncs entitlements formed by valid pairs of targets (nouns) and operators (verbs), such as `administer-space` or `read-space`.

Default operators (verbs): `administer`, `create`, `delete`, `export`, `read`, `restrict_content`
<Note>
When configuring the connector in C1, the noun and verb fields are pre-filled with a suggested subset (`space` noun and 6 common verbs). These suggested values only pre-populate the configuration form — they are **not** automatically applied. If you leave the noun and verb fields empty (or do not set `--noun` / `--verb` flags), the connector syncs **all** available nouns and verbs listed below.
</Note>

All available targets (nouns):

Expand All @@ -270,6 +292,10 @@ All available operators (verbs):

Not all target-operator (noun-verb) pairs are valid.

To change or limit what the Confluence connector syncs to C1, use the `--noun` and `--verb` flags when setting up the Confluence connector in self-hosted mode. See the [baton-confluence repo's README](https://github.com/conductorone/baton-confluence) for more information.
To limit what the Confluence connector syncs to C1, use the `--noun` and `--verb` flags when setting up the Confluence connector in self-hosted mode, or configure the noun and verb fields in the C1 UI for cloud-hosted connectors. See the [baton-confluence repo's README](https://github.com/conductorone/baton-confluence) for more information.

<Note>
Space permission entitlements are only synced when RBAC mode is **disabled** (the default). When `--use-rbac` is enabled, the connector syncs Space Roles and Space Role Assignments instead. See [RBAC space roles](/baton/confluence#rbac-space-roles) for details.
</Note>


Loading