diff --git a/zh-cn/application-dev/security/accesstoken-guidelines.md b/zh-cn/application-dev/security/accesstoken-guidelines.md index 40eb479b37df7ed905b461b3274ab01fe972f76f..9354ed496a1c07573f7f9000a54fe030c737aa73 100644 --- a/zh-cn/application-dev/security/accesstoken-guidelines.md +++ b/zh-cn/application-dev/security/accesstoken-guidelines.md @@ -24,9 +24,13 @@ ## 权限申请声明 -### FA模型 config.json文件声明 +应用需要在工程配置文件中，对需要的权限逐个声明，没有在配置文件中声明的权限，应用将无法获得授权。Ability框架提供了两种模型，分别为FA模型和Stage模型，更多信息可以参考[Ability框架概述](../ability/ability-brief.md)。 -FA模型中应用需要在config.json文件中对需要的权限逐个进行声明。没有在config.json中声明的权限，应用无法获得此应用授权。 +不同的Ability框架模型的应用包结构不同，所使用的配置文件不同，请开发者在申请权限时注意区分。 + +### FA模型 + +使用FA模型的应用，需要在config.json文件中声明权限。 **config.json标签说明：** @@ -69,9 +73,9 @@ FA模型中应用需要在config.json文件中对需要的权限逐个进行声 } ``` -### stage模型 module.json5文件声明 +### Stage模型 -stage模型中应用需要在module.json5文件中对需要的权限逐个进行声明。没有在module.json5中声明的权限，应用无法获得此应用授权。 +使用Stage模型的应用，需要在module.json5文件中声明权限。 **示例：** @@ -108,7 +112,7 @@ stage模型中应用需要在module.json5文件中对需要的权限逐个进行 如上述示例所示，权限"ohos.permission.PERMISSION2"的权限等级为system_basic，高于应用此时应用的APL等级，用户的最佳做法是使用ACL方式。 -在config.json文件声明的基础上，应用还需要在[profile文件](../quick-start/app-provision-structure.md)中声明不满足申请条件部分的权限。该场景中，用户应该在字段"acls"中做声明如下： +在配置文件声明的基础上，应用还需要在[profile文件](../quick-start/app-provision-structure.md)中声明不满足申请条件部分的权限。该场景中，用户应该在字段"acls"中做声明如下： ```json { "version-name": "1.0.0", diff --git a/zh-cn/application-dev/security/accesstoken-overview.md b/zh-cn/application-dev/security/accesstoken-overview.md index 94feaa30c186d4ea8a17d3ba323fef0f25e11603..29283090785f340d671e6b32b0dd2d8f4d6b9389 100644 --- a/zh-cn/application-dev/security/accesstoken-overview.md +++ b/zh-cn/application-dev/security/accesstoken-overview.md @@ -1,7 +1,6 @@ # 访问控制开发概述 -## 简介 -ATM(AccessTokenManager)是OpenHarmony上基于AccessToken构建的统一的应用权限管理能力。 +ATM（AccessTokenManager）是OpenHarmony上基于AccessToken构建的统一的应用权限管理能力。 默认情况下，应用只能访问有限的系统资源。但某些情况下，应用为了扩展功能的诉求，需要访问额外的系统或其他应用的数据（包括用户个人数据）、功能。系统或应用也必须以明确的方式对外提供接口来共享其数据或功能。OpenHarmony提供了一种访问控制机制来保证这些数据或功能不会被不当或恶意使用，即应用权限。 @@ -24,10 +23,32 @@ ATM(AccessTokenManager)是OpenHarmony上基于AccessToken构建的统一的应 应用使用权限的工作流程如图所示。 -![](figures/figure1.png) +![](figures/permission-workflow.jpg) + +1：应用可以参考下图，判断应用能否申请目标权限。 + +![](figures/permission-application-process.png) + +1：应用APL等级与权限等级的匹配关系请参考[权限等级说明](#权限等级说明)。 + +2：权限的授权方式分为user_grant（用户授权）和system_grant（系统授权），具体请参考[权限类型说明](#权限类型说明)。 + +3：应用可以通过ACL（访问控制列表）方式申请高级别的权限，具体请参考[访问控制列表（ACL）说明](#访问控制列表acl说明)。 ## 权限使用场景说明 +### 基本原则 + +在进行权限的申请和使用时，需要满足以下基本原则： + +- 应用申请的权限，都必须有明确、合理的使用场景和功能说明，确保用户能够清晰明了地知道申请权限的目的、场景、用途；禁止诱导、误导用户授权；应用使用权限必须与申请所述一致。 +- 应用权限申请遵循最小化原则，只申请业务功能所必要的权限，禁止申请不必要的权限。 +- 应用在首次启动时，避免频繁弹窗申请多个权限；权限须在用户使用对应业务功能时动态申请。 +- 用户拒绝授予某个权限时，与此权限无关的其他业务功能应能正常使用，不能影响应用的正常注册或登录。 +- 业务功能所需要的权限被用户拒绝且禁止后不再提示，当用户主动触发使用此业务功能或为实现业务功能所必须时，应用程序可通过界面内文字引导，让用户主动到“系统设置”中授权。 + +- 当前不允许应用自行定义权限，应用申请的权限应该从[已有的权限列表](permission-list.md)中选择。 + ### 场景示例 下面列举两种应用需要使用权限的常见场景，用作参考。 @@ -46,18 +67,6 @@ ATM(AccessTokenManager)是OpenHarmony上基于AccessToken构建的统一的应 (1) ohos.permission.CAMERA 允许应用使用相机拍摄照片和录制视频。 -### 基本原则 - -在进行权限的申请和使用时，需要满足以下基本原则： - -- 应用申请的权限，都必须有明确、合理的使用场景和功能说明，确保用户能够清晰明了地知道申请权限的目的、场景、用途；禁止诱导、误导用户授权；应用使用权限必须与申请所述一致。 -- 应用权限申请遵循最小化原则，只申请业务功能所必要的权限，禁止申请不必要的权限。 -- 应用在首次启动时，避免频繁弹窗申请多个权限；权限须在用户使用对应业务功能时动态申请。 -- 用户拒绝授予某个权限时，与此权限无关的其他业务功能应能正常使用，不能影响应用的正常注册或登录。 -- 业务功能所需要的权限被用户拒绝且禁止后不再提示，当用户主动触发使用此业务功能或为实现业务功能所必须时，应用程序可通过界面内文字引导，让用户主动到“系统设置”中授权。 - -- 当前不允许应用自行定义权限，应用申请的权限应该从已有的权限列表中选择。 - ## 权限等级说明 根据接口所涉数据的敏感程度或所涉能力的安全威胁影响，ATM模块定义了不同开放范围的权限等级来保护用户隐私。 @@ -100,33 +109,6 @@ ATM(AccessTokenManager)是OpenHarmony上基于AccessToken构建的统一的应 鉴于该类型权限对系统的影响程度非常大，目前暂不向任何应用开放。 -### 访问控制列表（ACL）说明 - -如上所述，权限等级和应用的APL等级是一一对应的。原则上，**拥有低APL等级的应用默认无法申请更高等级的权限**。 - -访问控制列表ACL（Access Control List）提供了解决低等级应用访问高等级权限问题的特殊渠道。 - -**场景举例：** - -开发者正在开发应用A，该应用的APL等级为normal级别。由于功能场景需要，应用A必须申请到权限B和权限C，其中，权限B的权限等级为system_basic，权限C的权限等级为normal级别。 - -在权限B的ACL使能为TRUE的情况下，此时，开发者可以使用ACL方式来申请权限B。 - -ACL方式的工作流程可以参考[ACL方式使用说明](#ACL方式使用说明)。 -权限的ACL使能情况可查阅[权限定义列表](permission-list.md)。 - -### ACL方式使用说明 - -如果应用申请的权限中，存在部分权限的权限等级比应用APL等级高，开发者可以选择通过ACL方式来解决这个等级不匹配的问题。 - -在上述的[授权流程](#不同权限类型的授权流程)的基础上，应用需要进行额外的ACL声明步骤。 - -应用除了需要在config.json文件声明所需申请的权限，还需要在应用的[profile文件中声明](accesstoken-guidelines.md#acl方式声明)不满足申请条件的高等级权限，接下来的授权流程不变。 - -**ACL申请方式须知** - -开发应用安装包时，需要修改应用的profile文件，在文件的"acl"字段声明目标的访问控制列表，并使用profile签名工具生成证书。具体签名流程可以查看页面[Hap包签名工具指导](hapsigntool-guidelines.md)。 - ## 权限类型说明 根据授权方式的不同，权限类型可分为system_grant（系统授权）和user_grant（用户授权）。 @@ -153,15 +135,15 @@ ACL方式的工作流程可以参考[ACL方式使用说明](#ACL方式使用说 应用获取权限的流程取决于相应的权限类型： -- 如果目标权限是system_grant类型，开发者需要在config.json文件中[声明目标权限](accesstoken-guidelines.md)，系统会在安装应用时为其进行权限预授予。 +- 如果目标权限是system_grant类型，开发者需要在配置文件中[声明目标权限](accesstoken-guidelines.md#权限申请声明)，系统会在安装应用时为其进行权限预授予。 -- 如果目标权限是user_grant类型，开发者需要先在config.json文件中[声明目标权限](accesstoken-guidelines.md)，然后运行时发送弹窗，请求用户授权。 +- 如果目标权限是user_grant类型，开发者需要先在配置文件中[声明目标权限](accesstoken-guidelines.md#权限申请声明)，然后运行时发送弹窗，请求用户授权。 ### user_grant权限请求授权的步骤详解 在应用需要获取user_grant权限时，请完成以下步骤： -1. 在config.json文件中，声明应用需要请求的权限，详见[访问控制开发指导](accesstoken-guidelines.md)。 +1. 在配置文件中，声明应用需要请求的权限，详见[访问控制开发指导](accesstoken-guidelines.md)。 2. 将应用中需要申请权限的目标对象与对应目标权限进行关联，让用户明确地知道，哪些操作需要用户向应用授予指定的权限。 @@ -172,7 +154,33 @@ ACL方式的工作流程可以参考[ACL方式使用说明](#ACL方式使用说 **注意事项：** - 每次执行需要目标权限的操作时，应用都必须检查自己是否已经具有该权限。 - - 如需检查用户是否已向您的应用授予特定权限，可以使用[verifyAccessToken](../reference/apis/js-apis-abilityAccessCtrl.md)函数，此方法会返回 [PERMISSION_GRANTED](../reference/apis/js-apis-abilityAccessCtrl.md)或[PERMISSION_DENIED](../reference/apis/js-apis-abilityAccessCtrl.md)。具体的示例代码可以查看[访问控制开发指导](accesstoken-guidelines.md)。 - user_grant权限授权要基于用户可知可控的原则，需要应用在运行时主动调用系统动态申请权限的接口，系统弹框由用户授权，用户结合应用运行场景的上下文，识别出应用申请相应敏感权限的合理性，从而做出正确的选择。 - 即使用户向应用授予过请求的权限，应用在调用受此权限管控的接口前，也应该先检查自己有无此权限，而不能把之前授予的状态持久化，因为用户在动态授予后还可以通过设置取消应用的权限。 + +## 访问控制列表（ACL）说明 + +如上所述，权限等级和应用的APL等级是一一对应的。原则上，**拥有低APL等级的应用默认无法申请更高等级的权限**。 + +访问控制列表ACL（Access Control List）提供了解决低等级应用访问高等级权限问题的特殊渠道。 + +**场景举例：** + +开发者正在开发应用A，该应用的APL等级为normal级别。由于功能场景需要，应用A必须申请到权限B和权限C，其中，权限B的权限等级为system_basic，权限C的权限等级为normal级别。 + +在权限B的ACL使能为TRUE的情况下，此时，开发者可以使用ACL方式来申请权限B。 + +ACL方式的工作流程可以参考[ACL方式使用说明](#ACL方式使用说明)。 +具体某个权限能否通过ACL使能情况可查阅[权限定义列表](permission-list.md)。 + +### ACL方式使用说明 + +如果应用申请的权限中，存在部分权限的权限等级比应用APL等级高，开发者可以选择通过ACL方式来解决这个等级不匹配的问题。 + +在上述的[授权流程](#不同权限类型的授权流程)的基础上，应用需要进行额外的ACL声明步骤。 + +应用除了需要在config.json文件声明所需申请的权限，还需要在应用的[profile文件中声明](accesstoken-guidelines.md#acl方式声明)不满足申请条件的高等级权限，接下来的授权流程不变。 + +**ACL申请方式须知** + +开发应用安装包时，需要修改应用的profile文件，在文件的"acl"字段声明目标的访问控制列表，并使用profile签名工具生成证书。具体签名流程可以查看页面[Hap包签名工具指导](hapsigntool-guidelines.md)。 \ No newline at end of file diff --git a/zh-cn/application-dev/security/permission-list.md b/zh-cn/application-dev/security/permission-list.md index be2aa546491a01e133bb5e2a5e2d59c2fa030539..691b9e229bf6342509bfc4fa05cbb76633b18dda 100644 --- a/zh-cn/application-dev/security/permission-list.md +++ b/zh-cn/application-dev/security/permission-list.md @@ -1,14 +1,8 @@ # 权限定义列表 -在符合[应用申请和使用权限的基本原则](accesstoken-overview.md#基本原则)的基础上，可以根据下图判断应用是否可以申请某权限。 +在申请目标权限前，建议开发者先阅读[访问控制开发概述-权限的工作流程](accesstoken-overview.md#权限的工作流程)。对权限的工作流程有基本的了解后，再结合下表判断应用能否申请目标权限，提高开发效率。 -![](figures/permission-application-process.png) - -1. 应用APL等级与权限等级的匹配关系请参考[访问控制开发概述-权限等级说明](accesstoken-overview.md#权限等级说明)。 -2. 权限的授权方式分为user_grant（用户授权）和system_grant（系统授权），具体请参考[访问控制开发概述-权限类型说明](accesstoken-overview.md#权限类型说明)。 -3. 应用可以通过ACL（访问控制列表）方式申请高级别的权限，具体请参考[访问控制开发概述-访问控制列表说明](accesstoken-overview.md#访问控制列表acl说明)。 - -以下给出当前系统定义的权限信息列表。权限的使用示例请参考[访问控制开发指导](accesstoken-guidelines.md)。 +权限的使用示例请参考[访问控制开发指导](accesstoken-guidelines.md)。 | 权限名 | 权限级别 | 授权方式 | ACL使能 | 权限说明 | | -------------------------------------------------------- | ------------ | ------------ | ------- | ------------------------------------------------------------ |