configuring-tauri-permissions

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Tauri Permissions Configuration

Tauri 权限配置

This skill covers the Tauri v2 permission system for controlling frontend access to backend commands and system resources.

本技能介绍用于控制前端对后端命令和系统资源访问的Tauri v2权限系统。

Permission System Overview

权限系统概述

Permissions in Tauri are explicit privileges that grant or deny access to specific commands. They form the security boundary between frontend code and system resources.

Tauri中的权限是明确的特权，用于授予或拒绝对特定命令的访问。它们构成了前端代码与系统资源之间的安全边界。

Core Components

核心组件

Component	Purpose
Permission	Defines access to specific commands
Scope	Restricts commands to specific paths/resources
Capability	Links permissions to windows/webviews
Identifier	Unique name referencing a permission

组件	用途
Permission	定义对特定命令的访问权限
Scope	将命令限制到特定路径/资源
Capability	将权限关联到窗口/网页视图
Identifier	引用权限的唯一名称

Security Model

安全模型

Frontend code cannot access commands without explicit permission
Deny rules always take precedence over allow rules
Permissions must be linked to capabilities to be active
Each window/webview can have different permissions

前端代码没有明确权限则无法访问命令
拒绝规则始终优先于允许规则
权限必须关联到Capability才能生效
每个窗口/网页视图可以拥有不同的权限

Permission Identifiers

权限标识符

Naming Convention

命名规范

Format:

<plugin-name>:<permission-type>

Pattern	Example	Description
`<name>:default`	`fs:default`	Default permission set
`<name>:allow-<command>`	`fs:allow-read-file`	Allow specific command
`<name>:deny-<command>`	`fs:deny-write-file`	Deny specific command
`<name>:allow-<scope>`	`fs:allow-app-read`	Allow with predefined scope

格式：

<plugin-name>:<permission-type>

模式	示例	说明
`<name>:default`	`fs:default`	默认权限集
`<name>:allow-<command>`	`fs:allow-read-file`	允许特定命令
`<name>:deny-<command>`	`fs:deny-write-file`	拒绝特定命令
`<name>:allow-<scope>`	`fs:allow-app-read`	允许使用预定义作用域

Identifier Rules

标识符规则

Lowercase ASCII letters only:
```
[a-z]
```
Maximum length: 116 characters
Plugin prefixes (
```
tauri-plugin-
```
) added automatically at compile time

仅使用小写ASCII字母：
```
[a-z]
```
最大长度：116个字符
插件前缀（
```
tauri-plugin-
```
）会在编译时自动添加

Directory Structure

目录结构

Application Structure

应用结构

src-tauri/
├── capabilities/
│   ├── default.json          # Main capability file
│   └── admin.toml            # Additional capabilities
├── permissions/
│   └── custom-permission.toml # Custom app permissions
└── tauri.conf.json

src-tauri/
├── capabilities/
│   ├── default.json          # 主能力配置文件
│   └── admin.toml            # 额外能力配置
├── permissions/
│   └── custom-permission.toml # 自定义应用权限
└── tauri.conf.json

Plugin Structure

插件结构

tauri-plugin-example/
├── permissions/
│   ├── default.toml          # Default permission set
│   ├── autogenerated/        # Auto-generated from commands
│   │   └── commands/
│   └── custom-scope.toml     # Custom scopes
└── src/
    ├── commands.rs
    └── build.rs

tauri-plugin-example/
├── permissions/
│   ├── default.toml          # 默认权限集
│   ├── autogenerated/        # 从命令自动生成
│   │   └── commands/
│   └── custom-scope.toml     # 自定义作用域
└── src/
    ├── commands.rs
    └── build.rs

Capability Configuration

能力配置

Capabilities link permissions to windows and define what frontend contexts can access.

Capability用于将权限关联到窗口，并定义哪些前端上下文可以访问资源。

JSON Format (Recommended for Apps)

JSON格式（推荐用于应用）

json

{
  "$schema": "../gen/schemas/desktop-schema.json",
  "identifier": "main-capability",
  "description": "Main window permissions",
  "windows": ["main"],
  "permissions": [
    "core:default",
    "fs:default",
    "fs:allow-read-text-file",
    {
      "identifier": "fs:allow-write-text-file",
      "allow": [{ "path": "$APPDATA/*" }]
    }
  ]
}

json

{
  "$schema": "../gen/schemas/desktop-schema.json",
  "identifier": "main-capability",
  "description": "主窗口权限",
  "windows": ["main"],
  "permissions": [
    "core:default",
    "fs:default",
    "fs:allow-read-text-file",
    {
      "identifier": "fs:allow-write-text-file",
      "allow": [{ "path": "$APPDATA/*" }]
    }
  ]
}

TOML Format

TOML格式

toml

"$schema" = "../gen/schemas/desktop-schema.json"
identifier = "main-capability"
description = "Main window permissions"
windows = ["main"]
permissions = [
  "core:default",
  "fs:default",
  "fs:allow-read-text-file"
]

[[permissions]]
identifier = "fs:allow-write-text-file"
allow = [{ path = "$APPDATA/*" }]

toml

"$schema" = "../gen/schemas/desktop-schema.json"
identifier = "main-capability"
description = "主窗口权限"
windows = ["main"]
permissions = [
  "core:default",
  "fs:default",
  "fs:allow-read-text-file"
]

[[permissions]]
identifier = "fs:allow-write-text-file"
allow = [{ path = "$APPDATA/*" }]

Window Targeting

窗口目标定位

json

{
  "identifier": "admin-capability",
  "windows": ["admin", "settings"],
  "permissions": ["fs:allow-write-all"]
}

Use

"*"

to target all windows:

json

{
  "windows": ["*"],
  "permissions": ["core:default"]
}

json

{
  "identifier": "admin-capability",
  "windows": ["admin", "settings"],
  "permissions": ["fs:allow-write-all"]
}

使用

"*"

定位所有窗口：

json

{
  "windows": ["*"],
  "permissions": ["core:default"]
}

Platform-Specific Capabilities

平台特定能力配置

json

{
  "identifier": "desktop-capability",
  "platforms": ["linux", "macOS", "windows"],
  "windows": ["main"],
  "permissions": ["fs:allow-app-read-recursive"]
}

json

{
  "identifier": "mobile-capability",
  "platforms": ["iOS", "android"],
  "windows": ["main"],
  "permissions": ["fs:allow-app-read"]
}

json

{
  "identifier": "desktop-capability",
  "platforms": ["linux", "macOS", "windows"],
  "windows": ["main"],
  "permissions": ["fs:allow-app-read-recursive"]
}

json

{
  "identifier": "mobile-capability",
  "platforms": ["iOS", "android"],
  "windows": ["main"],
  "permissions": ["fs:allow-app-read"]
}

Allow and Deny Lists

允许和拒绝列表

Basic Scope Configuration

基础作用域配置

json

{
  "identifier": "fs:allow-read-file",
  "allow": [
    { "path": "$HOME/Documents/*" },
    { "path": "$APPDATA/**" }
  ],
  "deny": [
    { "path": "$HOME/Documents/secrets/*" }
  ]
}

json

{
  "identifier": "fs:allow-read-file",
  "allow": [
    { "path": "$HOME/Documents/*" },
    { "path": "$APPDATA/**" }
  ],
  "deny": [
    { "path": "$HOME/Documents/secrets/*" }
  ]
}

Scope Variables

作用域变量

Variable	Description
`$APP`	Application install directory
`$APPCONFIG`	App config directory
`$APPDATA`	App data directory
`$APPLOCALDATA`	App local data directory
`$APPCACHE`	App cache directory
`$APPLOG`	App log directory
`$HOME`	User home directory
`$DESKTOP`	Desktop directory
`$DOCUMENT`	Documents directory
`$DOWNLOAD`	Downloads directory
`$RESOURCE`	App resource directory
`$TEMP`	Temporary directory

变量	说明
`$APP`	应用安装目录
`$APPCONFIG`	应用配置目录
`$APPDATA`	应用数据目录
`$APPLOCALDATA`	应用本地数据目录
`$APPCACHE`	应用缓存目录
`$APPLOG`	应用日志目录
`$HOME`	用户主目录
`$DESKTOP`	桌面目录
`$DOCUMENT`	文档目录
`$DOWNLOAD`	下载目录
`$RESOURCE`	应用资源目录
`$TEMP`	临时目录

Glob Patterns

通配符模式

Pattern	Matches
`*`	Any file in directory
`**`	Recursive (all subdirectories)
`*.txt`	Files with .txt extension

模式	匹配内容
`*`	目录中的任意文件
`**`	递归匹配（所有子目录）
`*.txt`	扩展名为.txt的文件

Deny Precedence

拒绝规则优先级

Deny rules always override allow rules:

json

{
  "permissions": [
    {
      "identifier": "fs:allow-read-file",
      "allow": [{ "path": "$HOME/**" }],
      "deny": [{ "path": "$HOME/.ssh/**" }]
    }
  ]
}

拒绝规则始终覆盖允许规则：

json

{
  "permissions": [
    {
      "identifier": "fs:allow-read-file",
      "allow": [{ "path": "$HOME/**" }],
      "deny": [{ "path": "$HOME/.ssh/**" }]
    }
  ]
}

Plugin Permissions

插件权限

Using Default Plugin Permissions

使用默认插件权限

json

{
  "permissions": [
    "fs:default",
    "shell:default",
    "http:default",
    "dialog:default"
  ]
}

json

{
  "permissions": [
    "fs:default",
    "shell:default",
    "http:default",
    "dialog:default"
  ]
}

Common Plugin Permission Patterns

常见插件权限模式

Filesystem Plugin

文件系统插件

json

{
  "permissions": [
    "fs:default",
    "fs:allow-read-text-file",
    "fs:allow-write-text-file",
    "fs:allow-app-read-recursive",
    "fs:allow-app-write-recursive",
    "fs:deny-default"
  ]
}

json

{
  "permissions": [
    "fs:default",
    "fs:allow-read-text-file",
    "fs:allow-write-text-file",
    "fs:allow-app-read-recursive",
    "fs:allow-app-write-recursive",
    "fs:deny-default"
  ]
}

HTTP Plugin

HTTP插件

json

{
  "permissions": [
    "http:default",
    {
      "identifier": "http:default",
      "allow": [{ "url": "https://api.example.com/*" }],
      "deny": [{ "url": "https://api.example.com/admin/*" }]
    }
  ]
}

json

{
  "permissions": [
    "http:default",
    {
      "identifier": "http:default",
      "allow": [{ "url": "https://api.example.com/*" }],
      "deny": [{ "url": "https://api.example.com/admin/*" }]
    }
  ]
}

Shell Plugin

Shell插件

json

{
  "permissions": [
    "shell:allow-open",
    {
      "identifier": "shell:allow-execute",
      "allow": [
        { "name": "git", "cmd": "git", "args": true }
      ]
    }
  ]
}

json

{
  "permissions": [
    "shell:allow-open",
    {
      "identifier": "shell:allow-execute",
      "allow": [
        { "name": "git", "cmd": "git", "args": true }
      ]
    }
  ]
}

Directory-Specific Filesystem Permissions

目录特定文件系统权限

Permission	Access
`fs:allow-appdata-read`	Read $APPDATA (non-recursive)
`fs:allow-appdata-read-recursive`	Read $APPDATA (recursive)
`fs:allow-appdata-write`	Write $APPDATA (non-recursive)
`fs:allow-appdata-write-recursive`	Write $APPDATA (recursive)
`fs:allow-home-read-recursive`	Read $HOME (recursive)
`fs:allow-temp-write`	Write to temp directory

权限	访问权限
`fs:allow-appdata-read`	读取$APPDATA（非递归）
`fs:allow-appdata-read-recursive`	读取$APPDATA（递归）
`fs:allow-appdata-write`	写入$APPDATA（非递归）
`fs:allow-appdata-write-recursive`	写入$APPDATA（递归）
`fs:allow-home-read-recursive`	读取$HOME（递归）
`fs:allow-temp-write`	写入临时目录

Custom Permission Definition

自定义权限定义

TOML Permission File

TOML权限文件

Create

src-tauri/permissions/my-permission.toml

toml

[[permission]]
identifier = "my-app:config-access"
description = "Access to app configuration files"
commands.allow = ["read_config", "write_config"]

[[scope.allow]]
path = "$APPCONFIG/*"

[[scope.deny]]
path = "$APPCONFIG/secrets.json"

创建

src-tauri/permissions/my-permission.toml

：

toml

[[permission]]
identifier = "my-app:config-access"
description = "访问应用配置文件"
commands.allow = ["read_config", "write_config"]

[[scope.allow]]
path = "$APPCONFIG/*"

[[scope.deny]]
path = "$APPCONFIG/secrets.json"

Permission Sets

权限集

Group multiple permissions:

toml

[[set]]
identifier = "my-app:full-access"
description = "Full application access"
permissions = [
  "my-app:config-access",
  "fs:allow-app-read-recursive",
  "fs:allow-app-write-recursive"
]

将多个权限分组：

toml

[[set]]
identifier = "my-app:full-access"
description = "完整应用访问权限"
permissions = [
  "my-app:config-access",
  "fs:allow-app-read-recursive",
  "fs:allow-app-write-recursive"
]

Auto-Generated Command Permissions

自动生成命令权限

In plugin

src/build.rs

rust

const COMMANDS: &[&str] = &["get_user", "save_user", "delete_user"];

fn main() {
    tauri_plugin::Builder::new(COMMANDS)
        .build();
}

This generates:

```
allow-get-user
```
/
```
deny-get-user
```
```
allow-save-user
```
/
```
deny-save-user
```
```
allow-delete-user
```
/
```
deny-delete-user
```

在插件

src/build.rs

中：

rust

const COMMANDS: &[&str] = &["get_user", "save_user", "delete_user"];

fn main() {
    tauri_plugin::Builder::new(COMMANDS)
        .build();
}

这会生成：

```
allow-get-user
```
/
```
deny-get-user
```
```
allow-save-user
```
/
```
deny-save-user
```
```
allow-delete-user
```
/
```
deny-delete-user
```

Default Permission Set

默认权限集

Create

permissions/default.toml

toml

[default]
description = "Default permissions for my-plugin"
permissions = [
  "allow-get-user",
  "allow-save-user"
]

创建

permissions/default.toml

：

toml

[default]
description = "我的插件默认权限"
permissions = [
  "allow-get-user",
  "allow-save-user"
]

Remote Access Configuration

远程访问配置

Allow remote URLs to access Tauri APIs (use with caution):

json

{
  "identifier": "remote-capability",
  "windows": ["main"],
  "remote": {
    "urls": ["https://*.myapp.com"]
  },
  "permissions": [
    "core:default"
  ]
}

Security Warning: Linux and Android cannot distinguish iframe requests from window requests.

允许远程URL访问Tauri API（谨慎使用）：

json

{
  "identifier": "remote-capability",
  "windows": ["main"],
  "remote": {
    "urls": ["https://*.myapp.com"]
  },
  "permissions": [
    "core:default"
  ]
}

安全警告：Linux和Android无法区分iframe请求与窗口请求。

Configuration in tauri.conf.json

在tauri.conf.json中配置

Reference capabilities by identifier:

json

{
  "app": {
    "security": {
      "capabilities": ["main-capability", "admin-capability"]
    }
  }
}

Or inline capabilities directly:

json

{
  "app": {
    "security": {
      "capabilities": [
        {
          "identifier": "inline-capability",
          "windows": ["*"],
          "permissions": ["core:default"]
        }
      ]
    }
  }
}

通过标识符引用能力：

json

{
  "app": {
    "security": {
      "capabilities": ["main-capability", "admin-capability"]
    }
  }
}

或者直接内联能力配置：

json

{
  "app": {
    "security": {
      "capabilities": [
        {
          "identifier": "inline-capability",
          "windows": ["*"],
          "permissions": ["core:default"]
        }
      ]
    }
  }
}

Troubleshooting

故障排除

Common Errors

常见错误

"Not allowed on this command"

Verify command permission is in capability
Check scope includes the target path
Ensure capability targets correct window

Permission not found

Check identifier spelling (lowercase only)
Verify plugin is installed
Run
```
cargo build
```
to regenerate permissions

"Not allowed on this command"

验证命令权限是否已添加到Capability中
检查作用域是否包含目标路径
确保Capability定位到了正确的窗口

Permission not found

检查标识符拼写（仅允许小写）
验证插件已安装
运行
```
cargo build
```
重新生成权限

Debugging Permissions

调试权限

Check generated schema:
```
src-tauri/gen/schemas/
```
Review capability files load correctly
Verify window names match capability targets
Check deny rules are not blocking access

检查生成的Schema：
```
src-tauri/gen/schemas/
```
确认能力文件已正确加载
验证窗口名称与Capability目标匹配
检查拒绝规则是否阻止了访问

Best Practices

最佳实践

Principle of Least Privilege: Only grant permissions actually needed
Use Specific Scopes: Prefer
```
$APPDATA/*
```
over
```
$HOME/**
```
Deny Sensitive Paths: Always deny access to
```
.ssh
```
, credentials, etc.
Separate Capabilities: Use different capabilities for different window types
Document Custom Permissions: Include clear descriptions
Review Plugin Defaults: Understand what default permissions grant
Platform-Specific Config: Use platform targeting for OS-specific needs

最小权限原则：仅授予实际需要的权限
使用特定作用域：优先使用
```
$APPDATA/*
```
而非
```
$HOME/**
```
拒绝敏感路径：始终拒绝访问
```
.ssh
```
、凭证等敏感路径
分离能力配置：为不同类型的窗口使用不同的Capability
文档化自定义权限：包含清晰的描述
审核插件默认权限：了解默认权限授予的访问范围
平台特定配置：使用平台定位满足操作系统特定需求