---
title: "Role-based access control (RBAC)"
description: ""
url: "https://docs.itrsgroup.com/docs/itrs-analytics/platform/2.18.0/install/advanced-keycloak/keycloak-rbac/index.html"
---

**Note**


Please use the [ITRS Analytics IAM app](https://docs.itrsgroup.com/docs/itrs-analytics/app/iam/current/user-guide/iam-configuration/index.html) to manage user access, roles, and permissions across the ITRS Analytics platform. It provides centralized authentication and integration with identity providers.



## Resources and scopes for ITRS Analytics services

The ability of a user to read or modify data is centered around the concept of `Entities` in ITRS Analytics. Entities represent physical or logical items that have metric data associated with them -- for example, a specific set of server nodes. For more information, see [Data model in Architecture](https://docs.itrsgroup.com/docs/itrs-analytics/platform/2.18.0/getting-started/architecture/index.html#data-model).

It is possible to restrict the visibility of data in the ITRS Analytics platform so that a user can only access the metric data for specific severs by creating rules that allow a user to view only entities with specified attributes. In addition to viewing the data in the platform, it is possible to directly modify Entity objects, or to change the rules which govern Entity structure and hierarchy. Therefore, you may want to restrict this capability to only admins or a set of power users.

Keycloak has the concepts of [resources and scopes](https://www.keycloak.org/docs/latest/authorization_services/#_overview_terminology) where `resources` represent something that is protected (for example, a service, API or application), and `scopes` generally represent the actions or aspects of the resource that a user is permitted to have access to.

The following resources are used in ITRS Analytics:

- The `entities` resource protects the visibility of data using the `scopes`:
  - `read` (full access), or
  - scopes defined as `expressions` (partial access).

- The `entity-management` resource protects the services which enable the modification of entities using the `scopes`:
  - `read` scope allowing a user to view the rules which can modify entities
  - `write` scope to allow modifying the Entities directly or indirectly using rules

When a user successfully authenticates (for example, by logging into the UI) in ITRS Analytics with a username and password, an access token is issued to the client browser. This token is used by ITRS Analytics internally to determine what resources and scopes are permitted for this user when using any functionality.

### Entity service

The `Entity Service` is an internal API used by applications in ITRS Analytics to fetch the entities currently in the platform and 
also to modify these entities either directly or indirectly.

Entity Service methods that allow this modification are protected by the `entity-management` resource
with the `write` scope:

```
ModifyEnrichmentRulesets
ModifyContainmentRules
ModifyAttributes
```

Fetching enrichment or containment rulesets created with the above methods requires the `entity-management` resource
with the `read` scope:

```
GetContainmentRules
GetEnrichmentRulesets
```

The other `Entity Service` methods allow fetching of the entities currently in the platform, or sub-elements of them.
These are protected by the `entities` resource and the `read` scope provided a complete view of all entities in the platform.

This resource also supports configuration of custom scopes in the form of entity expressions which provide a mechanism
to enforce policy permissions for a user or groups of users that restricts the view of entities returned from the following
service methods.

```
GetNames
GetValues
Query
Subscribe
```

### Metric Query service

The `Metric Query Service` is used internally in the ITRS Analytics platform for querying the time-series metric data that is displayed in the ITRS Analytics UI. All of this service's methods are protected by the `entities` resource with the `read` scope.

The view of the metrics returned from the service can also be restricted in the same way as `entities` above,
[Expression Scopes](#expression-scopes).

## Configuration

The configuration of authorisation for ITRS Analytics services is currently performed via the Keycloak UI directly. This is
accessible via `https://<external-obcerv-hostname>/auth`.

In the ITRS Analytics realm, you can view the current resources by navigating to:
```
Clients -> obcerv-platform -> Authorisation -> Resources
```

An out-of-the-box ITRS Analytics install should have the following default resources with attached scopes and
permissions:

> ![ITRS Analytics Platform Client Default Resources Image](https://docscdn.itrsgroup.com/obcerv-platform/images/thirdparty/default_resources.png)

The default permissions attached to each resource grant full read access to `entities`,
`read/write` permissions for `entity-management`, and full `read` access to metric queries for all users created within the ITRS Analytics realm.

## Restrictive vs permissive

Access to either the Entity or Metric query services requires the `entities` resource privilege and the `read`
scope, therefore to remove or limit access to the data returned from these services the `read` scope must be denied
to a user or group. Depending on the desired behaviour of the platform authorisation, one of two approaches can be taken:

1. Restrictive — Take a restrictive approach and delete the default permissions which are granting all users/groups in the ITRS Analytics realm
  this `read` scope. With this approach no users will have any access to the relevant services, therefore it requires
  creating explicit policies and permissions to grant full or partial access to the view of the data.

2. Permissive — Leave these default policies and permissions in place and take a permissive approach.
  Either creating restrictive policies to deny particular users or groups this scope or allow a limited view of the
  data through expressions or both. With this approach all users in the realm will, by default, have full access, but specific users/groups can be restricted.

## Expression scopes
Scopes in Keycloak are freeform text. It is possible to create custom scopes for the `entities` resources which take the form of `Expressions` (see [Syntax](#expression-syntax)).

When these are then applied to users or groups through policies or permissions they can enforce a limited view of the data in the platform. Expression scopes are evaluated against both the attributes and dimensions of the entities (or the entities associated with a time-series in the case of metrics) in the platform to determine what data should be returned from a service.

For example, given the following entities:

`Entity 1`
```
{
  "entity": {
    "dimensions": {
      "hostname": "host-1",
      "pod": "pod-1"
    },
    "attributes": [
      {
        "namespace": "itrs",
        "name": "department",
        "value": {
          "string": "support"
        }
      }
    ]
  }
}
```

`Entity 2`
```
{
  "entity": {
    "dimensions": {
      "hostname": "host-1",
      "pod": "pod-2"
    },
    "attributes": [
      {
        "namespace": "itrs",
        "name": "department",
        "value": {
          "string": "engineering"
        }
      }
    ]
  }
}
```

It is possible to create Expression scopes to match against `Entity 1`, for example against one of its attributes:

Matches `Entity 1` Only:
```
department=support
```

Or, matching against its dimensions:

Matches `Entity 1` Only:
```
pod=pod-1
```

Multiple scopes can be applied, however they are each evaluated independently with an `OR` logic operator,
meaning if any scope expression matches an entity this will allow the entity or metrics service to return this data.

For example, if a user/group had two resource scopes:

Matches both `Entity 1` and `Entity 2`:
```
hostname=host-1
pod=pod-2
```

This would match both entities as they are evaluated independently - `Entity 1` matches on `hostname=host-1` and
`Entity 2` matches on both `hostname=host-1` and `pod=pod-2`. If instead the desired behaviour is for the scope for a user/group to only match if both of these dimensions are present for an entity, then it would require the use of more complex scope syntax and combine the conditions into a single scope, becoming:

Matches `Entity 2` Only:
```
hostname=host-1 and pod=pod-2
```

## Using negative logic and multiple scopes

Given that scopes are evaluated individually against entities, caution should be used when using negative conditions as they can negate other scopes which may be applied to a user/group through a permission and policy.

For example, given a resource scope expression of:

```
pod != pod-1
```

A client request to a service protected by this resource would return entities which don't have a `pod=pod-1` attribute or dimension - only `Entity 2` in the examples above.

However, adding another negative condition match scope, against `Entity 2` this time, and applying it to the same resource and user/group:

```
pod != pod-1
pod != pod-2
```

Rather than return no entities, as the scopes are evaluated separately, the first scope would match `Entity 2`, and
the second scope would match on `Entity 1`, meaning both entities/metrics would be returned in results from a service.

### Expression syntax

The full syntax for expressions is described in [Expressions](https://docs.itrsgroup.com/docs/itrs-analytics/platform/2.18.0/getting-started/query-lang/index.html).

## Worked example
The following is the process to implement authorisation for the `Metric Query Service` to add a user to the system and to
restrict their view to a subset of metrics to entities for specific Kubernetes containers.

This example takes the approach of retaining the default of allowing all other users in the realm to have an
unrestricted view of all the platform's metrics (see [Restrictive vs Permissive](#restrictive-vs-permissive)).

1. Navigate to the `itrs-analytics` realm in Keycloak - click `itrs-analytics` in the top-left drop down menu.

2. Add a new user if required, or apply the policies and permissions below to an existing user in this realm.
    - To add a new user, navigate to `Users -> Add User`. Specify a `Username`, and click `Save`.
    ![Add a user in Keycloak](https://docscdn.itrsgroup.com/obcerv-platform/images/thirdparty/keycloak-add-user.gif)
    - Navigate to `Credentials` and set a password for the user. 
    ![Change User Password in Keycloak](https://docscdn.itrsgroup.com/obcerv-platform/images/thirdparty/keycloak-update-password.gif)

3. Navigate to  `Clients -> obcerv-platform -> Authorisation`.

4. To create a policy for this user with `Positive` logic that will be used to allow permission scopes, navigate to `Policies -> Create Policy -> User` and enter the following and click `Save`.
    ```
    Name:    allow-test-user-1
    Users:   test-user-1
    Logic:   Positive
    ```

5. Create a policy for this user with `Negative` logic that will be used to deny permission scopes. Navigate to `Policies -> Create Policy -> User` and enter the following and click `Save`.
    ```
    Name:    deny-test-user-1
    Users:   test-user-1
    Logic:   Negative
    ```

6. Create an expression-based authorisation scope. Navigate to `Authorization Scopes -> Create` and enter the following and click `Save`.
    ```
    Name: container in ('platformd', 'kafka', 'final-entity-stream')
    ```

7. Update the `entities` resource to add the new authorisation scope. Navigate to `Resources -> entities -> Scopes` and add the `container in ('platformd', 'kafka', 'final-entity-stream')` scope and click `Save`.

8. Create a new permission to `deny` a user the `read` scope for the resource. Navigate to `Resources -> Permissions -> Create Permission -> Scope-Based`,enter the following and click `Save`.
    ```
    Name:                deny-entities-read-scope
    Resource:            entities
    Scopes:              read
    Apply Policy:        deny-test-user-1
    Decision Strategy:   Unanimous
    ```

9. At this point the user has no scopes available and will have no permissions to view any metrics from the query service. Now add a permission to allow the authorisation scope created above. Navigate to `Resources -> Permissions -> Create Permission -> Scope-Based`, enter the following and click `Save`.
    ```
    Name:                allow-containers-for-test-user-1
    Resource:            entities
    Scopes:              container in ('platformd', 'kafka', 'final-entity-stream')
    Apply Policy:        allow-test-user-1
    Decision Strategy:   Unanimous
    ```

10. Log in to the ITRS Analytics web console with this user and access a dashboard view of metrics for containers, the view should be restricted to only those in the authorisation scope, for example:
    ![Verify Dashboard View](https://docscdn.itrsgroup.com/obcerv-platform/images/thirdparty/verify_dashboard.png)

## ITRS Analytics app permissions

After creating a client for ITRS Analytics apps (for example, `obcerv-apps`), you can manage permissions for each role that has access to an app.

1. From the **Authorization** > **Resources** tab, click **Create resource**.

2. Assign names that reflect functionalities in the app (for example, `forecaster-config-management` and `forecaster-forecast-management`).

3. On each resource, use **Authorization scopes** to define access levels such as `read` and `write`. 
  ![Add resources in Keycloak](https://docscdn.itrsgroup.com/obcerv-platform/images/thirdparty/keycloak-resources-sample.png)

4. On the **Permissions** tab, associate the created resources with their corresponding roles and assign appropriate policies.
  ![Permissions](https://docscdn.itrsgroup.com/obcerv-platform/images/thirdparty/keycloak-permissions-tab.png)

Set up the RBAC policies as follows:

### Signal Forecaster

| Permission     | Admin    | End-user |
|----------------|----------|----------|
| Add configs    | ✓        |         |
| View configs   | ✓        | ✓       |
| Edit configs   | ✓        | ✓       |
| Delete configs | ✓        |         |
| Save configs   | ✓        |         |

## Keycloak evaluate

A useful tool exists within the Keycloak UI which allows debugging of how the various policies and permissions will resolve for a user and resource. For the worked example above, enter the following to evaluate what `scopes` are granted for the `entities` resource for `test-user-1` and click `Evaluate`:
```
Client:     obcerv-platform
User:       test-user-1
Resources:  entities
```

![Keycloak Evaluate](https://docscdn.itrsgroup.com/obcerv-platform/images/thirdparty/keycloak_evaluate.png)

The output shows how the various policies created have been resolved, the
`read` scope has been denied for this user and the `container in ('platformd', 'kafka', 'final-entity-stream')` is allowed.

![Keycloak Evaluate Result](https://docscdn.itrsgroup.com/obcerv-platform/images/thirdparty/keycloak_evaluate_result.png)

