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. Credential Manager को इंस्टैंशिएट करना: एक 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)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

डेटा वापस लाने के लिए इस्तेमाल की जाने वाली कुंजी की मदद से साइन इन करना

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

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

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

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

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

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

  • डिवाइस पर पहली बार ऐप्लिकेशन लॉन्च करने पर. इस स्थिति में, क्रेडेंशियल वापस लाने की प्रोसेस, ऐप्लिकेशन का डेटा वापस लाने की प्रोसेस से अलग होती है.
  • अगर ऐप्लिकेशन के डेटा का बैकअप लेने और उसे वापस लाने की सुविधा चालू है, तो ऐप्लिकेशन का डेटा वापस लाने के तुरंत बाद, वापस लाने की कुंजी पाएं. अपने ऐप्लिकेशन के बैकअप को कॉन्फ़िगर करने के लिए, 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)