Authentication and Authorization: Overview

KubeRocketCI uses Keycloak as central access management solution, handling user permissions across various platform tools, including Kubernetes. Kubernetes clusters leverage Keycloak for RBAC implementation via OIDC. This consistent approach allows administrators to manage access uniformly. Within Kubernetes, Custom Resources (CRs) are used to refine and enforce access controls by configuring Keycloak, translating Kubernetes configurations into Keycloak access policies.

Keycloak Components Overview

Keycloak is a critical component in KubeRocketCI for managing authentication and authorization. It uses realms, roles and groups to control access across the platform.

The diagram below illustrates the Keycloak resources within the KubeRocketCI system. It shows how tools and their Keycloak configurations are managed within the shared and broker realms. The broker realm serves as a central "authentication proxy" (broker), connecting to external Identity Providers (IdPs) such as Google, Facebook, and Active Directory (AD) through OIDC and/or SAML protocols. The shared realm consolidates platform tools such as Argo CD, Nexus Repository, SonarQube, Report-portal, Harbor, and others as OIDC (OpenID Connect) clients.

Each component can have its own unique configurations, including Keycloak roles, groups, or client scopes.

Keycloak Roles and Groups

The diagram below provides an overview of the access control mechanisms for various tools integrated with Keycloak. It illustrates two primary methods of managing user access: Keycloak roles and Keycloak groups.

Components, highlighted in red, require additional configuration directly within the tool's UI.

info

${platform} is a placeholder for the platform name (namespace), where the KubeRocketCI is deployed.

For detailed instructions on setting up OIDC integration for various components, please refer to the following articles:

1. AWX - Community Documentation
2. DefectDojo - DefectDojo Permissions
3. Nexus - Nexus authentication process
4. Report Portal - Report Portal Keycloak Integration
5. Vault - OIDC provider configuration
6. Tekton - Tekton Dashboard Authentication
7. Gerrit - Gerrit Authentication

Roles

The shared Keycloak realm defines two composite roles:

• Administrator Role:

  • Designed for users who need administrative access to the tools used on the platform.
  • This composite role includes the administrator and sonar-administrators roles.
  • Users assigned the administrator composite role will inherit both roles.

• Developer Role:

  • Designed for users who need access to the development tools used on the platform.
  • This composite role includes the developer and sonar-developers roles.
  • Users assigned the developer composite role will inherit both roles.

These composite roles simplify the assignment of administrative and development permissions within the KubeRocketCI.

The table below provides an overview of the shared realm roles and their types:

Realm Role Name	Regular Role	Composite role
administrator		✅
developer		✅
sonar-administrators	✅
sonar-developers	✅

Groups

KubeRocketCI uses the shared realm for group management. The groups are designed to control access to various components such as Argo CD, the KubeRocketCI portal, and the EKS cluster.

Group Name	Purpose	Grants access to
ArgoCDAdmins	Administrator access to Argo CD instance	Argo CD only
ArgoCD-${platform}-users	Access to the Argo CD project mapped to the ${platform} tenant	Argo CD only
oidc-cluster-admins	Full administrator (cluster-admin) access to the kubernetes cluster	Kubernetes, cluster-wide
${platform}-oidc-admins	Administrator access to KubeRocketCI	Kubernetes and the Portal
${platform}-oidc-developers	Developer access to KubeRocketCI	Kubernetes and the Portal
${platform}-oidc-viewers	Read-only access to view resources in KubeRocketCI	Kubernetes and the Portal

These groups simplify the management of permissions and ensure that users have the appropriate level of access based on their roles and responsibilities.

warning

Platform groups and tool groups are independent of each other. Membership in ${platform}-oidc-admins, ${platform}-oidc-developers or ${platform}-oidc-viewers grants no access to Argo CD, SonarQube, Nexus or Report Portal. Those tools are authorized separately: Argo CD through its own groups and AppProject roles, SonarQube through the sonar-administrators and sonar-developers roles, and the remaining tools through their own configuration. A user normally needs membership in a platform group and in the relevant tool group or role.

note

Only a developer role, mapped to the ArgoCD-${platform}-users group, is defined in the reference AppProject. Argo CD does not ship a read-only role, so granting a user read-only access to Argo CD requires adding a dedicated role and group to the AppProject.

SonarQube OIDC

Access to SonarQube is managed through configurations in Keycloak (Keycloak Operator) and SonarQube (Sonar Operator). This section provides a detailed walkthrough for configuring access control.

Keycloak Configuration

SonarQube access is managed using Keycloak roles within the shared realm:

• sonar-developers: Grants developer access to SonarQube.
• sonar-administrators: Grants administrative access to SonarQube.

To grant access, the appropriate role must be assigned to the user in Keycloak.

Example

A user who needs developer access to SonarQube should be assigned the sonar-developers role or the developer composite role in Keycloak.

SonarQube Configuration

KubeRocketCI Sonar Operator provides a SonarQube Permission Template to manage user access and permissions for SonarQube projects.

The template is stored in the SonarQube custom resource of the operator. An example of a custom resource is shown below.

Sonar Permission Template

apiVersion: v2.edp.epam.com/v1
kind: SonarPermissionTemplate
metadata:
  name: edp-default
spec:
  name: edp-default
  description: "KubeRocketCI permission templates (DO NOT REMOVE)"
  projectKeyPattern: ".+"
  default: true
  groupsPermissions:
    view-group:
      - user
    sonar-developers:
      - user
      - securityhotspotadmin
      - issueadmin
      - codeviewer
    sonar-administrators:
      - admin
      - user
  sonarRef:
    name: sonar

The SonarQube Permission Template defines three groups: view-group, sonar-administrators, and sonar-developers:

• view-group: Users who have read-only access to the project. They can view project's data and metrics but cannot modify or interact with it.
• sonar-administrators: Users with full control over the SonarQube project. They can create, modify, delete projects, manage user access, and configure SonarQube settings.
• sonar-developers: Users actively working on the SonarQube project. They have read and write access, can modify project data and metrics, and configure project-specific settings.

These groups provide different levels of access based on the user's role and responsibilities.

info

If a user is not assigned to any group, they will be placed in the sonar-users group by default. This group does not have any permissions in the edp-default Permission Template.

Group Permissions

The following table describes the permissions assigned to each group:

Group Name	Sonar Permissions
view-group	user
sonar-administrators	admin, user
sonar-developers	codeviewer, issueadmin, securityhotspotadmin, user
sonar-users	-

Nexus Repository Manager

KubeRocketCI leverages oauth2-proxy to authenticate users in Nexus Repository Manager OSS.

The user's access level is determined by the roles assigned in Keycloak.

info

Only users with either the administrator or developer role in Keycloak can access Nexus.

The platform manages two distinct roles: edp-admin, edp-viewer.

Example of edp-admin NexusRole and NexusUser

apiVersion: edp.epam.com/v1alpha1
kind: NexusRole
metadata:
  name: edp-admin
spec:
  id: edp-admin
  nexusRef:
    name: nexus
    kind: Nexus
  name: edp-admin
  description: Read and write access to all repos and scripts
  privileges:
    - nx-apikey-all
    - nx-repository-view-*-*-add
    - nx-repository-view-*-*-browse
    - nx-repository-view-*-*-edit
    - nx-repository-view-*-*-read
    - nx-script-*-add
    - nx-script-*-delete
    - nx-script-*-run
    - nx-search-read

apiVersion: edp.epam.com/v1alpha1
kind: NexusUser
metadata:
  name: ci-user
  namespace: nexus
spec:
  email: ci.user@edp.com
  firstName: ci.user
  id: ci.user
  lastName: CI
  nexusRef:
    kind: Nexus
    name: nexus
  roles:
    - edp-admin
  secret: $ci-nexus:password
  status: active

KubeRocketCI Portal and Kubernetes Cluster

Both the KubeRocketCI Portal and the Kubernetes cluster use Keycloak groups for access control. Users must be added to the appropriate group in Keycloak to gain access. These groups are configured in the broker realm.

warning

For the Kubernetes cluster to manage access control correctly, Keycloak must be configured as an OpenID Connect (OIDC) provider. Ensure that your Keycloak setup is properly configured for OIDC before proceeding.

info

The broker realm keeps Kubernetes OIDC client.

Keycloak Groups

Each Keycloak group corresponds to a specific level of access within the Kubernetes cluster and the KubeRocketCI portal. Access is always granted per namespace: apart from oidc-cluster-admins, every group is bound with a namespaced RoleBinding rather than a cluster-wide ClusterRoleBinding. The effective permissions of a group therefore depend on which of the following three tiers is being considered:

• Platform namespace (${platform}) - where KubeRocketCI itself runs, and where Codebases, CDPipelines, Stages, PipelineRuns and platform configuration live.
• Environment namespaces - the namespaces the cd-pipeline-operator creates for each Stage, where applications are actually deployed.
• Cluster scope - cluster-scoped resources such as namespaces, nodes, customresourcedefinitions or clusterkeycloaks.

Group-to-Namespace Mapping

Group Name	Platform namespace ${platform}	Environment namespaces	Cluster scope
oidc-cluster-admins	cluster-admin	cluster-admin	cluster-admin
${platform}-oidc-admins	cluster-admin (namespace-scoped)	admin	no access
${platform}-oidc-developers	view + tenant-developer	admin	no access
${platform}-oidc-viewers	view	no access	no access

warning

${platform}-oidc-viewers is bound only in the platform namespace. Users in this group can see Codebases, CDPipelines, Stages, PipelineRuns and build logs in ${platform}, but they cannot list pods, read logs or view any workload in the environment namespaces. If read-only users need to observe deployed applications, an additional RoleBinding to the view ClusterRole has to be created in each environment namespace.

note

Group membership is additive. ${platform}-oidc-developers is a subject of both the tenant-viewer and the tenant-developer RoleBindings, so the developer permission set is the viewer permission set plus the write rules described below.

info

Because every binding except oidc-cluster-admins is a namespaced RoleBinding, the cluster-scoped resources that appear in the underlying ClusterRoles cannot be reached. This includes namespaces, nodes, persistentvolumes, storageclasses, customresourcedefinitions, and the cluster-scoped KubeRocketCI custom resources clusterkeycloaks and clusterkeycloakrealms. Only oidc-cluster-admins can read them.

The table below summarizes the groups and their associated permissions.

Group Name	View	Build	Deploy	Full Access to the Platform Namespace	Full Access to Environment Namespaces
${platform}-oidc-admins	✅	✅	✅	✅	✅
${platform}-oidc-developers	✅	✅	✅	❌	✅
${platform}-oidc-viewers	✅	❌	❌	❌	❌

View Permissions

In the KubeRocketCI portal, the following View permissions are granted to users based on their group membership:

Group Name	View Projects	View Branches	View Pipelines	View Deployments	View Environments	View Widgets	View Security	View Observability
${platform}-oidc-admins	✅	✅	✅	✅	✅	✅	✅	✅
${platform}-oidc-developers	✅	✅	✅	✅	✅	✅	✅	✅
${platform}-oidc-viewers	✅	✅	✅	✅	✅	✅	✅	✅

note

These permissions describe the Portal pages, which are rendered from the KubeRocketCI custom resources stored in the platform namespace. View Deployments and View Environments therefore mean that a user can see the CDPipeline, Stage and CDStageDeployment resources and their status. Drilling down into a deployed application - its pods, containers and logs in an environment namespace - additionally requires access to that namespace, which ${platform}-oidc-viewers does not have.

Permissions for the Configuration sections and Kubernetes resources

Permissions for Configuration sections in the KubeRocketCI portal:

Group Name	View QuickLinks	Create QuickLinks	Edit QuickLinks	Delete QuickLinks	View GitOps	Create GitOps	Delete GitOps	View Clusters	Create Clusters	Edit Clusters	Delete Clusters	View GitServers	Create GitServers	Edit GitServers	Delete GitServers	View Integrations	Create Integrations	Edit Integrations	Delete Integrations
${platform}-oidc-admins	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅
${platform}-oidc-developers	✅	❌	❌	❌	✅	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌
${platform}-oidc-viewers	✅	❌	❌	❌	✅	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌

Permissions for the most common Kubernetes resources:

Group Name	View Pods	Create Pods	Edit Pods	Delete Pods	View Deployments	Create Deployments	Edit Deployments	Delete Deployments	View Ingresses	Create Ingresses	Edit Ingresses	Delete Ingresses	View Services	Create Services	Edit Services	Delete Services	View Config Maps	Create Config Maps	Edit Config Maps	Delete Config Maps	View Cron Jobs	Create Cron Jobs	Edit Cron Jobs	Delete Cron Jobs	View Secrets	Create Secrets	Edit Secrets	Delete Secrets	View Roles	Create Roles	Edit Roles	Delete Roles	View Role Bindings	Create Role Bindings	Edit Role Bindings	Delete Role Bindings
${platform}-oidc-admins	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅
${platform}-oidc-developers	✅	❌	❌	❌	✅	❌	❌	❌	✅	❌	❌	❌	✅	❌	❌	❌	✅	✅	✅	✅	✅	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌
${platform}-oidc-viewers	✅	❌	❌	❌	✅	❌	❌	❌	✅	❌	❌	❌	✅	❌	❌	❌	✅	❌	❌	❌	✅	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌

note

The permissions in the table above apply to the platform namespace. In environment namespaces the ${platform}-oidc-admins and ${platform}-oidc-developers groups are bound to the admin ClusterRole and therefore have full access to every resource listed, including Secrets, Roles and Role Bindings, while ${platform}-oidc-viewers has no access at all. See Sensitive Capabilities.

Build Permissions

The following Build permissions are granted to users based on their group membership:

Group Name	Create Project	Edit Project	Delete Project	Create Branch	Edit Branch	Delete Branch	Build Project
${platform}-oidc-admins	✅	✅	✅	✅	✅	✅	✅
${platform}-oidc-developers	❌	❌	❌	✅	✅	✅	✅
${platform}-oidc-viewers	❌	❌	❌	❌	❌	❌	❌

Deploy Permissions

The following Deploy permissions are granted to users based on their group membership:

Group Name	Create PipelineRun	Create Deployment Flow	Edit Deployment Flow	Delete Deployment Flow	Create Environment	Edit Environment	Delete Environment	Clean Environment	Deploy Environment	Approve/Reject ApprovalTasks
${platform}-oidc-admins	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅
${platform}-oidc-developers	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅
${platform}-oidc-viewers	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌

Sensitive Capabilities

The capabilities below are the ones most often examined during an access review. PF stands for the platform namespace and ENV for the environment namespaces.

Capability	Viewers PF	Viewers ENV	Developers PF	Developers ENV	Admins PF / ENV
Read Secrets	❌	❌	❌	✅	✅
Create or modify Secrets	❌	❌	❌	✅	✅
Exec into a pod (pods/exec)	❌	❌	❌	✅	✅
Port-forward to a pod (pods/portforward)	❌	❌	❌	✅	✅
Create ServiceAccount tokens	❌	❌	❌	✅	✅
Create Roles and Role Bindings	❌	❌	❌	✅	✅
Delete workloads	❌	❌	❌	✅	✅
Read build logs (pods/log, Tekton Results)	✅	❌	✅	✅	✅
Approve or reject ApprovalTasks	❌	❌	✅	n/a	✅

warning

In environment namespaces ${platform}-oidc-developers is bound to the admin ClusterRole, which permits creating ServiceAccount tokens and impersonating ServiceAccounts inside that namespace. If a ServiceAccount in an environment namespace holds permissions wider than admin, a developer can assume that identity. Kubernetes privilege-escalation prevention still applies - a developer cannot escalate or bind roles they do not already hold - but the ServiceAccounts present in environment namespaces should be reviewed.

Cluster RBAC Resources

RBAC is created in two places. The Helm chart creates the bindings in the platform namespace, and the cd-pipeline-operator creates the binding in every environment namespace while reconciling a Stage.

Created by the Helm chart in the platform namespace ${platform}:

RoleBinding Name	Role Name	Groups
tenant-admin	cluster-admin	${platform}-oidc-admins
tenant-developer	tenant-developer	${platform}-oidc-developers
tenant-viewer	view	${platform}-oidc-viewers , ${platform}-oidc-developers

Created by the cd-pipeline-operator in every environment namespace:

RoleBinding Name	Role Name	Groups
tenant-admin	admin	${platform}-oidc-admins , ${platform}-oidc-developers

note

The tenant-admin RoleBinding in the platform namespace references the cluster-admin ClusterRole, but as a namespaced RoleBinding its effect is limited to that namespace. The tenant-admin RoleBinding created in environment namespaces references the admin ClusterRole instead. No viewer RoleBinding is created in environment namespaces.

Platform includes RBAC settings for the full cluster administration privileges.

Cluster Role Binding Name	Cluster Role Name	Group
cluster-admin	cluster-admin	oidc-cluster-admins

note

KubeRocketCI provides an aggregated ClusterRole edp-aggregate-view-${platform} with the permissions to view the KubeRocketCI custom resources. It carries the rbac.authorization.k8s.io/aggregate-to-view: "true" label, so its rules are merged into the built-in view ClusterRole and are inherited by the viewer and developer groups alike.

Customizing Group Names

Group names default to the platform namespace prefix but can be overridden:

Value	Default	Applies to
global.adminGroupName	${platform}-oidc-admins	Platform namespace and environment namespaces
global.developerGroupName	${platform}-oidc-developers	Platform namespace and environment namespaces
global.viewerGroupName	${platform}-oidc-viewers	Platform namespace only

The admin and developer values are passed to the cd-pipeline-operator as the OIDC_ADMIN_GROUP_NAME and OIDC_DEVELOPER_GROUP_NAME environment variables, so a custom name is honoured in environment namespaces as well. global.viewerGroupName has no effect outside the platform namespace, because no viewer RoleBinding is created in environment namespaces.

warning

The configured group name must exactly match the group name that reaches the Kubernetes API server in the token's groups claim. If the OIDC configuration applies a group prefix, that prefix has to be part of the value.

Grant User Access to the Created Namespaces

To provide users with admin or developer privileges for project namespaces, they need to be added to the ${platform}-oidc-admins and ${platform}-oidc-developers groups in Keycloak.

Adding a user to ${platform}-oidc-viewers does not grant access to project namespaces. Read-only access to deployed applications requires an additional RoleBinding to the view ClusterRole in each project namespace.

Verifying Effective Permissions

After assigning a group, verify that the group name reaches the cluster and that the resulting permissions are the expected ones. Run the following as the user:

# every rule the user has in the platform namespace
kubectl auth can-i --list -n <platform-namespace>

# access to a deployed application in an environment namespace
kubectl auth can-i get pods -n <environment-namespace>
kubectl auth can-i get pods/log -n <environment-namespace>

# capabilities that must not be granted to read-only users
kubectl auth can-i get secrets -n <platform-namespace>
kubectl auth can-i create pods/exec -n <environment-namespace>

A cluster administrator can check a group before onboarding anyone to it, without needing a real user, by impersonating the group:

kubectl auth can-i --list -n <platform-namespace> \
  --as=test-user --as-group=<platform-namespace>-oidc-viewers

If every check returns no, the group name carried in the token most likely does not match the RoleBinding subject.

Argo CD

In Argo CD, groups are specified when creating an AppProject to restrict access to deployed applications. To gain access to deployed applications within a project, users must be added to the corresponding Argo CD group in Keycloak. This ensures that only authorized users can access and modify applications within the project.

info

By default, only the ArgoCDAdmins group is automatically created in Keycloak.

Gerrit

Users should authenticate to Gerrit using their Keycloak credentials.

After logging into Gerrit, users are not automatically assigned to any groups. To add a user to a group, a GerritGroupMember custom resource must be created. This custom resource specifies the user's email address and the name of the group to which they should be added.

Below is an example of a GerritGroupMember custom resource:

Gerrit Group Member

apiVersion: v2.edp.epam.com/v1
kind: GerritGroupMember
metadata:
  name: user-admins
spec:
  accountId: user@user.com
  groupId: Administrators

Once the GerritGroupMember resource is created, the user will inherit the permissions and access levels associated with the specified group.

Related Articles

• KubeRocketCI Portal Overview
• EKS OIDC With Keycloak
• Argo CD Integration
• Audit Trails Setup