डिजिटल क्रेडेंशियल की मदद से फ़ोन नंबरों की पुष्टि करना

इस गाइड में, DigitalCredential API का इस्तेमाल करके, अपने उपयोगकर्ताओं के लिए पुष्टि किए गए फ़ोन नंबर पाने का तरीका बताया गया है. इस प्रोसेस में दो चरण शामिल हैं:

  1. TS.43 token का अनुरोध करना: आपका क्लाइंट ऐप्लिकेशन ("पुष्टि करने वाला"), उपयोगकर्ता के डिवाइस से कुछ समय के लिए TS.43 टोकन का अनुरोध करता है. TS.43 token, मोबाइल और इंटरनेट सेवा देने वाली कंपनी की ओर से जारी किया गया क्रेडेंशियल है. इससे उपयोगकर्ता की पहचान की पुष्टि होती है.
  2. टोकन को फ़ोन नंबर के लिए एक्सचेंज करना: आपके ऐप्लिकेशन का बैकएंड, उपयोगकर्ता के पुष्टि किए गए फ़ोन नंबर के लिए, एग्रीगेटर या कैरियर के साथ TS.43 token को एक्सचेंज करता है.

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

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

आपको अपनी Gradle बिल्ड स्क्रिप्ट में, यहां दी गई डिपेंडेंसी भी जोड़नी होंगी:

Kotlin

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

ग्रूवी

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

लागू करना

आम तौर पर, पूरी प्रोसेस में ये चरण शामिल होते हैं:

  1. एग्रीगेटर से डीसीक्यूएल (डिजिटल क्रेडेंशियल क्वेरी लैंग्वेज) पैरामीटर का अनुरोध करें: एक या उससे ज़्यादा एग्रीगेटर को कॉल करें और डीसीक्यूएल पैरामीटर के सेट का अनुरोध करें. DCQL की मदद से, हर एग्रीगेटर से आपको मिलने वाले डिजिटल क्रेडेंशियल के बारे में सटीक जानकारी दी जा सकती है.

  2. OpenID4VP अनुरोध बनाएं: अपने ऐप्लिकेशन के बैकएंड से, OpenID4VP अनुरोध बनाएं. साथ ही, इसमें एग्रीगेटर से मिले DCQL पैरामीटर शामिल करें. इसके बाद, OpenID4VP अनुरोध को अपने क्लाइंट ऐप्लिकेशन पर भेजें.

  3. Credential Manager API को कॉल करें: अपने क्लाइंट ऐप्लिकेशन में, Credential Manager API का इस्तेमाल करके, ऑपरेटिंग सिस्टम को OpenID4VP अनुरोध भेजें. इसके जवाब में, आपको OpenID4VP रिस्पॉन्स ऑब्जेक्ट मिलता है. इसमें TS.43 Digital Credential शामिल होता है. इस क्रेडेंशियल को एन्क्रिप्ट (सुरक्षित) किया जाता है. इसे सिर्फ़ उससे जुड़ा एग्रीगेटर डिक्रिप्ट (सुरक्षित तरीके से बदलना) कर सकता है. कैरियर टोकन मिलने के बाद, अपने क्लाइंट ऐप्लिकेशन से ऐप्लिकेशन के बैकएंड को जवाब भेजें.

  4. जवाब की पुष्टि करें: अपने ऐप्लिकेशन के बैकएंड में, OpenID4VP के जवाब की पुष्टि करें.

  5. फ़ोन नंबर के बदले में TS.43 Digital Credential: अपने ऐप्लिकेशन के बैकएंड से, एग्रीगेटर को TS.43 Digital Credential भेजें. एग्रीगेटर, क्रेडेंशियल की पुष्टि करता है और पुष्टि किया गया फ़ोन नंबर दिखाता है.

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

एग्रीगेटर से DCQL पैरामीटर का अनुरोध करना

अपने ऐप्लिकेशन के बैकएंड से, एग्रीगेटर को Digital Credential Query Language (DCQL) क्रेडेंशियल ऑब्जेक्ट का अनुरोध भेजें. अपने अनुरोध में, नॉन्स और अनुरोध आईडी ज़रूर दें. एग्रीगेटर, DCQL क्रेडेंशियल ऑब्जेक्ट दिखाता है. इसका स्ट्रक्चर इस तरह का होता है:

{
  // The credential ID is mapped to the request ID that is sent in your request to the aggregator.
  "id": "aggregator1",
  "format": "dc-authorization+sd-jwt",
  "meta": {
    "vct_values": [
      "number-verification/device-phone-number/ts43"
    ],
    "credential_authorization_jwt": "..."
  },
  "claims": [
    {
      "path": ["subscription_hint"],
      "values": [1]
    },
    {
      "path": ["phone_number_hint"],
      "values": ["+14155552671"]
    }
  ]
}

OpenID4VP अनुरोध बनाना

सबसे पहले, अपने ऐप्लिकेशन के बैकएंड से dcql_query ऑब्जेक्ट बनाएं. इसके लिए, DCQL क्रेडेंशियल ऑब्जेक्ट को dcql_query ऑब्जेक्ट में नेस्ट की गई credentials ऐरे में रखें. यहां दिए गए उदाहरण में इसे दिखाया गया है:

"dcql_query": {
  "credentials": [
      "id": "aggregator1",
      "format": "dc-authorization+sd-jwt",
      "meta": {
        "vct_values": [
          "number-verification/device-phone-number/ts43"
        ],
        "credential_authorization_jwt": "..."
      },
      "claims": [
        {
          "path": ["subscription_hint"],
          "values": [1]
        },
        {
          "path": ["phone_number_hint"],
          "values": ["+14155552671"]
        }
      ]
  ]
}

इसके बाद, इस स्ट्रक्चर के साथ OpenID4VP अनुरोध बनाएं:

{
  "protocol": "openid4vp-v1-unsigned",
  "data": {
    "response_type": "vp_token",
    "response_mode": "dc_api",
    "nonce": "...",
    "dcql_query": { ... }
  }
}
  • protocol: फ़ोन नंबर की पुष्टि करने के अनुरोधों के लिए, इसे openid4vp-v1-unsigned पर सेट करना ज़रूरी है.
  • response_type और response_mode: ये ऐसे कॉन्स्टेंट हैं जो अनुरोध के फ़ॉर्मैट को दिखाते हैं. इनकी वैल्यू vp_token और dc_api होती है.
  • nonce: यह एक यूनीक वैल्यू है. इसे आपका बैकएंड, हर अनुरोध के लिए जनरेट करता है. एग्रीगेटर के डीसीक्यूएल क्रेडेंशियल ऑब्जेक्ट में मौजूद नॉन्स, इस नॉन्स से मेल खाना चाहिए.
  • dcql_query: इस मामले में, dcql_query का इस्तेमाल करके यह बताएं कि TS.43 Digital Credential का अनुरोध किया जा रहा है. यहां अन्य डिजिटल क्रेडेंशियल का अनुरोध भी किया जा सकता है.

इसके बाद, OpenID4VP अनुरोध को DigitalCredential API अनुरोध ऑब्जेक्ट में रैप करें और उसे क्लाइंट ऐप्लिकेशन को भेजें.

{
  "requests":
    [
      {
        "protocol": "openid4vp-v1-unsigned",
        "data": {
          "response_type": "vp_token",
          "response_mode": "dc_api",
          "nonce": "...",
          "dcql_query": { ... }
        }
      }
    ]
}

यहां दिए गए स्निपेट में, DigitalCredential API का अनुरोध जनरेट करने का तरीका बताया गया है:

def GenerateDCRequest():
    credentials = []
    aggregator1_dcql = call_aggregator_endpoint(nonce, "aggregator1", additional_params)
    credentials.append(aggregator1_dcql) # You can optionally work with multiple
    # aggregators, or request other types of credentials

    val dc_request =
    {
      "requests":
        [
          {
            "protocol": "openid4vp-v1-unsigned",
            "data": {
              "response_type": "vp_token",
              "response_mode": "dc_api",
              "nonce": "...",
              "dcql_query": {"credentials": credentials}
            }
          }
        ]
    }
    return dc_request

Credential Manager API को कॉल करना

अपने क्लाइंट ऐप्लिकेशन में, Credential Manager API को कॉल करें. इसके लिए, अपने ऐप्लिकेशन के बैकएंड से मिले DigitalCredential API अनुरोध का इस्तेमाल करें.

val requestJson = generateTs43DigitalCredentialRequestFromServer()
val digiCredOption = GetDigitalCredentialOption(requestJson = requestJson)
val getCredRequest = GetCredentialRequest(
    listOf(digiCredOption)
)

coroutineScope.launch {
  try {
    val response = credentialManager.getCredential(
      context = activityContext,
      request = getCredRequest
    )
    val credential = response.credential
    when (credential) {
      is DigitalCredential -> {
        val responseJson = credential.credentialJson
        validateResponseOnServer(responseJson)
      }
      else -> {
        // Catch any unrecognized credential type here.
        Log.e(TAG, "Unexpected type of credential ${credential.type}")
      }
    }
  } catch (e : GetCredentialException) {
      // If user cancels the operation, the feature isn't available, or the
      // SIM doesn't support the feature, a GetCredentialCancellationException
      // will be returned. Otherwise, a GetCredentialUnsupportedException will
      // be returned with details in the exception message.
      handleFailure(e)
  }
}

DigitalCredential API के रिस्पॉन्स में, OpenID4VP का रिस्पॉन्स शामिल होता है. DigitalCredential के नतीजे से मिला एक सामान्य क्रेडेंशियल JSON यहां दिया गया है:

{
  "protocol": "openid4vp-v1-unsigned",

  "data": {
    "vp_token": {
      "aggregator1": ["eyJhbGciOiAiRVMy..."] # The encrypted TS.43 Digital
                                             # Credential in an array structure.
    }
  }
}

अपने क्लाइंट ऐप्लिकेशन से, DigitalCredential API के रिस्पॉन्स को बैकएंड सर्वर पर वापस भेजें. यहां इसकी पुष्टि की जा सकती है. साथ ही, इसका इस्तेमाल एग्रीगेटर के साथ पुष्टि किए गए फ़ोन नंबर को एक्सचेंज करने के लिए किया जा सकता है.

डिजिटल क्रेडेंशियल के जवाब की पुष्टि करना

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

def processDigitalCredentialsResponse(response):
  # Step 1: Parse out the TS.43 Digital Credential from the response
  openId4VpResponse = response['data']

  ts43_digital_credential = response['vp_token']["aggregator1"][0]

  # Step 2: Perform response validation
  verifyResponse(ts43_digital_credential)

def verifyResponse(ts43_digital_credential):
  # The returned ts43_digital_credential is an SD-JWT-based Verifiable Credentials
  # (SD-JWT VC) as defined in this IETF spec. The section 3.4 of the specification
  # outlines how to validate the credential. At a high level, the steps involves
  # validating (1) the nonce in the response credential matches the one in the
  # request, (2) the integrity of the credential by checking the credential is
  # signed by the trusted issuer Android Telephony, and (3) other validity
  # properties associated with this credential, such as issue time and expiration
  # time

  # In most cases, you can use an SD-JWT VC library to perform these validations.

  # Some aggregators may also perform the validation logic for you. Check with your
  # aggregator to decide the exact scope of the validation required.

फ़ोन नंबर के लिए एक्सचेंज

अपने ऐप्लिकेशन के बैकएंड से, पुष्टि किया गया TS.43 Digital Credential, एग्रीगेटर के एंडपॉइंट पर भेजें. इससे क्रेडेंशियल की पुष्टि की जा सकेगी और पुष्टि किया गया फ़ोन नंबर मिल सकेगा.

def processDigitalCredentialsResponse(response):
  # ... prior steps

  # Step 3: Call aggregator endpoint to exchange the verified phone number
  callAggregatorPnvEndpoint(ts43_digital_credential)