Device Trust از Android Enterprise - راهنمای ادغام

این سند باید راهنمای اصلی شما برای استفاده از کیت توسعه نرم‌افزار AMAPI برای دریافت سیگنال‌های اعتماد دستگاه باشد.

کیت توسعه نرم‌افزار AMAPI به برنامه شما امکان می‌دهد به نشان‌های اعتماد دستگاه از برنامه Android Device Policy (ADP) دسترسی پیدا کند. سپس برنامه شما می‌تواند از این نشان‌ها برای محاسبه وضعیت اعتماد دستگاه و اجرای منطق کسب‌وکار به‌دلخواه استفاده کند.

پیش‌نیازها

  • برنامه شما باید برای خواندن سیگنال‌های اعتماد دستگاه مجاز باشد:
    • برنامه‌های همراه در دستگاه‌های تحت‌مدیریت AMAPI: برنامه‌هایی که نقش COMPANION_APP در خط‌مشی به آن‌ها اختصاص داده شده است می‌توانند به سیگنال‌های اعتماد دستگاه دسترسی داشته باشند بدون اینکه در فهرست مجاز دستگاه‌های کاملاً مدیریت‌شده یا از داخل نمایه کاری باشند (با دسترسی محدود به سیگنال‌های نمایه کاری). برای جزئیات بیشتر، به مدیریت نقش‌های برنامه، پیکربندی خط‌مشی، و دسترسی به سیگنال‌ها از برنامه همراه مراجعه کنید.
    • همه برنامه‌ها و محیط‌های دیگر: دسترسی به سیگنال‌های اعتماد دستگاه از داخل نمایه شخصی، در دستگاه مدیریت‌نشده، در دستگاه مدیریت‌شده توسط DPC سفارشی، یا بدون نقش COMPANION_APP مستلزم این است که برنامه شما در فهرست مجاز باشد. برای کسب اطلاعات درباره نحوه درخواست، به صفحه دسترسی به سیگنال‌های اعتماد دستگاه بروید.
  • Android Enterprise توصیه می‌کند مجموعه Play Integrity از میاناهای برنامه‌سازی کاربردی را در برنامه کارخواه خود ادغام کنید و قبل‌از خواندن و تکیه بر سیگنال‌های اعتماد دستگاه، به نتیجه مراجعه کنید. دستگاه‌هایی که در بررسی‌های Play Integrity API مردود می‌شوند نباید قابل‌اعتماد تلقی شوند و هیچ‌کدام از سیگنال‌های برگرفته از دستگاه نباید برای تعیین وضعیت اعتماد استفاده شوند. برای جزئیات بیشتر می‌توانید به اسناد Play Integrity مراجعه کنید.

ادغام کردن با AMAPI SDK در برنامه

برای دسترسی به سیگنال‌های اعتماد دستگاه، برنامه شما باید با AMAPI SDK ادغام شود. در راهنمای ادغام AMAPI SDK می‌توانید اطلاعات بیشتری درباره این کتابخانه و نحوه افزودن آن به برنامه‌تان پیدا کنید.

افزودن اجازه‌های لازم

برخی‌از سیگنال‌های برگشتی از Device Trust از Android Enterprise API مستلزم این است که برنامه همان اجازه‌ای را اعلام کند که در وهله اول برای دسترسی به این اطلاعات لازم است، به‌ویژه:

نشان اجازه لازم است
وضعیت شبکه ACCESS_NETWORK_STATE
پیچیدگی قفل صفحه REQUEST_PASSWORD_COMPLEXITY

اگر این اجازه‌ها در AndroidManifest.xml برنامه گنجانده نشده باشد، Device Trust از Android Enterprise 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)
}

جاوا

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 ازقبل نصب شده باشد، میانای برنامه‌سازی کاربردی آن را بدون دخالت کاربر به‌طور بی‌صدا به‌روزرسانی خواهد کرد.

  • اگر برنامه ADP نصب نشده باشد، API از کاربر درخواست می‌کند تا نصب برنامه ADP را بپذیرد.

نصب «خط‌مشی دستگاه Android»

می‌توانید برای نظارت بر انتخاب کاربر، یک فراخوانی برگشتی ثبت کنید. برای جزئیات بیشتر، ردیابی تعامل کاربر درطول نصب برنامه ADP را ببینید.

توصیه می‌کنیم که فراخوانی prepareEnvironment از فرایند پیش‌زمینه درطول جریان تجربه کاربری آماده‌سازی انجام شود تا کاربر با کادر گفتگوی مدال نصب خط‌مشی دستگاه Android غافلگیر نشود. اگر تماس گرفتن از فرایند پیش‌زمینه ممکن نباشد، چون این یک جریان وب است و مؤلفه Android واسط کاربر ندارد، تماس گرفتن از پس‌زمینه مجاز است، مشروط بر اینکه این اتفاق درطول جریان تجربه کاربری آماده‌سازی رخ دهد.

وقتی محیط به‌درستی راه‌اندازی شد، می‌توان به «سیگنال‌های» اعتماد دستگاه دسترسی پیدا کرد. دسترسی به سیگنال‌های اعتماد دستگاه را ببینید.

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

جاوا

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) برقرار می‌کند که به‌طور خودکار هنگام غیرفعال بودن لغو اتصال می‌شود. چون نمونه‌های کارخواه روش خاموش کردن صریحی را نشان نمی‌دهند، ایجاد و دور انداختن چندین نمونه باعث می‌شود کانال‌های یتیم برای جمع‌آوری زباله باقی بمانند.

برای بهینه‌سازی عملکرد و جلوگیری از کانال‌های یتیم، یک نمونه واحد از DeviceClient در محدوده برنامه بااستفاده از DeviceClientFactory.create(context.applicationContext) ایجاد کنید و آن را برای استفاده مجدد در سراسر برنامه خود ذخیره کنید—برای مثال، به‌عنوان یک سینگلتون با محدوده برنامه یا بااستفاده از تزریق وابستگی.

برای دسترسی به سیگنال‌های اعتماد دستگاه موردنظرتان، از نمونه ذخیره‌شده در حافظه نهان 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)
}

جاوا

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 به آن اختصاص داده شده است می‌تواند سیگنال‌های اعتماد دستگاه را بدون ثبت شدن در فهرست مجاز بخواند.

وقتی از داخل نمایه کاری (در دستگاه متعلق به شرکت یا دستگاه متعلق به شخص) فراخوانی می‌شود، برنامه‌تان باید در داخل نمایه کاری اجرا شود و دسترسی به سیگنال‌های نمایه کاری محدود است (برای مثال، وضعیت مدیریت، پیچیدگی قفل صفحه، و برنامه‌های نصب‌شده فقط نمایه کاری را منعکس می‌کنند).

۱. اختصاص دادن نقش COMPANION_APP در خط‌مشی

خط‌مشی EMM خود را پیکربندی کنید تا roleType: "COMPANION_APP" را به برنامه شما در فهرست خط‌مشی applications اعطا کند:

۲. خواندن مستقیم نشان‌ها با DeviceClient

یک نمونه deviceClient را در محدوده برنامه بااستفاده از DeviceClientFactory.create ایجاد و ذخیره کنید (به توصیه استفاده از 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"
    }
}

جاوا

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

مدیریت کردن خطاها

اگر برنامه‌تان درخواست اعتماد دستگاه را ارسال کند و فراخوانی ناموفق باشد، برنامه‌تان استثنایی دریافت می‌کند. این استثناها ممکن است به دلایل مختلفی رخ دهند، ازجمله:

امتحان کردن مجدد استراتژی‌ها

برای استثناهای ناشی از شرایط گذرا، راهبرد تکرار مجدد را با عقب‌نشینی نمایی پیاده‌سازی کنید. پس‌از اولین شکست، با تأخیر اولیه ۵ ثانیه‌ای شروع کنید و سپس دوباره امتحان کنید.

راهبرد امتحان مجدد را با حداکثر تعداد تلاش به‌عنوان شرط خروج بااستفاده از تأخیر افزایش‌یافته نمایی در هر بار (۱۰ ثانیه، ۲۰ ثانیه، و غیره) پیاده‌سازی کنید.

ردیابی تعامل کاربر درطول نصب برنامه ADP

اگر دستگاه نیاز به نصب برنامه ADP درطول prepareEnvironment داشته باشد، برنامه شما می‌تواند تعامل کاربر را با پیاده‌سازی 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
    }
}

جاوا

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

مشکلات شناخته‌شده

درحال‌حاضر مشکل شناخته‌شده‌ای وجود ندارد.