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

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

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

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

ضبط إعدادات الجهاز

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

الإفصاح عن التبعيات

في ملف 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">
    <intent-filter>
        <action android:name="android.service.credentials.CredentialProviderService"/>
    </intent-filter>
    <meta-data
         android:name="android.credentials.provider"
         android:resource="@xml/provider"/>
</service>

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

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

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

<?xml version="1.0" encoding="utf-8"?>
<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>

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

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

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

المرحلة الأولى هي مرحلة البدء/الطلب التي يرتبط فيها النظام بخدمات مقدّمي بيانات الاعتماد ويُطلِب 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. وبصفتك مقدّم بيانات اعتماد، يمكنك استبدال هذا الإجراء باستخدام محلِّل النصوص الخاص بك.
تحقَّق من رابط مادة العرض لتطبيق الاتصال إذا كانت المكالمة ناتجة عن تطبيق Android أصلي.
عرض إشعار للمصادقة يستخدم المثال أدناه واجهة برمجة التطبيقات Android Biometric.
عند نجاح المصادقة، أنشئ credentialId و زوج مفتاح.
احفظ المفتاح الخاص في قاعدة بياناتك المحلية بجانب callingAppInfo.packageName.
أنشئ استجابة JSON في Web Authentication API تتكون من المفتاح العام وcredentialId. يستخدم المثال أدناه فئات أدوات محلية مثل AuthenticatorAttestationResponse و FidoPublicKeyCredential التي تساعد في إنشاء ملف JSON استنادًا إلى المواصفات المذكورة أعلاه.وبصفتك مقدّم بيانات الاعتماد، يمكنك استبدال هذه الفئات بأدوات الإنشاء الخاصة بك.
أنشئ CreatePublicKeyCredentialResponse باستخدام ملف JSON الذي تم إنشاؤه أعلاه.
اضبط CreatePublicKeyCredentialResponse كإضافة في Intent من خلال PendingIntentHander.setCreateCredentialResponse()، واضبط intent على نتيجة النشاط.
أكمِل النشاط.

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

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

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

  val biometricPrompt = BiometricPrompt(
    this,
    <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)

        // 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
        )
        val result = Intent()

        val createPublicKeyCredResponse =
          CreatePublicKeyCredentialResponse(credential.json())

        // Set the CreateCredentialResponse as the result of the Activity
        PendingIntentHandler.setCreateCredentialResponse(
          result, createPublicKeyCredResponse
        )
        setResult(Activity.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)
}

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

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 المقابل وعرض النشاط المرتبط به. يمكنك الوصول إلى النشاط المرتبط الذي تم تمريره في onCreate ونقله إلى فئة PendingIntentHander للحصول على طريقة ProviderCreateCredentialRequest.

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

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

val request: CreatePasswordRequest = createRequest.callingRequest as CreatePasswordRequest

// Fetch the ID and password from the request and save it in your database
<your_database>.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)
this@<activity>.finish()

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

عندما يحاول تطبيق العميل تسجيل دخول مستخدم، يُعدّ مثيلًا 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())
    }
}

بالنسبة إلى مقدّمي الخدمات الذين يطلبون فتح قفل بيانات الاعتماد قبل عرض أي 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 processGetCredentialsRequest(
request: BeginGetCredentialRequest
): BeginGetCredentialResponse {
    val callingPackage = request.callingAppInfo?.packageName
    val credentialEntries: MutableList<CredentialEntry> = mutableListOf()

    for (option in request.beginGetCredentialOptions) {
        when (option) {
            is BeginGetPasswordOption -> {
                credentialEntries.addAll(
                        populatePasswordData(
                            callingPackage,
                            option
                        )
                    )
                }
                is BeginGetPublicKeyCredentialOption -> {
                    credentialEntries.addAll(
                        populatePasskeyData(
                            callingPackage,
                            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
              ),
              beginPublicKeyCredentialOption = 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.credentialOption as GetPublicKeyCredentialOption

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

// Get the saved passkey from your database based on the credential ID
// from the publickeyRequest
val passkey = <your database>.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,
    <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
        )
        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.credentialOption as GetPasswordCredentialOption

val username = passwordOption.username
// Fetch the credentials for the calling app package name
val creds = <your_database>.getCredentials(callingAppInfo.packageName)
val passwords = creds.passwords
val it = passwords.iterator()
var password = ""
while (it.hasNext() == true) {
    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 في حال قفل بيانات الاعتماد. إذا اختار المستخدم هذا العنصر، يتمّ استدعاء "النشاط" المقابل للإجراء المقصود الذي تمّ ضبطه في PendingIntent. يمكن لمزوّدي بيانات الاعتماد بعد ذلك عرض مسار مصادقة باستخدام المقاييس الحيوية أو آلية مشابهة لفتح قفل بيانات الاعتماد. في حال نجاح العملية، يجب أن ينشئ مقدّم بيانات الاعتماد BeginGetCredentialResponseمشابهًا لطريقة معالجة تسجيل دخول المستخدم الموضّحة أعلاه، لأنّه تم الآن فتح قفل بيانات الاعتماد. يجب بعد ذلك ضبط هذا الردّ من خلال الأسلوب PendingIntentHandler.setBeginGetCredentialResponse() قبل ضبط النية المُعدّة كنتيجة وإنهاء النشاط.

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

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

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

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

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

رسم بياني يوضّح وظائف زرّي التغيير والفتح — **الشكل 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 في استجابة clientDataJSON. يستخدم "مدير كلمات المرور في Google" قائمة مسموح بها متاحة للجميع ل طلبات البيانات إلى getOrigin(). بصفتك مقدّم بيانات اعتماد، يمكنك استخدام هذه القائمة أو تقديم قائمتك الخاصة بتنسيق JSON الموضّح في واجهة برمجة التطبيقات. ويعود الأمر إلى الموفّر لاختيار القائمة التي سيتم استخدامها. للحصول على إذن وصول متميز من خلال موفّري بيانات اعتماد تابعين لجهات خارجية، يُرجى الرجوع إلى المستندات التي تقدّمها الجهة الخارجية.

تفعيل مقدّمي الخدمات على جهاز

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

fun createSettingsPendingIntent(): PendingIntent