Device Admin

Note: To display only the features present on a particular device, select one or more filters from the SmartDocs bar below.

Overview

The Device Administrator CSP (DevAdmin) controls which apps have administrative privileges, can access Android Device Admin APIs and how, when and whether the Screen-Lock is invoked.

Android defines some APIs as Device Administration APIs, as implemented within the DevicePolicyManager class. These APIs enable applications to perform tasks that can affect the security of the device. As such, they are restricted to specially approved "Device Administrator" applications. If an application is written to conform to the DeviceAdminReceiver model and is approved to become a Device Administrator, then it can use some or all of the Device Administration APIs.

In standard Android devices, an application that is written to conform to the DeviceAdminReceiver model must explicitly request the device user to approve it as a Device Administrator. This is based on the assumption that the device user is knowledgeable enough to make this determination. For a device that is owned and/or used by a single user, that assumption might be reasonable. For an Enterprise-owned device that might be shared among multiple device users, that assumption may be a poor one.

The DevAdmin provides direct access to certain device administration tasks and allows programmatic approval as a Device Administrator of applications written to conform to the DeviceAdminReceiver model without involving or notifying the device user. This allows an Enterprise to grant its own trusted applications access to the Device Administration APIs, thus enabling those applications to perform device administration tasks.

Main Functionality

  • Set Screen-Lock Timeout Interval
  • Set Screen Lock Type (or none)
  • Enable/Disable:
    • Installation of applications from Unknown sources
    • Device Administrator approval for an application
    • Secure Start-up Selection

Device Administration Action

Used to grant or deny approval as a Device Administrator from a qualifying application. To qualify, the app must be written to conform to the DeviceAdminReceiver model. All applications by default are initially denied approval as a Device Administrator and must be explicitly approved. Only an application that is currently installed and written to conform to the DeviceAdminReceiver model may be approved as a Device Administrator.

When an application is approved as a Device Administrator, it will be notified that it can begin using the Device Administration APIs. When Device Administrator approval is removed, the app is likewise notified that it must stop using the Device Administration APIs.

Note: The ability to grant or deny approval for an application using the DevAdmin does not prevent the device user from doing the same for an application using the System Settings panel. The effect of this parameter is the same as that of a device user going though System Settings. Access to the System Settings panel can be controlled with the UI Manager.

Parm Name: DevAdminAction

Option Name Description Note Requires
0 Do nothing This value (or the absence of this parm from the XML) will not make any change to whether any application is approved to be a Device Administrator; any previously selected setting will be retained.

OSX: 1.3+

MX: 4.3+

1 Turn On as Device Administrator Approves a specific application as a Device Administrator.

OSX: 1.3+

MX: 4.3+

2 Turn Off as Device Administrator Removes Device Administrator approval from a specific application.

OSX: 1.3+

MX: 4.3+

Device Admin Package Name

Used to enter the Package Name of an application to which to grant or deny Device Administrator privileges.

Note: The Package Name of the application must be known and specified. The Package Name can be acquired from the application developer, by looking up the Package Name on a device, or using developer tools to extract the Package Name from the APK file.

Parm value input rules:

  • String from 1 - 255 characters

Shown if: Device Administration Action is "Turn On as Device Administrator" or "Turn Off as Device Administrator"

Parm Name: DevAdminPkg

Requires:

  • OSX: 1.3+
  • MX: 4.3+

Device Admin Class Name

Used to enter the Class Name that will be added to or removed from the Device Admin list, which determines whether the application can access Android Device Admin APIs.

Note: The name of the class within the application that implements the DeviceAdminReceiver must be known and specified. This is not the same as the Activity class name required to launch the application and would likely need to be acquired from the application developer.

Parm value input rules:

  • String from 1 - 255 characters

Shown if: Device Administration Action is "Turn On as Device Administrator" or "Turn Off as Device Administrator"

Parm Name: DevAdminClass

Requires:

  • OSX: 1.3+
  • MX: 4.3+

Install from Unknown Sources

Controls whether apps can be installed (on devices with or without GMS) by the device user from sources other than Google Play. Off by default (code 2) on Zebra devices with GMS; On by default on non-GMS devices.

IMPORTANT: On non-GMS devices, disabling apps from Unknown Sources (code 2) prevents only the device user from installing apps on the device. It does NOT prevent apps from being installed through the App Manager or other programmatic means.

Note: Not supported on devices running Android 8.x Oreo or higher.

Parm Name: UnknownSourcesStatus

Option Name Description Note Requires
0 Do not change This value (or the absence of this parm from the XML) makes no change to the Unknown Sources Option; any previously selected setting is retained.

MX: 4.3+

Android API: 3+

1 Turn On Turns Unknown Sources On, allowing apps to be installed by the device user from sources other than Google Play.

MX: 4.3+

Android API: 3+

2 Turn Off Turns Unknown Sources Off, preventing apps from being installed by the device user from sources other than Google Play.

MX: 4.3+

Android API: 3+

Screen Lock Type

Controls whether a screen-lock will be invoked when the device powers up or user inactivity exceeds the Screen-Lock Timeout Interval parameter, and which Android lock screen will be displayed.

Note: On TC20/TC25 devices, available only when running Android 8.x Oreo and higher.

Parm Name: ScreenLockType

Option Name Description Note Requires
0 Do not change This value (or the absence of this parm from the XML) will cause no change to the Screen Lock Type; any previously selected setting will be retained.

OSX: 6.0+

MX: 6.0+

1 Swipe Causes the Swipe screen-lock to be displayed whenever the lock screen is invoked.

OSX: 6.0+

MX: 6.0+

2 Pattern Causes the Pattern screen-lock to be displayed whenever the lock screen is invoked.

OSX: 6.0+

MX: 6.0+

3 Pin Causes the numerical "Pin" screen-lock to be displayed whenever the lock screen is invoked.

OSX: 6.0+

MX: 6.0+

4 Password Causes the Password screen-lock to be displayed whenever the lock screen is invoked.

OSX: 6.0+

MX: 6.0+

5 None Prevents the display of any lock screen at any time.

OSX: 6.0+

MX: 6.0+

Screen-Lock Timeout Interval

Controls the length of time a device must remain inactive with the display screen off before a screen-lock is invoked.

Android supports two levels of inactivity, each controlled independently. The Display Screen Timeout, administered by the Display Manager, controls the length of time a device must remain inactive before the display screen is turned off. The Screen Lock Timeout interval (this parameter), controls how long the screen must remain off before a screen-lock will be invoked.

When the device screen is turned back on, manually by some sort of device user activity, or programmatically due to some device event, the result will depend on how long the device screen was off and the value set for the Screen Lock Timeout. If the display screen was off for less than the Screen Lock Timeout, then the screen will not be locked (and hence will not need to be unlocked by the device user). If the display screen was off for at least the Screen Lock Timeout, then the screen will be locked (and hence will need to be unlocked by the device user).

This behavior can be modified in two ways, based on other aspects of the device that may be configured. First, if no lock behavior is set for the device (e.g. no pin or password), then "unlocking" (if required) may require only a swipe, and not any actual data entry by the device user. Second, if the device is configured to lock automatically when the display screen is turned off by the power key, then a screen lock will always occur when the display screen is turned back on after being turned off via the power key, regardless of how much time the display screen was off.

Note: The Android display system supports a fixed set of interval values for the Screen-Lock Timeout as listed in the table below. This parameter is capable of configuring the timeout using only those supported values. Entering a value that is less than the smallest value shown in the table or greater than the largest value will be ignored and generate an error in the Result XML document. However, entering a value between two supported values will cause the closest value to the requested value to be selected, and generate no error in the Result XML document.

Parm Name: ScreenLockTimeoutInterval

Option Name Description Note Requires
0 Do not change This value (or the absence of this parm from the XML) will cause no change to the Screen Lock Timeout; any previously selected setting will be retained.

OSX: 1.3+

MX: 4.3+

1 Immediately after Display Timeout Causes the screen to be locked when the display screen is turned back on, regardless of how long the display screen was off.

OSX: 1.3+

MX: 4.3+

5 5 seconds after Display Timeout Causes the screen to be locked when the display screen is turned back on if the screen was off for at least 5 seconds.

OSX: 1.3+

MX: 4.3+

15 15 seconds after Display Timeout Causes the screen to be locked when the display screen is turned back on if the screen was off for at least 15 seconds.

OSX: 1.3+

MX: 4.3+

30 30 seconds after Display Timeout Causes the screen to be locked when the display screen is turned back on if the screen was off for at least 30 seconds.

OSX: 1.3+

MX: 4.3+

60 1 minute after Display Timeout Causes the screen to be locked when the display screen is turned back on if the screen was off for at least 1 minute.

OSX: 1.3+

MX: 4.3+

120 2 minutes after Display Timeout Causes the screen to be locked when the display screen is turned back on if the screen was off for at least 2 minutes.

OSX: 1.3+

MX: 4.3+

300 5 minutes after Display Timeout Causes the screen to be locked when the display screen is turned back on if the screen was off for at least 5 minutes.

OSX: 1.3+

MX: 4.3+

600 10 minutes after Display Timeout Causes the screen to be locked when the display screen is turned back on if the screen was off for at least 10 minutes.

OSX: 1.3+

MX: 4.3+

1800 30 minutes after Display Timeout Causes the screen to be locked when the display screen is turned back on if the screen was off for at least 30 minutes.

OSX: 1.3+

MX: 4.3+

Secure Start-up Selection

Controls whether the "YES" button is available for selection by a device user on the "Secure Start-up" dialog box after changing the device lock-screen password, PIN or swipe pattern in the Android Settings panel. If "YES" is pressed, the same password, PIN or pattern that protects access to the Android Launcher app also would be applied to protect the device start-up process, preventing the device from booting if restarted.

IMPORTANT: If the device is rebooted with this feature enabled, the device remains unmanaged and inoperable until the password, PIN or pattern is entered and the start-up process is allowed to complete.

Parm Name: SecureStartupSelection

Option Name Description Note Requires
0 Do not change This value (or the absence of this parm from the XML) makes no change to device settings; any previously selected setting is retained.

OSX: 6.2+

MX: 10.0+

Android API: 26+

1 Enable Allows the user to select "YES" when prompted to protect the device boot process.

OSX: 6.2+

MX: 10.0+

Android API: 26+

2 Disable Disables "YES" button, preventing device user from electing to protect the device boot process.

OSX: 6.2+

MX: 10.0+

Android API: 26+

Examples

Set the Screen to Lock to 1 Minute After the Display Times Out


<wap-provisioningdoc>
    <characteristic type="DevAdmin" version="4.3" >
        <parm name="ScreenLockTimeoutInterval" value="60"/>
    </characteristic>
</wap-provisioningdoc>

Allow Application Installs from Unknown Sources


<wap-provisioningdoc>
    <characteristic type="DevAdmin" version="4.3" >
        <parm name="UnknownSourcesStatus" value="1"/>
    </characteristic>
</wap-provisioningdoc>

Queries

Get Apps that are Active Device Admins

Input


<wap-provisioningdoc>
    <characteristic type="DevAdmin" version="4.3" >
        <characteristic-query type="AppAsDevAdmin"/>
    </characteristic>
</wap-provisioningdoc>

Output


<wap-provisioningdoc>
    <characteristic type="DevAdmin" version="4.3" >
        <characteristic type="AppAsDevAdmin">
            <parm name="DevAdminAction" value="1"/>
            <characteristic type="DevAdminDetails">
                <parm name="DevAdminPkg" value="PackageName1"/>
                <parm name="DevAdminClass" value="ClassName1"/>
            </characteristic>
        </characteristic>
    </characteristic>
    <characteristic type="DevAdmin" version="4.3" >
        <characteristic type="AppAsDevAdmin">
            <parm name="DevAdminAction" value="1"/>
            <characteristic type="DevAdminDetails">
                <parm name="DevAdminPkg" value="PackageName2"/>
                <parm name="DevAdminClass" value="ClassName2"/>
            </characteristic>
        </characteristic>
    </characteristic>
</wap-provisioningdoc>

Get Screen Lock Timeout Interval

Input


<wap-provisioningdoc>
    <characteristic type="DevAdmin">
        <parm-query name="ScreenLockTimeoutInterval"/>
    </characteristic>
</wap-provisioningdoc>

Output


<wap-provisioningdoc>
    <characteristic type="DevAdmin" version="4.3">
        <parm name="ScreenLockTimeoutInterval" value="1"/>
    </characteristic>
</wap-provisioningdoc>

Get Install Apps from Unknown Sources Status

Input


<wap-provisioningdoc>
    <characteristic type="DevAdmin">
        <parm-query name="UnknownSourcesStatus"/>
    </characteristic>
</wap-provisioningdoc>

Output


<wap-provisioningdoc>
    <characteristic type="DevAdmin" version="4.3">
        <parm name="UnknownSourcesStatus" value="1"/>
    </characteristic>
</wap-provisioningdoc>