目录

@ohos.enterprise.adminManager (Administrator Permission Management)

The adminManager module provides administrator permission management capabilities for enterprise MDM applications, including enabling or disabling administrator permissions, subscribing to events, delegating applications, and granting permissions.

The initial APIs of this module are supported since API version 12. Newly added APIs will be marked with a superscript to indicate their earliest API version.

The APIs of this module can be called only by a device administrator application. For details, see MDM Kit Development.

Modules to Import

import { adminManager } from '@kit.MDMKit';

adminManager.disableAdmin

disableAdmin(admin: Want, userId?: number): Promise<void>

Disables a device administrator application for the specified user. This API uses a promise to return the result. After this API is called successfully, the specified device administrator application will be deactivated and no longer have the device management capability.

Required permissions: ohos.permission.MANAGE_ENTERPRISE_DEVICE_ADMIN (available only to system applications), ohos.permission.START_PROVISIONING_MESSAGE, or ohos.permission.ENTERPRISE_DEACTIVATE_DEVICE_ADMIN

- Since API version 23, the ohos.permission.ENTERPRISE_DEACTIVATE_DEVICE_ADMIN permission is supported. This permission can be applied for only when an SDA or DA device administrator application deactivates itself.

- Since API version 20, the ohos.permission.START_PROVISIONING_MESSAGE permission is supported. This permission can be applied for only when a BYOD device administrator application deactivates itself.

- For API version 19 and earlier, the ohos.permission.MANAGE_ENTERPRISE_DEVICE_ADMIN permission (available only to system applications) is required.

System capability: SystemCapability.Customization.EnterpriseDeviceManager

Model restriction: This API can be used only in the stage model.

Parameters

Name Type Mandatory Description
admin Want Yes EnterpriseAdminExtensionAbility. Want must contain the ability name of the EnterpriseAdminExtensionAbility and the bundle name of the application. When deactivating the BYOD device administrator application, you can pass only the EnterpriseAdminExtensionAbility component of the current application.
userId number No

User ID, which must be greater than or equal to 0.

- If userId is passed in, this API applies to the specified user.

- If userId is not passed in, this API applies to the current user.

Return value

Type Description
Promise<void> Promise that returns no value. If the operation fails, an error object will be thrown.

Error codes

For details about the error codes, see Enterprise Device Management Error Codes and Universal Error Codes.

ID Error Message
9200005 Failed to deactivate the administrator application of the device.
201 Permission verification failed. The application does not have the permission required to call the API.

Example

import { adminManager } from '@kit.MDMKit';
import { Want } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let wantTemp: Want = {
  // Replace with actual values.
  bundleName: 'com.example.myapplication',
  abilityName: 'EnterpriseAdminAbility'
};

adminManager.disableAdmin(wantTemp, 100).catch((err: BusinessError) => {
  console.error(`Failed to disable admin. Code: ${err.code}, message: ${err.message}`);
});

adminManager.isByodAdmin20+

isByodAdmin(admin: Want): boolean

Checks whether the current application is activated as a BYOD device administrator application based on the EnterpriseAdminExtensionAbility component.

Required permission: ohos.permission.START_PROVISIONING_MESSAGE

System capability: SystemCapability.Customization.EnterpriseDeviceManager

Model restriction: This API can be used only in the stage model.

Parameters

Name Type Mandatory Description
admin Want Yes EnterpriseAdminExtensionAbility. Want must contain the ability name of the EnterpriseAdminExtensionAbility and the bundle name of the application. Only the EnterpriseAdminExtensionAbility component of the current application can be passed.

Return value

Type Description
boolean The value true indicates the application is activated as a BYOD device administrator application, and the value false indicates the opposite.

Error codes

For details about the error codes, see Enterprise Device Management Error Codes and Universal Error Codes.

ID Error Message
201 Permission verification failed. The application does not have the permission required to call the API.
9200012 Parameter verification failed.

Example

import { Want } from '@kit.AbilityKit';
import { adminManager } from '@kit.MDMKit';

let wantTemp: Want = {
  // Replace with actual values.
  bundleName: 'com.example.myapplication',
  abilityName: 'EnterpriseAdminAbility'
};

try {
  let result: boolean = adminManager.isByodAdmin(wantTemp);
  console.info(`Succeeded in querying admin is byod admin or not : ${result}`);
} catch (error) {
  console.error(`Failed to query admin is byod admin or not. Code is ${error.code}, message is ${error.message}`);
}

adminManager.subscribeManagedEventSync

subscribeManagedEventSync(admin: Want, managedEvents: Array<ManagedEvent>): void

Subscribes to system management events. After the call is successful, the device administrator application will receive a notification when a subscribed system management event occurs.

Since API version 26.0.0, error code 9200002 is returned when a non-super device administrator application calls this API to subscribe to the MANAGED_EVENT_POLICIES_CHANGED event.

Required permissions: ohos.permission.ENTERPRISE_SUBSCRIBE_MANAGED_EVENT

System capability: SystemCapability.Customization.EnterpriseDeviceManager

Model restriction: This API can be used only in the stage model.

Parameters

Name Type Mandatory Description
admin Want Yes EnterpriseAdminExtensionAbility. Want must contain the ability name of the EnterpriseAdminExtensionAbility and the bundle name of the application.
managedEvents Array<ManagedEvent> Yes Array of subscribed events, used to specify the system management events to subscribe to. The array elements are ManagedEvent enum values, and multiple event types can be subscribed to, such as application install/uninstall/start/stop events and system update events.

Error codes

For details about the error codes, see Enterprise Device Management Error Codes and Universal Error Codes.

ID Error Message
9200001 The application is not an administrator application of the device.
9200002

The administrator application does not have permission to manage the device.

Applicable version: 26.0.0+
9200008 The specified system event is invalid.
201 Permission verification failed. The application does not have the permission required to call the API.
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

import { adminManager } from '@kit.MDMKit';
import { Want } from '@kit.AbilityKit';

let wantTemp: Want = {
  // Replace with actual values.
  bundleName: 'com.example.myapplication',
  abilityName: 'EnterpriseAdminAbility'
};
let events: Array<adminManager.ManagedEvent> = [adminManager.ManagedEvent.MANAGED_EVENT_BUNDLE_ADDED,
  adminManager.ManagedEvent.MANAGED_EVENT_BUNDLE_REMOVED];

try {
  adminManager.subscribeManagedEventSync(wantTemp, events);
  console.info('Succeeded in subscribing managed event.');
} catch (err) {
  console.error(`Failed to subscribe managed event. Code: ${err.code}, message: ${err.message}`);
}

adminManager.unsubscribeManagedEventSync

unsubscribeManagedEventSync(admin: Want, managedEvents: Array<ManagedEvent>): void

Unsubscribes from system management events. After the API is successfully called, no notifications for the unsubscribed system management events will be received.

Required permissions: ohos.permission.ENTERPRISE_SUBSCRIBE_MANAGED_EVENT

System capability: SystemCapability.Customization.EnterpriseDeviceManager

Model restriction: This API can be used only in the stage model.

Parameters

Name Type Mandatory Description
admin Want Yes EnterpriseAdminExtensionAbility. Want must contain the ability name of the EnterpriseAdminExtensionAbility and the bundle name of the application.
managedEvents Array<ManagedEvent> Yes Array of system management events to be unsubscribed from. Each element in the array is a value from the ManagedEvent enumeration. The input event types must be the same as those passed during subscription.

Error codes

For details about the error codes, see Enterprise Device Management Error Codes and Universal Error Codes.

ID Error Message
9200001 The application is not an administrator application of the device.
9200008 The specified system event is invalid.
201 Permission verification failed. The application does not have the permission required to call the API.
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

import { adminManager } from '@kit.MDMKit';
import { Want } from '@kit.AbilityKit';

let wantTemp: Want = {
  // Replace with actual values.
  bundleName: 'com.example.myapplication',
  abilityName: 'EnterpriseAdminAbility'
};
let events: Array<adminManager.ManagedEvent> = [adminManager.ManagedEvent.MANAGED_EVENT_BUNDLE_ADDED,
  adminManager.ManagedEvent.MANAGED_EVENT_BUNDLE_REMOVED];

try {
  adminManager.unsubscribeManagedEventSync(wantTemp, events);
  console.info('Succeeded in unsubscribing managed event.');
} catch (err) {
  console.error(`Failed to unsubscribe managed event. Code: ${err.code}, message: ${err.message}`);
}

adminManager.setDelegatedPolicies14+

setDelegatedPolicies(admin: Want, bundleName: string, policies: Array<string>): void

Delegates other applications to set device management policies. The applications must request the permissions required.

Required permission: ohos.permission.ENTERPRISE_MANAGE_DELEGATED_POLICY

System capability: SystemCapability.Customization.EnterpriseDeviceManager

Model restriction: This API can be used only in the stage model.

Parameters

Name Type Mandatory Description
admin Want Yes EnterpriseAdminExtensionAbility. Want must contain the ability name of the EnterpriseAdminExtensionAbility and the bundle name of the application.
bundleName string Yes Bundle name of the delegated application. The distribution type of the delegated application must be enterprise_normal or enterprise_mdm. You can call the getBundleInfoForSelf API to query the BundleInfo of the application, where BundleInfo.appInfo.appDistributionType indicates the distribution type.
policies Array<string> Yes Delegable policy list.

Error codes

For details about the error codes, see Enterprise Device Management Error Codes and Universal Error Codes.

ID Error Message
9200001 The application is not an administrator application of the device.
9200002 The administrator application does not have permission to manage the device.
9200009 Failed to grant the permission to the application.
201 Permission verification failed. The application does not have the permission required to call the API.
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

import { adminManager } from '@kit.MDMKit';
import { Want } from '@kit.AbilityKit';

let admin: Want = {
  // Replace with actual values.
  bundleName: 'com.example.myapplication',
  abilityName: 'EnterpriseAdminAbility'
};
// Replace with actual values.
let policies: Array<string> = ["disabled_hdc"];

try {
  // Replace parameters with actual values.
  adminManager.setDelegatedPolicies(admin, "com.example.enterprise.xxx", policies);
  console.info('Succeeded in setting delegated policies.');
} catch (err) {
  console.error(`Failed to set delegated policies. Code: ${err.code}, message: ${err.message}`);
}

adminManager.getDelegatedPolicies14+

getDelegatedPolicies(admin: Want, bundleName: string): Array<string>

Queries the list of policies that can be accessed by the delegated application.

Required permission: ohos.permission.ENTERPRISE_MANAGE_DELEGATED_POLICY

System capability: SystemCapability.Customization.EnterpriseDeviceManager

Model restriction: This API can be used only in the stage model.

Parameters

Name Type Mandatory Description
admin Want Yes EnterpriseAdminExtensionAbility. Want must contain the ability name of the EnterpriseAdminExtensionAbility and the bundle name of the application.
bundleName string Yes Bundle name of the delegated application. The distribution type of the delegated application must be enterprise_normal or enterprise_mdm. You can call the getBundleInfoForSelf API to query the BundleInfo of the application, where BundleInfo.appInfo.appDistributionType indicates the distribution type.

Return value

Type Description
Array<string> Delegation policy list.

Error codes

For details about the error codes, see Enterprise Device Management Error Codes and Universal Error Codes.

ID Error Message
9200001 The application is not an administrator application of the device.
9200002 The administrator application does not have permission to manage the device.
201 Permission verification failed. The application does not have the permission required to call the API.
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

import { adminManager } from '@kit.MDMKit';
import { Want } from '@kit.AbilityKit';

let admin: Want = {
  // Replace with actual values.
  bundleName: 'com.example.myapplication',
  abilityName: 'EnterpriseAdminAbility'
};

try {
  // Replace parameters with actual values.
  let policies: Array<string> = adminManager.getDelegatedPolicies(admin, "com.example.enterprise.xxx");
  console.info(`Succeeded in getting delegated policies.${JSON.stringify(policies)}`);
} catch (err) {
  console.error(`Failed to get delegated policies. Code: ${err.code}, message: ${err.message}`);
}

adminManager.getDelegatedBundleNames14+

getDelegatedBundleNames(admin: Want, policy: string): Array<string>

Queries the delegated applications that can access a delegation policy and output the list of delegated applications.

Required permission: ohos.permission.ENTERPRISE_MANAGE_DELEGATED_POLICY

System capability: SystemCapability.Customization.EnterpriseDeviceManager

Model restriction: This API can be used only in the stage model.

Parameters

Name Type Mandatory Description
admin Want Yes EnterpriseAdminExtensionAbility. Want must contain the ability name of the EnterpriseAdminExtensionAbility and the bundle name of the application.
policy string Yes Delegation policy.

Return value

Type Description
Array<string> List of delegated applications.

Error codes

For details about the error codes, see Enterprise Device Management Error Codes and Universal Error Codes.

ID Error Message
9200001 The application is not an administrator application of the device.
9200002 The administrator application does not have permission to manage the device.
201 Permission verification failed. The application does not have the permission required to call the API.
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

import { adminManager } from '@kit.MDMKit';
import { Want } from '@kit.AbilityKit';

let admin: Want = {
  // Replace with actual values.
  bundleName: 'com.example.myapplication',
  abilityName: 'EnterpriseAdminAbility'
};

try {
  // Replace parameters with actual values.
  let bundleNames: Array<string> = adminManager.getDelegatedBundleNames(admin, "disabled_hdc");
  console.info(`Succeeded in getting delegated bundles.${JSON.stringify(bundleNames)}`);
} catch (err) {
  console.error(`Failed to get delegated bundles. Code: ${err.code}, message: ${err.message}`);
}

adminManager.startAdminProvision15+

startAdminProvision(admin: Want, type: AdminType, context: common.Context, parameters: Record<string, string>): void

Enables the device administrator application to open a page for the BYOD administrator to perform activation.

Required permission: ohos.permission.START_PROVISIONING_MESSAGE

System capability: SystemCapability.Customization.EnterpriseDeviceManager

Device behavior differences: This API can be properly called on phones and tablets but does not take effect on other devices.

Model restriction: This API can be used only in the stage model.

Parameters

Name Type Mandatory Description
admin Want Yes EnterpriseAdminExtensionAbility. Want must contain the ability name of the EnterpriseAdminExtensionAbility and the bundle name of the application.
type AdminType Yes Type of the activated device administrator application. Only the ADMIN_TYPE_BYOD type is supported.
context common.Context Yes Context information of the administrator application.
parameters Record<string, string> Yes

Custom parameter information. The Key value must include "activateId", and can include "customizedInfo" and "localDeactivationPolicy".

- activateId: project activation ID.

- customizedInfo: enterprise-defined custom information.

- localDeactivationPolicy: local delayed deactivation time (unit: hour). The duration passed in on the device side must be less than or equal to the duration configured on the cloud side; otherwise, activation fails and an invalid activation parameter is reported. The actual effective value is based on the duration passed in on the device side. This is supported since API version 22.
  1. This API takes effect only on enterprise devices.
  2. The credential parameter indicates the activation credential, which can be requested by the administrator on the HEM platform. |

Error codes

For details about the error codes, see Universal Error Codes.

ID Error Message
201 Permission verification failed. The application does not have the permission required to call the API.
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

import { adminManager } from '@kit.MDMKit';
import { common, Want } from '@kit.AbilityKit';

let wantTemp: Want = {
  // Replace with actual values.
  bundleName: 'com.example.myapplication',
  abilityName: 'EnterpriseAdminAbility'
};
let recordParameters: Record<string, string> = {
  // Replace with actual values.
  "activateId": "activateId testValue",
  "customizedInfo": "customizedInfo testValue"
};
// Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext.
const context = this.getUIContext().getHostContext() as common.UIAbilityContext;
try {
  console.info('context:' + JSON.stringify(context));
  adminManager.startAdminProvision(wantTemp, adminManager.AdminType.ADMIN_TYPE_BYOD, context, recordParameters);
  console.info('Succeeded in starting Admin Provision');
} catch (error) {
  console.error('Failed to start Admin Provision::errorCode: ' + error.code + ' errorMessage: ' + error.message);
}

adminManager.enableDeviceAdmin23+

enableDeviceAdmin(admin: Want): Promise<void>

Enables a DA application by a SDA application. This API uses a promise to return the result. After the API is successfully called, the specified DA application is enabled and granted device management capabilities. This API can be called only by super device administrator applications.

Required permissions: ohos.permission.ENTERPRISE_MANAGE_DEVICE_ADMIN

System capability: SystemCapability.Customization.EnterpriseDeviceManager

Device behavior differences: This API can be properly called on PCs/2-in-1 devices. If it is called on other device types, error code 801 is returned.

Model restriction: This API can be used only in the stage model.

Parameters

Name Type Mandatory Description
admin Want Yes EnterpriseAdminExtensionAbility. Want must contain the ability name of the EnterpriseAdminExtensionAbility and the bundle name of the application.

Return value

Type Description
Promise<void> Promise that returns no value. If the operation fails, an error object will be thrown.

Error codes

For details about the error codes, see Enterprise Device Management Error Codes and Universal Error Codes.

ID Error Message
9200001 The application is not an administrator application of the device.
9200002 The administrator application does not have permission to manage the device.
9200003 The administrator ability component is invalid.
9200004 Failed to activate the administrator application of the device.
201 Permission verification failed. The application does not have the permission required to call the API.
801 Capability not supported. Failed to call the API due to limited device capabilities.

Example

import { Want } from '@kit.AbilityKit';
import { adminManager } from '@kit.MDMKit';
import { BusinessError } from '@kit.BasicServicesKit';

let wantTemp: Want = {
  // Replace with actual values.
  bundleName: 'com.example.myapplication',
  abilityName: 'EnterpriseAdminAbility'
};

adminManager.enableDeviceAdmin(wantTemp).catch((err: BusinessError) => {
  console.error(`Failed to enable device admin. Code: ${err.code}, message: ${err.message}`);
});

adminManager.disableDeviceAdmin23+

disableDeviceAdmin(admin: Want): Promise<void>

Disables a DA application by a SDA application. This API uses a promise to return the result. After this API is called successfully, the specified device administrator application is disabled and no longer has the device management capability. This API can be called only by super device administrator applications.

Required permissions: ohos.permission.ENTERPRISE_MANAGE_DEVICE_ADMIN

System capability: SystemCapability.Customization.EnterpriseDeviceManager

Device behavior differences: This API can be properly called on PCs/2-in-1 devices. If it is called on other device types, error code 801 is returned.

Model restriction: This API can be used only in the stage model.

Parameters

Name Type Mandatory Description
admin Want Yes EnterpriseAdminExtensionAbility. Want must contain the ability name of the EnterpriseAdminExtensionAbility and the bundle name of the application.

Return value

Type Description
Promise<void> Promise that returns no value. If the operation fails, an error object will be thrown.

Error codes

For details about the error codes, see Enterprise Device Management Error Codes and Universal Error Codes.

ID Error Message
9200001 The application is not an administrator application of the device.
9200002 The administrator application does not have permission to manage the device.
9200005 Failed to deactivate the administrator application of the device.
201 Permission verification failed. The application does not have the permission required to call the API.
801 Capability not supported. Failed to call the API due to limited device capabilities.

Example

import { Want } from '@kit.AbilityKit';
import { adminManager } from '@kit.MDMKit';
import { BusinessError } from '@kit.BasicServicesKit';

let wantTemp: Want = {
  // Replace with actual values.
  bundleName: 'com.example.myapplication',
  abilityName: 'EnterpriseAdminAbility'
};

adminManager.disableDeviceAdmin(wantTemp).catch((err: BusinessError) => {
  console.error(`Failed to disable device admin. Code: ${err.code}, message: ${err.message}`);
});

adminManager.enableSelfDeviceAdmin

enableSelfDeviceAdmin(admin: Want, credential: string): void

Allows an MDM application to enable itself in scenarios where it is not pre-enabled on the enterprise device. This API supports enablement of the MDM application itself only, and cannot be used to enable other MDM applications. The supported enablement types include super device administrator application and normal device administrator application.

  1. This API takes effect only on enterprise devices.
  2. The credential parameter indicates the activation credential, which can be requested by the administrator on the HEM platform.

Since: 26.0.0

Required permissions: ohos.permission.ENTERPRISE_ACTIVATE_DEVICE_ADMIN

System capability: SystemCapability.Customization.EnterpriseDeviceManager

Device behavior differences: This API can be properly called on PCs/2-in-1 devices. If it is called on other device types, error code 801 is returned.

Model restriction: This API can be used only in the stage model.

Parameters

Name Type Mandatory Description
admin Want Yes EnterpriseAdminExtensionAbility. Want must contain the ability name of the EnterpriseAdminExtensionAbility and the bundle name of the application.
credential string Yes Enablement credential.

Error codes

For details about the error codes, see Enterprise Device Management Error Codes and Universal Error Codes.

ID Error Message
9200003 The administrator ability component is invalid.
9200004 Failed to activate the administrator application of the device.
9200012 Parameter verification failed.
9200017 The self-activation credential of the enterprise device administrator is invalid.
9200018 This device is not an enterprise device.
201 Permission verification failed. The application does not have the permission required to call the API.
801 Capability not supported. Failed to call the API due to limited device capabilities.

Example

import { Want } from '@kit.AbilityKit';
import { adminManager } from '@kit.MDMKit';

let wantTemp: Want = {
  // Replace with actual values.
  bundleName: 'com.example.myapplication',
  abilityName: 'EnterpriseAdminAbility'
};

// Replace with actual values.
let credential: string = '{"enterpriseId": "123456", "appIdentifier": "123456", "type": "SDA", "sign": "", "certs": []}';

try {
  adminManager.enableSelfDeviceAdmin(wantTemp, credential);
  console.info(`succeed in enabling self device admin.`);
} catch (err) {
  console.error(`Failed to enable self device admin. Code: ${err.code}, message: ${err.message}`);
}

ManagedEvent

Enumerates the system management events that can be subscribed to.

System capability: SystemCapability.Customization.EnterpriseDeviceManager

Name Value Description
MANAGED_EVENT_BUNDLE_ADDED 0 An application is installed.
MANAGED_EVENT_BUNDLE_REMOVED 1 An application is uninstalled.
MANAGED_EVENT_APP_START 2 An application is started.
MANAGED_EVENT_APP_STOP 3 An application is stopped.
MANAGED_EVENT_SYSTEM_UPDATE 4 The system is updated.
MANAGED_EVENT_ACCOUNT_ADDED18+ 5 An account is created.
MANAGED_EVENT_ACCOUNT_SWITCHED18+ 6 An account is switched.
MANAGED_EVENT_ACCOUNT_REMOVED18+ 7 An account is removed.
MANAGED_EVENT_STARTUP_GUIDE_COMPLETED24+ 8

The startup wizard is complete.

Model restriction: This API can be used only in the stage model.
MANAGED_EVENT_BOOT_COMPLETED24+ 9

Device startup is complete.

Model restriction: This API can be used only in the stage model.
MANAGED_EVENT_BUNDLE_UPDATED 10

Application update event.

Since: 26.0.0

Model restriction: This API can be used only in the stage model.
MANAGED_EVENT_POLICIES_CHANGED 11

Policy change event. Only super device administrator applications can subscribe to this event. If other types of device administrator applications attempt to subscribe, error code 9200002 is returned.

Since: 26.0.0

Model restriction: This API can be used only in the stage model.

AdminType15+

Enumerates the types of device administrator applications.

System capability: SystemCapability.Customization.EnterpriseDeviceManager

Name Value Description
ADMIN_TYPE_BYOD 0x02 BYOD device administrator application.

Policy20+

Defines the policy type for the trustlist or blocklist.

System capability: SystemCapability.Customization.EnterpriseDeviceManager

Model restriction: This API can be used only in the stage model.

Name Value Description
BLOCK_LIST 0 Blocklist.
TRUST_LIST 1 Trustlist.