Anwendungsrollen verwalten

Mit der Funktion „Anwendungsrollen“ können IT-Administratoren einer verwalteten Anwendung auf einem Android-Gerät spezielle Berechtigungen gewähren. Durch die Zuweisung einer bestimmten Rolle kann eine App von Energie- und Hintergrundbeschränkungen, Sperrungen und dem Ruhezustand (unter Android 14 oder höher) ausgenommen werden. Außerdem können Nutzersteuerelemente (z. B. Nutzeraktionen wie das Beenden und Löschen von App-Daten) deaktiviert werden (unter Android 11 oder höher), damit die App ihre wichtige Funktion ohne Unterbrechung ausführen kann. Außerdem kann die Anwendung über die ihr zugewiesenen Rollen benachrichtigt werden, sodass sie sich ohne Eingreifen des Nutzers selbst initialisieren kann.

Hinweis: Das Feature „Anwendungsrollen“ ersetzt das Feld extensionConfig in ApplicationPolicy.

Eine Liste der verfügbaren Anwendungsrollen und der speziellen Berechtigungen, die jeder Rolle gewährt werden, finden Sie unter RoleType.

Vorbereitung

Das Gerät wird von einem AMAPI-basierten EMM verwaltet (EMMs, die einen benutzerdefinierten DPC verwenden, werden nicht unterstützt).

App für die Verwendung der Funktion vorbereiten

Die Integration des AMAPI SDK ist nur erforderlich, wenn die App über ihre zugewiesenen Rollen benachrichtigt werden soll, damit sie sich selbst starten kann (d.h. automatischer Start ohne Nutzerinteraktion).

AMAPI SDK in Ihre App einbinden

Weitere Informationen zum AMAPI SDK und dazu, wie Sie es Ihrer App hinzufügen, finden Sie im Leitfaden zur Integration des AMAPI SDK.

Fügen Sie dem Manifest der App die erforderlichen Metadaten hinzu.

Android Device Policy (ADP) muss den ComponentName Ihrer Klasse kennen, die NotificationReceiverService implementiert, um Ihre App über die zugewiesenen Rollen zu benachrichtigen. Sie müssen Ihren Dienst in AndroidManifest.xml entsprechend taggen, damit er von ADP automatisch erkannt werden kann.

• Ihre Anwendung muss genau einen Dienst haben, der enabled ist und meta-data mit android:name gleich com.google.android.managementapi.notification.NotificationReceiverService.SERVICE_APP_ROLES hat.
• Für diesen Dienst muss android:exported auf true festgelegt sein
• Der android:value des meta-data muss auf einen leeren String gesetzt werden.

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

Hinweis: Die Basisklasse NotificationReceiverService übernimmt automatisch die Sicherheitsmaßnahmen. So wird sichergestellt, dass nur die Android Device Policy-App (ADP) sicher mit diesem Dienst kommunizieren kann. Sie müssen keine benutzerdefinierte BIND-Berechtigung deklarieren oder das aufrufende Paket manuell bestätigen.

Wenn Sie die Rolle COMPANION_APP testen, sollten Sie Ihrem Dienst auch den folgenden meta-data hinzufügen, damit Android Device Policy lokale Statusaktualisierungen für Befehle an Ihre App senden kann:

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

Erstelle einen Dienst, der NotificationReceiverService erweitert, oder aktualisiere den vorhandenen Dienst.

Erstellen oder aktualisieren Sie Ihre vorhandene NotificationReceiverService und implementieren Sie einen AppRolesListener, um auf Rollen zu warten, die Ihrer App zugewiesen sind. Nur getAppRolesListener() ist erforderlich, um auf Rollen zu warten, die Ihrer App zugewiesen sind. Wenn Ihrer App eine COMPANION_APP-Rolle zugewiesen ist, sollten Sie auch getCommandListener() implementieren:

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"
  }
}

Hinweis: Deine App wird nur dann über die ihr zugewiesenen Rollen benachrichtigt, wenn sich ihre Rollen oder ihre zusätzlichen Funktionen ändern.

Ihre App kann mehrmals benachrichtigt werden, wenn sich ihre Rollen mehrmals ändern. Wenn alle Rollen entfernt werden, wird deine App trotzdem mit einer leeren Liste von Rollen benachrichtigt. Durch diese Benachrichtigung wird die App aus dem angehaltenen Zustand geholt. Zusammen mit den für die App gewährten Ausnahmen kann sie sich ohne Nutzerinteraktion selbst starten. Dank der Benachrichtigung und der Ausnahmen für App-Rollen kann Ihre App auf ACTION_BOOT_COMPLETED-Broadcasts warten. Wenn Ihre App für das Bootstrapping auf ihre verwalteten Konfigurationen angewiesen ist, finden Sie unter Verwaltete Konfigurationen einrichten Informationen dazu, wie Sie Änderungen lesen und darauf reagieren können.

Ab AMAPI SDK 1.9.0 enthält jede Rolle in der AppRolesSetRequest auch die Role.ExtraCapabilities, die der IT-Administrator in der Richtlinie gewährt hat. Eine Companion-App kann beispielsweise prüfen, ob sie einen Befehl zum lokalen Löschen ausgeben darf:

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()
  }

Nur der IT-Administrator kann zusätzliche Funktionen gewähren. Wenn Sie extraCapabilities für eine Rolle festlegen, die Sie an EnvironmentClient übergeben, schlägt der Aufruf mit einem InvalidArgumentException fehl.

Gerät mit Richtlinien für App-Rollen bereitstellen

App-Entwickler können das Zuweisen von App-Rollen zu ihrer Anwendung mit einem EMM oder gemäß der Kurzanleitung zur Android Management API testen. Mit dem AMAPI-Colab-Notebook können Sie ein Unternehmen registrieren, eine Richtlinie erstellen und ein Gerät bereitstellen.

Richtlinie für Ihre Anwendung mit Anwendungsrollen festlegen

Richten Sie mit der ApplicationPolicy.roles eine policy mit den Anwendungsrollen ein, die Ihre Anwendung haben soll.

Im folgenden Beispiel wird gezeigt, wie die Rolle für MTD-Apps konfiguriert wird:

{
  "applications": [

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

Wichtig: Eine App kann mehrere Rollen haben, aber jede Rolle kann nur einer einzigen App zugewiesen werden. Eine Liste aller verfügbaren Anwendungsrollen finden Sie unter RoleType.

Nur die Rolle COMPANION_APP unterstützt extraCapabilities. Wenn Sie der Companion-App erlauben möchten, das Gerät oder Arbeitsprofil lokal zu löschen, legen Sie für diese Rolle extraCapabilities.localDeviceWipeCommand auf LOCAL_DEVICE_WIPE_COMMAND_ALLOWED fest.

Bevor die in der Richtlinie angegebenen Rollen zugewiesen werden, prüft das System, ob der Zertifikat-Fingerabdruck des Signaturschlüssels der App auf dem Gerät mit dem Fingerabdruck im Google Play Store übereinstimmt. Wenn der Fingerabdruck unterschiedlich ist, werden der App die Rollen nicht zugewiesen und die Nichtkonformität mit NonComplianceReason.APP_SIGNING_CERT_MISMATCH wird dem EMM gemeldet.

Hinweis: Es ist möglich, verschiedene Builds der Anwendung zu testen, die mit einem anderen Zertifikat signiert sind. Dazu müssen Sie zusätzliche Fingerabdrücke des Signaturschlüsselzertifikats (base64-codierter SHA-256-Hashwert des Signaturschlüsselzertifikats der App) angeben, die wie folgt verglichen werden:

{
  "applications": [

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

Wenn Ihre App eine verwaltete Konfiguration hat, kann der IT-Administrator eine Erstkonfiguration für die relevanten restrictions in der Anwendungsrichtlinie einrichten:

{
  "applications": [

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

Status der Ausnahme für Akkus prüfen

Apps mit der Rolle „Mobile Threat Defense“ (MTD) sind automatisch von den standardmäßigen Einschränkungen für die Hintergrundnutzung ausgenommen. Diese Ausnahme wird jedoch über den App-Standby-Bucket und nicht über die Zulassungsliste für die Energieverwaltung des Systems implementiert.

Wichtig: Wenn Sie MTD-bezogene Ausnahmen prüfen müssen, verwenden Sie nicht PowerManager.isIgnoringBatteryOptimizations(), da dies als false zurückgegeben wird. Diese API prüft die Zulassungsliste für die Energieverwaltung, die fälschlicherweise angibt, dass die App eingeschränkt ist.

So prüfen Sie, ob die App-Ausnahme aktiv ist:

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