يشير "مدير بيانات الاعتماد" إلى مجموعة من واجهات برمجة التطبيقات المقدَّمة في Android 14 والمتوافقة مع طرق تسجيل دخول متعددة، مثل كلمة مرور اسم المستخدم ومفاتيح المرور ومفاتيح المرور الموحدة حلول تسجيل الدخول (مثل تسجيل الدخول باستخدام حساب Google). عند استدعاء واجهة برمجة التطبيقات Credential Manager API، يجمع نظام Android بيانات الاعتماد من جميع مزوّدي بيانات الاعتماد المثبَّتين على الجهاز. يوضّح هذا المستند مجموعة واجهات برمجة التطبيقات التي توفّر نقاط نهاية الدمج لمزوّدي بيانات الاعتماد هؤلاء.
ضبط إعدادات الجهاز
قبل تنفيذ الوظيفة في موفِّر بيانات الاعتماد، عليك إكمال خطوات الإعداد الموضحة في الأقسام التالية.
تعريف التبعيات
في ملف build.gradle
الخاص بالوحدة، أفصح عن التبعية باستخدام
الإصدار من مكتبة مدير بيانات الاعتماد:
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
في Activity، يمكنك الوصول إلى الintent المرتبط ونقله إلى فئة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()
، وضبط ذلك النية في نتيجة النشاط. - أكمِل النشاط.
يوضّح مثال الرمز البرمجي أدناه هذه الخطوات. يجب التعامل مع هذه التعليمة البرمجية في
صف النشاط بعد استدعاء 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>
الإعدادات المقصودة
فتح الإعدادات: يؤدي الغرض android.settings.CREDENTIAL_PROVIDER
إلى عرض شاشة إعدادات يمكن للمستخدم من خلالها اختيار مقدّمي بيانات الاعتماد المفضّلين لديه
والمقدّمين الإضافيين.
خدمة بيانات الاعتماد المفضَّلة:
الغرض من 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