دمج "مدير بيانات الاعتماد" مع حلّ موفّر بيانات الاعتماد

يشير "مدير بيانات الاعتماد" إلى مجموعة من واجهات برمجة التطبيقات التي تم طرحها في Android 14 والتي تتيح استخدام طرق تسجيل دخول متعددة، مثل اسم المستخدم وكلمة المرور ومفاتيح المرور وحلول تسجيل الدخول الموحّدة (مثل "تسجيل الدخول باستخدام حساب Google"). عند استدعاء Credential Manager API، يجمع نظام Android بيانات الاعتماد من جميع مزوّدي بيانات الاعتماد المثبّتين على الجهاز. يصف هذا المستند مجموعة واجهات برمجة التطبيقات التي توفّر نقاط نهاية للتكامل مع مزوّدي بيانات الاعتماد هؤلاء.

الإعداد

قبل تنفيذ الوظائف في مزوّد بيانات الاعتماد، يُرجى إكمال خطوات الإعداد الموضّحة في الأقسام التالية.

تحديد الاعتماديات

أضِف الاعتماديات التالية إلى نص برمجة الإصدار لوحدة تطبيقك لاستخدام الـ أحدث إصدار من مكتبة "Credential Manager":

Kotlin

dependencies {
    implementation("androidx.credentials:credentials:1.7.0-alpha01")
}

Groovy

dependencies {
    implementation "androidx.credentials:credentials:1.7.0-alpha01"
}

تحديد عنصر الخدمة في ملف البيان

في ملف بيان تطبيقك AndroidManifest.xml، أدرِج <service> إعلانًا لفئة خدمة توسّع فئة CredentialProviderService من مكتبة androidx.credentials، كما هو موضّح في المثال التالي.

<service android:name=".MyCredentialProviderService"
    android:enabled="true"
    android:exported="true"
    android:label="My Credential Provider"
    android:icon="@mipmap/ic_launcher"
    android:permission="android.permission.BIND_CREDENTIAL_PROVIDER_SERVICE"
    tools:targetApi="upside_down_cake">
    <intent-filter>
        <action android:name="android.service.credentials.CredentialProviderService"/>
    </intent-filter>
    <meta-data
        android:name="android.credentials.provider"
        android:resource="@xml/provider"/>
</service>

إنّ الإذن وفلتر الأهداف الموضّحَين في المثال السابق ضروريان لكي يعمل مسار "مدير بيانات الاعتماد" على النحو المتوقّع. الإذن مطلوب لكي يتمكن نظام Android فقط من الربط بهذه الخدمة. يُستخدَم intent filter لاكتشاف هذه الخدمة كمزوّد بيانات اعتماد لاستخدامها من قِبل Credential Manager.

تحديد أنواع بيانات الاعتماد المتوافقة

في دليل res/xml، أنشِئ ملفًا جديدًا باسم provider.xml. في هذا الملف، حدِّد أنواع بيانات الاعتماد التي تتيحها خدمتك من خلال الثوابت المحدّدة لكل نوع من أنواع بيانات الاعتماد في المكتبة. في المثال التالي، تتيح الخدمة كلمات المرور التقليدية ومفاتيح المرور، ويتم تحديد الثوابت الخاصة بها على النحو التالي: TYPE_PASSWORD_CREDENTIAL وTYPE_PUBLIC_KEY_CREDENTIAL:

<credential-provider xmlns:android="http://schemas.android.com/apk/res/android">
    <capabilities>
        <capability name="android.credentials.TYPE_PASSWORD_CREDENTIAL" />
        <capability name="androidx.credentials.TYPE_PUBLIC_KEY_CREDENTIAL" />
    </capabilities>
</credential-provider>

في مستويات واجهة برمجة التطبيقات السابقة، تتكامل خدمات مزوّدي بيانات الاعتماد مع واجهات برمجة التطبيقات، مثل الملء التلقائي لكلمات المرور والبيانات الأخرى. يمكن لمزوّدي بيانات الاعتماد هؤلاء استخدام البنية الأساسية الداخلية نفسها لتخزين أنواع بيانات الاعتماد الحالية، مع توسيعها لتشمل أنواعًا أخرى، بما في ذلك مفاتيح المرور.

التعامل مع مزوّدي بيانات الاعتماد على مرحلتَين

يتفاعل "Credential Manager" مع مزوّدي بيانات الاعتماد على مرحلتَين:

المرحلة الأولى هي مرحلة البدء/الطلب التي يربط فيها النظام خدمات مزوّدي بيانات الاعتماد ويستدعي onBeginGetCredentialRequest() أو onBeginCreateCredentialRequest() أو onClearCredentialStateRequest() الطُرق مع طلبات Begin…. على مزوّدي بيانات الاعتماد معالجة هذه الطلبات والردّ عليها باستخدام ردود Begin…، مع ملئها بالإدخالات التي تمثّل الخيارات المرئية التي سيتم عرضها على أداة اختيار الحساب. يجب أن يتضمّن كل إدخال PendingIntent تم ضبطه.
بعد أن يختار المستخدم إدخالاً، تبدأ مرحلة الاختيار ويتم تفعيل PendingIntent المرتبط بالإدخال، ما يؤدي إلى ظهور نشاط مزوّد بيانات الاعتماد المقابل. بعد أن ينتهي المستخدم من التفاعل مع هذا النشاط، على مزوّد بيانات الاعتماد ضبط الردّ على نتيجة النشاط قبل إنهاء النشاط. بعد ذلك، يتم إرسال هذا الردّ إلى تطبيق العميل الذي استدعى "مدير بيانات الاعتماد".

التعامل مع إنشاء مفتاح مرور

التعامل مع طلبات إنشاء مفتاح مرور

عندما يريد تطبيق عميل إنشاء مفتاح مرور وتخزينه لدى مزوّد بيانات اعتماد ، يستدعي واجهة برمجة التطبيقات createCredential. للتعامل مع هذا الطلب في خدمة مزوّد بيانات الاعتماد بحيث يتم تخزين مفتاح المرور فعليًا في مساحة التخزين، يُرجى إكمال الخطوات الموضّحة في الأقسام التالية.

ألغِ الطريقة onBeginCreateCredentialRequest() في خدمتك التي تم توسيعها من CredentialProviderService.
تعامَل مع BeginCreateCredentialRequest من خلال إنشاء BeginCreateCredentialResponse مطابق وتمريره من خلال معاودة الاتصال.
أثناء إنشاء BeginCreateCredentialResponse، أضِف المطلوبة CreateEntries. يجب أن يتطابق كل CreateEntry مع حساب يمكن حفظ بيانات الاعتماد فيه، ويجب أن يتضمّن PendingIntent تم ضبطه بالإضافة إلى البيانات الوصفية المطلوبة الأخرى.

يوضّح المثال التالي كيفية تنفيذ هذه الخطوات.

override fun onBeginCreateCredentialRequest(
    request: BeginCreateCredentialRequest,
    cancellationSignal: CancellationSignal,
    callback: OutcomeReceiver<BeginCreateCredentialResponse, CreateCredentialException>,
) {
    val response: BeginCreateCredentialResponse? = processCreateCredentialRequest(request)
    if (response != null) {
        callback.onResult(response)
    } else {
        callback.onError(CreateCredentialUnknownException())
    }
}

fun processCreateCredentialRequest(request: BeginCreateCredentialRequest): BeginCreateCredentialResponse? {
    when (request) {
        is BeginCreatePublicKeyCredentialRequest -> {
            // Request is passkey type
            return handleCreatePasskeyQuery(request)
        }
    }
    // Request not supported
    return null
}

private fun handleCreatePasskeyQuery(
    request: BeginCreatePublicKeyCredentialRequest
): BeginCreateCredentialResponse {

    // Adding two create entries - one for storing credentials to the 'Personal'
    // account, and one for storing them to the 'Family' account. These
    // accounts are local to this sample app only.
    val createEntries: MutableList<CreateEntry> = mutableListOf()
    createEntries.add(
        CreateEntry(
            PERSONAL_ACCOUNT_ID,
            createNewPendingIntent(PERSONAL_ACCOUNT_ID, CREATE_PASSKEY_INTENT)
        )
    )

    createEntries.add(
        CreateEntry(
            FAMILY_ACCOUNT_ID,
            createNewPendingIntent(FAMILY_ACCOUNT_ID, CREATE_PASSKEY_INTENT)
        )
    )

    return BeginCreateCredentialResponse(createEntries)
}

private fun createNewPendingIntent(accountId: String, action: String): PendingIntent {
    val intent = Intent(action).setPackage(PACKAGE_NAME)

    // Add your local account ID as an extra to the intent, so that when
    // user selects this entry, the credential can be saved to this
    // account
    intent.putExtra(EXTRA_KEY_ACCOUNT_ID, accountId)

    return PendingIntent.getActivity(
        applicationContext, UNIQUE_REQ_CODE,
        intent,
        (
            PendingIntent.FLAG_MUTABLE
                or PendingIntent.FLAG_UPDATE_CURRENT
            )
    )
}

يجب أن يلتزم إنشاء PendingIntent بما يلي:

يجب إعداد النشاط المقابل لعرض أي طلب بيومتري أو تأكيد أو اختيار مطلوب.
يجب ضبط أي بيانات مطلوبة يحتاجها مزوّد بيانات الاعتماد عند استدعاء النشاط المقابل كبيانات إضافية في الهدف المستخدَم لإنشاء PendingIntent، مثل accountId في مسار الإنشاء.
يجب إنشاء PendingIntent باستخدام العلامة PendingIntent.FLAG_MUTABLE ليتمكّن النظام من إلحاق الطلب النهائي بالبيانات الإضافية للهدف.
يجب عدم إنشاء PendingIntent باستخدام العلامة PendingIntent.FLAG_ONE_SHOT لأنّ المستخدم قد يختار إدخالاً ثم يعود و يختاره مرة أخرى، ما سيؤدي إلى تفعيل PendingIntent مرّتين.
يجب إنشاء PendingIntent باستخدام رمز طلب فريد لكي يكون لكل إدخال PendingIntent المقابل له.

التعامل مع اختيار الإدخال لطلبات إنشاء مفتاح مرور

عندما يختار المستخدم CreateEntry تم ملؤه سابقًا، يتم استدعاء PendingIntent المقابل ويتم إنشاء Activity لمزوّد بيانات الاعتماد المرتبط.
بعد استدعاء طريقة onCreate في النشاط، يمكنك الوصول إلى الهدف المرتبط وتمريره إلى فئة PendingIntentHander للحصول على ProviderCreateCredentialRequest.
استخرِج requestJson وcallingAppInfo وclientDataHash من الطلب.
استخرِج accountId المحلي من البيانات الإضافية للهدف. هذا مثال على عملية تنفيذ خاصة بنموذج تطبيق وليس مطلوبًا. يمكن استخدام رقم تعريف الحساب هذا لتخزين بيانات الاعتماد هذه مقابل رقم تعريف الحساب هذا.
تحقَّق من صحة requestJson. يستخدم المثال أدناه فئات البيانات المحلية، مثل PublicKeyCredentialCreationOptions لتحويل JSON المُدخَل إلى فئة منظَّمة وفقًا لمواصفات WebAuthn. بصفتك مزوّد بيانات اعتماد، يمكنك استبدال ذلك بمحلّل JSON الخاص بك.
تحقَّق من رابط مواد العرض للتطبيق الذي يستدعي واجهة برمجة التطبيقات إذا كان الطلب صادرًا من تطبيق Android أصلي.
اعرض إشعارًا للمصادقة. يستخدم المثال أدناه Android Biometric API.
عند نجاح المصادقة، أنشِئ credentialId وزوج مفاتيح.
احفظ المفتاح الخاص في قاعدة البيانات المحلية مقابل callingAppInfo.packageName.
أنشِئ استجابة JSON لواجهة برمجة تطبيقات Web Authentication تتضمّن المفتاح العام وcredentialId. يستخدم المثال أدناه فئات الأدوات المساعدة المحلية، مثل AuthenticatorAttestationResponse وFidoPublicKeyCredential التي تساعد في إنشاء JSON استنادًا إلى المواصفات المذكورة سابقًا.بصفتك مزوّد بيانات اعتماد، يمكنك استبدال هذه الفئات بأدوات الإنشاء الخاصة بك.
أنشِئ CreatePublicKeyCredentialResponse باستخدام JSON الذي تم إنشاؤه أعلاه.
اضبط CreatePublicKeyCredentialResponse كبيانات إضافية في Intent من خلال PendingIntentHander.setCreateCredentialResponse()، واضبط هذا الهدف على نتيجة النشاط.
أنهِ النشاط.

يوضّح مثال الرمز البرمجي أدناه هذه الخطوات. يجب التعامل مع هذا الرمز في فئة النشاط بعد استدعاء onCreate().

override fun onCreate(savedInstanceState: Bundle?, persistentState: PersistableBundle?) {
    super.onCreate(savedInstanceState, persistentState)
    // ...

    val request =
        PendingIntentHandler.retrieveProviderCreateCredentialRequest(intent)

    val accountId = intent.getStringExtra(CredentialsRepo.EXTRA_KEY_ACCOUNT_ID)
    if (request != null && request.callingRequest is CreatePublicKeyCredentialRequest) {
        val publicKeyRequest: CreatePublicKeyCredentialRequest =
            request.callingRequest as CreatePublicKeyCredentialRequest
        createPasskey(
            publicKeyRequest.requestJson,
            request.callingAppInfo,
            publicKeyRequest.clientDataHash,
            accountId
        )
    }
}

@SuppressLint("RestrictedApi")
fun createPasskey(
    requestJson: String,
    callingAppInfo: CallingAppInfo?,
    clientDataHash: ByteArray?,
    accountId: String?
) {
    val request = PublicKeyCredentialCreationOptions(requestJson)

    val biometricPrompt = BiometricPrompt(
        this,
        { }, // Pass in your own executor
        object : AuthenticationCallback() {
            override fun onAuthenticationError(errorCode: Int, errString: CharSequence) {
                super.onAuthenticationError(errorCode, errString)
                finish()
            }

            override fun onAuthenticationFailed() {
                super.onAuthenticationFailed()
                finish()
            }

            @RequiresApi(VERSION_CODES.P)
            override fun onAuthenticationSucceeded(
                result: AuthenticationResult
            ) {
                super.onAuthenticationSucceeded(result)

                // Generate a credentialId
                val credentialId = ByteArray(32)
                SecureRandom().nextBytes(credentialId)

                // Generate a credential key pair
                val spec = ECGenParameterSpec("secp256r1")
                val keyPairGen = KeyPairGenerator.getInstance("EC")
                keyPairGen.initialize(spec)
                val keyPair = keyPairGen.genKeyPair()

                // Save passkey in your database as per your own implementation

                // Create AuthenticatorAttestationResponse object to pass to
                // FidoPublicKeyCredential

                val response = AuthenticatorAttestationResponse(
                    requestOptions = request,
                    credentialId = credentialId,
                    credentialPublicKey = getPublicKeyFromKeyPair(keyPair),
                    origin = appInfoToOrigin(callingAppInfo!!),
                    up = true,
                    uv = true,
                    be = true,
                    bs = true,
                    packageName = callingAppInfo.packageName
                )

                val credential = FidoPublicKeyCredential(
                    rawId = credentialId,
                    response = response,
                    authenticatorAttachment = "", // Add your authenticator attachment
                )
                val result = Intent()

                val createPublicKeyCredResponse =
                    CreatePublicKeyCredentialResponse(credential.json())

                // Set the CreateCredentialResponse as the result of the Activity
                PendingIntentHandler.setCreateCredentialResponse(
                    result,
                    createPublicKeyCredResponse
                )
                setResult(RESULT_OK, result)
                finish()
            }
        }
    )

    val promptInfo = BiometricPrompt.PromptInfo.Builder()
        .setTitle("Use your screen lock")
        .setSubtitle("Create passkey for ${request.rp.name}")
        .setAllowedAuthenticators(
            BiometricManager.Authenticators.BIOMETRIC_STRONG
            /* or BiometricManager.Authenticators.DEVICE_CREDENTIAL */
        )
        .build()
    biometricPrompt.authenticate(promptInfo)
}

@RequiresApi(VERSION_CODES.P)
fun appInfoToOrigin(info: CallingAppInfo): String {
    val cert = info.signingInfo.apkContentsSigners[0].toByteArray()
    val md = MessageDigest.getInstance("SHA-256")
    val certHash = md.digest(cert)
    // This is the format for origin
    return "android:apk-key-hash:${b64Encode(certHash)}"
}

التعامل مع طلبات إنشاء كلمة مرور

للتعامل مع طلبات إنشاء كلمة مرور، يُرجى اتّباع الخطوات التالية:

داخل طريقة processCreateCredentialRequest() المذكورة في القسم السابق، أضِف حالة أخرى داخل كتلة التعليمات البرمجية `switch` للتعامل مع طلبات كلمات المرور.
أثناء إنشاء BeginCreateCredentialResponse، أضِف CreateEntries المطلوبة.
يجب أن يتطابق كل CreateEntry مع حساب يمكن حفظ بيانات الاعتماد فيه، ويجب أن يتضمّن PendingIntent تم ضبطه بالإضافة إلى البيانات الوصفية الأخرى.

يوضّح المثال التالي كيفية تنفيذ هذه الخطوات:

fun processCreateCredentialRequest(
    request: BeginCreateCredentialRequest
): BeginCreateCredentialResponse? {
    when (request) {
        is BeginCreatePublicKeyCredentialRequest -> {
            // Request is passkey type
            return handleCreatePasskeyQuery(request)
        }

        is BeginCreatePasswordCredentialRequest -> {
            // Request is password type
            return handleCreatePasswordQuery(request)
        }
    }
    return null
}

@RequiresApi(VERSION_CODES.M)
private fun handleCreatePasswordQuery(
    request: BeginCreatePasswordCredentialRequest
): BeginCreateCredentialResponse {
    val createEntries: MutableList<CreateEntry> = mutableListOf()

    // Adding two create entries - one for storing credentials to the 'Personal'
    // account, and one for storing them to the 'Family' account. These
    // accounts are local to this sample app only.
    createEntries.add(
        CreateEntry(
            PERSONAL_ACCOUNT_ID,
            createNewPendingIntent(PERSONAL_ACCOUNT_ID, CREATE_PASSWORD_INTENT)
        )
    )
    createEntries.add(
        CreateEntry(
            FAMILY_ACCOUNT_ID,
            createNewPendingIntent(FAMILY_ACCOUNT_ID, CREATE_PASSWORD_INTENT)
        )
    )

    return BeginCreateCredentialResponse(createEntries)
}

التعامل مع اختيار الإدخال لطلبات إنشاء كلمة مرور

عندما يختار المستخدم CreateEntry تم ملؤه، يتم تنفيذ PendingIntent المقابل ويظهر `Activity` المرتبط. يمكنك الوصول إلى الهدف المرتبط الذي تم تمريره في onCreate وتمريره إلى فئة PendingIntentHander للحصول على طريقة ProviderCreateCredentialRequest.

يوضّح المثال أدناه كيفية تنفيذ هذه العملية. يجب التعامل مع هذا الرمز في طريقة onCreate() في النشاط.

val createRequest = PendingIntentHandler.retrieveProviderCreateCredentialRequest(intent)
val accountId = intent.getStringExtra(CredentialsRepo.EXTRA_KEY_ACCOUNT_ID)

if (createRequest == null) {
    return
}

val request: CreatePasswordRequest = createRequest.callingRequest as CreatePasswordRequest

// Fetch the ID and password from the request and save it in your database
mDatabase.addNewPassword(
    PasswordInfo(
        request.id,
        request.password,
        createRequest.callingAppInfo.packageName
    )
)

// Set the final response back
val result = Intent()
val response = CreatePasswordResponse()
PendingIntentHandler.setCreateCredentialResponse(result, response)
setResult(Activity.RESULT_OK, result)
finish()

يتم التعامل مع تسجيل دخول المستخدم من خلال الخطوات التالية:

عندما يحاول تطبيق عميل تسجيل دخول مستخدم، يُعدّ مثيلاً من GetCredentialRequest.
ينشر إطار عمل Android هذا الطلب إلى جميع مزوّدي بيانات الاعتماد المناسبين من خلال الربط بهذه الخدمات.
بعد ذلك، تتلقّى خدمة مزوّد بيانات الاعتماد BeginGetCredentialRequest يتضمّن قائمة BeginGetCredentialOption، ويحتوي كل منها على مَعلمات يمكن استخدامها لاسترداد بيانات الاعتماد المطابقة.

ملاحظة: على مزوّدي بيانات الاعتماد تخطّي عملية التحقّق من صحة البيانات التي تقارن المصدر الذي يطلب بيانات الاعتماد بمعرّف الطرف المعتمد (RP ID). هذا التحقّق غير ضروري ويؤدي إلى رفض طلبات المصدر المرتبط (ROR) الصالحة عندما تختلف المصادر، ما يؤدي إلى حدوث أعطال للأطراف المعتمدة التي تستخدم طلبات المصدر المرتبط. إذا كان عليك الاحتفاظ بعملية تحقّق إضافية من صحة البيانات ذات الصلة بمعرّف الطرف المعتمد، يجب أن تشير المنطقية صراحةً إلى تعريف طلبات المصدر المرتبط وأن تأخذها في الاعتبار.

للتعامل مع هذا الطلب في خدمة مزوّد بيانات الاعتماد، يُرجى إكمال الخطوات التالية:

ألغِ طريقة onBeginGetCredentialRequest() للتعامل مع الطلب. يُرجى العِلم أنّه إذا كانت بيانات الاعتماد مقفلة، يمكنك على الفور ضبط AuthenticationAction في الردّ واستدعاء معاودة الاتصال.

private val unlockEntryTitle = "Authenticate to continue"

override fun onBeginGetCredentialRequest(
    request: BeginGetCredentialRequest,
    cancellationSignal: CancellationSignal,
    callback: OutcomeReceiver<BeginGetCredentialResponse, GetCredentialException>,
) {
    if (isAppLocked()) {
        callback.onResult(
            BeginGetCredentialResponse(
                authenticationActions = mutableListOf(
                    AuthenticationAction(
                        unlockEntryTitle, createUnlockPendingIntent()
                    )
                )
            )
        )
        return
    }
    try {
        response = processGetCredentialRequest(request)
        callback.onResult(response)
    } catch (e: GetCredentialException) {
        callback.onError(GetCredentialUnknownException())
    }
}

على مزوّدي بيانات الاعتماد الذين يتطلّبون إلغاء قفل بيانات الاعتماد قبل عرض أي credentialEntries، إعداد هدف في انتظار المراجعة ينقل المستخدم إلى مسار إلغاء القفل في التطبيق:

private fun createUnlockPendingIntent(): PendingIntent {
    val intent = Intent(UNLOCK_INTENT).setPackage(PACKAGE_NAME)
    return PendingIntent.getActivity(
        applicationContext, UNIQUE_REQUEST_CODE, intent,
        (
            PendingIntent.FLAG_MUTABLE
                or PendingIntent.FLAG_UPDATE_CURRENT
            )
    )
}

استردِ بيانات الاعتماد من قاعدة البيانات المحلية واضبطها باستخدام CredentialEntries لعرضها على أداة الاختيار. بالنسبة إلى مفاتيح المرور، يمكنك ضبط credentialId كبيانات إضافية في الهدف لمعرفة بيانات الاعتماد التي يرتبط بها عندما يختار المستخدم هذا الإدخال.

companion object {
    // These intent actions are specified for corresponding activities
    // that are to be invoked through the PendingIntent(s)
    private const val GET_PASSKEY_INTENT_ACTION = "PACKAGE_NAME.GET_PASSKEY"
    private const val GET_PASSWORD_INTENT_ACTION = "PACKAGE_NAME.GET_PASSWORD"
}

fun processGetCredentialRequest(
    request: BeginGetCredentialRequest
): BeginGetCredentialResponse {
    val callingPackageInfo = request.callingAppInfo
    val callingPackageName = callingPackageInfo?.packageName.orEmpty()
    val credentialEntries: MutableList<CredentialEntry> = mutableListOf()

    for (option in request.beginGetCredentialOptions) {
        when (option) {
            is BeginGetPasswordOption -> {
                credentialEntries.addAll(
                    populatePasswordData(
                        callingPackageName,
                        option
                    )
                )
            }
            is BeginGetPublicKeyCredentialOption -> {
                credentialEntries.addAll(
                    populatePasskeyData(
                        callingPackageInfo,
                        option
                    )
                )
            } else -> {
                Log.i(TAG, "Request not supported")
            }
        }
    }
    return BeginGetCredentialResponse(credentialEntries)
}

اطلب بيانات الاعتماد من قاعدة البيانات، وأنشِئ إدخالات مفاتيح المرور وكلمات المرور لملئها.

private fun populatePasskeyData(
    callingAppInfo: CallingAppInfo?,
    option: BeginGetPublicKeyCredentialOption
): List<CredentialEntry> {
    val passkeyEntries: MutableList<CredentialEntry> = mutableListOf()
    val request = PublicKeyCredentialRequestOptions(option.requestJson)
    // Get your credentials from database where you saved during creation flow
    val creds = getCredentialsFromInternalDb(request.rpId)
    val passkeys = creds.passkeys
    for (passkey in passkeys) {
        val data = Bundle()
        data.putString("credId", passkey.credId)
        passkeyEntries.add(
            PublicKeyCredentialEntry(
                context = applicationContext,
                username = passkey.username,
                pendingIntent = createNewPendingIntent(
                    GET_PASSKEY_INTENT_ACTION,
                    data
                ),
                beginGetPublicKeyCredentialOption = option,
                displayName = passkey.displayName,
                icon = passkey.icon
            )
        )
    }
    return passkeyEntries
}

// Fetch password credentials and create password entries to populate to the user
private fun populatePasswordData(
    callingPackage: String,
    option: BeginGetPasswordOption
): List<CredentialEntry> {
    val passwordEntries: MutableList<CredentialEntry> = mutableListOf()

    // Get your password credentials from database where you saved during
    // creation flow
    val creds = getCredentialsFromInternalDb(callingPackage)
    val passwords = creds.passwords
    for (password in passwords) {
        passwordEntries.add(
            PasswordCredentialEntry(
                context = applicationContext,
                username = password.username,
                pendingIntent = createNewPendingIntent(
                    GET_PASSWORD_INTENT
                ),
                beginGetPasswordOption = option,
                displayName = password.username,
                icon = password.icon
            )
        )
    }
    return passwordEntries
}

private fun createNewPendingIntent(
    action: String,
    extra: Bundle? = null
): PendingIntent {
    val intent = Intent(action).setPackage(PACKAGE_NAME)
    if (extra != null) {
        intent.putExtra("CREDENTIAL_DATA", extra)
    }

    return PendingIntent.getActivity(
        applicationContext, UNIQUE_REQUEST_CODE, intent,
        (PendingIntent.FLAG_MUTABLE or PendingIntent.FLAG_UPDATE_CURRENT)
    )
}

بعد طلب بيانات الاعتماد وملئها، عليك الآن التعامل مع مرحلة الاختيار لبيانات الاعتماد التي يختارها المستخدم، سواء كانت مفتاح مرور أو كلمة مرور.

التعامل مع اختيار المستخدم لمفاتيح المرور

في طريقة onCreate للنشاط المقابل، استردِ الهدف المرتبط ، ومرِّره إلى PendingIntentHandler.retrieveProviderGetCredentialRequest().
استخرِج GetPublicKeyCredentialOption من الطلب الذي تم استرداده أعلاه. بعد ذلك، استخرِج requestJson وclientDataHash من هذا الخيار.
استخرِج credentialId من البيانات الإضافية للهدف، والتي تم ملؤها من قِبل مزوّد بيانات الاعتماد عند إعداد PendingIntent المقابل.
استخرِج مفتاح المرور من قاعدة البيانات المحلية باستخدام مَعلمات الطلب التي تم الوصول إليها أعلاه.

تأكَّد من أنّ مفتاح المرور صالح باستخدام البيانات الوصفية المستخرَجة وعملية التحقّق من هوية المستخدم.

val getRequest = PendingIntentHandler.retrieveProviderGetCredentialRequest(intent)
val publicKeyRequest = getRequest?.credentialOptions?.first() as GetPublicKeyCredentialOption

val requestInfo = intent.getBundleExtra("CREDENTIAL_DATA")
val credIdEnc = requestInfo?.getString("credId").orEmpty()

// Get the saved passkey from your database based on the credential ID from the PublicKeyRequest
val passkey = mDatabase.getPasskey(credIdEnc)

// Decode the credential ID, private key and user ID
val credId = b64Decode(credIdEnc)
val privateKey = b64Decode(passkey.credPrivateKey)
val uid = b64Decode(passkey.uid)

val origin = appInfoToOrigin(getRequest.callingAppInfo)
val packageName = getRequest.callingAppInfo.packageName

validatePasskey(
    publicKeyRequest.requestJson,
    origin,
    packageName,
    uid,
    passkey.username,
    credId,
    privateKey
)

للتحقّق من هوية المستخدم، اعرض طلبًا بيومتريًا (أو طريقة تأكيد أخرى). يستخدم مقتطف الرمز البرمجي أدناه Android Biometric API.
بعد نجاح المصادقة، أنشِئ استجابة JSON استنادًا إلى مواصفات W3 Web Authentication Assertion. في مقتطف الرمز البرمجي أدناه، تُستخدَم فئات البيانات المساعدة، مثل AuthenticatorAssertionResponse لتلقّي مَعلمات منظَّمة وتحويلها إلى تنسيق JSON المطلوب. تحتوي الاستجابة على توقيع رقمي من المفتاح الخاص لبيانات اعتماد WebAuthn. يمكن لخادم الطرف المعتمد التحقّق من هذا التوقيع لمصادقة المستخدم قبل تسجيل الدخول.
أنشِئ PublicKeyCredential باستخدام JSON الذي تم إنشاؤه أعلاه و اضبطه على GetCredentialResponse نهائي. اضبط هذا الردّ النهائي على نتيجة هذا النشاط.

يوضّح المثال التالي كيفية تنفيذ هذه الخطوات:

val request = PublicKeyCredentialRequestOptions(requestJson)
val privateKey: ECPrivateKey = convertPrivateKey(privateKeyBytes)

val biometricPrompt = BiometricPrompt(
    this,
    { }, // Pass in your own executor
    object : BiometricPrompt.AuthenticationCallback() {
        override fun onAuthenticationError(
            errorCode: Int,
            errString: CharSequence
        ) {
            super.onAuthenticationError(errorCode, errString)
            finish()
        }

        override fun onAuthenticationFailed() {
            super.onAuthenticationFailed()
            finish()
        }

        override fun onAuthenticationSucceeded(
            result: BiometricPrompt.AuthenticationResult
        ) {
            super.onAuthenticationSucceeded(result)
            val response = AuthenticatorAssertionResponse(
                requestOptions = request,
                credentialId = credId,
                origin = origin,
                up = true,
                uv = true,
                be = true,
                bs = true,
                userHandle = uid,
                packageName = packageName
            )

            val sig = Signature.getInstance("SHA256withECDSA")
            sig.initSign(privateKey)
            sig.update(response.dataToSign())
            response.signature = sig.sign()

            val credential = FidoPublicKeyCredential(
                rawId = credId,
                response = response,
                authenticatorAttachment = "", // Add your authenticator attachment
            )
            val result = Intent()
            val passkeyCredential = PublicKeyCredential(credential.json())
            PendingIntentHandler.setGetCredentialResponse(
                result, GetCredentialResponse(passkeyCredential)
            )
            setResult(RESULT_OK, result)
            finish()
        }
    }
)

val promptInfo = BiometricPrompt.PromptInfo.Builder()
    .setTitle("Use your screen lock")
    .setSubtitle("Use passkey for ${request.rpId}")
    .setAllowedAuthenticators(
        BiometricManager.Authenticators.BIOMETRIC_STRONG
        /* or BiometricManager.Authenticators.DEVICE_CREDENTIAL */
    )
    .build()
biometricPrompt.authenticate(promptInfo)

التعامل مع اختيار المستخدم للمصادقة باستخدام كلمة المرور

في النشاط المقابل، يمكنك الوصول إلى الهدف الذي تم تمريره إلى onCreate واستخراج ProviderGetCredentialRequest باستخدام PendingIntentHandler.

استخدِم GetPasswordOption في الطلب لاسترداد بيانات اعتماد كلمة المرور الواردة لاسم الحزمة.

val getRequest = PendingIntentHandler.retrieveProviderGetCredentialRequest(intent)

val passwordOption = getRequest?.credentialOptions?.first() as GetPasswordOption

val username = passwordOption.allowedUserIds.first()
// Fetch the credentials for the calling app package name
val creds = mDatabase.getCredentials(callingAppInfo.packageName)
val passwords = creds.passwords
val it = passwords.iterator()
var password = ""
while (it.hasNext()) {
    val passwordItemCurrent = it.next()
    if (passwordItemCurrent.username == username) {
        password = passwordItemCurrent.password
        break
    }
}

بعد استرداد بيانات اعتماد كلمة المرور المحدّدة، اضبط الردّ عليها.

// Set the response back
val result = Intent()
val passwordCredential = PasswordCredential(username, password)
PendingIntentHandler.setGetCredentialResponse(
    result, GetCredentialResponse(passwordCredential)
)
setResult(Activity.RESULT_OK, result)
finish()

التعامل مع اختيار إدخال إجراء المصادقة

كما ذكرنا سابقًا، يمكن لمزوّد بيانات الاعتماد ضبط AuthenticationAction إذا كانت بيانات الاعتماد مقفلة. إذا اختار المستخدم هذا الإدخال، يتم استدعاء `Activity` المقابل لإجراء الهدف الذي تم ضبطه في PendingIntent. يمكن لمزوّدي بيانات الاعتماد بعد ذلك عرض مسار المصادقة البيومترية أو آلية مشابهة لإلغاء قفل بيانات الاعتماد. عند النجاح، على مزوّد بيانات الاعتماد إنشاء BeginGetCredentialResponse، على غرار كيفية وصف عملية التعامل مع تسجيل دخول المستخدم أعلاه، لأنّه تم الآن إلغاء قفل بيانات الاعتماد. يجب بعد ذلك ضبط هذا الردّ من خلال الـ PendingIntentHandler.setBeginGetCredentialResponse() قبل ضبط الهدف المُعدّ كنتيجة وإنهاء `Activity`.

محو طلبات بيانات الاعتماد

قد يطلب تطبيق عميل محو أي حالة يتم الاحتفاظ بها لاختيار بيانات الاعتماد، مثل أن يتذكر مزوّد بيانات الاعتماد بيانات الاعتماد التي تم اختيارها سابقًا ولا يعرضها إلا في المرة القادمة. يستدعي تطبيق العميل واجهة برمجة التطبيقات هذه ويتوقّع محو عملية الاختيار الثابت. يمكن لخدمة مزوّد بيانات الاعتماد التعامل مع هذا الطلب من خلال إلغاء طريقة onClearCredentialStateRequest():

override fun onClearCredentialStateRequest(
    request: ProviderClearCredentialStateRequest,
    cancellationSignal: CancellationSignal,
    callback: OutcomeReceiver<Void?, ClearCredentialException>
) {
    // Delete any maintained state as appropriate.
}

إضافة إمكانية الربط بصفحة إعدادات مزوّد بيانات الاعتماد

للسماح للمستخدمين بفتح إعدادات مزوّد بيانات الاعتماد من شاشة كلمات المرور ومفاتيح المرور والملء التلقائي، على تطبيقات مزوّدي بيانات الاعتماد تنفيذ سمة البيان settingsActivity في credential-provider في res/xml/provider.xml. تتيح لك هذه السمة استخدام هدف لفتح شاشة إعدادات تطبيقك إذا نقر المستخدم على اسم مزوّد بيانات اعتماد في قائمة الخدمات كلمات المرور ومفاتيح المرور والملء التلقائي. اضبط قيمة هذه السمة على اسم النشاط الذي سيتم تشغيله من شاشة الإعدادات.

<credential-provider
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:settingsSubtitle="Example settings provider name"
    android:settingsActivity="com.example.SettingsActivity">
    <capabilities>
        <capability name="android.credentials.TYPE_PUBLIC_KEY_CREDENTIAL" />
    </capabilities>
</credential-provider>

مخطّط يوضّح وظائف زرّي "التغيير" و"فتح" — **الشكل 1:** يفتح الزر **تغيير** مربّع حوار الاختيار الحالي، ما يسمح للمستخدم باختيار مزوّد بيانات الاعتماد المفضّل لديه. يشغّل الزر **فتح** نشاط الإعدادات المحدّد في تغيير البيان، ويفتح صفحة إعدادات خاصة بمزوّد بيانات الاعتماد هذا.

أهداف الإعدادات

فتح الإعدادات: يؤدي الهدف android.settings.CREDENTIAL_PROVIDER إلى ظهور شاشة إعدادات يمكن للمستخدم من خلالها اختيار مزوّدي بيانات الاعتماد المفضّلين والإضافيين.

شاشة "كلمات المرور ومفاتيح المرور والملء التلقائي" — **الشكل 2:** شاشة إعدادات "كلمات المرور ومفاتيح المرور والملء التلقائي"

خدمة بيانات الاعتماد المفضّلة: يعيد الهدف ACTION_REQUEST_SET_AUTOFILL_SERVICE توجيه المستخدم إلى شاشة اختيار مزوّد بيانات الاعتماد المفضّل. يصبح المزوّد المحدّد على هذه الشاشة هو مزوّد بيانات الاعتماد والملء التلقائي المفضّل.

الحصول على قائمة السماح بالتطبيقات المميّزة

تُجري التطبيقات المميّزة، مثل متصفّحات الويب، طلبات إلى "مدير بيانات الاعتماد" نيابةً عن أطراف معتمَدة أخرى من خلال ضبط المَعلمة origin في "مدير بيانات الاعتماد"GetCredentialRequest() و CreatePublicKeyCredentialRequest() الطريقتَين. لمعالجة هذه الطلبات، يسترد مزوّد بيانات الاعتماد origin باستخدام getOrigin() واجهة برمجة التطبيقات.

لاسترداد origin، على تطبيق مزوّد بيانات الاعتماد تمرير قائمة بالمستدعين المميّزين والموثوق بهم إلى واجهة برمجة التطبيقات androidx.credentials.provider.CallingAppInfo's getOrigin(). يجب أن تكون قائمة السماح هذه كائن JSON صالحًا. يتم عرض origin إذا كان packageName وبصمات الأصابع للشهادة التي تم الحصول عليها من signingInfo تتطابق مع بصمات الأصابع لتطبيق تم العثور عليه في privilegedAllowlist الذي تم تمريره إلى واجهة برمجة التطبيقات getOrigin(). بعد الحصول على قيمة origin، على تطبيق مقدّمي الخدمات اعتبار ذلك طلبًا مميّزًا وضبط هذا origin على بيانات العميل في AuthenticatorResponse، بدلاً من احتساب origin باستخدام توقيع التطبيق الذي يستدعي واجهة برمجة التطبيقات.

إذا استرددت origin، استخدِم clientDataHash المقدَّم مباشرةً في CreatePublicKeyCredentialRequest() أو GetPublicKeyCredentialOption() بدلاً من تجميع clientDataJSON وتجزئته أثناء طلب التوقيع. لتجنُّب مشاكل تحليل JSON، اضبط قيمة عنصر نائب لـ clientDataJSON في استجابة المصادقة والتأكيد. يستخدم "مدير كلمات المرور في Google" قائمة سماح متاحة للجميع للطلبات الموجّهة إلى getOrigin(). بصفتك مزوّد بيانات اعتماد، يمكنك استخدام هذه القائمة أو تقديم قائمتك الخاصة بتنسيق JSON الموضّح من قِبل واجهة برمجة التطبيقات. يعود إلى مزوّد بيانات الاعتماد اختيار القائمة التي سيتم استخدامها. للحصول على إذن وصول مميّز باستخدام مزوّدي بيانات اعتماد تابعين لجهات خارجية، يُرجى الرجوع إلى المستندات التي تقدّمها الجهة الخارجية.

تفعيل مزوّدي بيانات الاعتماد على جهاز

على المستخدمين تفعيل مزوّد بيانات الاعتماد من خلال إعدادات الجهاز > كلمات المرور والحسابات > مزوّد بيانات الاعتماد > تفعيل أو إيقاف.

fun createSettingsPendingIntent(): PendingIntent