Skip to content
Governance Platform

Authentication and Authorization Guidelines

This document summarizes the auth-service RBAC model as implemented in auth-service/backend/pkg/rbac/roles.go and auth-service/backend/pkg/rbac/permissions.go.

Access Model

Section titled “Access Model”

The platform is multi-tenant:

  • Organizations are top-level tenants.
  • Projects belong to organizations.
  • Users can belong to multiple organizations and projects.
  • Organization roles apply across an organization.
  • Project roles apply only inside assigned projects.

Permissions are assigned to roles, not directly to users.

Roles

Section titled “Roles”

Organization-level role:

  • organization_owner - full organization administration and broad access across projects in the organization.

Project-level roles:

  • project_owner - project administration, project membership, policy application, certificates, declarations, reviews, and project data.
  • implementation_owner - create declarations, submit controls for review, and view project data.
  • implementation_contributor - create declarations and view project data.
  • audit_owner - create/revoke certificates, determine control outcomes, create comments, and view project data.
  • audit_contributor - create comments and view project data.
  • project_viewer - read-only project data access.

Permissions

Section titled “Permissions”

Current permission constants:

  • manage_org_settings
  • manage_org_users
  • create_projects
  • edit_project_settings
  • archive_projects
  • manage_project_members
  • create_policies
  • apply_project_policies
  • archive_project_policies
  • create_certificates
  • revoke_certificates
  • create_indicators
  • archive_indicators
  • apply_indicators
  • activate_indicators
  • disable_indicators
  • create_declarations
  • submit_controls_for_review
  • determine_control_outcomes
  • create_comments
  • upload_demo_data
  • view_project_data

Role Permission Summary

Section titled “Role Permission Summary”
RolePermission groups
organization_ownerAll organization, project, policy, certificate, indicator, declaration, review, demo-data, and project-data permissions
project_ownerProject settings/members, project policies, certificates, indicator lifecycle actions, declarations, review outcomes/comments, project data
implementation_ownerDeclarations, submit controls for review, project data
implementation_contributorDeclarations, project data
audit_ownerCertificates, review outcomes/comments, project data
audit_contributorReview comments, project data
project_viewerProject data

For exact role-to-permission arrays, use /api/v1/rbac/metadata/roles and /api/v1/rbac/metadata/permissions or inspect the RBAC package.

Token Claims

Section titled “Token Claims”

Claims enrichment adds organization, project, role, user context, and DID key claims for downstream services. Auth0 Actions and Keycloak/Entra token exchange should preserve the same high-level claim semantics:

  • app_organizations
  • app_projects
  • user_context
  • did_key_id
  • idp_provider
  • idp_user_id when applicable

Implementation Notes

Section titled “Implementation Notes”
  • Keep membership changes scoped to organization/project boundaries.
  • Resolve permissions from role assignments rather than trusting client-side role checks.
  • Use API keys for service-to-service routes and bearer IDP/enriched tokens for user routes.
  • Keep new provider documentation aligned with IDP_PROVIDER support: auth0, keycloak, entra, and generic.