@ohos.abilityAccessCtrl (程序访问控制管理)

程序访问控制提供程序的权限管理能力,包括鉴权、授权和取消授权等。

说明: 本模块首批接口从API version 8开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。

导入模块

import abilityAccessCtrl from '@ohos.abilityAccessCtrl'

abilityAccessCtrl.createAtManager

createAtManager(): AtManager

访问控制管理:获取访问控制模块对象。

系统能力: SystemCapability.Security.AccessToken

返回值:

类型 说明
AtManager 获取访问控制模块的实例。

示例:

let atManager = abilityAccessCtrl.createAtManager();

AtManager

管理访问控制模块的实例。

checkAccessToken9+

checkAccessToken(tokenID: number, permissionName: Permissions): Promise<GrantStatus>

校验应用是否授予权限。使用Promise异步回调。

系统能力: SystemCapability.Security.AccessToken

参数:

参数名 类型 必填 说明
tokenID number 要校验的目标应用的身份标识。可通过应用的ApplicationInfo获得。
permissionName Permissions 需要校验的权限名称,合法的权限名取值可在系统权限定义列表中查询。

返回值:

类型 说明
Promise<GrantStatus> Promise对象。返回授权状态结果。

错误码:

以下错误码的详细介绍请参见程序访问控制错误码

错误码ID 错误信息
12100001 The parameter is invalid. The tokenID is 0, or the string size of permissionName is larger than 256.

示例:

import abilityAccessCtrl from '@ohos.abilityAccessCtrl';

let atManager = abilityAccessCtrl.createAtManager();
let tokenID = 0; // 系统应用可以通过bundleManager.getApplicationInfo获取,普通应用可以通过bundleManager.getBundleInfoForSelf获取
try {
    atManager.checkAccessToken(tokenID, "ohos.permission.GRANT_SENSITIVE_PERMISSIONS").then((data) => {
        console.log(`checkAccessToken success, data->${JSON.stringify(data)}`);
    }).catch((err) => {
        console.log(`checkAccessToken fail, err->${JSON.stringify(err)}`);
    });
} catch(err) {
    console.log(`catch err->${JSON.stringify(err)}`);
}

verifyAccessTokenSync9+

verifyAccessTokenSync(tokenID: number, permissionName: Permissions): GrantStatus

校验应用是否被授予权限,同步返回结果。

系统能力: SystemCapability.Security.AccessToken

参数:

参数名 类型 必填 说明
tokenID number 要校验应用的身份标识。可通过应用的ApplicationInfo获得。
permissionName Permissions 需要校验的权限名称,合法的权限名取值可在系统权限定义列表中查询。

返回值:

类型 说明
GrantStatus 枚举实例,返回授权状态。

错误码:

以下错误码的详细介绍请参见程序访问控制错误码

错误码ID 错误信息
12100001 The parameter is invalid. The tokenID is 0, or the string size of permissionName is larger than 256.

示例:

let atManager = abilityAccessCtrl.createAtManager();
let tokenID = 0; // 系统应用可以通过bundleManager.getApplicationInfo获取,普通应用可以通过bundleManager.getBundleInfoForSelf获取
let data = atManager.verifyAccessTokenSync(tokenID, "ohos.permission.GRANT_SENSITIVE_PERMISSIONS");
console.log(`data->${JSON.stringify(data)}`);

grantUserGrantedPermission

grantUserGrantedPermission(tokenID: number, permissionName: Permissions, permissionFlags: number): Promise<void>

授予应用user grant权限。使用Promise异步回调。

系统接口: 此接口为系统接口。

需要权限: ohos.permission.GRANT_SENSITIVE_PERMISSIONS,仅系统应用可用。

系统能力: SystemCapability.Security.AccessToken

参数:

参数名 类型 必填 说明
tokenID number 目标应用的身份标识。可通过应用的ApplicationInfo获得。
permissionName Permissions 被授予的权限名称,合法的权限名取值可在系统权限定义列表中查询。
permissionFlags number 授权选项
- 0表示权限未经过用户主动设置。
- 1表示当次用户若选择禁止该权限,下次权限弹窗仍可以弹出申请用户授权。
- 2表示当次用户若选择禁止该权限,下次不会再弹出权限弹窗,需要用户在setting的权限管理中进行授权。
- 4表示当次权限设置为系统授权,用户不可更改这个权限授权状态。

返回值:

类型 说明
Promise<void> Promise对象。无返回结果的Promise对象。

错误码:

以下错误码的详细介绍请参见程序访问控制错误码

错误码ID 错误信息
12100001 The parameter is invalid. The tokenID is 0, or the string size of permissionName is larger than 256, or the flags value is invalid.
12100002 The specified tokenID does not exist.
12100003 The specified permission does not exist.
12100006 The application specified by the tokenID is not allowed to be granted with the specified permission. Either the application is a sandbox or the tokenID is from a remote device.
12100007 Service is abnormal.

示例:

import abilityAccessCtrl from '@ohos.abilityAccessCtrl';

let atManager = abilityAccessCtrl.createAtManager();
let tokenID = 0; // 系统应用可以通过bundleManager.getApplicationInfo获取,普通应用可以通过bundleManager.getBundleInfoForSelf获取
let permissionFlags = 1;
try {
    atManager.grantUserGrantedPermission(tokenID, "ohos.permission.GRANT_SENSITIVE_PERMISSIONS", permissionFlags).then(() => {
        console.log('grantUserGrantedPermission success');
    }).catch((err) => {
        console.log(`grantUserGrantedPermission fail, err->${JSON.stringify(err)}`);
    });
} catch(err) {
    console.log(`catch err->${JSON.stringify(err)}`);
}

grantUserGrantedPermission

grantUserGrantedPermission(tokenID: number, permissionName: Permissions, permissionFlags: number, callback: AsyncCallback<void>): void

授予应用user grant权限。使用callback异步回调。

系统接口: 此接口为系统接口。

需要权限: ohos.permission.GRANT_SENSITIVE_PERMISSIONS,仅系统应用可用。

系统能力: SystemCapability.Security.AccessToken

参数:

参数名 类型 必填 说明
tokenID number 目标应用的身份标识。可通过应用的ApplicationInfo获得。
permissionName Permissions 被授予的权限名称,合法的权限名取值可在系统权限定义列表中查询。
permissionFlags number 授权选项
- 0表示权限未经过用户主动设置。
- 1表示当次用户若选择禁止该权限,下次权限弹窗仍可以弹出申请用户授权。
- 2表示当次用户若选择禁止该权限,下次不会再弹出权限弹窗,需要用户在setting的权限管理中进行授权。
- 4表示当次权限设置为系统授权,用户不可更改这个权限授权状态。
callback AsyncCallback<void> 授予应用user grant权限。当授予权限成功时,err为undefine;否则为错误对象。

错误码:

以下错误码的详细介绍请参见程序访问控制错误码

错误码ID 错误信息
12100001 The parameter is invalid. The tokenID is 0, or the string size of permissionName is larger than 256, or the flags value is invalid.
12100002 TokenId does not exist.
12100003 Permission does not exist.
12100006 The application specified by the tokenID is not allowed to be granted with the specified permission. Either the application is a sandbox or the tokenID is from a remote device.
12100007 Service is abnormal.

示例:

import abilityAccessCtrl from '@ohos.abilityAccessCtrl';

let atManager = abilityAccessCtrl.createAtManager();
let tokenID = 0; // 系统应用可以通过bundleManager.getApplicationInfo获取,普通应用可以通过bundleManager.getBundleInfoForSelf获取
let permissionFlags = 1;
try {
    atManager.grantUserGrantedPermission(tokenID, "ohos.permission.GRANT_SENSITIVE_PERMISSIONS", permissionFlags, (err, data) => {
        if (err) {
            console.log(`grantUserGrantedPermission fail, err->${JSON.stringify(err)}`);
        } else {
            console.log('grantUserGrantedPermission success');
        }
    });
} catch(err) {
    console.log(`catch err->${JSON.stringify(err)}`);
}

revokeUserGrantedPermission

revokeUserGrantedPermission(tokenID: number, permissionName: Permissions, permissionFlags: number): Promise<void>

撤销应用user grant权限。使用Promise异步回调。

系统接口: 此接口为系统接口。

需要权限: ohos.permission.REVOKE_SENSITIVE_PERMISSIONS,仅系统应用可用。

系统能力: SystemCapability.Security.AccessToken

参数:

参数名 类型 必填 说明
tokenID number 目标应用的身份标识。可通过应用的ApplicationInfo获得。
permissionName Permissions 被撤销的权限名称,合法的权限名取值可在系统权限定义列表中查询。
permissionFlags number 授权选项
- 0表示权限未经过用户主动设置。
- 1表示当次用户若选择禁止该权限,下次权限弹窗仍可以弹出申请用户授权。
- 2表示当次用户若选择禁止该权限,下次不会再弹出权限弹窗,需要用户在setting的权限管理中进行授权。
- 4表示当次权限设置为系统授权,用户不可更改这个权限授权状态。

返回值:

类型 说明
Promise<void> Promise对象。无返回结果的Promise对象。

错误码:

以下错误码的详细介绍请参见程序访问控制错误码

错误码ID 错误信息
12100001 The parameter is invalid. The tokenID is 0, or the string size of permissionName is larger than 256, or the flags value is invalid.
12100002 The specified tokenID does not exist.
12100003 The specified permission does not exist.
12100006 The application specified by the tokenID is not allowed to be revoked with the specified permission. Either the application is a sandbox or the tokenID is from a remote device.
12100007 Service is abnormal.

示例:

import abilityAccessCtrl from '@ohos.abilityAccessCtrl';

let atManager = abilityAccessCtrl.createAtManager();
let tokenID = 0; // 系统应用可以通过bundleManager.getApplicationInfo获取,普通应用可以通过bundleManager.getBundleInfoForSelf获取
let permissionFlags = 1;
try {
    atManager.revokeUserGrantedPermission(tokenID, "ohos.permission.GRANT_SENSITIVE_PERMISSIONS", permissionFlags).then(() => {
        console.log('revokeUserGrantedPermission success');
    }).catch((err) => {
        console.log(`revokeUserGrantedPermission fail, err->${JSON.stringify(err)}`);
    });
} catch(err) {
    console.log(`catch err->${JSON.stringify(err)}`);
}

revokeUserGrantedPermission

revokeUserGrantedPermission(tokenID: number, permissionName: Permissions, permissionFlags: number, callback: AsyncCallback<void>): void

撤销应用user grant权限。使用callback异步回调。

系统接口: 此接口为系统接口。

需要权限: ohos.permission.REVOKE_SENSITIVE_PERMISSIONS,仅系统应用可用。

系统能力: SystemCapability.Security.AccessToken

参数:

参数名 类型 必填 说明
tokenID number 目标应用的身份标识。可通过应用的ApplicationInfo获得。
permissionName Permissions 被撤销的权限名称,合法的权限名取值可在系统权限定义列表中查询。
permissionFlags number 授权选项
- 0表示权限未经过用户主动设置。
- 1表示当次用户若选择禁止该权限,下次权限弹窗仍可以弹出申请用户授权。
- 2表示当次用户若选择禁止该权限,下次不会再弹出权限弹窗,需要用户在setting的权限管理中进行授权。
- 4表示当次权限设置为系统授权,用户不可更改这个权限授权状态。
callback AsyncCallback<void> 撤销应用user grant权限。当撤销权限成功时,err为undefine;否则为错误对象。

错误码:

以下错误码的详细介绍请参见程序访问控制错误码

错误码ID 错误信息
12100001 The parameter is invalid. The tokenID is 0, or the string size of permissionName is larger than 256, or the flags value is invalid.
12100002 TokenId does not exist.
12100003 Permission does not exist.
12100006 The application specified by the tokenID is not allowed to be revoked with the specified permission. Either the application is a sandbox or the tokenID is from a remote device.
12100007 Service is abnormal.

示例:

import abilityAccessCtrl from '@ohos.abilityAccessCtrl';

let atManager = abilityAccessCtrl.createAtManager();
let tokenID = 0; // 系统应用可以通过bundleManager.getApplicationInfo获取,普通应用可以通过bundleManager.getBundleInfoForSelf获取
let permissionFlags = 1;
try {
    atManager.revokeUserGrantedPermission(tokenID, "ohos.permission.GRANT_SENSITIVE_PERMISSIONS", permissionFlags, (err, data) => {
        if (err) {
            console.log(`revokeUserGrantedPermission fail, err->${JSON.stringify(err)}`);
        } else {
            console.log('revokeUserGrantedPermission success');
        }
    });
} catch(err) {
    console.log(`catch err->${JSON.stringify(err)}`);
}

getPermissionFlags

getPermissionFlags(tokenID: number, permissionName: Permissions): Promise<number>

获取指定应用的指定权限的flag。使用Promise异步回调。

系统接口: 此接口为系统接口。

需要权限: ohos.permission.GET_SENSITIVE_PERMISSIONS or ohos.permission.GRANT_SENSITIVE_PERMISSIONS or ohos.permission.REVOKE_SENSITIVE_PERMISSIONS,仅系统应用可用。

系统能力: SystemCapability.Security.AccessToken

参数:

参数名 类型 必填 说明
tokenID number 目标应用的身份标识。可通过应用的ApplicationInfo获得。
permissionName Permissions 查询的权限名称,合法的权限名取值可在系统权限定义列表中查询。

返回值:

类型 说明
Promise<number> Promise对象。返回查询结果。

错误码:

以下错误码的详细介绍请参见程序访问控制错误码

错误码ID 错误信息
12100001 The parameter is invalid. The tokenID is 0, or the string size of permissionName is larger than 256.
12100002 The specified tokenID does not exist.
12100003 The specified permission does not exist.
12100006 The operation is not allowed. Either the application is a sandbox or the tokenID is from a remote device.
12100007 Service is abnormal.

示例:

import abilityAccessCtrl from '@ohos.abilityAccessCtrl';

let atManager = abilityAccessCtrl.createAtManager();
let tokenID = 0; // 系统应用可以通过bundleManager.getApplicationInfo获取,普通应用可以通过bundleManager.getBundleInfoForSelf获取
try {
    atManager.getPermissionFlags(tokenID, "ohos.permission.GRANT_SENSITIVE_PERMISSIONS").then((data) => {
        console.log(`getPermissionFlags success, data->${JSON.stringify(data)}`);
    }).catch((err) => {
        console.log(`getPermissionFlags fail, err->${JSON.stringify(err)}`);
    });
} catch(err) {
    console.log(`catch err->${JSON.stringify(err)}`);
}

getVersion9+

getVersion(): Promise<number>

获取当前权限管理的数据版本。使用Promise异步回调。

系统接口: 此接口为系统接口。

系统能力: SystemCapability.Security.AccessToken

返回值:

类型 说明
Promise<number> Promise对象。返回查询到的版本号。

示例:

let atManager = abilityAccessCtrl.createAtManager();
let promise = atManager.getVersion();
promise.then(data => {
    console.log(`promise: data->${JSON.stringify(data)}`);
});

on9+

on(type: 'permissionStateChange', tokenIDList: Array<number>, permissionList: Array<Permissions>, callback: Callback<PermissionStateChangeInfo>): void;

订阅指定tokenId列表与权限列表的权限状态变更事件。

系统接口: 此接口为系统接口。

需要权限: ohos.permission.GET_SENSITIVE_PERMISSIONS,仅系统应用可用。

系统能力: SystemCapability.Security.AccessToken

参数:

参数名 类型 必填 说明
type string 订阅事件类型,固定为'permissionStateChange',权限状态变更事件。
tokenIDList Array<number> 订阅的tokenId列表,为空时表示订阅所有的应用的权限状态变化。
permissionList Array<Permissions> 订阅的权限名列表,为空时表示订阅所有的权限状态变化。
callback Callback<PermissionStateChangeInfo> 订阅指定tokenId与指定权限名状态变更事件的回调。

错误码:

以下错误码的详细介绍请参见程序访问控制错误码

错误码ID 错误信息
12100001 The parameter is invalid. The tokenID is 0, or the string size of permissionName is larger than 256.
12100004 The interface is called repeatedly with the same input.
12100005 The registration time has exceeded the limitation.
12100007 Service is abnormal.
12100008 Out of memory.

示例:

import {Permissions} from '@ohos.abilityAccessCtrl';
import bundleManager from '@ohos.bundle.bundleManager';

let atManager = abilityAccessCtrl.createAtManager();
let appInfo = bundleManager.getApplicationInfoSync('com.example.myapplication', 0, 100);
let tokenIDList: Array<number> = [appInfo.accessTokenId];
let permissionList: Array<Permissions> = ["ohos.permission.DISTRIBUTED_DATASYNC"];
try {
    atManager.on('permissionStateChange', tokenIDList, permissionList, (data) => {
        console.debug("receive permission state change, data:" + JSON.stringify(data));
    });
} catch(err) {
    console.log(`catch err->${JSON.stringify(err)}`);
}

off9+

off(type: 'permissionStateChange', tokenIDList: Array<number>, permissionList: Array<Permissions>, callback?: Callback<PermissionStateChangeInfo>): void;

取消订阅指定tokenId列表与权限列表的权限状态变更事件,使用callback回调异步返回结果。

系统接口: 此接口为系统接口。

需要权限: ohos.permission.GET_SENSITIVE_PERMISSIONS,仅系统应用可用。

系统能力: SystemCapability.Security.AccessToken

参数:

参数名 类型 必填 说明
type string 订阅事件类型,固定为'permissionStateChange',权限状态变更事件。
tokenIDList Array<number> 订阅的tokenId列表,为空时表示订阅所有的应用的权限状态变化,必须与on的输入一致。
permissionList Array<Permissions> 订阅的权限名列表,为空时表示订阅所有的权限状态变化,必须与on的输入一致。
callback Callback<PermissionStateChangeInfo> 取消订阅指定tokenId与指定权限名状态变更事件的回调。

错误码:

以下错误码的详细介绍请参见程序访问控制错误码

错误码ID 错误信息
12100001 The parameter is invalid. The tokenID in list is all invalid, or the permissionName in list is all invalid.
12100004 The interface is not used together with "on".
12100007 Service is abnormal.
12100008 Out of memory.

示例:

import {Permissions} from '@ohos.abilityAccessCtrl';
import bundleManager from '@ohos.bundle.bundleManager';

let atManager = abilityAccessCtrl.createAtManager();
let appInfo = bundleManager.getApplicationInfoSync('com.example.myapplication', 0, 100);
let tokenIDList: Array<number> = [appInfo.accessTokenId];
let permissionList: Array<Permissions> = ["ohos.permission.DISTRIBUTED_DATASYNC"];
try {
    atManager.off('permissionStateChange', tokenIDList, permissionList);
} catch(err) {
    console.log(`catch err->${JSON.stringify(err)}`);
}

verifyAccessToken9+

verifyAccessToken(tokenID: number, permissionName: Permissions): Promise<GrantStatus>

校验应用是否授予权限。使用Promise异步回调。

说明:

建议使用checkAccessToken替代。

系统能力: SystemCapability.Security.AccessToken

参数:

参数名 类型 必填 说明
tokenID number 要校验的目标应用的身份标识。可通过应用的ApplicationInfo获得。
permissionName Permissions 需要校验的权限名称,合法的权限名取值可在系统权限定义列表中查询。

返回值:

类型 说明
Promise<GrantStatus> Promise对象。返回授权状态结果。

示例:

import abilityAccessCtrl from '@ohos.abilityAccessCtrl';

let atManager = abilityAccessCtrl.createAtManager();
let tokenID = 0; // 系统应用可以通过bundleManager.getApplicationInfo获取,普通应用可以通过bundleManager.getBundleInfoForSelf获取
let promise = atManager.verifyAccessToken(tokenID, "ohos.permission.GRANT_SENSITIVE_PERMISSIONS");
promise.then(data => {
    console.log(`promise: data->${JSON.stringify(data)}`);
});

requestPermissionsFromUser9+

requestPermissionsFromUser(context: Context, permissionList: Array<Permissions>, requestCallback: AsyncCallback<PermissionRequestResult>) : void;

用于UIAbility拉起弹框请求用户授权。使用callback异步回调。

说明:

非UIAbility不支持调用本函数。

模型约束:此接口仅可在Stage模型下使用。

系统能力: SystemCapability.Security.AccessToken

参数:

参数名 类型 必填 说明
context Context 请求权限的UIAbility的UIAbilityContext。
permissionList Array<Permissions> 权限名列表,合法的权限名取值可在系统权限定义列表中查询。
callback AsyncCallback<PermissionRequestResult> 回调函数,返回接口调用是否成功的结果。

错误码:

以下错误码的详细介绍请参见程序访问控制错误码

错误码ID 错误信息
12100001 The parameter is invalid. The context is invalid when it does not belong to the application itself.

示例:

import abilityAccessCtrl from '@ohos.abilityAccessCtrl';
let atManager = abilityAccessCtrl.createAtManager();
try {
  atManager.requestPermissionsFromUser(this.context, ["ohos.permission.CAMERA"], (err, data)=>{
      console.info("data:" + JSON.stringify(data));
      console.info("data permissions:" + data.permissions);
      console.info("data authResults:" + data.authResults);
  });
} catch(err) {
  console.log(`catch err->${JSON.stringify(err)}`);
}

requestPermissionsFromUser9+

requestPermissionsFromUser(context: Context, permissionList: Array<Permissions>) : Promise<PermissionRequestResult>;

用于UIAbility拉起弹框请求用户授权。使用promise异步回调。

说明:

非UIAbility不支持调用本函数。

模型约束:此接口仅可在Stage模型下使用。

系统能力: SystemCapability.Security.AccessToken

参数:

参数名 类型 必填 说明
context Context 请求权限的UIAbility的UIAbilityContext。
permissionList Array<Permissions> 需要校验的权限名称,合法的权限名取值可在系统权限定义列表中查询。

返回值:

类型 说明
Promise<PermissionRequestResult> 返回一个Promise,包含接口的结果。

错误码:

以下错误码的详细介绍请参见程序访问控制错误码

错误码ID 错误信息
12100001 The parameter is invalid. The context is invalid when it does not belong to the application itself.

示例:

import abilityAccessCtrl from '@ohos.abilityAccessCtrl';
let atManager = abilityAccessCtrl.createAtManager();
try {
  atManager.requestPermissionsFromUser(this.context, ["ohos.permission.CAMERA"]).then((data) => {
      console.info("data:" + JSON.stringify(data));
      console.info("data permissions:" + data.permissions);
      console.info("data authResults:" + data.authResults);
  }).catch((err) => {
      console.info("data:" + JSON.stringify(err));
  })
} catch(err) {
  console.log(`catch err->${JSON.stringify(err)}`);
}

verifyAccessToken(deprecated)

verifyAccessToken(tokenID: number, permissionName: string): Promise<GrantStatus>

校验应用是否授予权限。使用Promise异步回调。

说明:

从API version 9开始不再维护,建议使用checkAccessToken替代。

系统能力: SystemCapability.Security.AccessToken

参数:

参数名 类型 必填 说明
tokenID number 要校验的目标应用的身份标识。可通过应用的ApplicationInfo获得。
permissionName string 需要校验的权限名称。

返回值:

类型 说明
Promise<GrantStatus> Promise对象。返回授权状态结果。

示例:

import abilityAccessCtrl from '@ohos.abilityAccessCtrl';

let atManager = abilityAccessCtrl.createAtManager();
let tokenID = 0; // 系统应用可以通过bundleManager.getApplicationInfo获取,普通应用可以通过bundleManager.getBundleInfoForSelf获取
let promise = atManager.verifyAccessToken(tokenID, "ohos.permission.GRANT_SENSITIVE_PERMISSIONS");
promise.then(data => {
    console.log(`promise: data->${JSON.stringify(data)}`);
});

GrantStatus

表示授权状态的枚举。

系统能力: SystemCapability.Security.AccessToken

名称 说明
PERMISSION_DENIED -1 表示未授权。
PERMISSION_GRANTED 0 表示已授权。

PermissionStateChangeType9+

表示权限授权状态变化操作类型的枚举。

系统接口: 此接口为系统接口。

系统能力: SystemCapability.Security.AccessToken

名称 说明
PERMISSION_REVOKED_OPER 0 表示权限取消操作。
PERMISSION_GRANTED_OPER 1 表示权限授予操作。

PermissionStateChangeInfo9+

表示某次权限授权状态变化的详情。

系统接口: 此接口为系统接口。

系统能力: SystemCapability.Security.AccessToken

名称 类型 可读 可写 说明
change PermissionStateChangeType 权限授权状态变化类型。
tokenID number 被订阅的应用身份标识。
permissionName Permissions 当前授权状态发生变化的权限名,合法的权限名取值可在系统权限定义列表中查询。