Roles and permissions

ArchGuard uses your company single sign-on (OpenID Connect). Your role comes from the groups your identity provider puts in your sign-in token.

The three roles

Capability Viewer Architect Admin
View dashboard, ADR drafts, rules, help Yes Yes Yes
Create, edit, disable and delete guardrail rules No Yes Yes
Edit, approve, commit and dismiss ADR drafts No Yes Yes
Connect Bitbucket, enable repositories, edit triage settings No No Yes

The Settings menu is only shown to Admins. Opening a page without the needed role shows a "Not allowed" message.

How groups map to roles

The administrator configures group names in the environment:

Setting Default group
AUTH_ROLE_ADMIN_GROUPS archguard-admins
AUTH_ROLE_ARCHITECT_GROUPS archguard-architects
AUTH_ROLE_VIEWER_GROUPS archguard-viewers

Each setting accepts several comma-separated names. Group names are not case sensitive. The claim that holds the groups is set by AUTH_OIDC_GROUPS_CLAIM (default groups). If you belong to several groups, you get the highest role.

Access rules

  • A user in none of these groups cannot sign in.
  • Roles are checked at every sign-in. If your group membership changes, sign out and in again. Sessions last 8 hours.
  • All users sign in to one organization, set by AUTH_DEFAULT_ORG_SLUG.

Identity providers

Any OpenID Connect provider works if it can put the user's groups or roles in the ID token:

  • Microsoft Entra ID: enable the groups claim in the app registration. The claim is groups.
  • Auth0: add a post-login Action that sets a URL-named claim, for example https://archguard.app/roles, and set AUTH_OIDC_GROUPS_CLAIM to the same name. See Cloud deployment.

Data separation

Each organization's data is isolated in the database by row-level security, so even a coding error cannot show one organization's data to another. See Security and data handling.