شماره تلفن را با اعتبار دیجیتال تأیید کنید

این راهنما نحوه استفاده از DigitalCredential API را برای به دست آوردن شماره تلفن تأیید شده برای کاربران خود شرح می دهد. فرآیند شامل دو مرحله است:

  1. درخواست TS.43 token : برنامه مشتری شما ("تأیید کننده") یک رمز موقت TS.43 از دستگاه کاربر درخواست می کند. TS.43 token یک اعتبارنامه صادر شده توسط حامل است که نشان دهنده هویت کاربر است.
  2. رمز را با شماره تلفن مبادله کنید : باطن برنامه شما TS.43 token با یک جمع‌آورنده یا حامل برای شماره تلفن تأیید شده کاربر مبادله می‌کند.

پیش نیازها

برای اجرای تأیید شماره تلفن با DigitalCredential API، به یک حساب کاربری با یک جمع‌کننده نیاز دارید. یک جمع‌کننده با حامل‌ها تعامل می‌کند و سطح API لازم را برای برنامه شما فراهم می‌کند، معمولاً به عنوان یک نقطه پایانی API ابری قابل پرداخت.

همچنین باید وابستگی های زیر را به اسکریپت ساخت Gradle خود اضافه کنید:

Kotlin

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

Groovy

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

پیاده سازی

فرآیند end-to-end به طور کلی مراحل زیر را دنبال می کند:

  1. درخواست پارامترهای DCQL (Digital Credential Query Language) از یک جمع کننده : یک یا چند جمع کننده را فراخوانی کنید و مجموعه ای از پارامترهای DCQL را درخواست کنید. 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 به جمع کننده ارسال کنید. تجمیع کننده اعتبارنامه را تأیید می کند و شماره تلفن تأیید شده را برمی گرداند.

تصویری که جریان درخواست تأیید شماره تلفن را نشان می دهد
شکل 1. طول عمر یک درخواست تأیید شماره تلفن، از قسمت Backend Verifier که پارامترها را از یک جمع‌کننده درخواست می‌کند شروع می‌شود و با یک شماره تلفن تأیید شده بازگشتی پایان می‌یابد.

درخواست پارامترهای DCQL از یک جمع کننده

از باطن برنامه‌تان، درخواستی برای یک شی اعتباری زبان اعتبار دیجیتال (DCQL) به جمع‌کننده ارسال کنید. مطمئن شوید که یک nonce و یک شناسه درخواست در درخواست خود وارد کنید. Aggregator شی اعتبار 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 در یک آرایه credentials تو در تو در یک شی dcql_query ایجاد کنید، همانطور که در مثال زیر نشان داده شده است:

"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 : یک مقدار منحصر به فرد ایجاد شده توسط باطن شما برای هر درخواست. nonce در شیء اعتبار جمع‌آوری کننده DCQL باید با این 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 تماس بگیرید

در برنامه مشتری خود، با درخواست DigitalCredential API که توسط باطن برنامه شما ارائه شده است، با Credential Manager 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 است. یک json اعتبار معمولی از نتیجه DigitalCredential به شرح زیر است:

{
  "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)