Hide navigation sidebar
Hide table of contents sidebar
Back to top
Toggle table of contents sidebar

# Authorization

When interacting with Incus over the Unix socket, members of the `incus-admin` group will have full access to the Incus API. Those who are only members of the `incus` group will instead be restricted to a single project tied to their user.

When interacting with Incus over the network (see How to expose Incus to the network for instructions), it is possible to further authenticate and restrict user access. There are two supported authorization methods:

- TLS authorization

- Open Fine-Grained Authorization (OpenFGA)

## TLS authorization

Incus natively supports restricting Trusted TLS clients to one or more projects. When a client certificate is restricted, the client will also be prevented from performing global configuration changes or altering the configuration (limits, restrictions) of the projects it’s allowed access to.

To restrict access, use `incus config trust edit <fingerprint>`. Set the `restricted` key to `true` and specify a list of projects to restrict the client to. If the list of projects is empty, the client will not be allowed access to any of them.

This authorization method is always used if a client authenticates with TLS, regardless of whether another authorization method is configured.

## Open Fine-Grained Authorization (OpenFGA)

Incus supports integrating with OpenFGA. This authorization method is highly granular. For example, it can be used to restrict user access to a single instance.

To use OpenFGA for authorization, you must configure and run an OpenFGA server yourself. To enable this authorization method in Incus, set the `openfga.*` server configuration options. Incus will connect to the OpenFGA server, write the OpenFGA model, and query this server for authorization for all subsequent requests.

### OpenFGA model

With OpenFGA, access to a particular API resource is determined by the user’s relationship to it. These relationships are determined by an OpenFGA authorization model. The Incus OpenFGA authorization model describes API resources in terms of their relationship to other resources, and a relationship a user or group might have with that resource. Some convenient relations have also been built into the model:

- `server -> admin`: Full access to Incus.

- `server -> operator`: Full access to Incus, without edit access on server configuration, certificates, or storage pools.

- `server -> viewer`: Can view all server level configuration but cannot edit. Cannot view projects or their contents.

- `project -> manager`: Full access to a single project, including edit access.

- `project -> operator`: Full access to a single project, without edit access.

- `project -> viewer`: View access for a single project.

- `instance -> manager`: Full access to a single instance, including edit access.

- `instance -> operator`: Full access to a single instance, without edit access.

- `instance -> user`: View access to a single instance, plus permissions for `exec`, `console`, and `file` APIs.

- `instance -> viewer`: View access to a single instance.

Important

Users that you do not trust with root access to the host should not be granted the following relations:

- `server -> admin`

- `server -> operator`

- `server -> can_edit`

- `server -> can_create_storage_pools`

- `server -> can_create_projects`

- `server -> can_create_certificates`

- `certificate -> can_edit`

- `storage_pool -> can_edit`

- `project -> manager`

The remaining relations may be granted. However, you must apply appropriate Project restrictions.

The full Incus OpenFGA authorization model is defined in `internal/server/auth/driver_openfga_model.openfga`:

    model
      schema 1.1
    type user
    type group
      relations
        define member: [user]
    type server
      relations
        define admin: [user, group#member]
        define operator: [user, group#member] or admin
        define viewer: [user, group#member] or operator
        define user: [user:*]
        define can_edit: admin
        define can_view: user
        define can_create_storage_pools: [user, group#member] or admin
        define can_create_projects: [user, group#member] or operator
        define can_view_resources: [user, group#member] or viewer
        define can_create_certificates: [user, group#member] or admin
        define can_view_metrics: [user, group#member] or viewer
        define can_override_cluster_target_restriction: [user, group#member] or admin
        define can_view_privileged_events: [user, group#member] or admin
    type certificate
      relations
        define server: [server]
        define can_edit: [user, group#member] or admin from server
        define can_view: user from server
    type storage_pool
      relations
        define server: [server]
        define can_edit: [user, group#member] or admin from server
        define can_view: user from server
    type project
      relations
        define server: [server]
        define manager: [user, group#member] or operator from server
        define operator: [user, group#member] or manager or operator from server
        define viewer: [user, group#member] or operator
        define can_edit: manager
        define can_view: viewer
        define can_create_images: [user, group#member] or operator or operator from server
        define can_create_image_aliases: [user, group#member] or operator or operator from server
        define can_create_instances: [user, group#member] or operator or operator from server
        define can_create_networks: [user, group#member] or operator or operator from server
        define can_create_network_acls: [user, group#member] or operator or operator from server
        define can_create_network_zones: [user, group#member] or operator or operator from server
        define can_create_profiles: [user, group#member] or operator or operator from server
        define can_create_storage_volumes: [user, group#member] or operator or operator from server
        define can_create_storage_buckets: [user, group#member] or operator or operator from server
        define can_view_operations: [user, group#member] or viewer
        define can_view_events: [user, group#member] or viewer
    type image
      relations
        define project: [project]
        define can_edit: [user, group#member] or operator from project
        define can_view: [user, group#member] or can_edit or viewer from project
    type image_alias
      relations
        define project: [project]
        define can_edit: [user, group#member] or operator from project
        define can_view: [user, group#member] or can_edit or viewer from project
    type instance
      relations
        define project: [project]
        define manager: [user, group#member]
        define operator: [user, group#member] or manager
        define user: [user, group#member] or operator
        define viewer: [user, group#member] or operator
        define can_edit: manager or operator from project
        define can_view: user or viewer or viewer from project
        define can_update_state: [user, group#member] or operator or operator from project
        define can_manage_snapshots: [user, group#member] or operator or operator from project
        define can_manage_backups: [user, group#member] or operator or operator from project
        define can_connect_sftp: [user, group#member] or user or operator from project
        define can_access_files: [user, group#member] or user or operator from project
        define can_access_console: [user, group#member] or user or operator from project
        define can_exec: [user, group#member] or user or operator from project
    type network
      relations
        define project: [project]
        define can_edit: [user, group#member] or operator from project
        define can_view: [user, group#member] or can_edit or viewer from project
    type network_acl
      relations
        define project: [project]
        define can_edit: [user, group#member] or operator from project
        define can_view: [user, group#member] or can_edit or viewer from project
    type network_zone
      relations
        define project: [project]
        define can_edit: [user, group#member] or operator from project
        define can_view: [user, group#member] or can_edit or viewer from project
    type profile
      relations
        define project: [project]
        define can_edit: [user, group#member] or operator from project
        define can_view: [user, group#member] or can_edit or viewer from project
    type storage_volume
      relations
        define project: [project]
        define can_edit: [user, group#member] or operator from project
        define can_view: [user, group#member] or can_edit or viewer from project
        define can_manage_snapshots: [user, group#member] or can_edit
        define can_manage_backups: [user, group#member] or can_edit
    type storage_bucket
      relations
        define project: [project]
        define can_edit: [user, group#member] or operator from project
        define can_view: [user, group#member] or can_edit or viewer from project