Android Enterprise 的 Device Trust - 整合指南

如要使用 AMAPI SDK 接收裝置信任信號,請務必參考這份文件。

AMAPI SDK 可讓應用程式存取 Android Device Policy (ADP) 應用程式的裝置信任信號。應用程式接著可以使用這些信號,計算裝置的信任狀態,並執行所選的商業邏輯。

必要條件

  • 應用程式必須獲得授權,才能讀取裝置信任信號:
    • AMAPI 管理裝置上的隨附應用程式:在政策中獲派 COMPANION_APP 角色的應用程式,不需加入全代管裝置或工作資料夾的許可清單,即可存取裝置信任信號 (僅限工作資料夾的信號)。詳情請參閱「管理應用程式角色」、「政策設定」和「從隨附應用程式存取信號」。
    • 所有其他應用程式和環境:如要從個人資料夾、非受管理裝置、自訂 DPC 管理的裝置,或在沒有 COMPANION_APP 角色時存取裝置信任信號,應用程式必須加入許可清單。如要瞭解如何申請,請前往裝置信任信號存取權頁面。
  • Android Enterprise 建議您將 Play Integrity API 套件整合至用戶端應用程式,並在讀取及依賴裝置信任信號前,先參考結果。如果裝置未通過 Play Integrity API 檢查,則不應信任該裝置,也不應信任從該裝置取得的任何信號,用於判斷信任狀態。詳情請參閱 Play Integrity 說明文件。

在應用程式中整合 AMAPI SDK

如要存取裝置信任信號,應用程式必須與 AMAPI SDK 整合。如要進一步瞭解這個程式庫,以及如何將其新增至應用程式,請參閱 AMAPI SDK 整合指南。

新增必要權限

Android Enterprise 的 Device Trust 傳回的部分信號,需要應用程式宣告與一開始存取這項資訊時相同的權限,尤其是:

信號 必要權限
網路狀態 ACCESS_NETWORK_STATE
螢幕鎖定複雜度 REQUEST_PASSWORD_COMPLEXITY

如果應用程式的 AndroidManifest.xml 未包含這些權限,Android Enterprise 的 Device Trust API 會在相關信號的中繼資料中傳回 PERMISSION_ISSUE:

internalDeviceSettings=DeviceSettings{
  screenLockComplexity=COMPLEXITY_UNSPECIFIED,
  internalScreenLockComplexityMetadata=Metadata{
    dataIssues=[
      DataIssue{
        issueType=PERMISSION_ISSUE,
        issueLevel=WARNING,
        issueDetails=IssueDetailsCase{none}
      }
    ]
  },

詳情請參閱可用的裝置信任信號清單。

存取裝置信任信號的步驟

許可清單中的應用程式 (包括在個人資料夾或非受管理裝置上執行的應用程式),必須先確認用戶端環境為最新狀態,並在必要時做好準備,才能要求信號。

如要讓許可清單中的應用程式存取裝置信任信號,請按照下列步驟操作:

存取裝置信任信號的步驟

驗證用戶端環境

下列程式碼範例說明如何使用 getEnvironment 讀取 ADP 應用程式的目前狀態。如果環境已準備就緒且為最新狀態,應用程式就能使用快取的 deviceClient 執行個體存取裝置信任信號 (請參閱「存取裝置信任信號」)。

Kotlin

import com.google.android.managementapi.common.model.Role
import com.google.android.managementapi.device.DeviceClient
import com.google.android.managementapi.device.DeviceClientFactory
import com.google.android.managementapi.device.model.GetDeviceRequest
import com.google.android.managementapi.environment.EnvironmentClient
import com.google.android.managementapi.environment.EnvironmentClientFactory
import com.google.android.managementapi.environment.model.Environment.AndroidDevicePolicyEnvironment.State.INSTALLED
import com.google.android.managementapi.environment.model.Environment.AndroidDevicePolicyEnvironment.State.NOT_INSTALLED
import com.google.android.managementapi.environment.model.Environment.AndroidDevicePolicyEnvironment.State.READY
import com.google.android.managementapi.environment.model.Environment.AndroidDevicePolicyEnvironment.Version.UP_TO_DATE
import com.google.android.managementapi.environment.model.GetEnvironmentRequest
import com.google.android.managementapi.environment.model.PrepareEnvironmentRequest

try {
    val context = applicationContext

    val roles = listOf(Role.builder().setRoleType(Role.RoleType.IDENTITY_PROVIDER).build())
    val request = GetEnvironmentRequest.builder().setRoles(roles).build()
    val environmentClient = EnvironmentClientFactory.create(context)
    val environmentResponse = environmentClient.getEnvironment(request)

    if (environmentResponse.hasAndroidDevicePolicyEnvironment()) {
        val adpEnvironment = environmentResponse.androidDevicePolicyEnvironment

        if (adpEnvironment.state == READY && adpEnvironment.version == UP_TO_DATE) {
            // AMAPI Environment State OK, Version OK. Requesting Device signals..
            checkDevice(deviceClient)
        } else if (adpEnvironment.state == INSTALLED) {
            // prepareEnvironment should be called, calling
            // prepareEnvironment won't show the UI
            prepareEnvironment(context, environmentClient)
        } else if (adpEnvironment.state == NOT_INSTALLED) {
            // prepareEnvironment should be called, calling
            // prepareEnvironment will show the UI
            prepareEnvironment(context, environmentClient)
        }
    }
} catch (e: Exception) {
    Log.e(TAG, "Exception", e)
}

Java

import static com.google.android.managementapi.environment.model.Environment.AndroidDevicePolicyEnvironment.State.INSTALLED;
import static com.google.android.managementapi.environment.model.Environment.AndroidDevicePolicyEnvironment.State.NOT_INSTALLED;
import static com.google.android.managementapi.environment.model.Environment.AndroidDevicePolicyEnvironment.State.READY;
import static com.google.android.managementapi.environment.model.Environment.AndroidDevicePolicyEnvironment.Version.UP_TO_DATE;

import com.google.android.managementapi.common.model.Role;
import com.google.android.managementapi.device.DeviceClient;
import com.google.android.managementapi.device.DeviceClientFactory;
import com.google.android.managementapi.device.model.Device;
import com.google.android.managementapi.device.model.GetDeviceRequest;
import com.google.android.managementapi.environment.EnvironmentClient;
import com.google.android.managementapi.environment.EnvironmentClientFactory;
import com.google.android.managementapi.environment.model.Environment;
import com.google.android.managementapi.environment.model.Environment.AndroidDevicePolicyEnvironment;
import com.google.android.managementapi.environment.model.GetEnvironmentRequest;
import com.google.android.managementapi.environment.model.PrepareEnvironmentRequest;
import com.google.android.managementapi.environment.model.PrepareEnvironmentResponse;

try {
    Context context = getApplicationContext();

    ImmutableList roles = new ImmutableList.Builder()
            .add(Role.builder()
                    .setRoleType(Role.RoleType.IDENTITY_PROVIDER)
                    .build())
            .build();

    EnvironmentClient environmentClient = EnvironmentClientFactory.create(context);
    GetEnvironmentRequest request = GetEnvironmentRequest.builder()
            .setRoles(roles)
            .build();

    ListenableFuture getEnvironmentFuture = environmentClient.getEnvironmentAsync(request);
    Futures.addCallback(getEnvironmentFuture, new FutureCallback<>() {
        @Override
        public void onSuccess(Environment environment) {
            AndroidDevicePolicyEnvironment adpEnvironment = environment.getAndroidDevicePolicyEnvironment();

            AndroidDevicePolicyEnvironment.State state = adpEnvironment.getState();
            AndroidDevicePolicyEnvironment.Version version = adpEnvironment.getVersion();
            if (state == READY && version == UP_TO_DATE) {
                // AMAPI Environment State OK, Version OK. Requesting Device signals..
                checkDevice(deviceClient);
            } else if (state == INSTALLED) {
                // prepareEnvironment should be called, calling
                // prepareEnvironment won't show the UI
                prepareEnvironment(context, environmentClient);
            } else if (state == NOT_INSTALLED) {
                // prepareEnvironment should be called, calling
                // prepareEnvironment will show the UI
                prepareEnvironment(context, environmentClient);
            }
        }

        @Override
        public void onFailure(Throwable t) {
            Log.d(TAG, t.toString());
        }
    }, MoreExecutors.directExecutor());
} catch (Exception e) {
    Log.d(TAG, e.toString());
}

如果已安裝 ADP 應用程式,但不是最新版本,您的應用程式應呼叫 prepareEnvironment,在不需使用者介入的情況下,自動更新 ADP 應用程式。

如果未安裝 ADP 應用程式,您的應用程式可以呼叫 prepareEnvironment,提示使用者安裝 ADP 應用程式。請參閱「準備用戶端環境」。

準備用戶端環境

  • 如果已安裝 ADP 應用程式,API 會在背景更新,不需使用者介入。

  • 如果未安裝 ADP 應用程式,API 會提示使用者接受安裝 ADP 應用程式。

安裝 Android Device Policy

您可以註冊回呼,監控使用者選擇。詳情請參閱「在 ADP 應用程式安裝期間追蹤使用者互動」。

建議您在新手上路使用者體驗流程中,從前景程序執行 prepareEnvironment 呼叫,以免使用者看到「安裝 Android Device Policy」強制回應對話方塊而感到意外。如果無法從前景程序呼叫 (因為這是網頁流程,且 Android 元件沒有 UI),則允許從背景呼叫,但必須在新進人員訓練使用者體驗流程中進行。

正確設定環境後,即可存取裝置信任信號。請參閱「存取裝置信任信號」。

Kotlin

try {
    val myNotificationReceiverService = ComponentName(
        context, MyNotificationReceiverService::class.java
    )

    val roles = listOf(Role.builder().setRoleType(Role.RoleType.IDENTITY_PROVIDER).build())
    val request = PrepareEnvironmentRequest.builder().setRoles(roles).build()

    val response =
        environmentClient.prepareEnvironment(request, myNotificationReceiverService)

    val environment = response.environment
    val adpEnvironment = environment.androidDevicePolicyEnvironment

    val state = adpEnvironment.state
    val version = adpEnvironment.version
    if (state == READY && version == UP_TO_DATE) {
        // Environment is prepared, access device posture signals using
        // DeviceClient.
        checkDevice(deviceClient)
    } else {
        // The prepareEnvironment call failed to prepare
        Log.w(
            TAG, "AMAPI environment was not ready: " + state + " - " + version
        )
    }

} catch (e: java.lang.Exception) {
    Log.d(TAG, e.toString())
}

Java

try {
    ComponentName myNotificationReceiverService = new ComponentName(
            context,
            MyNotificationReceiverService.class
    );

    ImmutableList roles = new ImmutableList.Builder()
            .add(Role.builder()
                    .setRoleType(Role.RoleType.IDENTITY_PROVIDER)
                    .build())
            .build();


    PrepareEnvironmentRequest request = PrepareEnvironmentRequest.builder()
            .setRoles(roles)
            .build();

    ListenableFuture environmentFuture =
            environmentClient.prepareEnvironmentAsync(
                    request,
                    myNotificationReceiverService
            );

    Futures.addCallback(environmentFuture, new FutureCallback<>() {
        @Override
        public void onSuccess(PrepareEnvironmentResponse response) {
            Environment environment = response.getEnvironment();
            AndroidDevicePolicyEnvironment adpEnvironment = environment.getAndroidDevicePolicyEnvironment();

            AndroidDevicePolicyEnvironment.State state = adpEnvironment.getState();
            AndroidDevicePolicyEnvironment.Version version = adpEnvironment.getVersion();
            if (state == READY && version == UP_TO_DATE) {
                // AMAPI Environment State OK, Version OK. Requesting Device signals..
                checkDevice(deviceClient);
            } else {
                // The prepareEnvironment call failed to prepare
                Log.w(
                        TAG, "AMAPI environment was not ready: "
                        + adpEnvironment.getState() + " - " + adpEnvironment.getVersion()
                );
            }
        }

        @Override
        public void onFailure(@NonNull Throwable t) {
            // Handle the error
            Log.d(TAG, "AMAPI response did not contain an ADP environment");
        }
    }, MoreExecutors.directExecutor());
} catch (Exception e) {
    Log.d(TAG, e.toString());
}

存取裝置信任信號

DeviceClient 使用建議

建立 deviceClient 執行個體 (或 EnvironmentClient 執行個體) 會與 Android 裝置政策 (ADP) 應用程式建立通訊管道,並在閒置時自動解除繫結。由於用戶端執行個體不會公開明確的關閉方法,因此建立及捨棄多個執行個體會留下孤立的管道,等待垃圾收集。

為提升效能並避免孤立管道,請使用 DeviceClientFactory.create(context.applicationContext) 在應用程式範圍建立單一 DeviceClient 執行個體,並快取該執行個體,以便在整個應用程式中重複使用,例如做為應用程式範圍的單例模式,或使用依附元件插入。

如要存取您感興趣的裝置信任信號,請使用快取的 deviceClient 執行個體要求 Device 物件:

Kotlin

runCatching {
    deviceClient.getDeviceAwait(GetDeviceRequest.getDefaultInstance())
}.onFailure { t ->
    Log.d(TAG, t.toString())
}.onSuccess { device ->
    // Access device posture signals available in device
    val deviceString = device.toString()
    Log.d(TAG, deviceString)
}

Java

ListenableFuture deviceFuture =
        deviceClient.getDevice(GetDeviceRequest.getDefaultInstance());

Futures.addCallback(deviceFuture, new FutureCallback() {
    @Override
    public void onSuccess(Device device) {
        // Access device posture signals available in device
        String deviceString = device.toString();
        Log.d(TAG, deviceString);
    }

    @Override
    public void onFailure(Throwable t) {
        Log.d(TAG, t.toString());
    }
}, MoreExecutors.directExecutor());

從隨附應用程式存取信號

在全代管裝置上,或在透過 Android Management API (AMAPI) 管理的工作資料夾中,獲派 COMPANION_APP 角色的應用程式不需註冊許可清單,即可讀取裝置信任信號。

從工作資料夾 (無論是公司擁有或個人擁有的裝置) 內呼叫時,應用程式必須在工作資料夾內執行,且只能存取工作資料夾的信號 (例如管理狀態、螢幕鎖定複雜度和已安裝的應用程式,只會反映工作資料夾)。

1. 在政策中指派 COMPANION_APP 角色

設定 EMM 政策,在 applications 政策清單中將 roleType: "COMPANION_APP" 授予應用程式:

  • 如要設定應用程式資訊清單,並視需要監聽角色指派作業,請參閱「管理應用程式角色」。
  • 如要瞭解政策設定語法,請參閱「政策設定」。

2. 直接使用 DeviceClient 讀取信號

使用 DeviceClientFactory.create 在應用程式範圍建立並快取單一 deviceClient 執行個體 (請參閱DeviceClient 使用建議),然後直接要求 Device 物件:

Kotlin

import android.content.Context
import android.util.Log
import com.google.android.managementapi.device.DeviceClient
import com.google.android.managementapi.device.DeviceClientFactory
import com.google.android.managementapi.device.model.GetDeviceRequest

// Instantiate once at application scope (for example, using dependency injection)
// to reuse a single DeviceClient instance across your app.
class DeviceTrustRepository(context: Context) {
    private val deviceClient: DeviceClient =
        DeviceClientFactory.create(context.applicationContext)

    suspend fun readSignalsFromCompanionApp() {
        runCatching {
            deviceClient.getDeviceAwait(GetDeviceRequest.getDefaultInstance())
        }.onSuccess { device ->
            Log.d(TAG, "Device signals: $device")
        }.onFailure { t ->
            Log.e(TAG, "Failed to read device signals", t)
        }
    }

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

Java

import android.content.Context;
import android.util.Log;
import com.google.android.managementapi.device.DeviceClient;
import com.google.android.managementapi.device.DeviceClientFactory;
import com.google.android.managementapi.device.model.Device;
import com.google.android.managementapi.device.model.GetDeviceRequest;
import com.google.common.util.concurrent.FutureCallback;
import com.google.common.util.concurrent.Futures;
import com.google.common.util.concurrent.ListenableFuture;
import com.google.common.util.concurrent.MoreExecutors;

// Instantiate once at application scope (for example, using dependency injection)
// to reuse a single DeviceClient instance across your app.
public class DeviceTrustRepository {
    private static final String TAG = "DeviceTrustRepository";
    private final DeviceClient deviceClient;

    public DeviceTrustRepository(Context context) {
        this.deviceClient = DeviceClientFactory.create(context.getApplicationContext());
    }

    public void readSignalsFromCompanionApp() {
        ListenableFuture deviceFuture =
                deviceClient.getDevice(GetDeviceRequest.getDefaultInstance());

        Futures.addCallback(deviceFuture, new FutureCallback() {
            @Override
            public void onSuccess(Device device) {
                Log.d(TAG, "Device signals: " + device);
            }

            @Override
            public void onFailure(Throwable t) {
                Log.e(TAG, "Failed to read device signals", t);
            }
        }, MoreExecutors.directExecutor());
    }
}

處理錯誤

如果應用程式發出裝置信任要求,但呼叫失敗,應用程式會收到例外狀況。造成這類例外狀況的原因有很多,例如:

重試策略

如果例外狀況是由暫時性狀況造成,請採用指數輪詢重試策略。首次失敗後,請等待 5 秒的初始延遲時間,然後再重試。

實作重試策略,並以最大重試次數做為結束條件,每次重試的延遲時間依指數遞增 (10 秒、20 秒等)。

追蹤 ADP 應用程式安裝期間的使用者互動

如果裝置需要在prepareEnvironment期間安裝 ADP 應用程式,您的應用程式可以追蹤使用者互動,方法是實作 NotificationReceiverService 接收通知,並覆寫 getPrepareEnvironmentListener:

Kotlin

import android.util.Log
import com.google.android.managementapi.environment.EnvironmentListener
import com.google.android.managementapi.environment.model.EnvironmentEvent.EventCase.Kind.ANDROID_DEVICE_POLICY_INSTALL_CONSENT_ACCEPTED
import com.google.android.managementapi.environment.model.EnvironmentEvent
import com.google.android.managementapi.notification.NotificationReceiverService

class MyNotificationReceiverService : NotificationReceiverService() {
    override fun getPrepareEnvironmentListener(): EnvironmentListener {
        return MyEnvironmentListener()
    }
}

class MyEnvironmentListener : EnvironmentListener {
    override fun onEnvironmentEvent(
        event: EnvironmentEvent
    ) {
        if (event.event.kind == ANDROID_DEVICE_POLICY_INSTALL_CONSENT_ACCEPTED) {
            Log.d(TAG, "User provided install consent")
        } else {
            Log.d(TAG, "User rejected install consent")
        }
    }

    companion object {
        private val TAG: String = MyEnvironmentListener::class.java.simpleName
    }
}

Java

import static com.google.android.managementapi.environment.model.EnvironmentEvent.EventCase.Kind.ANDROID_DEVICE_POLICY_INSTALL_CONSENT_ACCEPTED;

import android.util.Log;
import androidx.annotation.NonNull;
import com.google.android.managementapi.environment.EnvironmentListener;
import com.google.android.managementapi.environment.model.EnvironmentEvent;
import com.google.android.managementapi.notification.NotificationReceiverService;

class MyNotificationReceiverService extends NotificationReceiverService {
    @NonNull
    @Override
    protected EnvironmentListener getPrepareEnvironmentListener() {
        return new MyEnvironmentListener();
    }
}
class MyEnvironmentListener implements EnvironmentListener {
    final private String TAG = MyEnvironmentListener.class.getSimpleName();

    @Override
    public void onEnvironmentEvent(EnvironmentEvent event) {
        if (event.getEvent().getKind() == ANDROID_DEVICE_POLICY_INSTALL_CONSENT_ACCEPTED)
        {
            Log.d(TAG, "User provided install consent");
        } else {
            Log.d(TAG, "User rejected install consent");
        }
    }
}

已知問題

目前沒有已知問題。