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

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

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

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

تعريف التبعيات

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

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

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

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

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

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

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

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

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

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

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

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

  1. إلغاء طريقة onBeginCreateCredentialRequest() في خدمتك تم تمديده من CredentialProviderService.
  2. التعامل مع BeginCreateCredentialRequest من خلال إنشاء المقابلة BeginCreateCredentialResponse وتمريرها من خلال رد الاتصال.
  3. أثناء إنشاء 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 خاصة به.

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

  1. عندما يختار المستخدم CreateEntry التي تمت تعبئتها سابقًا، تم استدعاء PendingIntent المقابل ومقدّم الخدمة المرتبط تم إنشاء Activity.
  2. بعد استدعاء طريقة onCreate لنشاطك، يمكنك الوصول إلى ذات الصلة وتمريره إلى فئة PendingIntentHander للحصول على ProviderCreateCredentialRequest
  3. استخرِج requestJson وcallingAppInfo وclientDataHash من الطلب.
  4. يمكنك استخراج accountId المحلي من الغرض الإضافي. هذا نموذج تطبيق التنفيذ المحدد وليس مطلوبًا. يمكن استخدام رقم تعريف الحساب هذا لتخزين بيانات الاعتماد هذه مقابل رقم تعريف الحساب هذا بالتحديد.
  5. تحقَّق من صحة requestJson. يستخدم المثال أدناه فئات البيانات المحلية مثل PublicKeyCredentialCreationOptions لتحويل إدخال JSON إلى محددة وفقًا لمواصفات WebAuthn. بصفتك موفر بيانات اعتماد، يمكنك يمكنك استبداله بالمحلل الخاص بك.
  6. تحقَّق من رابط مادة العرض لتطبيق الاتصال إذا كانت المكالمة واردة من تطبيق Android الأصلي.
  7. عرض طلب للمصادقة يستخدم المثال أدناه واجهة برمجة التطبيقات Android Biometric.
  8. عندما تكون المصادقة ناجحة، يمكنك إنشاء credentialId مفتاحا التشفير.
  9. احفظ المفتاح الخاص في قاعدة البيانات المحلية على callingAppInfo.packageName
  10. عليك إنشاء استجابة JSON لواجهة برمجة تطبيقات الويب لمصادقة الويب يتكون من المفتاح العام وcredentialId. المثال أدناه فئات المرافق المحلية مثل AuthenticatorAttestationResponse FidoPublicKeyCredential التي تساعد في إنشاء ملف JSON بناءً على الروابط السابقة المواصفات المذكورة.وبصفتك موفر بيانات اعتماد، يمكنك استبدال هذه الفئات البنائين لديك.
  11. إنشاء CreatePublicKeyCredentialResponse باستخدام ملف JSON أعلاه.
  12. ضبط "CreatePublicKeyCredentialResponse" كخدمة إضافية من خلال "Intent" PendingIntentHander.setCreateCredentialResponse()، وضبط ذلك النية في نتيجة النشاط.
  13. أنهِ النشاط.

يوضّح مثال الرمز البرمجي أدناه هذه الخطوات. يجب معالجة هذا الرمز في صف Activity بعد استدعاء 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، يحتوي كلّ منها على مَعلمات يمكن استخدامها لاسترداد بيانات الاعتماد المطابقة.

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

  1. يمكنك إلغاء طريقة 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
        )
    )
}

  2. استرداد بيانات الاعتماد من قاعدة البيانات المحلية وإعدادها باستخدام 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)
}

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

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

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

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

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

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

    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
)

  6. للتأكّد من هوية المستخدم، يجب عرض طلب باستخدام المقاييس الحيوية (أو أي تأكيد آخر). ). يستخدِم مقتطف الرمز أدناه واجهة برمجة التطبيقات Android Biometric API.

  7. بعد نجاح المصادقة، يمكنك إنشاء استجابة JSON استنادًا إلى W3 مواصفات تأكيد مصادقة الويب. في مقتطف الرمز أدناه، تُستخدم فئات البيانات المساعدة مثل AuthenticatorAssertionResponse استخدام المعلمات المنظَّمة وتحويلها إلى تنسيق JSON المطلوب . يحتوي الرد على توقيع رقمي من مفتاح خاص لبيانات اعتماد WebAuthn. يمكن لخادم الجهة الموثوق بها التحقّق من هذا التوقيع لمصادقة مستخدم قبل تسجيل الدخول.

  8. أنشئ 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)

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

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

  2. استخدام 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
    }
}

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

    // 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 هو إعادة توجيه المستخدم إلى شاشة تحديد مقدم الخدمة المفضل. يصبح مقدّم الخدمة الذي تم اختياره في هذه الشاشة مقدّم بيانات الاعتماد والملء التلقائي المفضّل.

مخطّط بياني يعرض وظيفتَي زر التغيير وفتح
الشكل 3: الخدمة المفضّلة لكلمات المرور ومفاتيح المرور وشاشة إعدادات الملء التلقائي

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

تُجري التطبيقات المميّزة، مثل متصفّحات الويب، مكالمات "مدير بيانات الاعتماد" بالنيابة عن جهات اعتماد أخرى من خلال ضبط مَعلمة 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