From 916a103e8763d8020d672c3dfd5c12849a72c33a Mon Sep 17 00:00:00 2001 From: zengyawen Date: Tue, 18 Jul 2023 18:23:08 +0800 Subject: [PATCH] update permissions docs Signed-off-by: zengyawen --- .../security/accesstoken-guidelines.md | 65 ++++++++++++-- .../security/accesstoken-overview.md | 24 +++-- .../security/permission-group-list.md | 90 +++++++++++++++++++ .../security/permission-list.md | 1 + 4 files changed, 164 insertions(+), 16 deletions(-) create mode 100644 zh-cn/application-dev/security/permission-group-list.md diff --git a/zh-cn/application-dev/security/accesstoken-guidelines.md b/zh-cn/application-dev/security/accesstoken-guidelines.md index 527cc3b171..3612d22d55 100644 --- a/zh-cn/application-dev/security/accesstoken-guidelines.md +++ b/zh-cn/application-dev/security/accesstoken-guidelines.md @@ -6,10 +6,18 @@ 本文将从如下场景分别介绍： -- [配置文件权限声明](#配置文件权限声明) -- [ACL方式声明](#acl方式声明) -- [向用户申请授权](#向用户申请授权) -- [user_grant权限预授权](#user_grant权限预授权) +- [访问控制授权申请指导](#访问控制授权申请指导) + - [场景介绍](#场景介绍) + - [配置文件权限声明](#配置文件权限声明) + - [Stage模型](#stage模型) + - [FA模型](#fa模型) + - [权限使用理由的文案内容规范](#权限使用理由的文案内容规范) + - [ACL方式声明](#acl方式声明) + - [向用户申请授权](#向用户申请授权) + - [Stage模型](#stage模型-1) + - [FA模型](#fa模型-1) + - [user\_grant权限预授权](#user_grant权限预授权) + - [相关实例](#相关实例) ## 配置文件权限声明 @@ -24,8 +32,8 @@ | 标签 | 是否必填 | 说明 | | --------- | -------- | ------------------------------------------------------------ | | name | 是 | 权限名称。 | -| reason | 否 | 描述申请权限的原因。
> **说明**：当申请的权限为user_grant权限时，此字段必填。 | -| usedScene | 否 | 描述权限使用的场景和时机。
> **说明**：当申请的权限为user_grant权限时，此字段必填。 | +| reason | 否 | 描述申请权限的原因。
> **说明**：当申请的权限为user_grant权限时，此字段必填。 | +| usedScene | 否 | 描述权限使用的场景和时机，可参考[权限使用理由的文案内容规范](#权限使用理由的文案内容规范)。
> **说明**：当申请的权限为user_grant权限时，此字段必填。 | | abilities | 否 | 标识需要使用到该权限的Ability，标签为数组形式。
**适用模型**：Stage模型 | | ability | 否 | 标识需要使用到该权限的Ability，标签为数组形式。
**适用模型**：FA模型 | | when | 否 | 标识权限使用的时机，值为`inuse/always`。
- inuse：表示为仅允许前台使用。
- always：表示前后台都可使用。 | @@ -98,6 +106,44 @@ } ``` +### 权限使用理由的文案内容规范 + +当申请的权限为user_grant权限时，字段usedScene（权限使用理由和时机）必填。所有的user_grant权限均被归类到某个权限组中，使用时均通过[权限组](accesstoken-overview.md#权限组和子权限)进行申请。当前支持的权限组请查看[应用权限组列表](permission-group-list.md)。 + +**usedScene字段的内容写作规范及建议如下：** + +1. 如果需要申请“电话、信息、日历、通讯录、通话记录”这五个权限组的权限，根据工信部要求，需要展示具体子权限的内容与用途。 + + **建议句式**： + + 中文：包括子权限A和子权限B，用于某事。 + + 英文：Includes: PermissionA and PermissionB. This is used to do/for something. + + > **说明：**
中文使用逗号分割，英文使用句点分割。 + + **示例**：用于获取通话状态和移动网络信息，用于安全运营和统计计费服务。 + +2. 如果当前权限组申请不涉及子权限。 + + **建议句式**：用于某事。 + + **示例**：用于扫码拍照。 + + > **说明：**
保持句子简洁、不要加入多余的分割符号。 + +3. 用途描述的字串建议小于72个字符（即36个中文字符，UI界面显示大约为两行）。不能超过256个字符，以免在多语言适配后体验不好。 + +4. 如果不写，将展示默认的申请理由。 + +**权限使用理由展示方式：** + +向用户申请授权时，弹窗将以权限组维度显示，但在应用权限配置时，需要配置每个需要使用的子权限。 + +该用途有两个展示途径：授权弹窗界面和“设置（Settings）”界面。“设置”的具体路径：设置-隐私-权限管理-某应用某权限详情 + +系统将使用权限组内当前被申请的第一个子权限的使用理由，作为该权限组的使用理由进行展示。组内的排序，固定按照权限管理内排列的权限组数组顺序。举例说明：权限组A = {权限A, 权限B, 权限C}；申请传入的是{权限C, 权限B}，界面将展示权限B中的权限使用理由。 + ## ACL方式声明 当应用需要申请`system_basic`和`system_core`等级的权限时，比应用默认权限等级`normal`更高。如果需要申请的权限等级高于应用默认的等级，需要使用ACL方式声明使用。 @@ -120,7 +166,8 @@ 当应用需要访问用户的隐私信息或使用系统能力时，例如获取位置信息、访问日历、使用相机拍摄照片或录制视频等，应该向用户请求授权。这需要使用 `user_grant` 类型权限。在此之前，应用需要进行权限校验，以判断当前调用者是否具备所需的权限。如果权限校验结果表明当前应用尚未被授权该权限，则应使用动态弹框授权方式，为用户提供手动授权的入口。示意效果如下图所示。 -图1 向用户申请授权 +图1 向用户申请授权 + ![](figures/permission-read_calendar.png) > **说明**： @@ -222,6 +269,7 @@ ``` 在UI中向用户申请授权。 + ```typescript import abilityAccessCtrl, { Permissions } from '@ohos.abilityAccessCtrl'; import common from '@ohos.app.ability.common'; @@ -300,6 +348,7 @@ reqPermissions() { }); } ``` + ## user_grant权限预授权 应用在申请`user_grant`类型的权限默认未授权，需要通过拉起弹框由用户确认是否授予该权限。对于一些预制应用，不希望出现弹窗申请`user_grant`类型的权限，例如系统相机应用需要使用麦克风` ohos.permission.MICROPHONE`等权限，需要对麦克风等权限进行预授权，可以通过预授权的方式完成`user_grant`类型权限的授权。[预置配置文件](https://gitee.com/openharmony/vendor_hihope/blob/master/rk3568/preinstall-config/install_list_permissions.json)在设备上的路径为`/system/etc/app/install_list_permission.json`，设备开机启动时会读取该配置文件，在应用安装会对在文件中配置的`user_grant`类型权限授权。预授权配置文件字段内容包括`bundleName`、`app_signature`和`permissions`。 @@ -308,7 +357,7 @@ reqPermissions() { - `permissions`字段中`name`配置为需要预授权的`user_grant`类型的权限名；`permissions`字段中`userCancellable`表示为用户是否能够取消该预授权，配置为true，表示支持用户取消授权，为false则表示不支持用户取消授权。 > **说明**： -> +> > 当前仅支持预置应用配置该文件。 ```json diff --git a/zh-cn/application-dev/security/accesstoken-overview.md b/zh-cn/application-dev/security/accesstoken-overview.md index ef7e1d2011..07625677ef 100644 --- a/zh-cn/application-dev/security/accesstoken-overview.md +++ b/zh-cn/application-dev/security/accesstoken-overview.md @@ -22,7 +22,6 @@ ATM (AccessTokenManager) 是OpenHarmony上基于AccessToken构建的统一的应 - 应用在首次启动时，避免频繁弹窗申请多个权限；权限须在用户使用对应业务功能时动态申请。 - 用户拒绝授予某个权限时，与此权限无关的其他业务功能应能正常使用，不能影响应用的正常注册或登录。 - 业务功能所需要的权限被用户拒绝且禁止后不再提示，当用户主动触发使用此业务功能或为实现业务功能所必须时，应用程序可通过界面内文字引导，让用户主动到“系统设置”中授权。 - - 当前不允许应用自行定义权限，应用申请的权限应该从[已有的权限列表](permission-list.md)中选择。 ## 权限的工作流程 @@ -54,6 +53,7 @@ ATM (AccessTokenManager) 是OpenHarmony上基于AccessToken构建的统一的应 3：应用可以通过ACL（访问控制列表）方式申请高级别的权限，具体请参考[访问控制列表（ACL）说明](#访问控制列表acl说明)。 ### 权限校验的工作流程 + 应用在提供对外功能服务接口时，可以根据接口涉数据的敏感程度或所涉能力的安全威胁影响，在[权限定义列表](permission-list.md)选择合适的权限保护当前接口，对访问者进行权限校验。 当且仅当访问者获取当前接口所需权限后，才能通过当前接口的权限校验，并正常使用当前应用提供的目标功能。 @@ -70,7 +70,7 @@ ATM (AccessTokenManager) 是OpenHarmony上基于AccessToken构建的统一的应 3：应用可以使用权限校验接口对访问者进行鉴权，可参考[权限校验说明](permission-verify-guidelines.md)。 -## 权限等级说明 +## 权限等级 根据接口所涉数据的敏感程度或所涉能力的安全威胁影响，ATM模块定义了不同开放范围的权限等级来保护用户隐私。 @@ -130,7 +130,7 @@ ATM (AccessTokenManager) 是OpenHarmony上基于AccessToken构建的统一的应 - **system_core权限** system_core权限涉及到开放操作系统核心资源的访问操作。这部分系统资源是系统最核心的底层服务，如果遭受破坏，操作系统将无法正常运行。 - + 鉴于该类型权限对系统的影响程度非常大，目前暂不向任何三方应用开放。 ## 权限类型说明 @@ -153,6 +153,14 @@ ATM (AccessTokenManager) 是OpenHarmony上基于AccessToken构建的统一的应 应用需要在应用商店的详情页面，向用户展示所申请的user_grant权限列表。 +### 权限组和子权限 + +为了仅可能减少系统弹出的权限弹窗数量，优化交互体验，系统将逻辑紧密相关的user_grant权限组合在一起，形成多个权限组。 + +当应用请求权限时，同一个权限组的权限将会在一个弹窗内一起请求用户授权。权限组中的某个权限，称之为该权限组的子权限。 + +权限组和权限的归属关系并不是固定不变的，一个权限所属的权限组有可能发生变化。当前系统支持权限组请查阅[应用权限组列表](permission-group-list.md)。 + ### 不同权限类型的授权流程 如[权限的工作流程](#权限的工作流程)所示，如果应用需要获取目标权限，那么需要先进行权限申请。 @@ -163,14 +171,14 @@ ATM (AccessTokenManager) 是OpenHarmony上基于AccessToken构建的统一的应 - 权限授权 - - 如果目标权限是system_grant类型，开发者在进行权限申请后，系统会在安装应用时自动为其进行权限预授予，开发者不需要做其他操作即可使用权限。 - - 如果目标权限是user_grant类型，开发者在进行权限申请后，在运行时触发动态弹窗，请求用户授权，具体操作见[user_grant权限请求授权的步骤详解](#user_grant权限请求授权的步骤详解)。 + - 如果目标权限是system_grant类型，开发者在进行权限申请后，系统会在安装应用时自动为其进行权限预授予，开发者不需要做其他操作即可使用权限。 + - 如果目标权限是user_grant类型，开发者在进行权限申请后，在运行时触发动态弹窗，请求用户授权，具体操作见[user_grant权限请求授权的步骤详解](#user_grant权限请求授权的步骤详解)。 ### user_grant权限请求授权的步骤详解 在应用需要获取user_grant权限时，请完成以下步骤： -1. 在配置文件中，声明应用需要请求的权限，详见[访问控制开发指导](accesstoken-guidelines.md)。 +1. 在配置文件中，声明应用需要请求的权限，详见[访问控制开发指导-配置文件权限声明](accesstoken-guidelines.md#配置文件权限声明)。 2. 将应用中需要申请权限的目标对象与对应目标权限进行关联，让用户明确地知道，哪些操作需要用户向应用授予指定的权限。 @@ -178,10 +186,10 @@ ATM (AccessTokenManager) 是OpenHarmony上基于AccessToken构建的统一的应 4. 检查用户的授权结果，确认用户已授权才可以进行下一步操作。 -**注意事项：** +**注意事项：** - 每次执行需要目标权限的操作时，应用都必须检查自己是否已经具有该权限。 -- 如需检查用户是否已向您的应用授予特定权限，可以使用[checkAccessToken](../reference/apis/js-apis-abilityAccessCtrl.md#checkaccesstoken9)函数，此方法会返回 [PERMISSION_GRANTED](../reference/apis/js-apis-abilityAccessCtrl.md)或[PERMISSION_DENIED](../reference/apis/js-apis-abilityAccessCtrl.md)。具体的示例代码可以查看[访问控制开发指导](accesstoken-guidelines.md)。 +- 如需检查用户是否已向您的应用授予特定权限，可以使用[checkAccessToken](../reference/apis/js-apis-abilityAccessCtrl.md#checkaccesstoken9)函数，此方法会返回 [PERMISSION_GRANTED](../reference/apis/js-apis-abilityAccessCtrl.md)或[PERMISSION_DENIED](../reference/apis/js-apis-abilityAccessCtrl.md)。具体的示例代码可以查看[访问控制开发指导](accesstoken-guidelines.md#向用户申请授权)。 - user_grant权限授权要基于用户可知可控的原则，需要应用在运行时主动调用系统动态申请权限的接口，系统弹框由用户授权，用户结合应用运行场景的上下文，识别出应用申请相应敏感权限的合理性，从而做出正确的选择。 - 即使用户向应用授予过请求的权限，应用在调用受此权限管控的接口前，也应该先检查自己有无此权限，而不能把之前授予的状态持久化，因为用户在动态授予后还可以通过设置取消应用的权限。 diff --git a/zh-cn/application-dev/security/permission-group-list.md b/zh-cn/application-dev/security/permission-group-list.md new file mode 100644 index 0000000000..0d6d743668 --- /dev/null +++ b/zh-cn/application-dev/security/permission-group-list.md @@ -0,0 +1,90 @@ +# 应用权限组列表 + +在申请目标权限前，建议开发者先阅读[访问控制开发概述-权限组和子权限](accesstoken-overview.md#权限组和子权限)，了解权限组和子权限的概念，再合理申请对应的权限组。 + +当前系统支持权限组如下所示，各子权限的含义请查阅[应用权限列表](permission-list.md)。 + +## 位置信息 + +- ohos.permission.LOCATION_IN_BACKGROUND +- ohos.permission.LOCATION +- ohos.permission.APPROXIMATELY_LOCATION + +## 相机 + +- ohos.permission.CAMERA + +## 麦克风 + +- ohos.permission.MICROPHONE + +## 媒体和文件 + +- ohos.permission.MEDIA_LOCATION +- ohos.permission.READ_MEDIA +- ohos.permission.WRITE_MEDIA + +## 日历 + +- ohos.permission.READ_CALENDAR +- ohos.permission.WRITE_CALENDAR +- ohos.permission.READ_WHOLE_CALENDAR +- ohos.permission.WRITE_WHOLE_CALENDAR + +## 健身运动 + +- ohos.permission.ACTIVITY_MOTION + +## 身体传感器 + +- ohos.permission.READ_HEALTH_DATA + +## 多设备协同 + +- ohos.permission.DISTRIBUTED_DATASYNC + +## 电话 + +- ohos.permission.ANSWER_CALL +- ohos.permission.MANAGE_VOICEMAIL + +## 通讯录 + +- ohos.permission.READ_CONTACTS +- ohos.permission.WRITE_CONTACTS + +## 通话记录 + +- ohos.permission.READ_CALL_LOG +- ohos.permission.WRITE_CALL_LOG + +## 信息 + +- ohos.permission.READ_CELL_MESSAGES +- ohos.permission.READ_MESSAGES +- ohos.permission.RECEIVE_MMS +- ohos.permission.RECEIVE_SMS +- ohos.permission.RECEIVE_WAP_MESSAGES +- ohos.permission.SEND_MESSAGES + +## 音乐和音频 + +- ohos.permission.WRITE_AUDIO +- ohos.permission.READ_AUDIO + +## 文件 + +- ohos.permission.READ_DOCUMENT +- ohos.permission.WRITE_DOCUMENT +- ohos.permission.READ_MEDIA +- ohos.permission.WRITE_MEDIA + +## 图片和视频 + +- ohos.permission.WRITE_IMAGEVIDEO +- ohos.permission.READ_IMAGEVIDEO +- ohos.permission.MEDIA_LOCATION + +## 广告跟踪 + +- ohos.permission.APP_TRACKING_CONSENT diff --git a/zh-cn/application-dev/security/permission-list.md b/zh-cn/application-dev/security/permission-list.md index d93dd37619..32066aebf7 100644 --- a/zh-cn/application-dev/security/permission-list.md +++ b/zh-cn/application-dev/security/permission-list.md @@ -593,6 +593,7 @@ **ACL使能**：TRUE **起始版本**：7 + ## ohos.permission.ACCELEROMETER 允许应用读取加速度传感器的数据。 -- GitLab