Quản lý vai trò ứng dụng

Tính năng vai trò của ứng dụng cho phép quản trị viên CNTT cấp các đặc quyền cho một ứng dụng được quản lý trên thiết bị Android. Bằng cách chỉ định một vai trò cụ thể, ứng dụng có thể được miễn các quy định hạn chế về nguồn điện và hoạt động trong nền, tạm ngưng, ngủ đông (trên Android 14 trở lên) và tắt các chế độ kiểm soát của người dùng (tức là bao gồm các hành động của người dùng như buộc dừng và xoá dữ liệu ứng dụng) (trên Android 11 trở lên), cho phép ứng dụng thực hiện chức năng quan trọng mà không bị gián đoạn. Ngoài ra, ứng dụng có thể được thông báo về các vai trò được chỉ định, cho phép ứng dụng tự khởi động mà không cần người dùng can thiệp.

Lưu ý: Tính năng vai trò của ứng dụng thay thế trường extensionConfig trong ApplicationPolicy.

Để biết danh sách các vai trò có sẵn trong ứng dụng và các đặc quyền được cấp cho từng vai trò, hãy xem RoleType.

Điều kiện tiên quyết

Thiết bị do một EMM dựa trên AMAPI quản lý (không hỗ trợ các EMM sử dụng DPC tuỳ chỉnh).

Chuẩn bị ứng dụng để sử dụng tính năng này

Bạn chỉ cần tích hợp với SDK AMAPI nếu ứng dụng muốn được thông báo về các vai trò được chỉ định, cho phép ứng dụng tự khởi động (tức là tự động chạy mà không cần người dùng tương tác).

Tích hợp với SDK AMAPI trong ứng dụng

Bạn có thể tìm thêm thông tin về AMAPI SDK và cách thêm SDK này vào ứng dụng trong hướng dẫn tích hợp AMAPI SDK.

Thêm siêu dữ liệu bắt buộc vào tệp kê khai của ứng dụng

Chính sách thiết bị Android (ADP) cần biết ComponentName của lớp triển khai NotificationReceiverService để thông báo cho ứng dụng của bạn về vai trò được chỉ định. Bạn phải gắn thẻ dịch vụ của mình trong AndroidManifest.xml một cách phù hợp để ADP có thể tự động phát hiện dịch vụ đó.

• Ứng dụng của bạn phải có đúng một dịch vụ là enabled và có meta-data với android:name bằng com.google.android.managementapi.notification.NotificationReceiverService.SERVICE_APP_ROLES
• Dịch vụ này phải có android:exported được đặt thành true
• Bạn phải đặt android:value của meta-data thành một chuỗi trống

<service
 android:name=".MyNotificationReceiverService"
 android:exported="true">
    <meta-data android:name="com.google.android.managementapi.notification.NotificationReceiverService.SERVICE_APP_ROLES" android:value="" />
</service>

Lưu ý: Lớp cơ sở NotificationReceiverService tự động xử lý các biện pháp bảo vệ an ninh. Điều này đảm bảo rằng chỉ ứng dụng Android Device Policy (ADP) mới có thể giao tiếp an toàn với dịch vụ này. Bạn không cần khai báo quyền BIND tuỳ chỉnh hoặc xác minh gói gọi theo cách thủ công.

Nếu đang kiểm thử vai trò COMPANION_APP, bạn cũng nên thêm meta-data sau đây vào dịch vụ của mình để Chính sách thiết bị Android có thể gửi thông tin cập nhật về trạng thái lệnh cục bộ đến ứng dụng của bạn:

<meta-data android:name="com.google.android.managementapi.notification.NotificationReceiverService.SERVICE_COMMAND_STATUS" android:value="" />

Tạo một dịch vụ mở rộng NotificationReceiverService (hoặc cập nhật dịch vụ hiện có)

Tạo hoặc cập nhật NotificationReceiverService hiện có và triển khai AppRolesListener để theo dõi các vai trò được chỉ định cho ứng dụng của bạn. Bạn chỉ cần getAppRolesListener() để theo dõi các vai trò được chỉ định cho ứng dụng của mình. Nếu ứng dụng của bạn được chỉ định vai trò COMPANION_APP, bạn cũng nên triển khai getCommandListener():

import android.util.Log
import com.google.android.managementapi.approles.AppRolesListener
import com.google.android.managementapi.approles.model.AppRolesSetRequest
import com.google.android.managementapi.approles.model.AppRolesSetResponse
import com.google.android.managementapi.commands.CommandListener
import com.google.android.managementapi.commands.model.Command
import com.google.android.managementapi.notification.NotificationReceiverService

class MyNotificationReceiverService : NotificationReceiverService() {

  // If your app wants to listen for roles assigned
  override fun getAppRolesListener(): AppRolesListener =
    object : AppRolesListener {
      override fun onAppRolesSet(request: AppRolesSetRequest): AppRolesSetResponse {
        val roleTypes = request.roles.map { role -> role.roleType }
        Log.i(TAG, "onAppRolesSet: $roleTypes")

        return AppRolesSetResponse.getDefaultInstance()
      }
    }

 // If your app wants to listen for local command status updates
 // Only relevant for COMPANION_APP role
 override fun getCommandListener(): CommandListener {
    return object : CommandListener {
      override fun onCommandStatusChanged(command: Command) {
         Log.i(TAG, "onCommandStatusChanged")
      }
    }
  }

  private companion object {
    const val TAG = "MyNotificationReceiverService"
  }
}

Lưu ý: Ứng dụng của bạn sẽ chỉ được thông báo về các vai trò được chỉ định khi có thay đổi về vai trò hoặc các chức năng bổ sung của vai trò đó.

Ứng dụng của bạn có thể nhận được thông báo nhiều lần nếu vai trò của ứng dụng thay đổi nhiều lần. Nếu tất cả vai trò đều bị xoá, ứng dụng của bạn vẫn sẽ được thông báo bằng danh sách vai trò trống. Thông báo này sẽ đưa ứng dụng của bạn ra khỏi trạng thái dừng và cùng với các trường hợp miễn trừ được cấp cho ứng dụng, ứng dụng của bạn có thể tự khởi động mà không cần người dùng tương tác. Nhờ thông báo và các trường hợp miễn trừ về vai trò của ứng dụng, ứng dụng của bạn có thể theo dõi các thông báo truyền tin ACTION_BOOT_COMPLETED. Nếu ứng dụng của bạn phụ thuộc vào cấu hình được quản lý để tự khởi động, hãy xem phần Thiết lập cấu hình được quản lý để biết cách đọc và theo dõi các thay đổi.

Kể từ AMAPI SDK 1.9.0, mỗi vai trò trong AppRolesSetRequest cũng bao gồm Role.ExtraCapabilities mà quản trị viên CNTT đã cấp trong chính sách. Ví dụ: một ứng dụng đồng hành có thể kiểm tra xem ứng dụng đó có được phép đưa ra lệnh xoá cục bộ hay không:

import com.google.android.managementapi.approles.model.AppRolesSetRequest
import com.google.android.managementapi.approles.model.AppRolesSetResponse
import com.google.android.managementapi.common.model.Role
...

  override fun onAppRolesSet(request: AppRolesSetRequest): AppRolesSetResponse {
    val canWipeLocally =
      request.roles.any { role ->
        role.roleType == Role.RoleType.COMPANION_APP &&
          role.extraCapabilities.localDeviceWipeCommand ==
            Role.ExtraCapabilities.LocalDeviceWipeCommand.LOCAL_DEVICE_WIPE_COMMAND_ALLOWED
      }
    Log.i(TAG, "onAppRolesSet: canWipeLocally=$canWipeLocally")

    return AppRolesSetResponse.getDefaultInstance()
  }

Chỉ quản trị viên CNTT mới có thể cấp thêm quyền. Nếu bạn đặt extraCapabilities cho một vai trò mà bạn truyền đến EnvironmentClient, thì lệnh gọi sẽ không thành công và trả về lỗi InvalidArgumentException.

Cung cấp thiết bị có chính sách về vai trò của ứng dụng

Nhà phát triển ứng dụng có thể thử nghiệm việc chỉ định vai trò ứng dụng cho ứng dụng của họ bằng cách sử dụng EMM hoặc làm theo hướng dẫn bắt đầu nhanh về Android Management API. Sổ tay Colab AMAPI cho phép bạn đăng ký một doanh nghiệp, tạo chính sách và cấp phép cho một thiết bị.

Đặt chính sách cho ứng dụng của bạn bằng vai trò ứng dụng

Thiết lập policy với các vai trò mà ứng dụng của bạn dự định có bằng cách sử dụng ApplicationPolicy.roles.

Ví dụ sau đây cho thấy cách định cấu hình vai trò cho các ứng dụng MTD:

{
  "applications": [

    {
      "packageName": "com.example.mtd",
      "installType": "FORCE_INSTALLED",
      "roles": [
        { "roleType": "MOBILE_THREAT_DEFENSE_ENDPOINT_DETECTION_RESPONSE" }
      ]
    }
  ]
}

Điểm mấu chốt: Một ứng dụng có thể có nhiều vai trò nhưng bất kỳ vai trò nào cũng chỉ có thể được chỉ định cho một ứng dụng duy nhất. Hãy xem RoleType để biết danh sách tất cả các vai trò ứng dụng có sẵn.

Chỉ vai trò COMPANION_APP mới hỗ trợ extraCapabilities. Để cho phép ứng dụng đồng hành xoá thiết bị hoặc hồ sơ công việc trên thiết bị, hãy đặt extraCapabilities.localDeviceWipeCommand thành LOCAL_DEVICE_WIPE_COMMAND_ALLOWED cho vai trò đó.

Trước khi chỉ định các vai trò như đã nêu trong chính sách, hệ thống sẽ kiểm tra xem dấu vân tay chứng chỉ của khoá ký của ứng dụng trên thiết bị có khớp với dấu vân tay chứng chỉ trên Cửa hàng Play hay không. Nếu vân tay số khác nhau, thì các vai trò sẽ không được chỉ định cho ứng dụng và NonComplianceReason.APP_SIGNING_CERT_MISMATCH sự không tuân thủ sẽ được báo cáo cho EMM.

Lưu ý: Bạn có thể kiểm thử nhiều bản dựng của ứng dụng, được ký bằng một chứng chỉ khác, bằng cách cung cấp thêm vân tay số của chứng chỉ khoá ký (giá trị băm SHA-256 được mã hoá theo chuẩn base64 của chứng chỉ khoá ký của ứng dụng) để so sánh như sau:

{
  "applications": [

    {
      "packageName": "com.example.mtd",
      "installType": "FORCE_INSTALLED",
      "signingKeyCerts": [
         { "signingKeyCertFingerprintSha256": "base64-encoded-sha256" }
       ],
      "roles": [
        { "roleType": "MOBILE_THREAT_DEFENSE_ENDPOINT_DETECTION_RESPONSE" }
      ]
    }
  ]
}

Nếu ứng dụng của bạn có cấu hình được quản lý, thì quản trị viên CNTT có thể thiết lập cấu hình ban đầu cho restriction có liên quan trong chính sách ứng dụng:

{
  "applications": [

    {
      "packageName": "com.example.mtd",
      "installType": "FORCE_INSTALLED",
      "roles": [
        { "roleType": "MOBILE_THREAT_DEFENSE_ENDPOINT_DETECTION_RESPONSE" }
      ],
      "managedConfiguration": {
        "<key>": "<value>"
      }
    }
  ]
}

Xác minh trạng thái miễn trừ pin

Các ứng dụng có vai trò Chống mối đe doạ trên thiết bị di động (MTD) sẽ tự động được miễn trừ khỏi các quy định hạn chế về nguồn điện tiêu chuẩn ở chế độ nền. Tuy nhiên, trường hợp miễn trừ này được triển khai bằng Nhóm ứng dụng chờ thay vì Danh sách cho phép về nguồn điện của hệ thống.

Quan trọng: Nếu bạn cần xác minh mọi trường hợp miễn trừ liên quan đến MTD, đừng sử dụng PowerManager.isIgnoringBatteryOptimizations() vì hàm này sẽ trả về false. API này kiểm tra Danh sách cho phép về nguồn điện, danh sách này sẽ cho biết không chính xác rằng ứng dụng bị hạn chế.

Cách xác minh xem trường hợp miễn trừ ứng dụng có hiệu lực hay không:

import android.app.usage.UsageStatsManager
import android.content.Context

// UsageStatsManager.STANDBY_BUCKET_EXEMPTED is annotated as a @SystemApi. We can redefine it for clarity.
// Define this at the top level of your file, or inside a companion object
private const val STANDBY_BUCKET_EXEMPTED = 5

private fun isAppExemptedFromAppStandbyBucket(): Boolean =
    (getSystemService(Context.USAGE_STATS_SERVICE) as? UsageStatsManager)
        ?.appStandbyBucket == STANDBY_BUCKET_EXEMPTED