Skip to main content
This page covers Control Plane permissions - policies that control access to Formal’s web interface and APIs. For policies that control data access through Connectors (like database query policies), see the Policies section.

​
Introduction

Formal’s permission system is built on the Open Policy Agent (OPA), allowing you to restrict user access to specific applications through Rego policies. By defining granular permissions, you can ensure users have access only to the applications necessary for their roles and responsibilities. These permissions are enforced against our API endpoints.

​
Default permissions

Upon account creation, Formal operates under an allow-by-default model. Meaning, by default, if no permission blocks an endpoint for a given user, then the endpoint is allowed.

​
Permission Model

Unlike other software products, Formal does not have the traditional concept of Roles. Instead, users can leverage Permissions to create role based access control (RBAC) using your organization’s Groups (which can be SCIM provisioned from your IDP into Formal).

​
User experience when blocked

The Formal APIs will return HTTP 403 error status codes if a user is blocked on a particular endpoint. Users who are interacting with the Formal APIs through the Control Plane will experience “Forbidden” toasts or dialogs.

​
List of inputs

You can block or allow requests based on the following user and application inputs:

​
User inputs

  • input.user.id
  • input.user.name
  • input.user.first­_name
  • input.user.last­_name
  • input.user.email
  • input.user.groups
  • input.user.ip­_address

​
Application inputs

  • input.app.name
  • input.app.command.name
  • input.app.command.type

​
List of command types

Here is a table listing all command types that can be used. If the API call contains the operation, then it is categorized as the corresponding type.
TypeOperations
readGet, List
createCreate
updateUpdate
deleteDelete
loginLogin

​
List of applications

API endpoints are segmented into Applications. Here is a table listing all applications that can be configured for access permissions:
NameDescription
AccessGive access to managing user access tokens.
ConnectorGive access to Formal Connectors.
DashboardGive access to dashboards and account overview.
DesktopGive access to the Formal Desktop app features and settings.
DeveloperGive access to developer setting and API credentials.
DirectorySyncGive access to directory sync configuration.
DSPMGive access to DSPM features and findings.
GroupGive access to group management and permissions.
IntegrationBIGive access to Business Intelligence integrations (e.g. Metabase).
IntegrationCloudGive access to all cloud integrations (e.g. AWS).
IntegrationMDMGive access to MDM integrations.
IntegrationsLogGive access to all log integrations (e.g. Splunk).
InventoryGive access to the Formal Data Inventory.
LogsGive access to all logs.
PermissionsGive access to manage permissions.
PoliciesGive access to policies.
PolicyDataLoaderGive access to policy data loaders.
ResourceGive access to resources.
SatelliteGive access to satellites.
SessionsGive access to user session recordings.
SidecarAn older app that is similar to the Connectors app.
SlackGive access to Slack integration management.
SpaceGive access to Space (workspace) management.
SsoGive access to Single Sign-On (SSO) management.
TrackersGive access to row level trackers.
UserGive access to user management and administration.
VersionGive access to version and build information.

​
Example

Below is an example of a Rego policy that grants access to the Sessions application exclusively for users in the admin group. 

package formal.app

import future.keywords.in

default allow = false

allow := true {
    input.app.name == "Sessions"
    "admin" in input.user.groups
}
This policy sets the default access to false, meaning no access is granted unless specified by a rule. The allow rule checks if the application requested is Sessions and if the user belongs to the admin group. If both conditions are met, access is granted.