Role Based Access Control

Beyond the higher level permission controls provided in the Roles page of the Faros app, there are two APIs that allow granular control of which Faros report tables and collections a Faros role has access to. You can also view the Swagger docs for more information about the Pipeline Role APIs.

Please note: the terms pipeline, workspace and graph can be a little confusing but they effectively mean the same thing. Apologies for any confusion, we are actively working on cleaning this up!

Controlling Data Access

Each Faros role can be configured to have access to a different set of report tables, the tables underlying all of the charts and dashboards. This configuration can be different from one workspace to another. Roles can be granted either the all or none permission to a report table.

Table Permissions:

• all - Users that have the role with this permission on a report table can create charts using the report table, can drill into questions built on the report table and can make direct queries to the report table.
• none - Users that have the role with this permission on a report table cannot create charts using the report table, cannot drill into a question, and cannot make direct queries to the report table. However, they can still view data in a chart that is shared with them that was built using the report table!

A note on the 'none' permission

Setting a table permission to none means the role cannot query the data or build new questions but they are able to see the result of pre-created questions that others have built on a table. For example, a Faros Admin may create a dashboard that displays information about the average cycle time for PRs. If a different role has 'none' access to the PR table, and they have access to the dashboard the admin created, they will be able to see the average PR cycle time but won't be able to drill into specifics about individual PR stats.

If you wish to go further and lock down all references to PR data you would need to restrict access to all of the existing charts built on PR data as well as setting the none permission on the PR table. See more information here.

GET /reports/pipeline/{id}/roles/{role}/data

You can easily control report table permissions by role via API. First you will need to determine the pipeline ID that corresponds to the Faros workspace that you wish to update. You can retrieve the pipeline ID from this step. Now you can retrieve the data permissions for a role for all the report tables for the given pipeline. Note: the main schema is the only schema that is currently used so you can ignore it other than when structuring the request for the PUT.

{
  "role": "viewer",
  "pipeline": "AAAABBBB",
  "permissions": {
    "data": {
      "schemas": {
        "main": [
          {
            "tableId": 1234,
            "tableName": "Activity Log",
            "permission": "all"
          },
          {
            "tableId": 5678,
            "tableName": "Application Ownership",
            "permission": "all"
          },
          ...
        ]
      }
    }
  }
}

PUT /reports/pipeline/{id}/roles/{role}/data

The PUT call updates the permissions for the provided tables. Use the GET response as the starting point for any updates that you would like to make as it will provide you the form and ids that you need to supply in the body of the PUT. You need only provide the tables you would like to update:

{
  "permissions": {
    "data": {
      "schemas": {
        "main": [
          {
            "tableId": 1234,
            "tableName": "Activity Log",
            "permission": "none"
          }
        ]
      }
    }
  }
}

This request sets the none permission for the Activity Log report table for users with the specified role without changing any of the other table permissions

If you want to update every table at once, instead of setting permissions at the table level, you can set the permission at the schema level:

{
  "permissions": {
    "data": {
      "schemas": {
        "main": "none"
    }
  }
}

This sets the none permission for ever table for users with the specified role

Controlling Collection Access

Like report tables, each Faros role can be configured to have access to certain collections. This configuration can also be setup differently from one workspace to the next. Roles can be granted either the read, write, or none permission to a collection.

Collection Permissions:

• read - Users that have the role with this permission for a collection can view the collection and its contents
• write- Users that have the role with this permissions for a collection can edit the collection and its contents
• none- Users that have the role with this permission for a collection cannot view a collection or its contents

GET /reports/pipelines/{id}/roles/{role}

You can easily control collection permissions by role via API. First you will need to determine the pipeline ID that corresponds to the Faros workspace that you wish to update. You can retrieve the pipeline ID from this step. Now you can retrieve the collection permissions for a role for all the collections in the given pipeline.

{
  "role": "viewer",
  "pipeline": "AAAABBBB",
  "permissions": {
    "collections": [
      {
        "id": 123,
        "path": "/Custom reports",
        "name": "Custom reports",
        "permission": "read"
      },
      {
        "id": 456,
        "path": "/Faros reports",
        "name": "Faros reports",
        "permission": "read"
      },
      {
        "id": 789,
        "path": "/Faros reports/DevOps Management",
        "name": "DevOps Management",
        "permission": "read"
      }
    ]
  }
}

PUT /reports/pipelines/{id}/roles/{role}

The PUT updates the permissions for the provided collections and their children. Use the GET response as the starting point for any updates that you would like to make as it will provide you the form and ids that you need to supply in the body of the PUT. When you update a parent collection, unless you specify a different permission for a child collection, all of the updated parent collection's children will inherit the new permission.

{
  "permissions": {
    "collections": [
      {
        "id": 123,
        "path": "/Custom reports",
        "name": "Custom reports",
        "permission": "none"
      },
      {
        "id": 456,
        "path": "/Faros reports",
        "name": "Faros reports",
        "permission": "none"
      },
      {
        "id": 789,
        "path": "/Faros reports/DevOps Management",
        "name": "DevOps Management",
        "permission": "read"
      }
    ]
  }
}

This request sets the none permission for both the /Custom reports and /Faros reports collections. All of the children in the /Custom reports collection will inherit the none permission. Every child in the /Faros reports collection will inherit the none permission except /Faros reports/DevOps Management as it is explicitly being set to read. When a parent of a collection is set to none but a role still has read or write access to a child collection, the child collection will appear to the user within the first parent the user's role has access to (this might be the root collection).

Getting a pipeline ID

To determine the pipeline ID, you can make the following API request to list all pipelines that you have access to. Note the id of the pipeline with the graph value of the Faros graph/workspace you wish to update. You will need to authenticate with an API key or your current JWT.

GET /reports/pipelines

[
  {
    "id": "AAAABBBB",
    "tenant": "acme",
    "graph": "default",
    "status": "ACTIVE_IDLE",
    "statusCategory": "ACTIVE",
    "statusUpdatedAt": 1722861229823,
    "createdAt": 1718133859333,
    "updatedAt": 1722861229824
  }
]

In the above example, the pipeline ID is AAAABBBB

How to prevent a role from seeing data in a report table entirely

If you want to restrict a role from seeing data in a Faros report table, you will need to do the following:

1. Create a new collection. This collection will be restricted from the role in the next step
2. Restrict the collection so the role cannot access it. See Controlling Collection Access
3. Move all charts and dashboards that use the restricted report table into the restricted collection
4. Set the role's data permissions to none for the table(s) you would like to restrict. See Controlling Data Access

Restricting permissions can affect the product

When you restrict report tables for roles, this can affect functionality within the Faros app. The following chart shows which feature will be impacted if you restrict access to a table.

Note: For team pages, not all widgets need to be enabled. You can restrict data permissions for widgets that are not being used by your teams without impact.