Credential Manager की मदद से, क्रेडेंशियल वापस लाने की सुविधा लागू करना

इस पेज पर, रीस्टोर पासकोड बनाने, उससे साइन इन करने, और उसे मिटाने का तरीका बताया गया है.

वर्शन की ज़रूरी शर्तें

क्रेडेंशियल मैनेजर की 'क्रेडेंशियल रीस्टोर करें' सुविधा, Android 9 और इसके बाद के वर्शन वाले डिवाइसों पर काम करती है. साथ ही, यह Google Play services (GMS) के कोर वर्शन 24220000 या इसके बाद के वर्शन और androidx.credentials लाइब्रेरी के वर्शन 1.5.0 या इसके बाद के वर्शन पर भी काम करती है.

ज़रूरी शर्तें

पासकी के सर्वर की तरह, रिलाइंग पार्टी सर्वर सेट अप करें. अगर आपने पासकी की मदद से पुष्टि करने के लिए पहले से कोई सर्वर सेट अप किया है, तो रीस्टोर पासकोड के लिए भी उसी सर्वर-साइड इंटिग्रेशन का इस्तेमाल करें.

डिपेंडेंसी

अपने ऐप्लिकेशन मॉड्यूल की build.gradle फ़ाइल में, ये डिपेंडेंसी जोड़ें:

Kotlin

dependencies {
    implementation("androidx.credentials:credentials:1.7.0-alpha02")
    implementation("androidx.credentials:credentials-play-services-auth:1.7.0-alpha02")
}

Groovy

dependencies {
    implementation "androidx.credentials:credentials:1.7.0-alpha02"
    implementation "androidx.credentials:credentials-play-services-auth:1.7.0-alpha02"
}

क्रेडेंशियल रीस्टोर करने की सुविधा, androidx.credentials लाइब्रेरी के वर्शन 1.5.0 और इसके बाद के वर्शन में उपलब्ध है. हालांकि, हमारा सुझाव है कि जहां तक हो सके, डिपेंडेंसी के सबसे नए और स्टेबल वर्शन का इस्तेमाल करें.

खास जानकारी

  1. रीस्टोर पासकोड बनाना: रीस्टोर पासकोड बनाने के लिए, यह तरीका अपनाएं:
    1. क्रेडेंशियल मैनेजर को इंस्टैंशिएट करना: CredentialManager ऑब्जेक्ट बनाएं.
    2. ऐप्लिकेशन सर्वर से क्रेडेंशियल बनाने के विकल्प पाना: अपने ऐप्लिकेशन सर्वर से, क्लाइंट ऐप्लिकेशन को वह जानकारी भेजें जिसकी मदद से रीस्टोर पासकोड बनाया जा सकता है.
    3. रीस्टोर पासकोड बनाना: अगर उपयोगकर्ता आपके ऐप्लिकेशन में साइन इन है, तो उसके खाते के लिए रीस्टोर पासकोड बनाएं.
    4. क्रेडेंशियल बनाने के जवाब को मैनेज करना: प्रोसेस करने के लिए, अपने क्लाइंट ऐप्लिकेशन से क्रेडेंशियल को अपने ऐप्लिकेशन सर्वर पर भेजें. साथ ही, किसी भी तरह की गड़बड़ी को मैनेज करें.
  2. रीस्टोर पासकोड से साइन इन करना: रीस्टोर पासकोड से साइन इन करने के लिए, यह तरीका अपनाएं:
    1. ऐप्लिकेशन सर्वर से क्रेडेंशियल वापस पाने के विकल्प पाना: अपने ऐप्लिकेशन सर्वर से, क्लाइंट ऐप्लिकेशन को वह जानकारी भेजें जिसकी मदद से रीस्टोर पासकोड वापस पाया जा सकता है.
    2. रीस्टोर पासकोड पाना: जब उपयोगकर्ता कोई नया डिवाइस सेट अप करता है, तो क्रेडेंशियल मैनेजर से रीस्टोर पासकोड का अनुरोध करें. इससे उपयोगकर्ता, कोई और जानकारी दिए बिना साइन इन कर सकता है.
    3. क्रेडेंशियल वापस पाने के जवाब को मैनेज करना: उपयोगकर्ता को साइन इन करने के लिए, क्लाइंट ऐप्लिकेशन से रीस्टोर पासकोड को ऐप्लिकेशन सर्वर पर भेजें.
  3. रीस्टोर पासकोड मिटाना.

रीस्टोर पासकोड बनाना

आपके ऐप्लिकेशन में, उपयोगकर्ता के साइन इन करने के सभी मामलों को शामिल किया जाना चाहिए. इससे यह पक्का किया जा सकेगा कि सक्रिय उपयोगकर्ताओं के लिए रीस्टोर पासकोड बनाया गया हो. इन स्थितियों में रीस्टोर पासकोड बनाएं:

  • अगर उपयोगकर्ता साइन इन है और उसके लिए रीस्टोर पासकोड पहले से नहीं बनाया गया है. जैसे, मुख्य Activity के लिए onCreate तरीके में.
  • जब उपयोगकर्ता साइन इन कर रहा हो या नए खाते के रजिस्ट्रेशन की प्रोसेस पूरी कर रहा हो.

परफ़ॉर्मेंस को ऑप्टिमाइज़ करने और हर बार लॉग इन करने पर, रीस्टोर क्रेडेंशियल बनाने या उसकी जांच करने से बचने के लिए, लोकल स्टोरेज में boolean फ़्लैग या क्रेडेंशियल बनाने का टाइमस्टैंप सेट करें. जैसे, has_synced_restore_credential. इससे यह ट्रैक किया जा सकेगा कि पासकोड पहले से बनाया गया है या नहीं.

क्रेडेंशियल मैनेजर को इंस्टैंशिएट करना

CredentialManager ऑब्जेक्ट को इंस्टैंशिएट करने के लिए, अपने ऐप्लिकेशन के गतिविधि के कॉन्टेक्स्ट का इस्तेमाल करें.

// Use your app or activity context to instantiate a client instance of
// CredentialManager.
private val credentialManager = CredentialManager.create(context)

अपने ऐप्लिकेशन सर्वर से क्रेडेंशियल बनाने के विकल्प पाना

अपने क्लाइंट ऐप्लिकेशन को रीस्टोर क्रेडेंशियल बनाने के लिए ज़रूरी जानकारी भेजने के लिए, अपने ऐप्लिकेशन सर्वर में फ़ाइडो के नियमों के मुताबिक काम करने वाली लाइब्रेरी का इस्तेमाल करें. जैसे, उपयोगकर्ता, ऐप्लिकेशन, और कॉन्फ़िगरेशन की अतिरिक्त प्रॉपर्टी के बारे में जानकारी. सर्वर-साइड इंटिग्रेशन के बारे में ज़्यादा जानकारी के लिए, सर्वर-साइड के लिए दिशा-निर्देश देखें.

रीस्टोर पासकोड बनाना

सर्वर से भेजे गए सार्वजनिक पासकोड बनाने के विकल्पों को पार्स करने के बाद, रीस्टोर पासकोड बनाएं. इसके लिए, इन विकल्पों को a CreateRestoreCredentialRequest ऑब्जेक्ट में रैप करें. इसके बाद, the createCredential() तरीके को the CredentialManager ऑब्जेक्ट के साथ कॉल करें.

// createRestoreRequest contains the details sent by the server 
val response = credentialManager.createCredential(context, createRestoreRequest)

कोड के बारे में अहम बातें

  • CreateRestoreCredentialRequest ऑब्जेक्ट में ये फ़ील्ड शामिल होते हैं:

    • requestJson: ऐप्लिकेशन सर्वर से भेजे गए क्रेडेंशियल बनाने के विकल्प. ये विकल्प, वेब ऑथेंटिकेशन एपीआई फ़ॉर्मैट में होते हैं PublicKeyCredentialCreationOptionsJSON.

    • isCloudBackupEnabled: Boolean फ़ील्ड. इससे यह तय किया जाता है कि रीस्टोर पासकोड का बैकअप क्लाउड पर लिया जाना चाहिए या नहीं. डिफ़ॉल्ट रूप से, इस फ़्लैग की वैल्यू true होती है. इस फ़ील्ड की ये वैल्यू होती हैं:

      • true: (सुझाया जाता है) अगर उपयोगकर्ता ने Google बैकअप और पूरी तरह सुरक्षित (E2EE) एन्क्रिप्ट करने की सुविधा चालू की है, तो इस वैल्यू से रीस्टोर पासकोड का बैकअप क्लाउड पर लिया जा सकता है. जैसे, स्क्रीन लॉक.
      • false: इस वैल्यू से पासकोड को लोकल तौर पर सेव किया जाता है, न कि क्लाउड पर. अगर उपयोगकर्ता क्लाउड से डेटा वापस पाने का विकल्प चुनता है, तो पासकोड नए डिवाइस पर उपलब्ध नहीं होता.

क्रेडेंशियल बनाने के जवाब को मैनेज करना

क्रेडेंशियल मैनेजर एपीआई, टाइप CreateRestoreCredentialResponse का जवाब दिखाता है. इस जवाब में, सार्वजनिक पासकोड क्रेडेंशियल के रजिस्ट्रेशन का जवाब JSON फ़ॉर्मैट में होता है.

अपने ऐप्लिकेशन से सार्वजनिक पासकोड को रिलाइंग पार्टी सर्वर पर भेजें. यह सार्वजनिक पासकोड, पासकी बनाते समय जनरेट किए गए सार्वजनिक पासकोड जैसा होता है. सर्वर पर पासकी बनाने की प्रोसेस को मैनेज करने के लिए इस्तेमाल किया गया कोड, रीस्टोर पासकोड बनाने की प्रोसेस को भी मैनेज कर सकता है. सर्वर-साइड इंटिग्रेशन के बारे में ज़्यादा जानकारी के लिए, पासकी के लिए दिशा-निर्देश देखें.

रीस्टोर पासकोड बनाने की प्रोसेस के दौरान, इन गड़बड़ियों को मैनेज करें:

  • CreateRestoreCredentialDomException: यह गड़बड़ी तब होती है, जब requestJson अमान्य होता है और PublicKeyCredentialCreationOptionsJSON के लिए, WebAuthn फ़ॉर्मैट के मुताबिक नहीं होता.
  • E2eeUnavailableException: यह गड़बड़ी तब होती है, जब isCloudBackupEnabled की वैल्यू true होती है, लेकिन उपयोगकर्ता के डिवाइस में डेटा बैकअप या पूरी तरह सुरक्षित (E2EE) एन्क्रिप्ट करने की सुविधा नहीं होती. जैसे, स्क्रीन लॉक.
    यह पक्का करने के लिए कि रीस्टोर क्रेडेंशियल हर मामले में बनाए जाएं, आपको E2eeUnavailableException को साफ़ तौर पर मैनेज करना होगा. इसके लिए, isCloudBackupEnabled को true पर सेट करके, createCredential को कॉल करें. अगर E2eeUnavailableException गड़बड़ी होती है, तो इसे पकड़ें और isCloudBackupEnabled को false पर सेट करके, createCredential को फिर से कॉल करें.
  • IllegalArgumentException: यह गड़बड़ी तब होती है, जब createRestoreRequest खाली हो या मान्य JSON न हो. इसके अलावा, यह गड़बड़ी तब भी होती है, जब इसमें WebAuthn की खास जानकारी के मुताबिक, मान्य user.id न हो.

रीस्टोर पासकोड से साइन इन करना

डिवाइस सेट अप करने की प्रोसेस के दौरान, उपयोगकर्ता को चुपचाप साइन इन करने के लिए, क्रेडेंशियल रीस्टोर करने की सुविधा का इस्तेमाल करें.

ऐप्लिकेशन सर्वर से क्रेडेंशियल वापस पाने के विकल्प पाना

सर्वर से रीस्टोर पासकोड पाने के लिए, क्लाइंट ऐप्लिकेशन को ज़रूरी विकल्प भेजें. इस चरण के लिए, पासकी के बारे में इसी तरह के दिशा-निर्देश पाने के लिए, पासकी से साइन इन करना देखें. सर्वर-साइड इंटिग्रेशन के बारे में ज़्यादा जानकारी के लिए, सर्वर-साइड ऑथेंटिकेशन गाइड देखें.

रीस्टोर पासकोड पाना

नए डिवाइस पर रीस्टोर पासकोड पाने के लिए, CredentialManager ऑब्जेक्ट पर getCredential() तरीके को कॉल करें.

हमारा सुझाव है कि इन दोनों स्थितियों में रीस्टोर पासकोड फ़ेच करें:

  • डिवाइस पर ऐप्लिकेशन को पहली बार लॉन्च करने पर. इस स्थिति में, क्रेडेंशियल रीस्टोर करने की प्रोसेस, ऐप्लिकेशन का डेटा रीस्टोर करने की प्रोसेस से अलग होती है.
  • अगर ऐप्लिकेशन का डेटा बैकअप लेने और उसे रीस्टोर करने की सुविधा चालू है, तो ऐप्लिकेशन का डेटा रीस्टोर होने के तुरंत बाद, रीस्टोर पासकोड पाएं. अपने ऐप्लिकेशन के बैकअप को कॉन्फ़िगर करने के लिए, BackupAgent का इस्तेमाल करें. साथ ही, पक्का करें कि आपने onRestoreFinished कॉलबैक में, getCredential फ़ंक्शनैलिटी पूरी कर ली हो. onRestore तरीके का इस्तेमाल न करें, क्योंकि इसे सिर्फ़ की-वैल्यू बैकअप के लिए कॉल किया जाता है. वहीं, onRestoreFinished को किसी भी तरह के बैकअप रीस्टोर के लिए कॉल किया जाता है. इससे, उपयोगकर्ताओं के नए डिवाइस को पहली बार खोलने पर होने वाली संभावित देरी से बचा जा सकता है. साथ ही, उपयोगकर्ता आपके ऐप्लिकेशन को खुलने का इंतज़ार किए बिना, उससे इंटरैक्ट कर सकते हैं. उदाहरण के लिए, इससे आपका ऐप्लिकेशन, उपयोगकर्ता को नए डिवाइस पर पहली बार ऐप्लिकेशन खोलने से पहले सूचनाएं भेज सकता है. यह सुविधा, मैसेजिंग या कम्यूनिकेशन ऐप्लिकेशन के लिए खास तौर पर काम की है.
// Fetch the options required to get the restore key
val authenticationJson = fetchAuthenticationJson()

// Create the GetRestoreCredentialRequest object
val options = GetRestoreCredentialOption(authenticationJson)
val getRequest = GetCredentialRequest(listOf(options))

val response = credentialManager.getCredential(context, getRequest)

// Type-check and extract the restore credential
val credential = response.credential as RestoreCredential

क्रेडेंशियल मैनेजर एपीआई, टाइप GetCredentialResponse का जवाब दिखाता है. इस जवाब में मौजूद क्रेडेंशियल, साफ़ तौर पर RestoreCredential टाइप का होता है. इसमें सार्वजनिक पासकोड होता है.

साइन-इन के जवाब को मैनेज करना

ऐप्लिकेशन से सार्वजनिक पासकोड को रिलाइंग पार्टी सर्वर पर भेजें. इसका इस्तेमाल उपयोगकर्ता को साइन इन करने के लिए किया जा सकता है. सर्वर साइड पर, यह कार्रवाई पासकी का इस्तेमाल करके साइन इन करने जैसी होती है. सर्वर पर पासकी की मदद से साइन इन करने की प्रोसेस को मैनेज करने के लिए इस्तेमाल किया गया कोड, रीस्टोर पासकोड की मदद से साइन इन करने की प्रोसेस को भी मैनेज कर सकता है. पासकी के लिए सर्वर-साइड इंटिग्रेशन के बारे में ज़्यादा जानकारी के लिए, पासकी से साइन इन करना देखें.

रीस्टोर पासकोड मिटाना

क्रेडेंशियल मैनेजर, स्टेटलेस होता है. साथ ही, इसे उपयोगकर्ता की गतिविधि के बारे में जानकारी नहीं होती. इसलिए, यह इस्तेमाल के बाद रीस्टोर पासकोड को अपने-आप नहीं मिटाता. रीस्टोर पासकोड मिटाने के लिए, clearCredentialState() तरीके को कॉल करें. सुरक्षा के लिए, जब भी कोई उपयोगकर्ता साइन आउट करता है, तो पासकोड मिटा दें. इससे यह पक्का किया जा सकेगा कि अगली बार जब उपयोगकर्ता उसी डिवाइस पर ऐप्लिकेशन खोलेगा, तो वह साइन आउट होगा. साथ ही, उसे फिर से साइन इन करने के लिए कहा जाएगा.

किसी ऐप्लिकेशन को अनइंस्टॉल करने का मतलब है कि उपयोगकर्ता उस डिवाइस से, उससे जुड़े रीस्टोर पासकोड को मिटाना चाहता है. यह उपयोगकर्ता के साइन आउट करने के इरादे जैसा ही है.

रीस्टोर पासकोड सिर्फ़ इन स्थितियों में हटाए जाते हैं:

  • सिस्टम-लेवल की कार्रवाइयां: उपयोगकर्ता ऐप्लिकेशन को अनइंस्टॉल करता है या उसका डेटा मिटाता है.
  • ऐप्लिकेशन-लेवल के कॉल: अपने ऐप्लिकेशन के कोड में, उपयोगकर्ता के साइन आउट करने की प्रोसेस को मैनेज करते समय, clearCredentialState() को कॉल करके, पासकोड को प्रोग्राम के ज़रिए मिटाएं.

जब उपयोगकर्ता आपके ऐप्लिकेशन से साइन आउट करता है, तो CredentialManager ऑब्जेक्ट पर clearCredentialState() तरीके को कॉल करें.

// Create a ClearCredentialStateRequest object
val clearRequest = ClearCredentialStateRequest(TYPE_CLEAR_RESTORE_CREDENTIAL)

// When the user logs out, delete the restore key
val response = credentialManager.clearCredentialState(clearRequest)