Credential Holder API

Credential Holder API برنامه‌های Android را قادر می‌سازد تا اعتبار دیجیتال را مدیریت کرده و به تأییدکنندگان ارائه دهند.

شروع کنید

برای استفاده از Credential Holder API، وابستگی های زیر را به اسکریپت ساخت ماژول برنامه خود اضافه کنید:

// In your app module's build.gradle:
dependencies {
    implementation(libs.androidx.registry.provider)
    implementation(libs.androidx.registry.provider.play.services)
}

// In libs.versions.toml:
registryDigitalCredentials = "1.0.0-alpha01"

androidx-registry-provider = { module = "androidx.credentials.registry:registry-provider", version.ref = "registryDigitalCredentials" }
androidx-registry-provider-play-services = { module = "androidx.credentials.registry:registry-provider-play-services", version.ref = "registryDigitalCredentials" }

ثبت اعتبار با مدیر اعتبار

یک کیف پول باید ابرداده اعتبارنامه را ثبت کند تا مدیر اعتبار بتواند آنها را فیلتر کرده و در انتخاب کننده اعتبار زمانی که درخواستی وارد می شود، نمایش دهد.

تصویری که رابط کاربری اعتبار دیجیتال را در Credential Manager نشان می‌دهد
شکل 1. رابط کاربری اعتبار دیجیتال.

رابط کاربری انتخابگر مدیر اعتبار

قالب این ابرداده به یک RegisterCredentialsRequest منتقل می شود. یک [RegistryManager][1] ایجاد کنید و اعتبارنامه ها را ثبت کنید:

در این مثال، ابرداده از یک پایگاه داده از ورودی های اعتبار جمع آوری شده است. می توانید مرجعی را در کیف پول نمونه ما بیابید که ابرداده را در بارگذاری برنامه ثبت می کند. در آینده، ترکیب پایگاه داده اعتبار توسط API Jetpack پشتیبانی خواهد شد. در آن مرحله، می توانید ابرداده اعتبارنامه را به عنوان ساختارهای داده به خوبی تعریف شده ثبت کنید.

رجیستری در طول راه اندازی مجدد دستگاه باقی می ماند. ثبت مجدد همان رجیستری از همان ID + نوع رکورد قبلی رجیستری را بازنویسی می کند. بنابراین، تنها زمانی باید دوباره ثبت نام کنید که اطلاعات اعتبار شما تغییر کرده باشد.

اختیاری: یک تطبیق ایجاد کنید

مدیر اعتبار پروتکل آگونیست است. این رجیستری ابرداده را به عنوان یک لکه مات در نظر می گیرد و محتوای آن را تأیید یا بررسی نمی کند. بنابراین، کیف پول باید یک تطبیق، یک باینری قابل اجرا فراهم کند که می‌تواند داده‌های کیف پول را پردازش کند و متادیتای نمایشگر را بر اساس درخواست دریافتی تولید کند. Credential Manager تطبیق را در یک محیط sandbox بدون دسترسی به شبکه یا دیسک اجرا می کند، به طوری که قبل از رندر شدن رابط کاربری به کاربر، چیزی به کیف پول نشت نمی کند.

Credential Manager API تطبیق دهنده هایی را برای پروتکل های محبوب، امروز OpenID4VP، ارائه می دهد. هنوز به طور رسمی منتشر نشده است، بنابراین در حال حاضر از تطبیق نمونه ما برای پروتکل OpenID4VP v24 استفاده کنید.

یک اعتبار انتخاب شده را مدیریت کنید

در مرحله بعد، زمانی که یک اعتبار توسط کاربر انتخاب می شود، کیف پول باید رسیدگی کند. می‌توانید یک Activity تعریف کنید که به فیلتر هدف androidx.credentials.registry.provider.action.GET_CREDENTIAL گوش می‌دهد. کیف پول نمونه ما این روش را نشان می دهد .

هدفی که فعالیت را راه‌اندازی می‌کند حاوی درخواست Verifier و مبدا فراخوانی است که می‌تواند با تابع PendingIntentHandler.retrieveProviderGetCredentialRequest استخراج شود. API یک ProviderGetCredentialRequest حاوی تمام اطلاعات مرتبط با درخواست تأییدکننده داده شده را برمی گرداند. سه جزء کلیدی وجود دارد:

  • برنامه ای که درخواست را ارائه کرده است. می توانید این را با getCallingAppInfo بازیابی کنید.
  • اعتبار انتخاب شده شما می توانید اطلاعاتی در مورد نامزدی که کاربر انتخاب کرده است را از طریق روش افزونه selectedEntryId دریافت کنید. این با شناسه اعتباری که ثبت کرده اید مطابقت دارد.
  • هر درخواست خاصی که تأیید کننده ارائه کرده است. می توانید این را از روش getCredentialOptions دریافت کنید. در این مورد، باید انتظار داشته باشید که یک GetDigitalCredentialOption در این لیست پیدا کنید که حاوی درخواست Digital Credentials است.

معمولاً، تأیید کننده یک درخواست ارائه اعتبار دیجیتالی می‌کند تا بتوانید آن را با کد نمونه زیر پردازش کنید:

request.credentialOptions.forEach { option ->
    if (option is GetDigitalCredentialOption) {
        Log.i(TAG, "Got DC request: ${option.requestJson}")
        processRequest(option.requestJson)
    }
}

می توانید نمونه ای از این را در کیف پول نمونه ما مشاهده کنید.

رابط کاربری کیف پول را رندر کنید

پس از انتخاب اعتبار، کیف پول فراخوانی می شود و کاربر از طریق رابط کاربری آن هدایت می شود. در نمونه، این یک اعلان بیومتریک است.

پاسخ اعتبارنامه را برگردانید

هنگامی که کیف پول برای ارسال نتیجه آماده شد، می توانید این کار را با پایان دادن به فعالیت با پاسخ اعتبار انجام دهید:

PendingIntentHandler.setGetCredentialResponse(
    resultData,
    GetCredentialResponse(DigitalCredential(response.responseJson))
)
setResult(RESULT_OK, resultData)
finish()

اگر یک استثنا وجود دارد، می توانید به طور مشابه استثنای اعتبارنامه را ارسال کنید:

PendingIntentHandler.setGetCredentialException(
    resultData,
    GetCredentialUnknownException() // Configure the proper exception
)
setResult(RESULT_OK, resultData)
finish()

برای مثالی از نحوه بازگرداندن پاسخ اعتبارنامه در زمینه، به برنامه نمونه مراجعه کنید.