diff --git a/zh-cn/application-dev/security/accesstoken-guidelines.md b/zh-cn/application-dev/security/accesstoken-guidelines.md index 4f6ff8eb4951782e77c4b334d5c1bfab305d077b..45cd9279b55872bed403e2b1ce8e3e74a34a591e 100644 --- a/zh-cn/application-dev/security/accesstoken-guidelines.md +++ b/zh-cn/application-dev/security/accesstoken-guidelines.md @@ -1,4 +1,4 @@ -# 访问控制（权限）开发指导 +# 访问控制授权申请指导 ## 场景介绍 @@ -16,11 +16,11 @@ ## 接口说明 -以下仅列举本指导使用的接口，更多说明可以查阅[API参考](../reference/apis/js-apis-abilityAccessCtrl.md)。 +以下仅列举本指导使用的接口，更多说明可以查阅[API参考](../reference/apis/js-apis-ability-context.md)。 | 接口名 | 描述 | | ------------------------------------------------------------ | --------------------------------------------------- | -| verifyAccessToken(tokenID: number, permissionName: string): Promise<GrantStatus> | 校验应用是否授予权限，使用Promise方式异步返回结果。 | +| requestPermissionsFromUser(permissions: Array<string>, requestCallback: AsyncCallback<PermissionRequestResult>) : void; | 拉起弹窗请求用户授权。 | ## 权限申请声明 @@ -111,7 +111,7 @@ ## ACL方式声明 -如上述示例所示，权限"ohos.permission.PERMISSION2"的权限等级为system_basic，高于应用此时应用的APL等级，用户的最佳做法是使用ACL方式。 +如上述示例所示，权限"ohos.permission.PERMISSION2"的权限等级为system_basic，高于此时应用的APL等级，用户的最佳做法是使用ACL方式。 在配置文件声明的基础上，应用还需要在Profile文件中声明不满足申请条件部分的权限。Profile文件的字段说明可参考[HarmonyAppProvision配置文件的说明](../quick-start/app-provision-structure.md)。 @@ -137,15 +137,15 @@ > **注意：** > -> 不能把之前授予的状态持久化，每次访问受目标权限保护的接口前，都应该检查权限授权状态，因为用户在动态授予后可能通过设置取消应用的权限。 +> 不能把之前授予的状态持久化，每次访问受目标权限保护的接口前，都应该调用requestPermissionsFromUser接口请求权限，因为用户在动态授予后可能通过设置取消应用的权限。 ## 完整示例 -对访问者进行权限校验的开发步骤为： +请求用户授权权限的开发步骤为： 1. 获取ability的上下文context。 -2. 调用requestPermissionsFromUser接口进行权限校验。 -3. 根据权限校验结果采取对应的措施。 +2. 调用requestPermissionsFromUser接口请求权限。运行过程中，该接口会根据应用是否已获得目标权限决定是否拉起动态弹框请求用户授权。 +3. 根据requestPermissionsFromUser接口返回值判断是否已获取目标权限。如果当前已经获取权限，则可以继续正常访问目标接口。 ```js //ability的onWindowStageCreate生命周期 diff --git a/zh-cn/application-dev/security/accesstoken-overview.md b/zh-cn/application-dev/security/accesstoken-overview.md index 38125982222979b14bdf9d7d3668bbaaa8a00d4b..cc770131447915f7c35b49af80bd6f3272475f31 100644 --- a/zh-cn/application-dev/security/accesstoken-overview.md +++ b/zh-cn/application-dev/security/accesstoken-overview.md @@ -1,6 +1,6 @@ # 访问控制（权限）开发概述 -ATM（AccessTokenManager）是OpenHarmony上基于AccessToken构建的统一的应用权限管理能力。 +ATM (AccessTokenManager) 是OpenHarmony上基于AccessToken构建的统一的应用权限管理能力。 默认情况下，应用只能访问有限的系统资源。但某些情况下，应用为了扩展功能的诉求，需要访问额外的系统或其他应用的数据（包括用户个人数据）、功能。系统或应用也必须以明确的方式对外提供接口来共享其数据或功能。OpenHarmony提供了一种访问控制机制来保证这些数据或功能不会被不当或恶意使用，即应用权限。 @@ -27,6 +27,8 @@ ATM（AccessTokenManager）是OpenHarmony上基于AccessToken构建的统一的 ## 权限的工作流程 +### 权限申请使用的工作流程 + 应用在访问数据或者执行操作时，需要评估该行为是否需要应用具备相关的权限。如果确认需要目标权限，则需要在应用安装包中申请目标权限。 然后，需要判断目标权限是否属于用户授权类。如果是，应用需要使用动态授权弹框来提供用户授权界面，请求用户授权目标权限。 @@ -47,6 +49,21 @@ ATM（AccessTokenManager）是OpenHarmony上基于AccessToken构建的统一的 3：应用可以通过ACL（访问控制列表）方式申请高级别的权限，具体请参考[访问控制列表（ACL）说明](#访问控制列表acl说明)。 +### 权限校验的工作流程 +应用在提供对外功能服务接口时，可以根据接口涉数据的敏感程度或所涉能力的安全威胁影响，在[权限定义列表](permission-list.md)选择合适的权限保护当前接口，对访问者进行权限校验。 + +当且仅当访问者获取当前接口所需权限后，才能通过当前接口的权限校验，并正常使用当前应用提供的目标功能。 + +应用使用权限校验的工作流程如图所示。 + +![](figures/permission-verify-process.png) + +1：根据应用当前提供的接口是否涉及敏感的数据或者功能，使用应用权限对当前接口进行访问控制。 + +2：应用可以在系统已经存在的权限中[访问控制列表（ACL）说明](#访问控制列表acl说明)选择适合的权限。比如应用提供的接口会涉及到联系人信息的话，推荐使用联系人相关的权限对接口进行保护。 + +3：应用可以使用权限校验接口对访问者进行鉴权，可参考[权限校验说明](permission-verify-guidelines.md)。 + ## 权限等级说明 根据接口所涉数据的敏感程度或所涉能力的安全威胁影响，ATM模块定义了不同开放范围的权限等级来保护用户隐私。 @@ -134,11 +151,14 @@ ATM（AccessTokenManager）是OpenHarmony上基于AccessToken构建的统一的 如[权限的工作流程](#权限的工作流程)所示，如果应用需要获取目标权限，那么需要先进行权限申请。 -应用获取权限的流程取决于相应的权限类型： +- 权限申请 +开发者需要在配置文件中[声明目标权限](accesstoken-guidelines.md#权限申请声明)。 -- 如果目标权限是system_grant类型，开发者需要在配置文件中[声明目标权限](accesstoken-guidelines.md#权限申请声明)，系统会在安装应用时为其进行权限预授予。 +- 权限授权 -- 如果目标权限是user_grant类型，开发者需要先在配置文件中[声明目标权限](accesstoken-guidelines.md#权限申请声明)，然后运行时发送弹窗，请求用户授权。 +如果目标权限是system_grant类型，开发者在进行权限申请后，系统会在安装应用时自动为其进行权限预授予，开发者不需要做其他操作即可使用权限。 +
+如果目标权限是user_grant类型，开发者在进行权限申请后，在运行时触发动态弹窗，请求用户授权，具体操作见[user_grant权限请求授权的步骤详解](#user_grant权限请求授权的步骤详解)。 ### user_grant权限请求授权的步骤详解 @@ -148,9 +168,9 @@ ATM（AccessTokenManager）是OpenHarmony上基于AccessToken构建的统一的 2. 将应用中需要申请权限的目标对象与对应目标权限进行关联，让用户明确地知道，哪些操作需要用户向应用授予指定的权限。 -3. 运行应用时，需要检查当前用户是否以及授权应用所需的权限，如果已授权，那么应用可以直接访问操作目标对象。如果当前用户尚未授予应用所需的权限，在用户触发访问操作目标对象时精准触发动态授权弹框。 +3. 运行应用时，在用户触发访问操作目标对象时应该调用接口，精准触发动态授权弹框。该接口的内部会检查当前用户是否已经授权应用所需的权限，如果当前用户尚未授予应用所需的权限，该接口会拉起动态授权弹框，向用户请求授权。 -4. 检查用户的授权结果。确认用户已授权才可以进行下一步操作。 +4. 检查用户的授权结果，确认用户已授权才可以进行下一步操作。 **注意事项：** diff --git a/zh-cn/application-dev/security/figures/permission-verify-process.png b/zh-cn/application-dev/security/figures/permission-verify-process.png new file mode 100644 index 0000000000000000000000000000000000000000..e82bf5eb307bb6ec45abc139da46f5985e061dd0 Binary files /dev/null and b/zh-cn/application-dev/security/figures/permission-verify-process.png differ diff --git a/zh-cn/application-dev/security/permission-verify-guidelines.md b/zh-cn/application-dev/security/permission-verify-guidelines.md new file mode 100644 index 0000000000000000000000000000000000000000..5f738e40c602a18331b4abcb0d529e756a9d32e4 --- /dev/null +++ b/zh-cn/application-dev/security/permission-verify-guidelines.md @@ -0,0 +1,46 @@ +# 访问控制权限校验指导 + +## 场景介绍 + +应用在提供对外功能服务接口时，可以根据接口涉数据的敏感程度或所涉能力的安全威胁影响，在系统定义的权限列表中[权限定义列表](permission-list.md)选择合适的权限限制当前接口的开放范围，对接口访问者进行权限校验。 + +## 接口说明 + +以下仅列举本指导使用的接口，更多说明可以查阅[API参考](../reference/apis/js-apis-ability-context.md)。 + +| 接口名 | 描述 | +| ------------------------------------------------------------ | --------------------------------------------------- | +| verifyAccessToken(tokenID: number, permissionName: string): Promise<GrantStatus> | 校验指定的应用进程是否已被授权指定的权限。 | + + +## 完整示例 + +进行权限校验的开发步骤为： + +1. 获取调用者的身份标识：tokenId。 +2. 待校验的权限名：ohos.permission.PERMISSION。 +3. 使用verifyAccessToken接口对当前调用者进行权限校验。 +4. 根据权限校验结果采取对应的措施。 + +```js + import abilityAccessCtrl from '@ohos.abilityAccessCtrl' + import rpc from '@ohos.rpc' + + class Stub extends rpc.RemoteObject { + onRemoteRequest(code, data, reply, option) { + let callerTokenId = rpc.IPCSkeleton.getCallingTokenId(); + console.log("RpcServer: getCallingTokenId result: " + callerTokenId); + var atManager = abilityAccessCtrl.createAtManager(); + var result = await atManager.verifyAccessToken(tokenID, "ohos.permission.PERMISSION"); + if (result == abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED) { + // 允许访问者调用当前应用提供的接口 + } else { + // 不允许访问者调用当前应用提供的接口 + } + return true; + } + } + +``` +> **说明：** +> 获取访问者身份标识tokenId的方法 getCallingTokenId 可参考[API参考](../reference/apis/js-apis-rpc.md)。 \ No newline at end of file