Migrate from RBAC v1 to RBAC v2

Under Construction

We are working on improving the documentation

This is a guide for the first phase of migration of existing Insights applications from RBACv1 to Kessel. In this initial phase, the goal is to start using Kessel for authorization enforcement while keeping parity with the current behaviors. Further “workspacification” (i.e. making assets other than hosts workspace-aware) is out of scope for the initial phase and this guide.

Questions? Please raise them in #mgmt-fabric-insights-integrations

Identify the patterns

We start the migration process by identifying the patterns used by our application. Refer to KSL-016: Migrating host and organization level permissions for more information about the patterns.

Note that an application may fall under more than one of these patterns. For example, an application may use a combination of:

• permission protecting access to an org-wide setting
• permission protecting access to inventory group aware assets (e.g. host vulnerabilities)

The patterns identified for each application are tracked in Insights | Kessel Requirements - Service Resource & Permissions Data

Model the permissions

Afterwards, we need to convert permission definitions from the legacy format to permission definitions expressed using the ksl language. More information about modeling permissions with the ksl language can be found in Design permissions schema.

Example definition of permissions that follow the Root workspace pattern (protecting org-wide settings):

version 0.1
namespace config_manager

import rbac

@rbac.add_v1_based_permission(app:'config_manager', resource:'profile', verb:'read', v2_perm:'config_manager_profile_view');
@rbac.add_v1_based_permission(app:'config_manager', resource:'profile', verb:'write', v2_perm:'config_manager_profile_edit');

Example definition of permissions that follow the Native, workspace-level list pattern (protecting patches applicable to a host, which are workspace-aware assets)

version 0.1
namespace patch

import rbac
import hbi

@rbac.add_v1_based_permission(app:'patch', resource:'system', verb:'read', v2_perm:'patch_system_view_assigned');
@rbac.add_contingent_permission(first: 'inventory_host_view', second: 'patch_system_view_assigned', contingent: 'patch_system_view');
@hbi.expose_host_permission(v2_perm: 'patch_system_view', host_perm: 'patch_system_view');

@rbac.add_v1_based_permission(app:'patch', resource:'system', verb:'write', v2_perm:'patch_system_edit_assigned');
@rbac.add_contingent_permission(first: 'inventory_host_view', second: 'patch_system_edit_assigned', contingent: 'patch_system_edit');
@hbi.expose_host_permission(v2_perm: 'patch_system_edit', host_perm: 'patch_system_edit');

The permission definitions from ksl files are transpiled into a zed schema.

Tip: Play with the schema

A good way to understand the resulting schema is by tinkering and evaluating different scenarios and test data is by loading the generated schema into SpiceDB Playground.

Role definitions

Note that the way these permissions are associated with a role remains the same, i.e. via role files.

In some cases a completely new permission may be defined in the process of onboarding to Kessel. In that case, consider defining this permission in RHEL persona-based roles (e.g. RHEL Viewer) in addition to application-specific roles (e.g. Advisor Viewer). See RHCLOUD-35891 for additional details.

Implement the changes in the application code

The implementation part typically consists of the following steps:

1. Import the Kessel client library
2. Implement the authorization check in the application code
3. Add tests
4. Add configuration options for the Kessel client

Importing the client library

Kessel client libraries are available for these languages:

• Java
• golang
• Python

Why gRPC and not REST?

In case you are wondering why the Kessel clients use gRPC to communicate with Kessel services instead of REST, take a look at AUTHZ-005: gRPC vs. REST for platform RBAC Relation API calls

Implement the authorization check in the application code

The authorization check is typically implemented at the middleware layer. The actual implementation differs based on the selected pattern(s).

Root/Default workspace pattern

The implementation of root workspace pattern and default workspace pattern starts with a lookup of the default/root workspace id for the given organization.

The workspace ID can be obtained from the RBAC service via a REST call:

GET /v2/workspaces?type=root
GET /v2/workspaces?type=default

The default/root workspace for a given organization is guaranteed to never change and is therefore easily cacheable. However, in the future the need to look up the default/root workspace ID will be resolved transparently on the Kessel side. There is therefore no need to implement the caching code in the application code at this time.

With the workspace id resolved, the authorization check call can be made to Kessel. The actual method called depends on the nature of the operation.

Use CheckForUpdate for performing authorization check for

• any write operations
• highly-sensitive read operations (e.g. access to read credentials for connecting to a customer’s cluster)

In all other cases, use Check.

The parameters provided for the Check/CheckForUpdate request for the Root/Default workspace pattern should be structured as follows:

object := &kesselv2.ResourceReference{
  ResourceType: "workspace",
  ResourceId:   defaultOrRootWorkspaceID,
  Reporter: &kesselv2.ReporterReference{
    Type: "rbac",
  },
}

relation = // the permission to check for

subject := &kesselv2.SubjectReference{
  Resource: &kesselv2.ResourceReference{
    ResourceType: "principal",
    ResourceId:   fmt.Sprintf("redhat/%s", principalID),
    Reporter: &kesselv2.ReporterReference{
      Type: "rbac",
    },
  },
}

Supporting all principal types

Note that the principalID will differ based on the type of the principal:

• user principal - identity.User.UserId
• service account - identity.ServiceAccount.UserId

Default workspace pattern implementations and PoCs:

• Config Manager
• Resource Optimization Service
• Advisor

See Default workspace for additional information.

Native, workspace-level list

The Native, workspace-level list pattern is typically implemented by resolving the ids of all the workspaces for which the given principal possesses the given permission and then using these workspace ids to filter the assets in application database query.

The workspace ids are obtained using the StreamedListObjects method and its parameters should be defined as follows:

objectType := &kesselv2.RepresentationType{
  ResourceType: "workspace",
  ReporterType: "rbac",
},

relation = // the permission to check for

subject := &kesselv2.SubjectReference{
  Resource: &kesselv2.ResourceReference{
    ResourceType: "principal",
    ResourceId:   fmt.Sprintf("redhat/%s", principalID),
    Reporter: &kesselv2.ReporterReference{
      Type: "rbac",
    },
  },
}

Supporting all principal types

Note that the principalID will differ based on the type of the principal:

• user principal - identity.User.UserId
• service account - identity.ServiceAccount.UserId

Native, workspace-level list pattern implementations and PoCs:

• Digital Roadmap
• Resource Optimization Service
• Malware
• Advisor

See Native, workspace-level list for additional information.

Adding tests

TBD

Example of a testcase for Kessel integration

Add configuration options for the Kessel client

The application should add the following configuration options for Kessel:

• KESSEL_ENABLED
• KESSEL_URL
• KESSEL_AUTH_ENABLED
• KESSEL_AUTH_CLIENT_ID
• KESSEL_AUTH_CLIENT_SECRET
• KESSEL_AUTH_OIDC_ISSUER
• KESSEL_INSECURE

The ClowdApp template should also be updated accordingly to enable environment-specific configuration. See Config Manager’s configuration for an example.

Validate the changes

• see Ephemeral Deployments with Kessel Inventory API for information on how to deploy Kessel in the ephemeral environment.
• insights-service-deployer is a feature-rich script for end-to-end deployment and configuration of Kessel related services in the ephemeral environment.

Deploy the changes

Follow Using Kessel in production to set up your service to use Kessel in stage and prod.