ลงชื่อเข้าใช้ผู้ใช้ด้วยตัวจัดการข้อมูลเข้าสู่ระบบ

Credential Manager เป็น Jetpack API ที่รองรับวิธีการลงชื่อเข้าใช้หลายวิธี เช่น ชื่อผู้ใช้และรหัสผ่าน พาสคีย์ และโซลูชันการลงชื่อเข้าใช้แบบรวมศูนย์ (เช่น ฟีเจอร์ลงชื่อเข้าใช้ด้วย Google) ใน API เดียว ซึ่งช่วยให้นักพัฒนาแอปผสานรวมได้ง่ายขึ้น

นอกจากนี้ Credential Manager ยังรวบรวมอินเทอร์เฟซการลงชื่อเข้าใช้ต่างๆ เข้าด้วยกัน ทั้งวิธีการตรวจสอบสิทธิ์ต่างๆ เพื่อให้การลงชื่อเข้าใช้แอปชัดเจนและง่ายขึ้น ไม่ว่าผู้ใช้จะเลือกวิธีการใดก็ตาม

หน้านี้อธิบายแนวคิดของพาสคีย์และขั้นตอนในการใช้งานการสนับสนุนฝั่งไคลเอ็นต์สำหรับโซลูชันการตรวจสอบสิทธิ์ ซึ่งรวมถึงพาสคีย์ โดยใช้ Credential Manager API นอกจากนี้ยังมีหน้าคำถามที่พบบ่อยแยกต่างหากซึ่งให้คำตอบสำหรับคำถามที่เฉพาะเจาะจงและละเอียดยิ่งขึ้น

เกี่ยวกับพาสคีย์

พาสคีย์เป็นทางเลือกที่ปลอดภัยกว่าและใช้งานง่ายกว่าเมื่อเทียบกับรหัสผ่าน เมื่อใช้พาสคีย์ ผู้ใช้จะลงชื่อเข้าใช้แอปและเว็บไซต์ได้โดยใช้เซ็นเซอร์ข้อมูลไบโอเมตริก (เช่น การจดจำลายนิ้วมือหรือใบหน้า), PIN หรือรูปแบบ ซึ่งจะช่วยให้ผู้ใช้ลงชื่อเข้าใช้ได้อย่างราบรื่นโดยไม่ต้องจดจำชื่อผู้ใช้หรือรหัสผ่าน

พาสคีย์ใช้ WebAuthn (การตรวจสอบสิทธิ์ผ่านเว็บ) ซึ่งเป็นมาตรฐานที่ FIDO Alliance และ World Wide Web Consortium (W3C) พัฒนาร่วมกัน WebAuthn ใช้วิทยาการเข้ารหัสคีย์สาธารณะเพื่อตรวจสอบสิทธิ์ผู้ใช้ เว็บไซต์หรือแอปที่ผู้ใช้ลงชื่อเข้าใช้จะเห็นและจัดเก็บคีย์สาธารณะได้ แต่จะไม่เห็นคีย์ส่วนตัว คีย์ส่วนตัวจะเก็บไว้เป็นความลับและปลอดภัย และเนื่องจากพาสคีย์เป็นคีย์ที่ไม่ซ้ำกันและเชื่อมโยงกับเว็บไซต์หรือแอป จึงไม่สามารถฟิชชิงได้ ซึ่งช่วยเพิ่มความปลอดภัยอีกขั้น

เครื่องมือจัดการข้อมูลเข้าสู่ระบบช่วยให้ผู้ใช้สร้างพาสคีย์และจัดเก็บไว้ในเครื่องมือจัดการรหัสผ่านบน Google ได้

อ่านการตรวจสอบสิทธิ์ผู้ใช้ด้วยพาสคีย์เพื่อดูคำแนะนำเกี่ยวกับวิธีใช้ขั้นตอนการตรวจสอบสิทธิ์ด้วยพาสคีย์อย่างราบรื่นด้วยเครื่องมือจัดการข้อมูลเข้าสู่ระบบ

สิ่งที่ต้องมีก่อน

หากต้องการใช้เครื่องมือจัดการข้อมูลเข้าสู่ระบบ ให้ทำตามขั้นตอนในส่วนนี้

ใช้แพลตฟอร์มเวอร์ชันล่าสุด

เครื่องมือจัดการข้อมูลเข้าสู่ระบบใช้ได้ใน Android 4.4 (API ระดับ 19) ขึ้นไป

เพิ่มการพึ่งพาไปยังแอป

เพิ่มการพึ่งพาต่อไปนี้ลงในสคริปต์บิลด์ของโมดูลแอป

implementation(libs.androidx.credentials)

// optional - needed for credentials support from play services, for devices running
// Android 13 and below.
implementation(libs.androidx.credentials.play.services.auth)

ดูข้อมูลเพิ่มเติมเกี่ยวกับวิธีลดขนาด สร้างความสับสน และเพิ่มประสิทธิภาพแอป

เพิ่มการรองรับลิงก์เนื้อหาดิจิทัล

หากต้องการเปิดใช้การรองรับพาสคีย์สําหรับแอป Android ให้เชื่อมโยงแอปกับเว็บไซต์ที่แอปเป็นเจ้าของ คุณสามารถประกาศการเชื่อมโยงนี้ได้โดยทำตามขั้นตอนต่อไปนี้

  1. สร้างไฟล์ JSON ของลิงก์เนื้อหาดิจิทัล (Digital Asset Links) ตัวอย่างเช่น หากต้องการประกาศว่าเว็บไซต์ https://signin.example.com และแอป Android ที่มีชื่อแพ็กเกจ com.example สามารถแชร์ข้อมูลเข้าสู่ระบบ ให้สร้างไฟล์ชื่อ assetlinks.json ที่มีเนื้อหาดังต่อไปนี้

    [
  {
    "relation" : [
      "delegate_permission/common.handle_all_urls",
      "delegate_permission/common.get_login_creds"
    ],
    "target" : {
      "namespace" : "android_app",
      "package_name" : "com.example.android",
      "sha256_cert_fingerprints" : [
        SHA_HEX_VALUE
      ]
    }
  }
]

    ช่อง relation คืออาร์เรย์สตริงอย่างน้อย 1 รายการที่อธิบายความสัมพันธ์ที่ประกาศ หากต้องการประกาศว่าแอปและเว็บไซต์ใช้ข้อมูลเข้าสู่ระบบร่วมกัน ให้ระบุความสัมพันธ์เป็น delegate_permission/handle_all_urls และ delegate_permission/common.get_login_creds

    ฟิลด์ target คือออบเจ็กต์ที่ระบุเนื้อหาที่ใช้ประกาศ ฟิลด์ต่อไปนี้จะระบุเว็บไซต์

    namespace web
    site

    URL ของเว็บไซต์ในรูปแบบ https://domain[:optional_port] เช่น https://www.example.com

    domain ต้องระบุอย่างเต็มรูปแบบ และจะต้องไม่ใส่ optional_port เมื่อใช้พอร์ต 443 สําหรับ HTTPS

    เป้าหมาย site ต้องเป็นโดเมนรูทเท่านั้น คุณไม่สามารถจํากัดการเชื่อมโยงแอปกับไดเรกทอรีย่อยที่เฉพาะเจาะจงได้ อย่าใส่เส้นทางใน URL เช่น เครื่องหมายทับต่อท้าย

    ระบบจะไม่ถือว่าโดเมนย่อยตรงกัน กล่าวคือ หากคุณระบุ domain เป็น www.example.com โดเมน www.counter.example.com จะไม่เชื่อมโยงกับแอปของคุณ

    ฟิลด์ต่อไปนี้จะระบุแอป Android

    namespace android_app
    package_name ชื่อแพ็กเกจที่ประกาศในไฟล์ Manifest ของแอป เช่น com.example.android
    sha256_cert_fingerprints ลายนิ้วมือ SHA256 ของใบรับรองการลงนามของแอป

  2. โฮสต์ไฟล์ JSON ของลิงก์เนื้อหาดิจิทัล (Digital Asset Links) ในตำแหน่งต่อไปนี้ในโดเมนการลงชื่อเข้าใช้

    https://domain[:optional_port]/.well-known/assetlinks.json

    เช่น หากโดเมนการลงชื่อเข้าใช้คือ signin.example.com ให้โฮสต์ไฟล์ JSON ที่ https://signin.example.com/.well-known/assetlinks.json

    ประเภท MIME ของไฟล์ลิงก์เนื้อหาดิจิทัล (Digital Asset Links) ต้องเป็น JSON ยืนยันว่าเซิร์ฟเวอร์ส่งส่วนหัว Content-Type: application/json ในการตอบกลับ

  3. ยืนยันว่าโฮสต์ของคุณอนุญาตให้ Google ดึงข้อมูลไฟล์ลิงก์เนื้อหาดิจิทัล (Digital Asset Links) หากคุณมีไฟล์ robots.txt ไฟล์ดังกล่าวต้องอนุญาตให้ตัวแทน Googlebot ดึงข้อมูล /.well-known/assetlinks.json เว็บไซต์ส่วนใหญ่อนุญาตให้ตัวแทนอัตโนมัติดึงข้อมูลไฟล์ในเส้นทาง /.well-known/ เพื่อให้บริการอื่นๆ เข้าถึงข้อมูลเมตาในไฟล์เหล่านั้นได้ โดยทำดังนี้

    User-agent: *
Allow: /.well-known/

  4. เพิ่มบรรทัดต่อไปนี้ลงในไฟล์ Manifest ในส่วน <application>

    <meta-data android:name="asset_statements" android:resource="@string/asset_statements" />

  5. หากคุณใช้การลงชื่อเข้าใช้ด้วยรหัสผ่านผ่านเครื่องมือจัดการข้อมูลเข้าสู่ระบบ ให้ทําตามขั้นตอนนี้เพื่อกําหนดค่าการลิงก์ชิ้นงานดิจิทัลในไฟล์ Manifest ขั้นตอนนี้ไม่จําเป็นหากคุณใช้พาสคีย์เท่านั้น

    ประกาศการเชื่อมโยงในแอป Android เพิ่มออบเจ็กต์ที่ระบุไฟล์ assetlinks.json ที่จะโหลด คุณต้องหลีกเครื่องหมายคำพูดเดี่ยวและเครื่องหมายคำพูดที่ใช้ในสตริง เช่น

    <string name="asset_statements" translatable="false">
[{
  \"include\": \"https://signin.example.com/.well-known/assetlinks.json\"
}]
</string>

    > GET /.well-known/assetlinks.json HTTP/1.1
> User-Agent: curl/7.35.0
> Host: signin.example.com

< HTTP/1.1 200 OK
< Content-Type: application/json

กำหนดค่าเครื่องมือจัดการข้อมูลเข้าสู่ระบบ

หากต้องการกําหนดค่าและเริ่มต้นวัตถุ CredentialManager ให้เพิ่มตรรกะคล้ายกับตัวอย่างต่อไปนี้

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

ระบุช่องข้อมูลเข้าสู่ระบบ

ใน Android 14 ขึ้นไป คุณสามารถใช้แอตทริบิวต์ isCredential เพื่อระบุช่องข้อมูลเข้าสู่ระบบ เช่น ช่องชื่อผู้ใช้หรือรหัสผ่าน แอตทริบิวต์นี้บ่งชี้ว่ามุมมองนี้เป็นช่องข้อมูลเข้าสู่ระบบที่มีไว้เพื่อทำงานร่วมกับเครื่องมือจัดการข้อมูลเข้าสู่ระบบและผู้ให้บริการข้อมูลเข้าสู่ระบบบุคคลที่สาม ขณะเดียวกันก็ช่วยให้บริการป้อนข้อความอัตโนมัติแสดงคำแนะนำการป้อนข้อความอัตโนมัติที่ดีขึ้น เมื่อแอปใช้ Credential Manager API ระบบจะแสดงชีตด้านล่างของเครื่องมือจัดการข้อมูลเข้าสู่ระบบที่มีข้อมูลเข้าสู่ระบบพร้อมใช้งาน และคุณไม่จําเป็นต้องแสดงกล่องโต้ตอบการกรอกข้อความอัตโนมัติสําหรับชื่อผู้ใช้หรือรหัสผ่านอีก ในทํานองเดียวกัน คุณไม่จําเป็นต้องแสดงกล่องโต้ตอบบันทึกของฟีเจอร์ป้อนข้อความอัตโนมัติสําหรับรหัสผ่าน เนื่องจากแอปจะขอ Credential Manager API เพื่อบันทึกข้อมูลเข้าสู่ระบบ

หากต้องการใช้แอตทริบิวต์ isCredential ให้เพิ่มแอตทริบิวต์นั้นลงในข้อมูลพร็อพเพอร์ตี้ที่เกี่ยวข้อง ดังนี้

<TextView
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:isCredential="true" />

ลงชื่อเข้าใช้ผู้ใช้

หากต้องการเรียกข้อมูลพาสคีย์และตัวเลือกรหัสผ่านทั้งหมดที่เชื่อมโยงกับบัญชีของผู้ใช้ ให้ทำตามขั้นตอนต่อไปนี้

  1. เริ่มต้นตัวเลือกการตรวจสอบสิทธิ์ด้วยรหัสผ่านและพาสคีย์ ดังนี้

    // Retrieves the user's saved password for your app from their
// password provider.
val getPasswordOption = GetPasswordOption()

// Get passkey from the user's public key credential provider.
val getPublicKeyCredentialOption = GetPublicKeyCredentialOption(
  requestJson = requestJson
)

  2. ใช้ตัวเลือกที่ดึงมาจากขั้นตอนก่อนหน้าเพื่อสร้างคำขอลงชื่อเข้าใช้

    val credentialRequest = GetCredentialRequest(
  listOf(getPasswordOption, getPublicKeyCredentialOption),
)

  3. เปิดขั้นตอนการลงชื่อเข้าใช้

    coroutineScope {
  try {
    result = credentialManager.getCredential(
      // Use an activity-based context to avoid undefined system UI
      // launching behavior.
      context = activityContext,
      request = credentialRequest
    )
    handleSignIn(result)
  } catch (e: GetCredentialException) {
    // Handle failure
  }
}
    
    fun handleSignIn(result: GetCredentialResponse) {
  // Handle the successfully returned credential.
  val credential = result.credential

  when (credential) {
    is PublicKeyCredential -> {
      val responseJson = credential.authenticationResponseJson
      // Share responseJson i.e. a GetCredentialResponse on your server to
      // validate and  authenticate
    }

    is PasswordCredential -> {
      val username = credential.id
      val password = credential.password
      // Use id and password to send to your server to validate
      // and authenticate
    }

    is CustomCredential -> {
      // If you are also using any external sign-in libraries, parse them
      // here with the utility functions provided.
      if (credential.type == ExampleCustomCredential.TYPE) {
        try {
          val ExampleCustomCredential =
            ExampleCustomCredential.createFrom(credential.data)
          // Extract the required credentials and complete the authentication as per
          // the federated sign in or any external sign in library flow
        } catch (e: ExampleCustomCredential.ExampleCustomCredentialParsingException) {
          // Unlikely to happen. If it does, you likely need to update the dependency
          // version of your external sign-in library.
          Log.e(TAG, "Failed to parse an ExampleCustomCredential", e)
        }
      } else {
        // Catch any unrecognized custom credential type here.
        Log.e(TAG, "Unexpected type of credential")
      }
    }
    else -> {
      // Catch any unrecognized credential type here.
      Log.e(TAG, "Unexpected type of credential")
    }
  }
}

ตัวอย่างต่อไปนี้แสดงวิธีจัดรูปแบบคำขอ JSON เมื่อคุณได้รับพาสคีย์

{
  "challenge": "T1xCsnxM2DNL2KdK5CLa6fMhD7OBqho6syzInk_n-Uo",
  "allowCredentials": [],
  "timeout": 1800000,
  "userVerification": "required",
  "rpId": "credential-manager-app-test.glitch.me"
}

ตัวอย่างต่อไปนี้แสดงลักษณะของการตอบกลับ JSON หลังจากที่คุณได้รับข้อมูลเข้าสู่ระบบด้วยคีย์สาธารณะ

{
  "id": "KEDetxZcUfinhVi6Za5nZQ",
  "type": "public-key",
  "rawId": "KEDetxZcUfinhVi6Za5nZQ",
  "response": {
    "clientDataJSON": "eyJ0eXBlIjoid2ViYXV0aG4uZ2V0IiwiY2hhbGxlbmdlIjoiVDF4Q3NueE0yRE5MMktkSzVDTGE2Zk1oRDdPQnFobzZzeXpJbmtfbi1VbyIsIm9yaWdpbiI6ImFuZHJvaWQ6YXBrLWtleS1oYXNoOk1MTHpEdll4UTRFS1R3QzZVNlpWVnJGUXRIOEdjVi0xZDQ0NEZLOUh2YUkiLCJhbmRyb2lkUGFja2FnZU5hbWUiOiJjb20uZ29vZ2xlLmNyZWRlbnRpYWxtYW5hZ2VyLnNhbXBsZSJ9",
    "authenticatorData": "j5r_fLFhV-qdmGEwiukwD5E_5ama9g0hzXgN8thcFGQdAAAAAA",
    "signature": "MEUCIQCO1Cm4SA2xiG5FdKDHCJorueiS04wCsqHhiRDbbgITYAIgMKMFirgC2SSFmxrh7z9PzUqr0bK1HZ6Zn8vZVhETnyQ",
    "userHandle": "2HzoHm_hY0CjuEESY9tY6-3SdjmNHOoNqaPDcZGzsr0"
  }
}

จัดการข้อยกเว้นเมื่อไม่มีข้อมูลเข้าสู่ระบบ

ในบางกรณี ผู้ใช้อาจไม่มีข้อมูลเข้าสู่ระบบ หรือผู้ใช้อาจไม่ให้ความยินยอมในการใช้ข้อมูลเข้าสู่ระบบที่มีอยู่ หากเรียกใช้ getCredential() และไม่พบข้อมูลเข้าสู่ระบบ ระบบจะแสดงผล NoCredentialException หากเกิดเหตุการณ์นี้ขึ้น โค้ดของคุณควรจัดการNoCredentialException อินสแตนซ์

coroutineScope {
  try {
    result = credentialManager.getCredential(
      context = activityContext,
      request = credentialRequest
    )
  } catch (e: GetCredentialException) {
    Log.e("CredentialManager", "No credential available", e)
  }
}

ใน Android 14 ขึ้นไป คุณสามารถลดเวลาในการตอบสนองเมื่อแสดงตัวเลือกบัญชีได้โดยใช้เมธอด prepareGetCredential() ก่อนเรียกใช้ getCredential()

coroutineScope {
  val response = credentialManager.prepareGetCredential(
    GetCredentialRequest(
      listOf(
        getPublicKeyCredentialOption,
        getPasswordOption
      )
    )
  )
}

เมธอด prepareGetCredential() จะไม่เรียกใช้องค์ประกอบ UI การดำเนินการนี้จะช่วยคุณเตรียมงานเพื่อให้สามารถเปิดใช้งานการดำเนินการรับข้อมูลเข้าสู่ระบบที่เหลือ (ซึ่งเกี่ยวข้องกับ UI) ผ่าน getCredential() API ในภายหลัง

ระบบจะแสดงข้อมูลที่แคชไว้ในออบเจ็กต์ PrepareGetCredentialResponse หากมีข้อมูลเข้าสู่ระบบอยู่แล้ว ระบบจะแคชผลลัพธ์ไว้ จากนั้นคุณจะเปิด getCredential() API ที่เหลือในภายหลังเพื่อแสดงตัวเลือกบัญชีที่มีข้อมูลที่แคชไว้ได้

ขั้นตอนการลงทะเบียน

คุณสามารถลงทะเบียนผู้ใช้เพื่อตรวจสอบสิทธิ์ได้โดยใช้พาสคีย์หรือรหัสผ่าน

สร้างพาสคีย์

หากต้องการให้ผู้ใช้มีตัวเลือกในการลงทะเบียนพาสคีย์และใช้เพื่อตรวจสอบสิทธิ์อีกครั้ง ให้ลงทะเบียนข้อมูลเข้าสู่ระบบของผู้ใช้โดยใช้ออบเจ็กต์ CreatePublicKeyCredentialRequest

suspend fun createPasskey(requestJson: String, preferImmediatelyAvailableCredentials: Boolean) {
  val createPublicKeyCredentialRequest = CreatePublicKeyCredentialRequest(
    // Contains the request in JSON format. Uses the standard WebAuthn
    // web JSON spec.
    requestJson = requestJson,
    // Defines whether you prefer to use only immediately available
    // credentials, not hybrid credentials, to fulfill this request.
    // This value is false by default.
    preferImmediatelyAvailableCredentials = preferImmediatelyAvailableCredentials,
  )

  // Execute CreateCredentialRequest asynchronously to register credentials
  // for a user account. Handle success and failure cases with the result and
  // exceptions, respectively.
  coroutineScope {
    try {
      val result = credentialManager.createCredential(
        // Use an activity-based context to avoid undefined system
        // UI launching behavior
        context = activityContext,
        request = createPublicKeyCredentialRequest,
      )
      //  Handle passkey creation result
    } catch (e : CreateCredentialException){
      handleFailure(e)
    }
  }
}

fun handleFailure(e: CreateCredentialException) {
  when (e) {
    is CreatePublicKeyCredentialDomException -> {
      // Handle the passkey DOM errors thrown according to the
      // WebAuthn spec.
    }
    is CreateCredentialCancellationException -> {
      // The user intentionally canceled the operation and chose not
      // to register the credential.
    }
    is CreateCredentialInterruptedException -> {
      // Retry-able error. Consider retrying the call.
    }
    is CreateCredentialProviderConfigurationException -> {
      // Your app is missing the provider configuration dependency.
      // Most likely, you're missing the
      // "credentials-play-services-auth" module.
    }
    is CreateCredentialCustomException -> {
      // You have encountered an error from a 3rd-party SDK. If you
      // make the API call with a request object that's a subclass of
      // CreateCustomCredentialRequest using a 3rd-party SDK, then you
      // should check for any custom exception type constants within
      // that SDK to match with e.type. Otherwise, drop or log the
      // exception.
    }
    else -> Log.w(TAG, "Unexpected exception type ${e::class.java.name}")
  }
}

จัดรูปแบบคำขอ JSON

หลังจากสร้างพาสคีย์แล้ว คุณต้องเชื่อมโยงพาสคีย์กับบัญชีของผู้ใช้ และเก็บคีย์สาธารณะของพาสคีย์ไว้ในเซิร์ฟเวอร์ ตัวอย่างโค้ดต่อไปนี้แสดงวิธีจัดรูปแบบคำขอ JSON เมื่อคุณสร้างพาสคีย์

บล็อกโพสต์เกี่ยวกับการทำให้แอปของคุณมีการตรวจสอบสิทธิ์ที่ราบรื่นนี้จะแสดงวิธีจัดรูปแบบคำขอ JSON เมื่อคุณสร้างพาสคีย์และเมื่อคุณตรวจสอบสิทธิ์โดยใช้พาสคีย์ นอกจากนี้ ยังอธิบายถึงเหตุผลที่รหัสผ่านไม่ใช่โซลูชันการตรวจสอบสิทธิ์ที่มีประสิทธิภาพ วิธีใช้ประโยชน์จากข้อมูลเข้าสู่ระบบไบโอเมตริกที่มีอยู่ วิธีเชื่อมโยงแอปกับเว็บไซต์ที่คุณเป็นเจ้าของ วิธีสร้างพาสคีย์ และวิธีตรวจสอบสิทธิ์โดยใช้พาสคีย์

{
  "challenge": "abc123",
  "rp": {
    "name": "Credential Manager example",
    "id": "credential-manager-test.example.com"
  },
  "user": {
    "id": "def456",
    "name": "helloandroid@gmail.com",
    "displayName": "helloandroid@gmail.com"
  },
  "pubKeyCredParams": [
    {
      "type": "public-key",
      "alg": -7
    },
    {
      "type": "public-key",
      "alg": -257
    }
  ],
  "timeout": 1800000,
  "attestation": "none",
  "excludeCredentials": [
    {
      "id": "ghi789",
      "type": "public-key"
    },
    {
      "id": "jkl012",
      "type": "public-key"
    }
  ],
  "authenticatorSelection": {
    "authenticatorAttachment": "platform",
    "requireResidentKey": true,
    "residentKey": "required",
    "userVerification": "required"
  }
}

กำหนดค่าสำหรับ authenticatorAttachment

ตั้งค่าพารามิเตอร์ authenticatorAttachment ได้ในเวลาที่สร้างข้อมูลเข้าสู่ระบบเท่านั้น คุณสามารถระบุ platform, cross-platform หรือไม่มีค่าก็ได้ ในกรณีส่วนใหญ่ เราขอแนะนำให้ไม่ระบุค่า

  • platform: หากต้องการลงทะเบียนอุปกรณ์ปัจจุบันของผู้ใช้หรือแจ้งให้ผู้ใช้ที่มีรหัสผ่านอัปเกรดเป็นพาสคีย์หลังจากลงชื่อเข้าใช้ ให้ตั้งค่า authenticatorAttachment เป็น platform
  • cross-platform: ค่านี้มักใช้เมื่อลงทะเบียนข้อมูลเข้าสู่ระบบแบบหลายปัจจัย และไม่ใช้ในบริบทของพาสคีย์
  • ไม่มีค่า: เพื่อมอบความยืดหยุ่นให้กับผู้ใช้ในการสร้างพาสคีย์ในอุปกรณ์ที่ต้องการ (เช่น ในการตั้งค่าบัญชี) คุณไม่ควรระบุพารามิเตอร์ authenticatorAttachment เมื่อผู้ใช้เลือกที่จะเพิ่มพาสคีย์ ในกรณีส่วนใหญ่ การไม่ระบุพารามิเตอร์เป็นตัวเลือกที่ดีที่สุด

ป้องกันการสร้างพาสคีย์ที่ซ้ำกัน

แสดงรหัสข้อมูลเข้าสู่ระบบในอาร์เรย์ excludeCredentials (ไม่บังคับ) เพื่อป้องกันการสร้างพาสคีย์ใหม่หากมีพาสคีย์ที่มีผู้ให้บริการพาสคีย์เดียวกันอยู่แล้ว

จัดการการตอบกลับ JSON

ข้อมูลโค้ดต่อไปนี้แสดงตัวอย่างการตอบกลับ JSON สำหรับการสร้างข้อมูลเข้าสู่ระบบด้วยคีย์สาธารณะ ดูข้อมูลเพิ่มเติมเกี่ยวกับวิธีจัดการข้อมูลเข้าสู่ระบบคีย์สาธารณะที่แสดงผล

{
  "id": "KEDetxZcUfinhVi6Za5nZQ",
  "type": "public-key",
  "rawId": "KEDetxZcUfinhVi6Za5nZQ",
  "response": {
    "clientDataJSON": "eyJ0eXBlIjoid2ViYXV0aG4uY3JlYXRlIiwiY2hhbGxlbmdlIjoibmhrUVhmRTU5SmI5N1Z5eU5Ka3ZEaVh1Y01Fdmx0ZHV2Y3JEbUdyT0RIWSIsIm9yaWdpbiI6ImFuZHJvaWQ6YXBrLWtleS1oYXNoOk1MTHpEdll4UTRFS1R3QzZVNlpWVnJGUXRIOEdjVi0xZDQ0NEZLOUh2YUkiLCJhbmRyb2lkUGFja2FnZU5hbWUiOiJjb20uZ29vZ2xlLmNyZWRlbnRpYWxtYW5hZ2VyLnNhbXBsZSJ9",
    "attestationObject": "o2NmbXRkbm9uZWdhdHRTdG10oGhhdXRoRGF0YViUj5r_fLFhV-qdmGEwiukwD5E_5ama9g0hzXgN8thcFGRdAAAAAAAAAAAAAAAAAAAAAAAAAAAAEChA3rcWXFH4p4VYumWuZ2WlAQIDJiABIVgg4RqZaJyaC24Pf4tT-8ONIZ5_Elddf3dNotGOx81jj3siWCAWXS6Lz70hvC2g8hwoLllOwlsbYatNkO2uYFO-eJID6A"
  }
}

ยืนยันต้นทางจาก JSON ของข้อมูลไคลเอ็นต์

origin แสดงแอปพลิเคชันหรือเว็บไซต์ที่ส่งคำขอ และพาสคีย์จะใช้เพื่อป้องกันการโจมตีฟิชชิง เซิร์ฟเวอร์ของแอปต้องตรวจสอบแหล่งที่มาของข้อมูลไคลเอ็นต์กับรายการที่อนุญาตของแอปและเว็บไซต์ที่ได้รับอนุมัติ หากเซิร์ฟเวอร์ได้รับคําขอจากแอปหรือเว็บไซต์จากต้นทางที่ไม่รู้จัก ก็ควรปฏิเสธคําขอนั้น

ในกรณีของเว็บ origin จะแสดงต้นทางในเว็บไซต์เดียวกันที่ลงชื่อเข้าใช้ข้อมูลเข้าสู่ระบบ ตัวอย่างเช่น เมื่อ URL คือ https://www.example.com:8443/store?category=shoes#athletic origin จะเท่ากับ https://www.example.com:8443

สําหรับแอป Android User Agent จะตั้งค่า origin เป็นลายเซ็นของแอปที่เรียกใช้โดยอัตโนมัติ คุณควรยืนยันลายเซ็นนี้ว่าตรงกันในเซิร์ฟเวอร์เพื่อตรวจสอบผู้เรียกใช้ Passkey API origin ของ Android คือ URI ที่มาจากแฮช SHA-256 ของใบรับรองการรับรอง APK เช่น

android:apk-key-hash:<sha256_hash-of-apk-signing-cert>

คุณดูแฮช SHA-256 ของใบรับรองการรับรองจากคีย์สโตร์ได้โดยเรียกใช้คำสั่งเทอร์มินัลต่อไปนี้

keytool -list -keystore <path-to-apk-signing-keystore>

แฮช SHA-256 อยู่ในรูปแบบเลขฐานสิบหกที่คั่นด้วยโคลอน (91:F7:CB:F9:D6:81…) และค่า origin ของ Android จะอยู่ในรูปแบบ Base64url ตัวอย่าง Python นี้แสดงวิธีแปลงรูปแบบแฮชเป็นรูปแบบฐานสิบหกที่คั่นด้วยโคลอนซึ่งเข้ากันได้

import binascii
import base64
fingerprint = '91:F7:CB:F9:D6:81:53:1B:C7:A5:8F:B8:33:CC:A1:4D:AB:ED:E5:09:C5'
print("android:apk-key-hash:" + base64.urlsafe_b64encode(binascii.a2b_hex(fingerprint.replace(':', ''))).decode('utf8').replace('=', ''))

แทนที่ค่าของ fingerprint ด้วยค่าของคุณเอง ตัวอย่างผลลัพธ์มีดังนี้

android:apk-key-hash:kffL-daBUxvHpY-4M8yhTavt5QnFEI2LsexohxrGPYU

จากนั้นคุณสามารถจับคู่สตริงนั้นเป็นแหล่งที่มาที่อนุญาตในเซิร์ฟเวอร์ได้ หากคุณมีใบรับรองการรับรองหลายรายการ เช่น ใบรับรองสำหรับการแก้ไขข้อบกพร่องและรุ่น หรือแอปหลายรายการ ให้ทำขั้นตอนซ้ำและยอมรับต้นทางทั้งหมดเหล่านั้นว่าถูกต้องในเซิร์ฟเวอร์

บันทึกรหัสผ่านของผู้ใช้

หากผู้ใช้ระบุชื่อผู้ใช้และรหัสผ่านสำหรับขั้นตอนการตรวจสอบสิทธิ์ในแอป คุณจะลงทะเบียนข้อมูลเข้าสู่ระบบของผู้ใช้ที่สามารถใช้ตรวจสอบสิทธิ์ผู้ใช้ได้ โดยสร้างออบเจ็กต์ CreatePasswordRequest ดังนี้

suspend fun registerPassword(username: String, password: String) {
  // Initialize a CreatePasswordRequest object.
  val createPasswordRequest =
    CreatePasswordRequest(id = username, password = password)

  // Create credential and handle result.
  coroutineScope {
    try {
      val result =
        credentialManager.createCredential(
          // Use an activity based context to avoid undefined
          // system UI launching behavior.
          activityContext,
          createPasswordRequest
        )
      // Handle register password result
    } catch (e: CreateCredentialException) {
      handleFailure(e)
    }
  }
}

รองรับการกู้คืนข้อมูลเข้าสู่ระบบ

หากผู้ใช้เข้าถึงอุปกรณ์ที่เก็บข้อมูลเข้าสู่ระบบไม่ได้แล้ว ก็อาจต้องกู้คืนจากข้อมูลสำรองออนไลน์ที่ปลอดภัย หากต้องการดูข้อมูลเพิ่มเติมเกี่ยวกับวิธีรองรับกระบวนการกู้คืนข้อมูลเข้าสู่ระบบนี้ โปรดอ่านส่วน "การกู้คืนสิทธิ์เข้าถึงหรือเพิ่มอุปกรณ์ใหม่" ในบล็อกโพสต์ความปลอดภัยของพาสคีย์ในเครื่องมือจัดการรหัสผ่านของ Google

สร้างพาสคีย์ให้ผู้ใช้โดยอัตโนมัติ

หากผู้ใช้ไม่มีพาสคีย์ คุณจะสร้างพาสคีย์ให้ผู้ใช้โดยอัตโนมัติได้เมื่อผู้ใช้ลงชื่อเข้าใช้ครั้งถัดไปโดยใช้รหัสผ่านที่บันทึกไว้ในเครื่องมือจัดการรหัสผ่าน โดยตั้งค่าช่อง isConditionalCreateRequest เมื่อขอข้อมูลเข้าสู่ระบบแบบสาธารณะ

CreatePublicKeyCredentialRequest(
    // other parameters
    isConditionalCreateRequest: Boolean = true
)

เมื่อผู้ใช้ลงชื่อเข้าใช้ ระบบจะสร้างพาสคีย์โดยอัตโนมัติและจัดเก็บไว้ในเครื่องมือจัดการรหัสผ่านที่ผู้ใช้เลือก หากใช้เครื่องมือจัดการรหัสผ่านบน Google ผู้ใช้ต้องเคยใช้ (โดยใช้เครื่องมือจัดการข้อมูลเข้าสู่ระบบหรือป้อนข้อความอัตโนมัติ) รหัสผ่านที่บันทึกไว้ในเครื่องมือจัดการรหัสผ่าน ผู้ใช้จะได้รับการแจ้งเตือนเมื่อสร้างพาสคีย์นี้ และสามารถไปที่เครื่องมือจัดการรหัสผ่านเพื่อจัดการพาสคีย์ได้

ฟีเจอร์นี้ต้องใช้เวอร์ชัน 1.6.0-alpha01 ขึ้นไป

เพิ่มการรองรับเครื่องมือจัดการรหัสผ่านที่มี URL ที่รู้จักของปลายทางพาสคีย์

เราขอแนะนำให้เพิ่มการรองรับ URL ที่รู้จักของปลายทางพาสคีย์เพื่อให้ผสานรวมได้อย่างราบรื่นและใช้งานร่วมกับเครื่องมือการจัดการรหัสผ่านและข้อมูลเข้าสู่ระบบได้ในอนาคต ซึ่งเป็นโปรโตคอลแบบเปิดสำหรับให้บุคคลที่เกี่ยวข้องประกาศการรองรับพาสคีย์อย่างเป็นทางการและระบุลิงก์โดยตรงสำหรับการลงทะเบียนและการจัดการพาสคีย์

  1. สําหรับบุคคลที่เชื่อถือที่ https://example.com ซึ่งมีเว็บไซต์และแอป Android และ iOS URL ที่รู้จักกันดีจะเป็น https://example.com/.well-known/passkey-endpoints

  2. เมื่อมีการค้นหา URL การตอบกลับควรใช้สคีมาต่อไปนี้

    {
  "enroll": "https://example.com/account/manage/passkeys/create"
  "manage": "https://example.com/account/manage/passkeys"
}

  3. หากต้องการให้ลิงก์นี้เปิดในแอปโดยตรงแทนที่จะเป็นในเว็บ ให้ใช้ลิงก์แอป Android

  4. โปรดดูรายละเอียดเพิ่มเติมในคำอธิบายURL ที่รู้จักของปลายทางพาสคีย์ใน GitHub

ช่วยให้ผู้ใช้จัดการพาสคีย์ได้โดยแสดงผู้ให้บริการที่สร้างพาสคีย์

ปัญหาหนึ่งที่ผู้ใช้พบเมื่อจัดการพาสคีย์หลายรายการที่เชื่อมโยงกับแอปหนึ่งๆ คือ การระบุพาสคีย์ที่ถูกต้องสำหรับการแก้ไขหรือลบ เพื่อช่วยแก้ปัญหานี้ เราขอแนะนำให้แอปและเว็บไซต์ระบุข้อมูลเพิ่มเติม เช่น ผู้ให้บริการที่สร้างข้อมูลเข้าสู่ระบบ วันที่สร้าง และวันที่ใช้ล่าสุดในรายการพาสคีย์ในหน้าจอการตั้งค่าของแอป โดยระบบจะดูข้อมูลผู้ให้บริการจาก AAGUID ที่เชื่อมโยงกับพาสคีย์ที่เกี่ยวข้อง AAGUID จะอยู่ในข้อมูลโปรแกรมตรวจสอบสิทธิ์ของพาสคีย์

ตัวอย่างเช่น หากผู้ใช้สร้างพาสคีย์ในอุปกรณ์ที่ใช้ Android โดยใช้เครื่องมือจัดการรหัสผ่านของ Google แล้ว RP จะได้รับ AAGUID ลักษณะดังนี้ "ea9b8d66-4d01-1d21-3ce4-b6b48cb575d4" ฝ่ายที่เชื่อถือสามารถกำกับเนื้อหาเพิ่มเติมในพาสคีย์ในรายการพาสคีย์เพื่อระบุว่าสร้างพาสคีย์โดยใช้เครื่องมือจัดการรหัสผ่านบน Google

หากต้องการแมป AAGUID กับผู้ให้บริการพาสคีย์ RP สามารถใช้ที่เก็บ AAGUID ที่มาจากชุมชน ค้นหา AAGUID ในรายการเพื่อดูชื่อและไอคอนของผู้ให้บริการพาสคีย์

อ่านเพิ่มเติมเกี่ยวกับการผสานรวม AAGUID

แก้ปัญหาข้อผิดพลาดที่พบบ่อย

ดูรหัสข้อผิดพลาดที่พบบ่อย คําอธิบาย และข้อมูลเกี่ยวกับสาเหตุของข้อผิดพลาดในคู่มือการแก้ปัญหาเกี่ยวกับเครื่องมือจัดการข้อมูลเข้าสู่ระบบ

แหล่งข้อมูลเพิ่มเติม

ดูข้อมูลเพิ่มเติมเกี่ยวกับเครื่องมือจัดการข้อมูลเข้าสู่ระบบ API และพาสคีย์ได้ที่แหล่งข้อมูลต่อไปนี้