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

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

वर्शन के साथ काम करने की सुविधा

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

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

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

ध्यान दें: पासकी और रीस्टोर करने के लिए इस्तेमाल की जाने वाली कुंजियों के लिए, सर्वर-साइड पर लागू करने का तरीका एक जैसा होता है. हालांकि, आपका क्लाइंट-साइड ऐप्लिकेशन, पासकी की सुविधा के बिना भी रीस्टोर करने के लिए इस्तेमाल की जाने वाली कुंजियों का इस्तेमाल कर सकता है. ऐसा इसलिए है, क्योंकि रीस्टोर करने के लिए इस्तेमाल किए जाने वाले कोड, आपके ऐप्लिकेशन में पुष्टि करने के तरीके से अलग काम करते हैं. जैसे, पासवर्ड या'Google से साइन इन करें' सुविधा. इसलिए, आपको अपने ऐप्लिकेशन के कोड में, पुष्टि करने के मौजूदा तरीकों में कोई अतिरिक्त बदलाव करने की ज़रूरत नहीं है.

डिपेंडेंसी

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

Kotlin

dependencies {
    implementation("androidx.credentials:credentials:1.6.0-rc01")
    implementation("androidx.credentials:credentials-play-services-auth:1.6.0-rc01")
}

Groovy

dependencies {
    implementation "androidx.credentials:credentials:1.6.0-rc01"
    implementation "androidx.credentials:credentials-play-services-auth:1.6.0-rc01"
}

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

ध्यान दें: क्रेडेंशियल वापस लाने की सुविधा, इस बात से कोई फ़र्क़ नहीं पड़ता कि manifest में allowBackup सेट है या नहीं.

खास जानकारी

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

डेटा वापस लाने की कुंजी बनाना

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

ध्यान दें: रीस्टोर करने का पासकोड, ऐप्लिकेशन के यूनीक पैकेज के नाम से जुड़ा होता है. अगर आपके संगठन के मुख्य ऐप्लिकेशन और उप-ऐप्लिकेशन के पैकेज के नाम अलग-अलग हैं, तो हर ऐप्लिकेशन के लिए अलग-अलग रीस्टोर की बनाएं.

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

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

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

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

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

डेटा वापस लाने की कुंजी बनाना

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

val credentialManager = CredentialManager.create(context)

// On a successful authentication create a Restore Key
// Pass in the context and CreateRestoreCredentialRequest object
val response = credentialManager.createCredential(context, createRestoreRequest)

कोड के बारे में मुख्य बातें

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

  • requestJson: यह क्रेडेंशियल बनाने के विकल्पों के बारे में बताता है. इन्हें ऐप्लिकेशन सर्वर, Web Authentication API फ़ॉर्मैट में PublicKeyCredentialCreationOptionsJSON के लिए भेजता है.

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

    • true: (सुझाया गया) अगर उपयोगकर्ता ने Google Backup और एंड-टू-एंड एन्क्रिप्शन की सुविधा चालू की है, तो इस वैल्यू की मदद से क्लाउड पर बैकअप और रीस्टोर करने की कुंजियां सेव की जा सकती हैं. जैसे, स्क्रीन लॉक.
    • false: यह वैल्यू, कुंजी को स्थानीय तौर पर सेव करती है, न कि क्लाउड में. अगर उपयोगकर्ता क्लाउड से डेटा वापस लाने का विकल्प चुनता है, तो नई डिवाइस पर कुंजी उपलब्ध नहीं होगी.
  चेतावनी: हमारा सुझाव है कि isCloudBackupEnabled को true पर सेट करें. अगर क्लाउड बैकअप की सुविधा बंद है और उपयोगकर्ता क्लाउड बैकअप से डेटा वापस लाता है, तो डेटा वापस लाने की कुंजी को वापस पाने का अनुरोध पूरा नहीं होता. क्लाउड बैकअप की मदद से, आपके ऐप्लिकेशन को वापस लाने वाले उपयोगकर्ताओं को रीस्टोर करने की कुंजी नहीं मिलती. साथ ही, वे अपने-आप साइन इन नहीं होते.

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

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

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

कुंजी को वापस लाने की प्रोसेस के दौरान, इन अपवादों को मैनेज करें:

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

रिस्टोर करने की कुंजी की मदद से साइन इन करना

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

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

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

डेटा वापस लाने के लिए कुंजी पाना

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

इन स्थितियों में, वापस लाने का कोड पाया जा सकता है:

• (सुझाया गया) ऐप्लिकेशन का डेटा वापस लाए जाने के तुरंत बाद. अपने ऐप्लिकेशन के बैकअप को कॉन्फ़िगर करने के लिए, BackupAgent का इस्तेमाल करें. साथ ही, onRestore कॉलबैक में getCredential फ़ंक्शन को पूरा करें, ताकि ऐप्लिकेशन का डेटा वापस पाने के तुरंत बाद, ऐप्लिकेशन के क्रेडेंशियल वापस मिल जाएं. इससे, लोगों को पहली बार नया डिवाइस खोलने पर होने वाली संभावित देरी से बचाया जा सकता है. साथ ही, उन्हें आपका ऐप्लिकेशन खुलने का इंतज़ार किए बिना इंटरैक्ट करने की सुविधा मिलती है.
• डिवाइस पर पहली बार ऐप्लिकेशन लॉन्च करने पर.

किसी उपयोगकर्ता को नए डिवाइस पर पहली बार ऐप्लिकेशन खोलने से पहले सूचनाएं भेजने के लिए, BackupAgent के onRestore कॉलबैक में वापस लाने की कुंजी फ़ेच करें. यह खास तौर पर मैसेजिंग या बातचीत के ऐप्लिकेशन के लिए काम का है.

// Fetch the Authentication JSON from server
val authenticationJson = fetchAuthenticationJson()

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

// The restore key can be fetched in two scenarios to
// 1. On the first launch of app on the device, fetch the Restore Key
// 2. In the onRestore callback (if the app implements the Backup Agent)
val response = credentialManager.getCredential(context, getRequest)

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

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

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

ध्यान दें: रीस्टोर की और पासकी, दोनों एक ही सर्वर पर काम करती हैं. हालांकि, इन्हें अपने ऐप्लिकेशन सर्वर के डेटाबेस में सेव करते समय, दोनों के बीच अंतर करें. पासकी मैनेज करने वाला पेज मौजूद होने पर, यह अंतर बहुत ज़रूरी होता है. इसकी वजह यह है कि उपयोगकर्ता, खुद बनाई गई पासकी को सीधे तौर पर मैनेज कर सकते हैं. वहीं, पासकी को वापस लाने की कुंजियां, सिस्टम मैनेज करता है और उन्हें पासकी मैनेज करने वाले पेज पर नहीं दिखाया जाता.

डेटा वापस लाने की कुंजी मिटाना

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

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

कुंजियां वापस लाने की सुविधा सिर्फ़ इन स्थितियों में हटाई जाती है:

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

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

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

// On user log-out, clear the restore key
val response = credentialManager.clearCredentialState(clearRequest)