تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

ضبط إعدادات الميزة

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

تعريف العناصر التابعة

في ملف build.gradle الخاص بالوحدة، حدِّد عنصرًا تابعًا باستخدام أحدث إصدار من مكتبة Credential Manager:

implementation "androidx.credentials:credentials:1.2.0-{latest}"

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

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

<service android:name=".MyCredentialProviderService"
    android:enabled="true"
    android:exported="true"
    android:label="My Credential Provider"
    android:icon="<any drawable icon>"
    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>AndroidManifest.xml

إنّ الإذن وفلتر الأهداف الموضّحَين في المثال السابق هما جزءان أساسيان لكي يعمل مسار Credential Manager على النحو المتوقّع. ويجب الحصول على هذا الإذن لكي يتم ربط هذه الخدمة بنظام Android فقط. يتم استخدام فلتر الأهداف لإتاحة إمكانية العثور على هذه الخدمة كموفّر بيانات اعتماد يمكن أن يستخدمه مدير بيانات الاعتماد.

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

في الدليل 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>provider.xml

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

اتّباع نهج من مرحلتَين للتفاعل مع مقدِّمي الخدمات

تتفاعل "أداة إدارة بيانات الاعتماد" مع مزوّدي بيانات الاعتماد على مرحلتَين:

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

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

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

عندما يريد تطبيق عميل إنشاء مفتاح مرور وتخزينه لدى مقدّم خدمة بيانات الاعتماد، فإنه يستدعي واجهة برمجة التطبيقات 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
            )
    )
}MyCredentialProviderService.kt

يجب أن يلتزم تصميم PendingIntent بما يلي:

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

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

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

يوضّح مثال الرمز البرمجي أدناه هذه الخطوات. يجب التعامل مع هذا الرمز في فئة Activity عند استدعاء 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)}"
}CredentialProviderDummyActivity.kt

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

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

داخل طريقة processCreateCredentialRequest() المذكورة في القسم السابق، أضِف حالة أخرى داخل كتلة التبديل للتعامل مع طلبات كلمات المرور.
أثناء إنشاء 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)
}CredentialProviderDummyActivity.kt

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

عندما يختار المستخدم CreateEntry تم ملؤه، يتم تنفيذ PendingIntent المقابل ويتم عرض النشاط المرتبط به. يمكنك الوصول إلى الغرض المرتبط الذي تم تمريره في 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()CredentialProviderDummyActivity.kt

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

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

للتعامل مع هذا الطلب في خدمة مقدّم بيانات الاعتماد، أكمِل الخطوات التالية:

تجاوز طريقة 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())
    }
}MyCredentialProviderService.kt

على مقدّمي الخدمات الذين يطلبون فتح بيانات الاعتماد قبل عرض أي credentialEntries، إعداد PendingIntent ينقل المستخدم إلى مسار فتح القفل في التطبيق:

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
            )
    )
}MyCredentialProviderService.kt

استرجِع بيانات الاعتماد من قاعدة البيانات المحلية واضبطها باستخدام 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)
}MyCredentialProviderService.kt

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

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)
    )
}MyCredentialProviderService.kt

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

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

في طريقة onCreate الخاصة بالنشاط المعنيّ، استرجِع النية المرتبطة، ومرِّرها إلى PendingIntentHandler.retrieveProviderGetCredentialRequest().
استخرِج GetPublicKeyCredentialOption من الطلب الذي تم استرداده أعلاه. بعد ذلك، استخرِج requestJson وclientDataHash من هذا الخيار.
استخرِج credentialId من بيانات إضافية في Intent، والتي تم ملؤها بواسطة موفّر بيانات الاعتماد عند إعداد 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
)CredentialProviderDummyActivity.kt

لإثبات هوية المستخدم، اعرض طلب مصادقة بيومترية (أو طريقة تأكيد أخرى). يستخدم مقتطف الرمز البرمجي أدناه واجهة برمجة التطبيقات 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)CredentialProviderDummyActivity.kt

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

في النشاط المعنيّ، يمكنك الوصول إلى الغرض الذي تم تمريره إلى 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
    }
}CredentialProviderDummyActivity.kt

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

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

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

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

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

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

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

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

للسماح للمستخدمين بفتح إعدادات مقدّم الخدمة من شاشة كلمات المرور ومفاتيح المرور والملء التلقائي، يجب أن تنفّذ تطبيقات مقدّم بيانات الاعتماد السمة credential-provider settingsActivity في ملف البيان 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>provider_settings.xml

مخطّط يوضّح وظائف زرّي "التغيير" و"فتح" — **الشكل 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