Skip to content
Tutorials Center
My learning

Topics

Lesson 27 of 39 ยท Security and Permissions

Capabilities and Permissions in Tauri 2

Learn how Tauri 2 capabilities, permissions and permission sets decide what each window may call. Covers file layout, platforms, remote URLs, deny rules and a runnable resolver stand-in.

In Tauri 2 the frontend cannot call a command just because the command exists. A request is allowed only if a capability grants a matching permission to the window that sent it. This one rule is the center of Tauri's security story, and once you understand it, errors such as "not allowed by ACL" turn from mysterious into trivial.

This lesson shows the file format, the three building blocks (permission, permission set, capability), how to target windows and platforms, and how a request is resolved. It follows The Tauri Security Model and leads into Scopes and Input Validation.

Real versus stand-in. The JSON and TOML are real Tauri 2 configuration. The runnable block is a JavaScript model of how permissions are resolved, written for learning.

The three building blocks

  • A permission allows or denies one or more commands, optionally with a scope. Example: fs:allow-read-text-file, dialog:deny-open.
  • A permission set bundles permissions under one name. Example: fs:default, core:window:default.
  • A capability is a file that says which windows receive which permissions.

Permission identifiers follow <plugin>:<name>. Names beginning with allow- or deny- are generated for each command (command read_text_file becomes allow-read-text-file). Core features use the core: prefix, for example core:window:allow-set-title and core:event:default.

Capability files

Every file in src-tauri/capabilities/ (JSON, JSON5 or TOML) is loaded automatically. A typical one:

JSON
{
  "$schema": "../gen/schemas/desktop-schema.json",
  "identifier": "main-capability",
  "description": "Permissions for the main window",
  "windows": ["main"],
  "permissions": [
    "core:default",
    "core:window:allow-set-title",
    "dialog:default",
    "store:default",
    {
      "identifier": "fs:allow-read-text-file",
      "allow": [{ "path": "$APPDATA/**" }]
    }
  ]
}
  • identifier must be unique.
  • windows lists window labels. A glob such as "*" matches every window; avoid it. Use webviews instead if you embed several webviews in one window.
  • permissions mixes plain strings and objects with a scope.
  • The $schema line gives your editor autocomplete for every permission in your project, generated into gen/schemas at build time.

If tauri.conf.json has an app.security.capabilities array, only the listed capabilities are enabled; otherwise every file in the folder is.

Which windows?

A common pattern: a main window with broad but scoped rights, and a "preferences" or "about" window with almost none. The label comes from the window configuration or from WebviewWindowBuilder::new(app, "settings", ...). Dynamically created windows are matched by label, so a capability for "settings" also protects a window you create later at runtime.

Platforms

A capability can apply to certain platforms only:

JSON
{
  "identifier": "desktop-only",
  "windows": ["main"],
  "platforms": ["linux", "macOS", "windows"],
  "permissions": ["global-shortcut:default", "window-state:default"]
}

Valid values are linux, macOS, windows, iOS and android. Mobile schemas are generated into separate files (mobile-schema.json), so a mobile build will not complain about desktop-only plugins.

Remote content

By default, only your own app content (the bundled frontend or the dev server) can use commands. If you must let a remote site call a command, say it explicitly, narrowly:

JSON
{
  "identifier": "remote-docs",
  "windows": ["help"],
  "remote": { "urls": ["https://docs.example.com/*"] },
  "permissions": ["core:event:default"]
}

Treat remote capabilities as high risk. Give them as little as possible, and prefer rendering remote content as plain iframes or in a window that has no capability at all.

Allow and deny

Permissions can be combined, and deny always wins. The fs plugin demonstrates it well:

JSON
{
  "permissions": [
    {
      "identifier": "fs:allow-read-text-file",
      "allow": [{ "path": "$DOCUMENT/**" }],
      "deny":  [{ "path": "$DOCUMENT/private/**" }]
    }
  ]
}

Everything under Documents may be read except the private folder. You can also use the standalone deny- permissions to take a command away from a set: add "fs:default" then "fs:deny-write-file".

Application commands

Your own #[tauri::command] functions are allowed by default for every window, which is convenient but too generous for a larger app. To bring them under the same system, list them in build.rs:

Rust
fn main() {
    tauri_build::try_build(
        tauri_build::Attributes::new().app_manifest(
            tauri_build::AppManifest::new().commands(&["list_notes", "save_note", "delete_note"]),
        ),
    )
    .unwrap();
}

Tauri then generates allow-list-notes, allow-save-note and allow-delete-note permissions, which you grant in capabilities like any plugin permission. The settings window can receive list_notes while only main gets delete_note.

How a request is resolved

When invoke("plugin:fs|read_text_file", { path }) arrives, the runtime does the following:

flowchart TD
  A["invoke from window 'main'"] --> B{"A capability for this window<br/>(and platform, and origin) exists?"}
  B -- no --> X["Rejected: not allowed"]
  B -- yes --> C{"Does a permission allow this command?"}
  C -- no --> X
  C -- yes --> D{"Does a deny entry match?"}
  D -- yes --> X
  D -- no --> E["Command runs, and checks its scope on the path"]

Origin, window, command, then scope: each must pass.

The model below implements this check, including permission sets and deny precedence, so you can try your own rules.

Node.js Stand-in: a permission resolver with sets and deny

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Debugging permission errors

A refused call prints something like fs.read_text_file not allowed. Permissions associated with this command: fs:allow-read-text-file. The recipe:

  1. Read the permission name in the message and add it to the capability for that window label.
  2. Check the window label in the error or your config: a capability for main does nothing for a window called editor.
  3. If it is a path problem, the message mentions the scope: extend allow, or check a deny.
  4. Restart tauri dev after editing capabilities, because they are compiled into the app.
  5. Check gen/schemas/*.json for the exact names of the permissions your plugins provide.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which sentence about deny rules is true?

    Whenever a deny entry matches, the request is refused, even if an allow entry also matches.
  2. 2. Where does Tauri look for capabilities by default?

    All JSON, JSON5 or TOML files in src-tauri/capabilities are loaded unless you list specific ones in tauri.conf.json.
  3. 3. How do you give only your own list_notes command to the settings window?

    App commands can be placed under the ACL by declaring them in the app manifest; then capabilities control access.
  4. 4. A capability lists windows: ["main"] and you open a window labelled "editor". What can editor call?

    Capabilities are matched by window label, so editor needs its own capability or must be added to the list.

Summary

  • Permissions allow or deny commands; permission sets bundle them; capabilities attach them to windows, platforms and (rarely) remote URLs.
  • Capability files in src-tauri/capabilities are checked on every IPC call, and deny beats allow.
  • Put your own commands under the system with an app manifest in build.rs.
  • Debug errors by reading the missing permission name and matching the window label.

Next: Scopes and Input Validation