웹 인증:
공개 키 자격 증명에 접근하기 위한 API
레벨 3

1. 소개

이 섹션은 규범적인 내용이 아닙니다.

이 명세서는 웹 애플리케이션이 강력하고 증명 가능한, 범위 지정된 공개 키 기반 자격 증명을 생성하고 사용할 수 있도록 하는 API를 정의하며, 사용자를 강력하게 인증하는 목적을 가지고 있습니다. 공개 키 자격 증명은 WebAuthn 인증기에 의해 WebAuthn 의존 당사자의 요청에 따라 생성되고 저장되며, 사용자 동의의 대상이 됩니다. 이후 해당 공개 키 자격 증명은 그 오리진에 속하는 의존 당사자만 접근할 수 있습니다. 이 범위 지정은 준수하는 사용자 에이전트와 인증기에 의해 공동으로 강제됩니다. 또한 서로 다른 의존 당사자 간의 프라이버시도 유지됩니다; 한 의존 당사자는 다른 의존 당사자에 범위 지정된 자격 증명의 속성이나 존재 여부조차도 감지할 수 없습니다.

의존 당사자는 사용자와 관련된 두 가지 구별되지만 관련된 절차 동안 Web Authentication API를 사용합니다. 첫 번째는 등록으로, 이 절차에서는 공개 키 자격 증명이 인증기에 생성되어 현재 사용자의 계정에 범위 지정됩니다(계정은 이미 존재할 수도 있고 이때 생성될 수도 있습니다). 두 번째는 인증으로, 이 절차에서는 의존 당사자에게 등록된 사용자의 존재와 동의를 증명하는 인증 어설션이 제시됩니다. 기능적으로, Web Authentication API는 Credential Management API를 확장한 PublicKeyCredential과, 이러한 자격 증명을 navigator.credentials.create() 및 navigator.credentials.get()으로 사용하게 해 주는 인프라로 구성됩니다. 전자는 등록 동안 사용되며, 후자는 인증 동안 사용됩니다.

전반적으로, 준수하는 인증기는 공개 키 자격 증명을 보호하고, 사용자 에이전트와 상호 작용하여 Web Authentication API를 구현합니다. 준수하는 인증기는 (a) 범용 컴퓨팅 장치에서 소프트웨어로 실행되거나, (b) 기기 내 보안 실행 환경, 신뢰할 수 있는 플랫폼 모듈(TPM) 또는 보안 요소(SE) 상에서 동작하거나, (c) 장치 외부에서 구현될 수 있습니다. 장치 내에서 구현되는 인증기를 플랫폼 인증기(platform authenticators)라 부릅니다. 장치 외부에서 구현되는 인증기(예: 로밍 인증기)는 USB, 블루투스 저에너지(BLE), 근거리 무선 통신(NFC)과 같은 전송 수단을 통해 접근할 수 있습니다.

1.1. 명세 로드맵

많은 W3C 명세서가 주로 사용자 에이전트 개발자와 웹 애플리케이션 개발자(즉, "웹 저자")를 대상으로 하지만, Web Authentication의 특성상 이 명세서는 아래에 설명된 바와 같이 여러 대상이 올바르게 사용해야 합니다.

모든 대상은 먼저 § 1.2 사용 사례, § 1.3 샘플 API 사용 시나리오, 및 § 4 용어를 읽어야 하며, 전체 튜토리얼을 위해 [WebAuthnAPIGuide]도 참조해야 합니다. 그 밖에 이 문서의 의도된 주요 대상은 다음과 같습니다.

• 의존 당사자 웹 애플리케이션 개발자 — 특히 로그인 흐름, 계정 복구 흐름, 사용자 계정 데이터베이스 내용 등을 담당하는 사람들.

• 웹 프레임워크 개발자

  • 위의 두 대상은 특히 § 7 WebAuthn 의존 당사자 작업을 참조해야 합니다. § 5 Web Authentication API의 도입부가 도움이 될 수 있지만, 해당 섹션은 사용자 에이전트 개발자를 구체적으로 겨냥하고 있음을 이해해야 합니다. 또한 인증기의 증명을 검증하려는 경우 § 6.5 증명 및 § 8 정의된 증명 문장 형식도 관련이 있습니다. 확장을 사용하려면 § 9 WebAuthn 확장과 § 10 정의된 확장이 관심 대상이 될 것입니다. 마지막으로, § 13.4 의존 당사자를 위한 보안 고려사항 및 § 14.6 의존 당사자를 위한 개인정보 고려사항을 읽고 어떤 과제가 애플리케이션과 사용자에 적용되는지 고려해야 합니다.

• 사용자 에이전트 개발자

• 운영체제 플랫폼 개발자 — 플랫폼별 인증기 API 설계 및 구현, 플랫폼별 WebAuthn 클라이언트 인스턴스화 등에 책임이 있는 사람들.

  • 위의 두 대상은 확장을 지원하려는 경우 § 5 Web Authentication API와 함께 § 9 WebAuthn 확장을 매우 주의 깊게 읽어야 합니다. 또한 § 14.5 클라이언트를 위한 개인정보 고려사항를 주의 깊게 읽어야 합니다.

• 인증기 개발자. 이 독자들은 § 6 WebAuthn 인증기 모델, § 8 정의된 증명 문장 형식, § 9 WebAuthn 확장, 및 § 10 정의된 확장을 특히 주의 깊게 볼 것입니다. 또한 § 13.3 인증기를 위한 보안 고려사항 및 § 14.4 인증기를 위한 개인정보 고려사항도 주의 깊게 읽어야 합니다.

1.2. 사용 사례

아래 사용 사례 시나리오는 두 가지 매우 다른 유형의 인증기와 두 가지 일반적인 배포 유형에서의 자격 증명 사용을 설명하고, 추가 시나리오의 개요도 제공합니다. 추가 시나리오(샘플 코드 포함)는 이후 § 1.3 샘플 API 사용 시나리오에 제시되어 있습니다. 이 예제들은 예시용일 뿐이며, 기능 가용성은 클라이언트 및 인증기 구현에 따라 다를 수 있습니다.

1.2.1. 다중 장치 자격 증명을 사용하는 소비자

이 사용 사례는 소비자 중심의 의존 당사자가 사용자의 장치에 내장된 인증기를 활용하여 다중 장치 자격 증명(일반적으로 동기화된 패스키라고 함)을 사용한 피싱 저항 로그인 제공 방법을 보여줍니다.

1.2.1.1. 등록

• 휴대전화에서:

  • 사용자가 브라우저에서 example.com으로 이동하여 기존 계정에 자신이 사용하던 방법(예: 기존 비밀번호 등)으로 로그인하거나 새 계정을 생성합니다.

  • 휴대전화가 "example.com에 대한 패스키를 만들겠습니까?"라는 메시지를 표시합니다.

  • 사용자가 동의합니다.

  • 휴대전화가 이전에 구성된 권한 제스처(PIN, 생체 인식 등)를 요청하며, 사용자가 이를 제공합니다.

  • 웹사이트에 "등록이 완료되었습니다."라는 메시지가 표시됩니다.

1.2.1.2. 인증

• 노트북 또는 데스크톱에서:

  • 사용자가 브라우저에서 example.com으로 이동하여 로그인 절차를 시작합니다.

  • 장치에서 다중 장치 자격 증명(일반적으로 동기화된 패스키라고 함)이 사용 가능한 경우:

    • 브라우저나 운영체제가 이전에 구성된 권한 제스처(PIN, 생체 인식 등)를 요청합니다; 사용자가 이를 제공합니다.

    • 웹 페이지는 선택된 사용자가 로그인되었음을 표시하고, 로그인 후 페이지로 이동합니다.

  • 동기화된 패스키가 장치에서 이용할 수 없는 경우:

    • 브라우저나 운영체제가 전화기나 보안 키와 같은 외부 인증기를 요청합니다.

    • 사용자가 이전에 연결한 휴대전화를 선택합니다.

• 다음으로, 휴대전화에서:

  • 사용자가 "example.com에 로그인"이라는 알림이나 알림창을 봅니다.

  • 사용자가 이 알림을 선택합니다.

  • 사용자에게 example.com의 신원 목록(예: "Mohamed로 로그인 / 张三로 로그인")이 표시됩니다.

  • 사용자가 신원을 선택하고 권한 제스처(PIN, 생체 인식 등)를 요청받아 이를 제공합니다.

• 이제 노트북으로 돌아가면:

  • 웹 페이지는 선택된 사용자가 로그인되었음을 표시하고, 로그인 후 페이지로 이동합니다.

1.2.2. 단일 장치 자격 증명을 사용하는 인력

이 사용 사례는 인력 중심의 의존 당사자가 USB 보안 키와 같은 로밍 인증기와 내장 지문 센서와 같은 플랫폼 인증기의 조합을 활용하여 사용자가 다음을 가질 수 있도록 하는 방법을 보여줍니다:

• 새로운 클라이언트 장치(예: 노트북, 데스크톱)에서 인증할 때 사용하거나 플랫폼 인증기가 없는 클라이언트 장치에서 사용하는 "주(primary)" 로밍 인증기,

• 플랫폼 인증기가 있는 클라이언트 장치에서 낮은 마찰로 강력하게 재인증할 수 있는 수단, 또는

• 단일 장치 자격 증명(single-device credentials, 일반적으로 장치 바인딩된 패스키라 함)을 지원하지 않는 패스키 플랫폼 인증기가 있는 클라이언트 장치에서 강력하게 재인증할 수 있는 수단.

1.2.2.1. 등록

이 예에서는 사용자의 고용주가 장치 바인딩된 패스키로 미리 구성된 보안 키를 우편으로 보냅니다.

임시 PIN이 채널 밖(예: RCS 메시지 등)을 통해 사용자에게 전송되었습니다.

1.2.2.2. 인증

• 노트북 또는 데스크톱에서:

  • 사용자가 브라우저에서 corp.example.com으로 이동하여 로그인 절차를 시작합니다.

  • 브라우저나 운영체제가 사용자에게 보안 키를 요구합니다.

  • 사용자가 USB 보안 키를 연결합니다.

  • USB 보안 키는 버튼을 누르라는 신호를 보내며, 사용자가 이를 누릅니다.

  • 브라우저나 운영체제가 사용자에게 PIN을 입력하라고 요청합니다.

  • 사용자는 제공된 임시 PIN을 입력하고 계속 진행합니다.

  • 브라우저나 운영체제가 사용자가 PIN을 변경해야 한다고 알려주고 새 PIN을 요청합니다.

  • 사용자가 새 PIN을 입력하고 계속합니다.

  • 브라우저나 운영체제가 인증 흐름을 재시작하고 사용자가 PIN을 입력하도록 요청합니다.

  • 사용자가 새 PIN을 입력하고 보안 키를 탭합니다.

  • 웹 페이지는 선택된 사용자가 로그인되었음을 표시하고, 로그인 후 페이지로 이동합니다.

1.2.3. 기타 사용 사례 및 구성

다음과 같은 다양한 추가 사용 사례 및 구성도 가능합니다(예시는 제한되지 않음):

• 사용자가 노트북에서 example.com으로 이동하여 휴대전화에서 자격 증명을 생성하고 등록하도록 안내되는 흐름.

• 사용자가 USB 및/또는 NFC 연결 옵션을 가진 보안 키와 같은 별도의 로밍 인증기를 획득하고, 노트북이나 휴대전화의 브라우저에서 example.com을 로드한 뒤 보안 키에서 자격 증명을 생성하고 등록하도록 안내되는 흐름.

• 의존 당사자가 단일 거래(예: 결제 또는 기타 금융 거래)를 승인하기 위해 사용자에게 권한 제스처를 요청하는 경우.

1.3. 샘플 API 사용 시나리오

이 섹션은 규범적인 내용이 아닙니다.

이 섹션에서는 공개 키 자격 증명의 수명 주기에서 발생하는 몇 가지 이벤트와 이 API를 사용하는 해당 샘플 코드를 살펴봅니다. 이는 예시 흐름이며 API 사용 범위를 제한하지 않습니다.

이전 섹션과 마찬가지로, 이 흐름은 자체 디스플레이가 있는 패스키 로밍 인증기를 사용하는 사용 사례에 초점을 맞춥니다. 이러한 인증기의 예로는 스마트폰이 있습니다. 다른 인증기 유형도 이 API에 의해 지원되며 이는 클라이언트 플랫폼의 구현에 따라 달라집니다. 예를 들어, 이 흐름은 클라이언트 장치에 내장된 인증기의 경우에도 수정 없이 작동합니다. 자체 디스플레이가 없는 인증기(스마트 카드와 유사한)의 경우에도 특정 구현 고려사항이 충족되면 흐름이 작동합니다. 구체적으로, 클라이언트 플랫폼은 인증기가 표시했을 프롬프트를 대신 표시해야 하고, 인증기는 클라이언트 플랫폼이 모든 인증기 자격 증명을 열거할 수 있도록 허용해야 하여 클라이언트가 적절한 프롬프트를 표시할 정보를 가질 수 있어야 합니다.

1.3.1. 등록

이것은 최초 흐름으로, 새 자격 증명이 생성되어 서버에 등록됩니다. 이 흐름에서 WebAuthn 의존 당사자는 플랫폼 인증기(platform authenticators)나 로밍 인증기(roaming authenticators) 중 특정 선호를 갖지 않습니다.

1. 사용자가 example.com을 방문하면 스크립트를 제공합니다. 이 시점에서 사용자는 이미 기존 사용자 이름과 비밀번호 또는 추가 인증기 등 의존 당사자가 허용하는 다른 수단으로 로그인했을 수 있으며, 또는 새 계정을 생성하는 중일 수 있습니다.

2. 의존 당사자 스크립트가 아래 코드 스니펫을 실행합니다.

3. 클라이언트 플랫폼이 인증기를 검색하고 찾습니다.

4. 클라이언트가 필요한 경우 페어링 동작을 수행하면서 인증기에 연결합니다.

5. 인증기는 사용자에게 생체 인식 또는 다른 권한 제스처를 제공하라는 적절한 UI를 표시합니다.

6. 인증기는 클라이언트에 응답을 반환하며, 클라이언트는 다시 의존 당사자 스크립트에 응답을 반환합니다. 사용자가 인증기 선택을 거부하거나 권한 제공을 거부한 경우 적절한 오류가 반환됩니다.

7. 새 자격 증명이 생성된 경우,

   • 의존 당사자 스크립트는 새로 생성된 자격 증명 공개 키를 서버에 전송하며, 인증기의 출처 및 특성에 관한 증명(attestation)과 같은 추가 정보를 함께 보냅니다.

   • 서버는 자격 증명 공개 키를 데이터베이스에 저장하고 이를 사용자 및 증명에서 나타난 인증 특성과 연관시키며, 나중에 사용할 친숙한 이름도 저장합니다.

   • 스크립트는 향후 사용자 경험을 개선하기 위해 자격 증명 ID와 같은 데이터를 로컬 스토리지에 저장할 수 있습니다.

새 키를 생성하고 등록하는 샘플 코드는 다음과 같습니다:

if (!window.PublicKeyCredential) { /* Client not capable. Handle error. */ }

var publicKey = {
  // The challenge is produced by the server; see the Security Considerations
  challenge: new Uint8Array([21,31,105 /* 29 more random bytes generated by the server */]),

  // Relying Party:
  rp: {
    name: "ACME Corporation"
  },

  // User:
  user: {
    id: Uint8Array.from(window.atob("MIIBkzCCATigAwIBAjCCAZMwggE4oAMCAQIwggGTMII="), c=>c.charCodeAt(0)), 
    name: "alex.mueller@example.com",
    displayName: "Alex Müller",
  },

  // This Relying Party will accept either an ES256 or RS256 credential, but
  // prefers an ES256 credential.
  pubKeyCredParams: [{
      type: "public-key",>
      alg: -7 // "ES256" as registered in the IANA COSE Algorithms registry
    },
    {
      type: "public-key",>
      alg: -257 // Value registered by this specification for "RS256"
    }
  ],

  authenticatorSelection: {
    // Try to use UV if possible. This is also the default.
    userVerification: "preferred"
  },

  timeout: 300000,  // 5 minutes
  excludeCredentials: [// Don't re-register any authenticator that has one of these credentials
    {"id": Uint8Array.from(window.atob("ufJWp8YGlibm1Kd9XQBWN1WAw2jy5In2Xhon9HAqcXE="), c=>c.charCodeAt(0)), "type": "public-key"},
    {"id": Uint8Array.from(window.atob("E/e1dhZc++mIsz4f9hb6NifAzJpF1V4mEtRlIPBiWdY="), c=>c.charCodeAt(0)), "type": "public-key"}
  ],

  // Make excludeCredentials check backwards compatible with credentials registered with U2F
  extensions: {"appidExclude": "https://acme.example.com"}
};

// Note: The following call will cause the authenticator to display UI.
navigator.credentials.create({ publicKey })
  .then(function (newCredentialInfo) {
    // Send new credential info to server for verification and registration.
  }).catch(function (err) {
    // No acceptable authenticator or user refused consent. Handle appropriately.
  });

1.3.2. 사용자 검증 플랫폼 인증기를 사용한 등록 예시

이 예시는 WebAuthn 의존 당사자가 특히 공개 키 자격 증명을 사용자 검증 플랫폼 인증기으로 생성하는 데 관심이 있을 때의 흐름입니다.

1. 사용자가 example.com을 방문하고 로그인 버튼을 클릭하면 login.example.com으로 리디렉션됩니다.

2. 사용자가 사용자 이름과 비밀번호로 로그인합니다. 로그인 성공 후 사용자는 다시 example.com으로 리디렉션됩니다.

3. 의존 당사자 스크립트가 아래 코드 스니펫을 실행합니다.

   1. 사용자 에이전트는 사용자 검증 플랫폼 인증기가 사용 가능한지 확인합니다. 사용 불가능하면 이 흐름을 종료합니다.

   2. 의존 당사자는 사용자에게 함께 자격 증명을 생성할지 묻습니다. 원치 않으면 흐름을 종료합니다.

   3. 사용자 에이전트 및/또는 운영체제는 적절한 UI를 표시하고 사용자가 사용 가능한 플랫폼 인증기 중 하나를 사용하여 자격 증명을 생성하도록 안내합니다.

   4. 자격 증명 생성에 성공하면 의존 당사자 스크립트는 새 자격 증명을 서버로 전달합니다.

if (!window.PublicKeyCredential) { /* Client not capable of the API. Handle error. */ }

PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable()
    .then(function (uvpaAvailable) {
        // If there is a user-verifying platform authenticator
        if (uvpaAvailable) {
            // Render some RP-specific UI and get a Promise for a Boolean value
            return askIfUserWantsToCreateCredential();
        }
    }).then(function (userSaidYes) {
        // If there is a user-verifying platform authenticator
        // AND the user wants to create a credential
        if (userSaidYes) {
            var publicKeyOptions = { /* Public key credential creation options. */};
            return navigator.credentials.create({ "publicKey": publicKeyOptions });
        }
    }).then(function (newCredentialInfo) {
        if (newCredentialInfo) {
            // Send new credential info to server for verification and registration.
        }
    }).catch(function (err) {
        // Something went wrong. Handle appropriately.
    });

1.3.3. 인증

이것은 이미 등록된 자격 증명을 가진 사용자가 웹사이트를 방문하여 해당 자격 증명으로 인증하려는 흐름입니다.

1. 사용자가 example.com을 방문하면 스크립트를 제공합니다.

2. 스크립트는 가능한 한 많은 정보를 제공하여 사용자에 대해 허용 가능한 자격 증명의 선택을 좁히기 위해 클라이언트에게 인증 어설션을 요청합니다. 이 정보는 등록 후 로컬에 저장된 데이터나 사용자에게 사용자 이름을 묻는 등의 다른 수단으로 얻을 수 있습니다.

3. 의존 당사자 스크립트가 아래 코드 스니펫 중 하나를 실행합니다.

4. 클라이언트 플랫폼이 인증기를 검색하고 찾습니다.

5. 클라이언트가 필요한 경우 페어링 동작을 수행하면서 인증기에 연결합니다.

6. 인증기는 사용자의 주의가 필요하다는 알림을 표시합니다. 알림을 열면 사용자는 자격 증명을 생성할 때 제공된 계정 정보를 사용하여 허용 가능한 자격 증명의 친숙한 선택 메뉴와, 이러한 키를 요청하는 오리진에 대한 일부 정보를 보게 됩니다.

7. 인증기는 사용자로부터 생체 인식 또는 다른 권한 제스처를 얻습니다.

8. 인증기는 클라이언트에 응답을 반환하고, 클라이언트는 다시 의존 당사자 스크립트에 응답을 반환합니다. 사용자가 자격 증명 선택을 거부하거나 권한 제공을 거부한 경우 적절한 오류가 반환됩니다.

9. 어설션이 성공적으로 생성되어 반환된 경우,

   • 스크립트는 어설션을 서버로 보냅니다.

   • 서버는 어설션을 검사하여 자격 증명 ID를 추출하고, 데이터베이스에서 등록된 자격 증명 공개 키를 찾아 어설션 서명을 검증합니다. 유효한 경우, 어설션의 자격 증명 ID에 연관된 신원을 찾아 그것을 인증된 것으로 간주합니다. 만약 자격 증명 ID가 서버에서 인식되지 않으면(예: 비활성으로 인해 등록 해제된 경우) 인증은 실패합니다; 각 의존 당사자는 이를 자체 방식으로 처리합니다.

   • 서버는 이제 인증 성공 시 수행할 작업(성공 페이지 반환, 인증 쿠키 설정 등)을 수행합니다.

만약 의존 당사자 스크립트가 로컬에 저장된 데이터 등과 같이 자격 증명 목록을 좁히는 힌트를 갖고 있지 않다면, 인증을 수행하는 샘플 코드는 다음과 같을 수 있습니다:

if (!window.PublicKeyCredential) { /* Client not capable. Handle error. */ }

// credentialId is generated by the authenticator and is an opaque random byte array
var credentialId = new Uint8Array([183, 148, 245 /* more random bytes previously generated by the authenticator */]);
var options = {
  // The challenge is produced by the server; see the Security Considerations
  challenge: new Uint8Array([4,101,15 /* 29 more random bytes generated by the server */]),
  timeout: 300000,  // 5 minutes
  allowCredentials: [{ type: "public-key", id: credentialId }]
};

navigator.credentials.get({ "publicKey": options })
    .then(function (assertion) {
    // Send assertion to server for verification
}).catch(function (err) {
    // No acceptable credential or user refused consent. Handle appropriately.
});

반면, 의존 당사자 스크립트가 자격 증명 목록을 좁히는 데 도움이 되는 힌트를 가지고 있다면, 다음과 같은 샘플 코드가 될 수 있습니다. 이 샘플은 자격 증명 속성 확장을 사용하는 방법도 보여줍니다.

if (!window.PublicKeyCredential) { /* Client not capable. Handle error. */ }

var encoder = new TextEncoder();
var acceptableCredential1 = {
    type: "public-key",
    id: encoder.encode("BA44712732CE")
};
var acceptableCredential2 = {
    type: "public-key",
    id: encoder.encode("BG35122345NF")
};

var options = {
  // The challenge is produced by the server; see the Security Considerations
  challenge: new Uint8Array([8,18,33 /* 29 more random bytes generated by the server */]),
  timeout: 300000,  // 5 minutes
  allowCredentials: [acceptableCredential1, acceptableCredential2],
  extensions: { 'credProps': true }
};

navigator.credentials.get({ "publicKey": options })
    .then(function (assertion) {
    // Send assertion to server for verification
}).catch(function (err) {
    // No acceptable credential or user refused consent. Handle appropriately.
});

1.3.4. 인증 작업 중단

아래 예시는 개발자가 AbortSignal 매개변수를 사용하여 자격 증명 등록 작업을 중단하는 방법을 보여줍니다. 인증 작업에도 유사한 절차가 적용됩니다.

const authAbortController = new AbortController();
const authAbortSignal = authAbortController.signal;

authAbortSignal.onabort = function () {
    // Once the page knows the abort started, inform user it is attempting to abort.
}

var options = {
    // A list of options.
}

navigator.credentials.create({
    publicKey: options,
    signal: authAbortSignal})
    .then(function (attestation) {
        // Register the user.
    }).catch(function (error) {
        if (error == "AbortError") {
            // Inform user the credential hasn't been created.
            // Let the server know a key hasn't been created.
        }
    });

// Assume widget shows up whenever authentication occurs.
if (widget == "disappear") {
    authAbortController.abort();
}

1.3.5. 운영 중지(Decommissioning)

다음은 자격 증명 운영 중지(제거)를 원할 수 있는 가능한 상황들입니다. 이 모든 상황은 서버 측에서 처리되며 여기 지정된 API의 지원을 필요로 하지 않습니다.

• 가능성 #1 — 사용자가 자격 증명을 분실했다고 신고하는 경우.

  • 사용자는 server.example.net에 접속하여 인증하고 분실/도난된 인증기를 신고하는 링크를 따릅니다.

  • 서버는 등록된 자격 증명의 목록을 친숙한 이름과 함께 표시하는 페이지를 반환합니다.

  • 사용자가 자격 증명을 선택하면 서버는 데이터베이스에서 해당 자격 증명을 삭제합니다.

  • 향후에는 의존 당사자 스크립트가 해당 자격 증명을 허용 목록에 포함시키지 않으며, 해당 자격 증명으로 서명된 어설션은 거부됩니다.

• 가능성 #2 — 서버가 비활성으로 인해 자격 증명을 등록 해제하는 경우.

  • 서버는 유지 관리 활동 중에 데이터베이스에서 자격 증명을 삭제합니다.

  • 향후에는 의존 당사자 스크립트가 해당 자격 증명을 허용 목록에 포함시키지 않으며, 해당 자격 증명으로 서명된 어설션은 거부됩니다.

• 가능성 #3 — 사용자가 인증기에서 자격 증명을 삭제하는 경우.

  • 사용자는 인증기-특유의 방법(예: 기기 설정 UI)을 사용하여 인증기에서 자격 증명을 삭제합니다.

  • 이 시점부터 해당 자격 증명은 선택 프롬프트에 나타나지 않으며, 더 이상 해당 자격 증명으로 어설션을 생성할 수 없습니다.

  • 나중에 서버가 비활성으로 인해 이 자격 증명을 등록 해제할 수 있습니다.

1.4. 플랫폼별 구현 지침

이 명세서는 일반적인 사례에서 Web Authentication을 사용하는 방법을 정의합니다. 특정 플랫폼 지원(예: 앱)과 연계하여 Web Authentication을 사용할 때는 추가 지침과 제한 사항에 대해서는 플랫폼별 문서와 가이드를 참조하는 것이 권장됩니다.

2. 준수

이 명세서는 세 가지 준수 클래스(conformance classes)를 정의합니다. 이들 각 클래스는 해당 클래스의 준수 구성원이 다른 클래스의 비준수 또는 적대적 구성원에 대해 안전하도록 지정되어 있습니다.

2.1. 사용자 에이전트

사용자 에이전트는 준수로 간주되기 위해 § 5 Web Authentication API에 설명된 대로 동작해야 합니다. 준수하는 사용자 에이전트는 이 명세서에 제시된 알고리즘을 원하는 방식으로 구현할 수 있지만, 최종 결과는 명세서의 알고리즘으로 얻을 수 있는 결과와 구별되지 않아야 합니다.

준수하는 사용자 에이전트는 또한 이 명세서의 IDL 단편을 준수하는 구현이어야 하며, 이는 "Web IDL" 명세에 설명되어 있습니다. [WebIDL]

2.1.1. DOMString 유형으로서의 열거형 호환성

열거형 타입은 Web IDL의 다른 부분에서 참조되지 않는데, 이는 명세서와 구현을 업데이트하지 않고 다른 값을 사용하는 것을 금지하게 되기 때문입니다. 이전 호환성을 위해 클라이언트 플랫폼과 의존 당사자는 알려지지 않은 값을 처리해야 합니다. 이 명세서의 열거형은 문서화 및 레지스트리 용도로 존재합니다. 열거형이 다른 곳에 표현될 때는 DOMString으로 타입이 지정됩니다. 예를 들어 transports와 같이.

2.2. 인증기

WebAuthn 인증기는 § 6 WebAuthn 인증기 모델에 정의된 작업을 제공해야 하며, 그 동작은 해당 섹션에 설명된 대로 동작해야 합니다. 이는 인증기가 준수하는 사용자 에이전트에 의해 사용 가능하도록 하기 위한 기능적 및 보안 요건의 집합입니다.

§ 1.2 사용 사례에 설명된 바와 같이, 인증기는 사용자 에이전트의 기반이 되는 운영체제에 구현될 수도 있고, 외부 하드웨어에 또는 둘의 조합으로 구현될 수도 있습니다.

2.2.1. FIDO U2F와의 하위 호환성

인증기가 오직 § 8.6 FIDO U2F 증명 문장 형식만을 지원하는 경우, 사용자 핸들(user handle)을 저장할 메커니즘이 없으므로 반환되는 userHandle은 항상 null이 됩니다.

2.3. WebAuthn 의존 당사자

WebAuthn 의존 당사자는 이 명세서가 제공하는 모든 보안 혜택을 얻기 위해 § 7 WebAuthn 의존 당사자 작업에 설명된 대로 동작해야 합니다. 자세한 논의는 § 13.4.1 WebAuthn 의존 당사자를 위한 보안 혜택을 참조하세요.

2.4. 모든 준수 클래스

위의 준수 클래스 구성원들이 수행하는 모든 CBOR 인코딩은 CBOR 표준에 따라 CTAP2 표준의 정형화된(Canonical) CBOR 인코딩 형식을 사용하여 수행되어야 합니다. 위 준수 클래스의 모든 디코더는 CTAP2 정형화 CBOR 인코딩 형식으로 유효하게 인코딩되지 않은 CBOR을 거부해야 하며, 중복 맵 키가 있는 메시지도 거부하는 것이 권장됩니다.

3. 종속성

이 명세서는 아래 및 참조로 정의된 용어에 나열된 여러 다른 기본 명세들에 의존합니다.

Base64url encoding

용어 Base64url Encoding은 [RFC4648]의 섹션 5에 정의된 URL 및 파일명 안전 문자 집합을 사용하는 base64 인코딩을 가리키며, 모든 꼬리의 '=' 문자는(섹션 3.2에서 허용된 대로) 생략되고 줄바꿈, 공백 또는 기타 추가 문자가 포함되지 않은 것을 의미합니다.

CBOR

이 명세서의 여러 구조(증명 문장 및 확장 등)는 Compact Binary Object Representation(CBOR)의 CTAP2 정형화(Canonical) CBOR 인코딩 형식으로 인코딩됩니다. CBOR 자체는 [RFC8949] 및 [FIDO-CTAP]에 정의되어 있습니다.

CDDL

이 명세서는 모든 CBOR 인코딩 데이터를 기술하기 위해 CBOR Data Definition Language(CDDL)를 사용하며, 이는 [RFC8610]에 정의되어 있습니다.

COSE

CBOR Object Signing and Encryption(COSE) 관련 규격으로는 [RFC9052] 및 [RFC9053]가 있습니다. 또한 IANA COSE Algorithms 레지스트리([IANA-COSE-ALGS-REG])는 원래 [RFC8152]에 의해 설립되었고 이들 규격들에 의해 갱신되어 사용됩니다.

Credential Management

이 문서에 설명된 API는 Credential 개념을 정의한 [CREDENTIAL-MANAGEMENT-1]의 확장입니다.

DOM

DOMException 및 이 명세서에서 사용하는 DOMException 값들은 [DOM4]에 정의되어 있습니다.

ECMAScript

%ArrayBuffer%는 [ECMAScript]에 정의되어 있습니다.

URL

domain, host, port, scheme, valid domain 및 valid domain string과 같은 개념들은 [URL]에 정의되어 있습니다.

Web IDL

이 명세서의 많은 인터페이스 정의와 모든 IDL은 [WebIDL]에 의존합니다. 이 업데이트된 Web IDL 표준은 이제 비동기 상호작용을 위한 우선 메커니즘인 Promise에 대한 지원을 추가합니다.

FIDO AppID

호출 애플리케이션의 FacetID 결정 및 호출자의 FacetID가 AppID에 대해 권한이 있는지 결정하는 알고리즘(앱ID 확장에서만 사용)은 [FIDO-APPID]에 정의되어 있습니다.

문서 내에서 대문자로만 나타나는 경우(여기와 같이) "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY" 및 "OPTIONAL"과 같은 핵심 단어들은 BCP 14의 규정에 따라 해석됩니다. 자세한 내용은 [RFC2119] 및 [RFC8174]를 참조하세요.

4. 용어

증명(Attestation)

일반적으로 attestation(증명)은 증언하거나 확인하거나 인증함을 의미합니다. WebAuthn 맥락에서 증명은 인증기와 그것이 생성하는 데이터의 출처에 대한 검증 가능한 증거를 제공하는 데 사용됩니다. 여기에는 자격 증명 ID, 자격 증명 키 쌍, 서명 카운터 등과 같은 항목이 포함됩니다.

증명 문장(attestation statement)은 증명 객체 내에서 등록 절차 동안 제공됩니다. 또한 § 6.5 증명 및 그림 6도 참고하세요. 클라이언트가 증명 문장과 aaguid 부분을 의존 당사자에게 어떻게 전달하는지는 증명 전달 방식에서 설명합니다.

증명 인증서(Attestation Certificate)

증명 키 쌍에 대한 X.509 인증서로, 인증기가 제조 및 기능을 증명하기 위해 사용합니다. 등록 시점에 인증기는 증명 비밀 키로 생성하여 반환하는 의존 당사자 특정 자격 증명 공개 키(및 추가 데이터)에 서명합니다. 의존 당사자는 증명 인증서에 담긴 증명 공개 키을 사용하여 증명 서명을 검증합니다. 자체 증명(self attestation)의 경우에는 인증기가 별도의 증명 키 쌍이나 증명 인증서를 가지지 않는 점을 참조하세요(self attestation 참조).

인증(Authentication)

인증 절차(Authentication Ceremony)

사용자와 그 사용자의 클라이언트 플랫폼(하나 이상의 인증기를 포함하거나 연결함)이 협력하여 의존 당사자에게 사용자가 이전에 등록한 자격 증명 개인 키를 제어하고 있음을 암호학적으로 증명하는 절차를 말합니다(등록 참조). 여기에는 사용자 존재 확인 또는 사용자 검증이 포함됩니다.

WebAuthn 인증 절차는 § 7.2 인증 어설션 검증에 정의되어 있으며, 의존 당사자가 navigator.credentials.get()을 publicKey 인수와 함께 호출하여 시작됩니다. 도입부는 § 5 Web Authentication API를 참조하고, 구현 예시는 § 1.3.3 인증을 참조하세요.

인증 어설션(Authentication Assertion)

어설션(Assertion)

AuthenticatorAssertionResponse 객체는 인증기가 authenticatorGetAssertion 작업의 결과로 반환하는 암호학적으로 서명된 응답입니다.

이는 [CREDENTIAL-MANAGEMENT-1] 명세서의 일회용 credentials와 대응됩니다.

인증기(Authenticator)

WebAuthn 인증기

하드웨어 또는 소프트웨어로 존재하는 암호학적 엔터티로서, 특정 의존 당사자에 대해 사용자를 등록하고 이후에 등록된 공개 키 자격 증명의 소유를 증명할 수 있으며, 선택적으로 사용자를 검증하여 의존 당사자에게 전달할 수 있습니다. 인증기는 등록 시 및 어설션 시 증명을 통해 자신의 유형 및 보안 특성에 관한 정보를 보고할 수 있습니다.

WebAuthn Authenticator는 로밍 인증기, 클라이언트 장치에 통합된 전용 하드웨어 서브시스템, 또는 클라이언트나 클라이언트 장치의 소프트웨어 구성요소일 수 있습니다. WebAuthn 인증기는 지역적 맥락에서만 동작하도록 제한되지 않으며, 클라이언트 측 하드웨어 외부의 서버에 자격 증명 키 쌍을 생성하거나 저장할 수 있습니다.

일반적으로 인증기는 하나의 사용자만 갖는 것으로 가정됩니다. 여러 자연인이 하나의 인증기에 대한 접근을 공유하는 경우, 해당 자연인들은 그 인증기의 맥락에서는 동일한 사용자로 간주됩니다. 만약 인증기 구현이 분리된 구획에서 다수의 사용자를 지원하면, 각 구획은 다른 사용자의 자격 증명에 접근할 수 없는 단일 사용자로서 별개의 인증기로 간주됩니다.

권한 제스처(Authorization Gesture)

권한 제스처는 절차의 일부로 사용자가 인증기와 수행하는 물리적 상호작용을 의미하며, 예를 들어 등록 또는 인증과 같은 절차에서 사용됩니다. 이러한 권한 제스처를 수행함으로써 사용자는 사용자 동의를 제공합니다(즉, 절차의 진행을 허가합니다). 이는 인증기가 가능하면 사용자 검증을 포함할 수 있으며, 또는 단순한 사용자 존재 테스트일 수 있습니다.

백업됨(Backed Up)

공개 키 자격 증명 소스는 생성 인증기 이외의 인증기에서 나타날 수 있도록 어떤 방식으로든 백업될 수 있습니다. 백업은 피어 투 피어 동기화, 클라우드 동기화, 로컬 네트워크 동기화, 수동 내보내기/가져오기 등 여러 메커니즘을 통해 발생할 수 있습니다. 자세한 내용은 § 6.1.3 자격 증명 백업 상태를 참조하세요.

백업 허용성(Backup Eligibility)

백업 가능(Backup Eligible)

Public Key Credential Source의 생성 시점에 생성 인증기가 해당 공개 키 자격 증명 소스가 백업될 수 있는지 여부를 결정합니다. 백업 허용성은 인증기 데이터의 플래그와 현재 백업 상태에 의해 신호됩니다. 백업 허용성은 자격 증명 속성이며 주어진 공개 키 자격 증명 소스에 대해 영구적입니다. 백업 가능인 공개 키 자격 증명 소스는 다중 장치 자격 증명(multi-device credential)이라 부르며, 백업 불가능한 것은 단일 장치 자격 증명(single-device credential)이라 부릅니다. 자세한 내용은 § 6.1.3 자격 증명 백업 상태를 참조하세요.

백업 상태(Backup State)

현재 다중 장치 자격 증명의 백업 상태는 현재 관리 인증기(managing authenticator)에 의해 결정됩니다. 백업 상태는 인증기 데이터의 플래그로 신호되며 시간이 지나면서 변경될 수 있습니다. 또한 백업 허용성 및 § 6.1.3 자격 증명 백업 상태를 참조하세요.

생체 인증기(Biometric Authenticator)

생체 인식(biometric recognition)을 구현하는 모든 인증기를 말합니다.

생체 인식(Biometric Recognition)

개인의 생물학적·행동적 특징을 기반으로 한 자동 인식입니다([ISOBiometricVocabulary]).

바인딩된 자격 증명(Bound credential)

"Authenticator contains a credential"

"Credential created on an authenticator"

공개 키 자격 증명 소스 또는 공개 키 자격 증명은 그 관리 인증기에 바인딩(bound)되어 있다고 합니다. 이는 오직 그 관리 인증기만이 그에 바인딩된 어설션을 생성할 수 있음을 의미합니다.

이를 "관리 인증기(managing authenticator이 contains 바인딩된 자격 증명을 포함한다)" 또는 "바인딩된 자격 증명이 그 관리 인증기에서 생성되었다(created on)"고 표현할 수 있습니다. 다만 서버 측 자격 증명은 인증기 내부의 영구 메모리에 물리적으로 저장되지 않을 수 있으므로, "바인딩된(bound to)"이 기본 용어입니다. 자세한 내용은 § 6.2.2 자격 증명 저장 방식을 참조하세요.

절차(Ceremony)

절차 개념은 인간 노드와 컴퓨터 노드가 함께 작동하고 사용자 인터페이스, 사람 간 통신, 데이터가 포함된 물리적 객체의 전달을 포함하는 통신 링크를 갖는 네트워크 프로토콜 개념의 확장입니다. 프로토콜에서는 아웃-오브-밴드인 것이 절차에서는 인-밴드일 수 있습니다. 이 명세서에서 등록 및 인증은 절차이며, 권한 제스처는 종종 이러한 절차의 구성 요소입니다.

클라이언트(Client)

WebAuthn 클라이언트

여기서는 단순히 클라이언트라고도 합니다. 또한 준수하는 사용자 에이전트도 참조하세요. WebAuthn Client는 일반적으로 사용자 에이전트에 구현된 중개자 역할을 하며, 개념적으로는 Web Authentication API를 하부에서 구현하고 [[Create]](origin, options, sameOriginWithAncestors) 및 [[DiscoverFromExternalSource]](origin, options, sameOriginWithAncestors) 같은 내부 메서드를 구현합니다. 이는 하부의 인증기 연산에 대한 입력을 마샬링하고, 그 결과를 Web Authentication API의 호출자에게 반환하는 역할을 합니다.

WebAuthn Client는 WebAuthn Client Device 상에서 실행되며, 이는 서로 구분됩니다.

클라이언트 장치(Client Device)

WebAuthn 클라이언트 장치

WebAuthn Client가 실행되는 하드웨어 장치, 예를 들어 스마트폰, 노트북 또는 데스크톱 컴퓨터와 그 하드웨어에서 실행되는 운영체제를 의미합니다.

WebAuthn Client device와 클라이언트의 구분은 다음과 같습니다:

• 단일 클라이언트 장치는 동일한 여러 클라이언트(예: 브라우저 구현)를 실행할 수 있으며, 이들은 해당 장치에서 사용할 수 있는 동일한 인증기에 접근할 수 있습니다.

• 플랫폼 인증기는 클라이언트 장치에 바인딩되어 있으며 WebAuthn Client에 바인딩되지 않습니다.

하나의 클라이언트 장치와 클라이언트는 함께 클라이언트 플랫폼을 구성합니다.

클라이언트 플랫폼(Client Platform)

클라이언트 장치와 클라이언트가 함께 클라이언트 플랫폼을 이룹니다. 단일 하드웨어 장치는 서로 다른 운영체제 및/또는 클라이언트를 실행하여 서로 다른 시점에 여러 개의 별개의 클라이언트 플랫폼의 일부가 될 수 있습니다.

클라이언트 측(Client-Side)

일반적으로 이는 사용자의 클라이언트 플랫폼, 인증기 및 이를 모두 연결하는 모든 요소들의 결합을 의미합니다.

클라이언트 측 검색 가능한 공개 키 자격 증명 소스

클라이언트 측 검색 가능한 자격 증명

검색 가능한 자격 증명(Discoverable Credential)

패스키(Passkey)

[DEPRECATED] 거주 자격 증명(Resident Credential)

[DEPRECATED] 거주 키(Resident Key)

참고: 역사적으로, 클라이언트 측 검색 가능한 크리덴셜은 거주(레지던트) 크리덴셜 또는 거주(레지던트) 키로도 알려져 있습니다. ResidentKey와 residentKey라는 용어는 WebAuthn API와 Authenticator Model 모두에서 (예: 딕셔너리 멤버 이름, 알고리즘 변수명, 연산 파라미터 등) 널리 사용되고 있으므로, 이름에 resident라는 단어 사용은 하위 호환성을 위해 변경되지 않았습니다. 또한 이곳에서 거주 키(resident key)는 클라이언트 측 검색 가능한 크리덴셜과 동의어로 정의됩니다.

클라이언트 측 검색 가능한 공개키 크리덴셜 소스(영어 약칭: 검색 가능한 크리덴셜(Discoverable Credential))는, 검색 가능하며, 인증 절차에서 Relying Party가 어떠한 credential ID도 제공하지 않을 때 사용할 수 있는 public key credential source입니다. 즉, Relying Party가 navigator.credentials.get() 호출 시 비어 있는 allowCredentials 인자를 주는 경우를 뜻합니다. 즉, Relying Party가 반드시 사용자를 먼저 식별할 필요가 없음을 의미합니다.

결과적으로, 검색 가능한 크리덴셜 지원 authenticator는 단지 RP ID만 주어져도 검색 가능한 크리덴셜에 대해 assertion signature를 생성할 수 있습니다. 이는 public key credential source가 authenticator 또는 클라이언트 플랫폼에 저장되어 있어야 함을 뜻합니다. 이는 서버 측 공개키 크리덴셜 소스(Server-side Public Key Credential Source)와 대조적이며, 후자는 authenticator에게 RP ID와 credential ID가 모두 제공되어야 하지만 클라이언트 측에 public key credential source를 저장할 필요는 없습니다.

참조: 클라이언트 측 크리덴셜 저장 방식 및 비검색형(non-discoverable) 크리덴셜도 참고하십시오.

참고: 클라이언트 측 검색 가능한 크리덴셜은 인증 절차에서 credential ID가 제공되는 경우(즉, navigator.credentials.get() 호출 시 비어 있지 않은 allowCredentials 인자와 함께 호출할 때)에도 사용할 수 있습니다.

준수하는 사용자 에이전트(Conforming User Agent)

하부의 클라이언트 장치와 협력하여 Web Authentication API 및 본 명세서에 주어진 알고리즘을 구현하고, 인증기와 의존 당사자 간 통신을 처리하는 사용자 에이전트를 말합니다.

자격 증명 ID(Credential ID)

확률적으로 고유한 바이트 시퀀스로서 공개 키 자격 증명 소스와 그에 따른 인증 어설션을 식별합니다. 길이는 최대 1023 바이트입니다.

자격 증명 ID는 인증기에 의해 두 가지 형태로 생성됩니다:

1. 적어도 16바이트이며 최소 100비트의 엔트로피를 포함하는 경우, 또는

2. 공개 키 자격 증명 소스 자체를, 그 안의 Credential ID나 mutable items를 제외한 채로 암호화하여 오직 해당 관리 인증기만 복호화할 수 있게 하는 형태. 이 형태는 인증기를 거의 상태 비저장(state-light)으로 만들 수 있으며, 필요한 상태는 의존 당사자가 저장합니다.

   참고: [FIDO-UAF-AUTHNR-CMDS]는 "Security Guidelines"에서 암호화 기법에 대한 지침을 포함합니다.

의존 당사자는 이 두 가지 자격 증명 ID 형태를 구분할 필요가 없습니다.

자격 증명 키 쌍(Credential Key Pair)

자격 증명 개인 키(Credential Private Key)

자격 증명 공개 키(Credential Public Key)

사용자 공개 키(User Public Key)

자격 증명 키 쌍은 인증기에 의해 생성되며 특정 WebAuthn 의존 당사자에게 범위 지정됩니다. 이는 공개 키 자격 증명의 핵심 요소입니다.

자격 증명 공개 키는 자격 증명 키 쌍의 공개 키 부분입니다. 이 자격 증명 공개 키는 등록 절차 중에 의존 당사자에게 반환됩니다.

자격 증명 개인 키는 자격 증명 키 쌍의 개인 키 부분입니다. 자격 증명 개인 키는 특정 인증기 - 즉 그 관리 인증기에 바인딩되며, 소유자나 인증기 자체에도 노출되어서는 안 됩니다.

자체 증명(self attestation)의 경우에는 자격 증명 키 쌍이 증명 키 쌍으로도 사용된다는 점을 참조하세요(self attestation 참조).

참고: 자격 증명 공개 키는 FIDO UAF의 [UAFProtocol] 및 FIDO U2F의 [FIDO-U2F-Message-Formats]에서 'user public key'로 언급되며, 이 명세서의 일부 관련 부분에서도 동일하게 사용됩니다.

자격 증명 속성(Credential Properties)

자격 증명 속성은 해당 공개 키 자격 증명 소스의 특징적인 속성으로, 예를 들어 그것이 클라이언트 측 검색 가능한 자격 증명인지 또는 서버 측 자격 증명인지 등을 포함합니다.

자격 증명 레코드(Credential Record)

§ 7 WebAuthn 의존 당사자 작업에 정의된 알고리즘을 구현하기 위해, 의존 당사자는 등록된 공개 키 자격 증명 소스의 일부 속성을 저장해야 합니다. 자격 증명 레코드 struct는 이러한 속성들의 추상화입니다. 자격 증명 레코드는 등록 절차 동안 생성되며 이후의 인증 절차에서 사용됩니다. 의존 당사자는 필요하거나 사용자가 요청할 때 자격 증명 레코드를 삭제할 수 있습니다.

다음의 항목들은 § 7.1 새 자격 증명 등록 및 § 7.2 인증 어설션 검증의 모든 단계를 구현하기 위해 권장됩니다:

type

해당 공개 키 자격 증명 소스의 type.

id

해당 공개 키 자격 증명 소스의 Credential ID.

publicKey

해당 공개 키 자격 증명 소스의 자격 증명 공개 키.

signCount

해당 공개 키 자격 증명 소스를 사용한 어떤 절차에서든지 반환된 인증기 데이터의 최신 서명 카운터 값입니다.

transports

getTransports() 호출 시 해당 공개 키 자격 증명 소스가 등록될 때 반환한 값입니다.

참고: getTransports()이 반환한 값에서 항목을 수정하거나 제거하면 사용자 경험에 부정적 영향을 주거나 해당 자격 증명의 사용을 방해할 수 있습니다.

uvInitialized

해당 credential 중 이 공개 키 자격 증명 소스에 대해 UV 플래그가 설정된 적이 있는지를 나타내는 불리언 값입니다.

이 값이 true이면 의존 당사자는 해당 UV 플래그를 인증 절차에서 인증 요소(authentication factor)로 간주할 수 있습니다. 예를 들어 의존 당사자는 uvInitialized가 true이고 UV 플래그가 설정되어 있으면 비록 사용자 검증이 요구되지 않았더라도 비밀번호 프롬프트를 건너뛸 수 있습니다.

이 값이 false인 경우(이를 true로 업데이트할 수 있는 인증 절차를 포함하여), UV 플래그는 authentication factor로 신뢰되어서는 안 됩니다. 이는 공개 키 자격 증명 소스가 처음으로 UV 플래그를 1로 설정했을 때, 아직 의존 당사자와 해당 인증기의 사용자 검증 사이에 신뢰 관계가 확립되지 않았기 때문입니다. 따라서 uvInitialized를 false에서 true로 업데이트할 때는 WebAuthn의 사용자 검증에 상응하는 추가적인 authentication factor에 의한 승인이 필요할 것을 권장합니다.

backupEligible

BE 플래그의 값으로, 해당 공개 키 자격 증명 소스가 생성될 때의 값을 나타냅니다.

backupState

해당 공개 키 자격 증명 소스를 사용하는 어떤 절차에서든지 반환된 인증기 데이터의 BS 플래그의 최신 값을 나타냅니다.

다음의 항목들은 선택사항(OPTIONAL)입니다:

attestationObject

해당 공개 키 자격 증명 소스가 등록될 때의 attestationObject 속성 값입니다. 이를 저장하면 의존 당사자가 이후에 자격 증명의 증명 문장을 참조할 수 있게 됩니다.

attestationClientDataJSON

해당 공개 키 자격 증명 소스가 등록될 때의 clientDataJSON 속성 값입니다. 이를 위의 attestationObject 항목과 함께 저장하면 의존 당사자가 나중에 증명 서명을 재검증할 수 있게 됩니다.

WebAuthn 확장은 확장을 처리하는 데 필요한 추가 항목들을 정의할 수 있습니다. 의존 당사자는 필요에 따라 추가적인 항목을 포함하거나 구현에 필요하지 않은 항목을 생략할 수 있습니다.

자격 증명 레코드에 대한 자격 증명 기술자(credential descriptor)는 다음 내용을 가진 PublicKeyCredentialDescriptor 값입니다:

type

해당 type of the credential record.

id

해당 id of the credential record.

transports

해당 transports of the credential record.

생성 인증기(Generating Authenticator)

생성 인증기(Generating Authenticator)는 특정 공개 키 자격 증명 소스의 생성을 초래하는 authenticatorMakeCredential 작업에 관여한 인증기입니다. 생성 인증기는 단일 장치 자격 증명의 경우 해당 자격 증명의 관리 인증기와 동일합니다. 다중 장치 자격 증명의 경우에는 생성 인증기가 현재 특정 인증 작업에 참여하는 관리 인증기와 같을 수도 있고 다를 수도 있습니다.

사람이 이해하기 쉬운 식별자(Human Palatability)

사람이 기억하고 재현하기 쉬운 식별자는 일반적으로 무작위로 생성된 비트 시퀀스와 달리 일반 사용자들이 기억하고 재현할 수 있도록 의도된 식별자입니다([EduPersonObjectClassSpec] 참조).

비검색 가능 자격 증명(Non-Discoverable Credential)

이것은 credential로서, 자격 증명 ID를 제공하여 allowCredentials 인수를 지정하고 navigator.credentials.get()을 호출해야 하는 자격 증명입니다. 이는 서버 측 자격 증명과 관련이 있습니다.

등록 가능한 오리진 레이블(Registrable Origin Label)

도메인의 도메인 레이블 중 첫 번째 레이블로서, 호스트의 등록 가능한 도메인의 첫 번째 레이블입니다. 등록 가능한 도메인이 null이면 null을 반환합니다. 예를 들어 example.co.uk와 www.example.de의 등록 가능한 오리진 레이블은 각각 example입니다(단, co.uk와 de가 퍼블릭 서픽스일 때).

공개 키 자격 증명(Public Key Credential)

일반적으로 크리덴셜(credential)은 한 엔티티가 다른 엔티티에게 본인을 인증하기 위해 제시하는 데이터입니다 [RFC4949]. 공개키 크리덴셜(public key credential)이라는 용어는 다음 중 하나를 의미합니다: 공개키 크리덴셜 소스, attestation이 추가될 수도 있는 크리덴셜 공개키(credential public key)(이는 공개키 크리덴셜 소스와 대응됨), 또는 인증 어서션(authentication assertion). 어떤 의미인지는 일반적으로 문맥에 따라 결정됩니다.

참고: 이는 [RFC4949]의 정의에 대한 의도적 위반입니다. 영어에서 "credential"은 a) 어떤 진술을 증명하기 위해 제시되는 것과 b) 여러 번 사용될 목적으로 만들어진 것을 동시에 의미할 수 있습니다. 공개 키 시스템에서 단일 데이터가 두 가지 요건을 안전하게 만족시키는 것은 불가능합니다. [RFC4949]은 credential을 여러 번 사용될 수 있는 것(공개 키)으로 정의하지만, 이 명세서는 영어 용어의 유연성을 허용합니다. 이 명세서는 관련 데이터를 더 구체적인 용어로 구분합니다:

"Authentication information" (possibly including a private key)

Public key credential source

"Signed value"

Authentication assertion

[RFC4949] "credential"

Credential public key 또는 attestation object

등록 시점에 인증기는 비대칭 키 쌍을 생성하고 해당 의존 당사자로부터의 정보를 공개 키 자격 증명 소스에 저장합니다. 공개 키 부분은 의존 당사자에게 반환되며, 의존 당사자는 이를 활성 사용자 계정에 저장합니다. 이후 해당 의존 당사자는 그 등록된 자격 증명 공개 키를 사용하여 결과적인 인증 어설션을 검증합니다. 이 공개 키 자격 증명은 등록된 RP ID로 식별된 동일한 엔터티에서만 인증에 사용될 수 있습니다.

공개 키 자격 증명 소스(Public Key Credential Source)

credential source ([CREDENTIAL-MANAGEMENT-1])로서, 인증기가 인증 어설션을 생성하는 데 사용하는 것입니다. 공개 키 자격 증명 소스는 다음과 같은 struct의 항목들으로 구성됩니다:

type

값은 PublicKeyCredentialType이며, 기본값은 public-key입니다.

id

자격 증명 ID(Credential ID)입니다.

privateKey

자격 증명 개인 키입니다.

rpId

이 공개 키 자격 증명 소스가 범위가 지정된 신뢰 당사자 식별자(Relying Party Identifier)입니다. 이는 rp. id 파라미터와 create() 동작에 의해 결정됩니다.

userHandle

이 공개 키 자격 증명 소스가 생성될 때 연결된 사용자 핸들입니다. 이 항목(item)은 null일 수도 있지만, 검색 가능한 자격 증명(discoverable credentials)의 경우 user handle이 항상 채워져 있어야 합니다.

otherUI

인증자(authenticator)가 UI에 정보를 제공할 때 사용하는 선택적 추가 정보입니다. 예를 들어 사용자의 displayName이 포함될 수 있습니다. otherUI는 mutable item이며, 공개 키 자격 증명 소스에 업데이트 가능성을 저해하지 않도록 묶여서는 안 됩니다.

authenticatorMakeCredential 작업은 공개 키 자격 증명 소스를 특정 관리 인증자(managing authenticator)에 바인딩하여 생성하고, 그 자격 증명 공개키를 반환합니다. 이 공개키는 자격 증명 개인키와 연관되어 있습니다. 신뢰 당사자는 이 자격 증명 공개키를 사용하여 이 공개 키 자격 증명 소스가 만든 인증 어설션을 검증할 수 있습니다.

속도 제한(Rate Limiting)

속도 제한(일명 스로틀링)은 인증자가 연속된 인증 실패 시도 횟수를 제한함으로써 무차별 대입(brute force) 공격을 방지하기 위해 제어를 구현하는 역할입니다. 제한에 도달하면 인증자는 각 시도가 반복될수록 지연 시간을 기하급수적으로 증가시키거나, 현재 인증 방식을 비활성화하고 사용 가능한 경우 다른 인증 요소(authentication factor)를 표시해야 합니다. 속도 제한은 사용자 검증(user verification)의 일부로 자주 구현됩니다.

등록(Registration)

등록 절차(Registration Ceremony)

절차(ceremony)로, 사용자와 신뢰 당사자, 사용자 클라이언트 플랫폼(하나 이상의 인증자를 포함/연결)이 협력하여 공개 키 자격 증명을 생성하여 사용자 계정에 연결합니다. 이것은 사용자 존재 테스트(test of user presence)나 사용자 검증(user verification)을 반드시 포함합니다. 등록 절차(registration ceremony)가 성공하면 사용자는 인증 절차(authentication ceremony)를 통해 인증할 수 있습니다.

WebAuthn 등록 절차는 § 7.1 새 자격 증명 등록에 정의되어 있으며, 신뢰 당사자가 navigator.credentials.create() 를 publicKey 인자로 호출함으로써 시작됩니다. § 5 Web Authentication API에서 개요, § 1.3.1 등록에서 구현 예시를 참고하세요.

신뢰 당사자(Relying Party)

WebAuthn 신뢰 당사자(WebAuthn Relying Party)

웹 애플리케이션의 주체로, Web Authentication API를 이용해 사용자를 등록 및 인증합니다.

신뢰 당사자 구현은 보통 Web Authentication API를 호출하는 클라이언트 측 스크립트와 클라이언트 및 신뢰 당사자 서버 동작 및 기타 애플리케이션 로직을 실행하는 서버 측 구성요소로 이루어집니다. 두 구성요소 간의 통신은 반드시 HTTPS 또는 이에 준하는 전송 보안으로 이루어져야 하며, 그 이외 사항은 본 명세의 범위를 벗어납니다.

참고: 신뢰 당사자 용어는 X.509나 OAuth 등 다른 맥락에서도 자주 쓰입니다. 하지만 한 맥락에서 신뢰 당사자로 동작한다고 해서 다른 맥락에서도 반드시 신뢰 당사자인 것은 아닙니다. 본 명세에서 WebAuthn 신뢰 당사자는 약칭으로 단순히 신뢰 당사자라고도 하며, WebAuthn 맥락의 신뢰 당사자를 명시적으로 지칭합니다. 실제로 WebAuthn 환경은 더 광범위한 맥락(예: OAuth 기반) 안에 내장될 수 있습니다.

신뢰 당사자 식별자(Relying Party Identifier)

RP ID

WebAuthn API 맥락에서, 신뢰 당사자 식별자는 유효 도메인 문자열로, 특정 등록 또는 인증 절차가 실행되는 WebAuthn 신뢰 당사자를 식별합니다. 공개 키 자격 증명은 최초 등록시의 같은 주체(RP ID로 구분)에 대해서만 인증에 사용할 수 있습니다.

기본적으로, WebAuthn 동작의 RP ID는 호출자의 origin의 유효 도메인으로 설정됩니다. 이 기본값은 호출자가 제공하는 RP ID 값이 호출자의 origin의 유효 도메인의 등록 가능한 도메인 접미사이거나 동일한 경우에 한해 대체할 수 있습니다. 자세한 내용은 § 5.1.3 새 자격 증명 생성 - PublicKeyCredential의 [[Create]](origin, options, sameOriginWithAncestors) 내부 메서드 및 § 5.1.4 기존 자격 증명을 사용한 어설션 생성을 참고하세요.

RP ID는 호스트의 도메인 이름을 기반으로 합니다. (origin과 달리) 자체적으로 스킴이나 포트를 포함하지 않습니다. 공개 키 자격 증명의 RP ID는 해당 자격 증명의 범위(scope)를 결정합니다. 다시 말해, 해당 공개 키 자격 증명을 사용할 수 있는 origin의 집합을 결정합니다:

• RP ID는 반드시 origin의 유효 도메인과 같거나, 등록 가능한 도메인 접미사여야 합니다.

• 다음 중 하나가 참이어야 합니다:

  • origin의 스킴이 https이다.

  • origin의 host가 localhost이고, 스킴이 http이다.

• origin의 포트(port)는 제한되지 않습니다.

예를 들어, origin이 https://login.example.com:1337인 신뢰 당사자의 경우, RP ID로 login.example.com(기본), example.com은 가능하지만, m.login.example.com, com은 허용되지 않습니다. 또 다른 예시로 http://localhost:8000도 origin이 localhost이므로 유효합니다.

이는 쿠키 등 널리 배포된 환경 자격 증명(ambient credentials, 예: [RFC6265])의 동작과 맞추기 위함입니다. 여기서의 처리 범위는 document.domain의 setter가 제공하는 "동일 출처"보다 완화되어 있음을 유의하세요.

이러한 origin 값 제한은 WebAuthn 클라이언트에 적용됩니다.

다른 규격에서 WebAuthn 공개 키 자격 증명을 네이티브 모바일 앱 등 Web 플랫폼 이외 환경에서 사용하도록 WebAuthn API와 유사하게 구현하는 경우에는, 호출자를 신뢰 당사자 식별자에 바인딩하는 규칙을 다르게 정의할 수 있습니다. 다만, RP ID 문법은 반드시 유효 도메인 문자열이나 URI([RFC3986] [URL]) 규격을 따라야 합니다.

서버 측 공개 키 자격 증명 소스(Server-side Public Key Credential Source)

서버 측 자격 증명(Server-side Credential)

[DEPRECATED] 비상주 자격 증명(Non-Resident Credential)

참고: 서버 측 자격 증명은 과거에는 비상주 자격 증명(non-resident credential)으로 알려졌습니다. 하위 호환성을 위해 WebAuthn API 및 Authenticator Model 구성요소 중 resident 관련 이름은 변경되지 않았습니다.

서버 측 공개 키 자격 증명 소스 또는 약칭으로 서버 측 자격 증명은 공개 키 자격 증명 소스 중에서 오직 신뢰 당사자가 navigator.credentials.get()의 allowCredentials 인자로 그 자격 증명 ID를 제공할 때에만 인증 절차에서 사용할 수 있습니다. 즉, 신뢰 당사자가 자격 증명의 저장 및 식별 관리를 책임져야 하며, 사용자를 미리 식별해서 자격 증명 ID 목록을 제공할 수 있어야 합니다.

클라이언트 측에서 공개 키 자격 증명 소스를 저장하는 것은 서버 측 자격 증명에는 필요하지 않습니다. 반면, 클라이언트 측 검색 가능한 자격 증명(client-side discoverable credential)은 사용자를 미리 식별하지 않고도 자격 증명 ID를 navigator.credentials.get() 인자에 제공할 수 있습니다.

참고: 서버 측 자격 증명 저장 방식(server-side credential storage modality) 및 비검색 자격 증명(non-discoverable credential)도 참고하세요.

사용자 존재 테스트(Test of User Presence)

사용자 존재 테스트는 권한 부여 제스처(authorization gesture)의 한 형태이자, 사용자가 인증자와 단순히 접촉(다른 방식도 있음)하는 기술적 절차로, Boolean(참/거짓) 결과를 제공합니다. 이 테스트는 사용자 검증(user verification)에는 해당하지 않습니다. 사용자 존재 테스트는 본질적으로 생체 인식이 불가능하며, 공유 비밀번호나 PIN 등 비밀 입력도 포함하지 않습니다.

사용자 계정(User Account)

본 명세의 맥락에서 사용자 계정은 일련의 자격 증명 ([CREDENTIAL-MANAGEMENT-1])을 신뢰 당사자 소유의 일부 리소스에 매핑한 것으로, 신뢰 당사자에 의해 관리 및 허가됩니다. 신뢰 당사자는 공개 키 자격 증명에 대해 사용자 핸들을 할당하고, 자격 증명 기록(credential record)을 사용자 계정에 저장함으로써 자격 증명을 사용자 계정과 연결합니다. 이 매핑, 자격 증명 집합, 권한 정보는 시간이 지남에 따라 변할 수 있습니다. 사용자 계정 하나가 여러 자연인(게 사용자)에 의해 접근될 수도 있고, 한 자연인이 여러 사용자 계정에 접근할 수도 있습니다. 이는 사용자/신뢰 당사자 동작에 따라 달라질 수 있습니다.

사용자 동의(User Consent)

사용자 동의란 사용자가 요청받는 내용에 동의하는 것(예: 안내문을 읽고 이해함)을 의미합니다. 권한 부여 제스처는 절차(ceremony)의 한 부분으로, 사용자 동의(user consent)를 표시하는 데 자주 사용됩니다.

사용자 핸들(User Handle)

사용자 핸들은 사용자 계정의 식별자로, 신뢰 당사자가 user. id 에 지정합니다(등록 때). 검색 가능한 자격 증명(discoverable credentials)은 이 식별자를 저장하고, 인증 절차(authentication ceremonies)에서, response. userHandle 에 반드시 반환해야 합니다. (단, 빈 allowCredentials 인자로 시작한 경우)

사용자 핸들의 주요 역할은 이러한 인증 절차에서 사용자 계정을 식별하는 것입니다. 자격 증명 ID도 사용할 수 있지만, 자격 증명 ID는 인증자가 정해 각 자격 증명마다 독립적이고, user handle은 신뢰 당사자가 지정해 같은 자격 증명 집합 모두에 동일하게 할당해야 한다는 점이 다릅니다.

인증자는 RP ID와 사용자 핸들의 쌍을 공개 키 자격 증명 소스에 매핑합니다. 이로 인해 인증자는 하나의 user handle 및 신뢰 당사자별로 최다 하나의 검색 가능한 자격 증명만 저장합니다. 따라서 사용자 핸들은 인증자가 등록 절차(registration ceremony) 중 기존 검색 가능한 자격 증명을 새 것으로 교체해야 하는지 판단하는 데에도 사용됩니다.

사용자 핸들은 최대 64바이트 길이의 불투명한 바이트 시퀀스로, 사용자에게 표시해서는 안 됩니다. 개인정보 식별 정보가 포함되어선 안 되며, § 14.6.1 사용자 핸들 내용 참조.

사용자가 존재함(User Present)

사용자 존재 테스트가 성공적으로 완료되면 사용자가 "존재한다"고 간주합니다.

사용자 검증(User Verification)

인증자가 authenticatorMakeCredential 및 authenticatorGetAssertion 동작 호출을 로컬에서 허가하는 기술적 과정입니다. 사용자 검증(user verification)은 다양한 권한 부여 제스처로 유도될 수 있습니다. 예를 들어 터치 후 PIN, 비밀번호 입력, 생체 인식(biometric recognition) 등 (지문 등) ([ISOBiometricVocabulary])이 목적입니다. 이는 개별 사용자의 식별을 구분하려는 의도를 갖습니다. 자세한 내용은 § 6.2.3 인증 요소 능력(Authentication Factor Capability) 참조.

사용자 검증만으로 신뢰 당사자가 사용자 본인을 정확히 식별할 수 있는 것은 아니지만, 똑같은 자격 증명으로 2회 이상 사용자 검증이 수행됐다면 항상 동일 사용자가 해당 과정을 실행했음을 표현합니다. 단, 하나의 인증자를 여러 자연인이 공유하면 논리적 동일 사용자와 실제 자연인이 반드시 일치하진 않습니다.

참고: 자연인 구분은 클라이언트 플랫폼과 인증자의 역량에 크게 달려 있습니다. 예를 들어, 단일 사용자가 쓰는 기기로 설계되었지만, 여러 자연인이 지문을 등록하거나 같은 PIN을 공유할 수 있는 경우라면 여러 계정(user account)에도 접근 가능할 수 있습니다.

참고: authenticatorMakeCredential 및 authenticatorGetAssertion 호출은 인증자에서 관리하는 키 자료의 사용을 의미합니다.

보안을 위해, 사용자 검증 및 자격 증명 개인키 사용은 모두 반드시 인증자가 정의하는 논리(적) 보안 경계 안에서 이루어져야 합니다.

사용자 검증 절차는 무차별 대입 공격에 대한 방어책으로 속도 제한(rate limiting)을 구현할 수 있습니다.

사용자 검증됨(User Verified)

사용자 검증 과정이 성공적으로 완료되면, 사용자가 "검증됨"으로 간주합니다.

5. 웹 인증 API

이 절에서는 공개 키 자격 증명을 생성하고 사용하는 API를 규범적으로 명세합니다. 기본 개념은 자격 증명이 사용자에게 속하고 인증기에 의해 관리되며, WebAuthn 인증기와 WebAuthn Relying Party가 클라이언트 플랫폼을 통해 상호작용한다는 것입니다. Relying Party 스크립트는 (사용자 동의(user’s consent)를 얻어) 브라우저에 Relying Party가 향후 사용할 새 자격 증명을 생성하도록 요청할 수 있습니다. 아래 그림 을 참조하세요.

스크립트는 또한 기존 자격 증명으로 인증 작업을 수행하는 것에 대해 사용자의 허가를 요청할 수 있습니다. 아래 그림 을 참조하세요.

이러한 모든 작업은 인증기에서 수행되며 사용자를 대신해 클라이언트 플랫폼에 의해 중개됩니다. 스크립트가 자격 증명 자체에 접근하는 일은 전혀 없으며, 오직 객체 형태로 된 자격 증명에 대한 정보만 받게 됩니다.

위의 스크립트 인터페이스 외에도, 인증기는 사용자 인터페이스를 구현(MAY)하거나 해당 기능을 구현하는 클라이언트 소프트웨어와 함께 제공될 수 있습니다. 이러한 인터페이스는 예를 들어 인증기를 초기 상태로 재설정하거나 인증기의 현재 상태를 검사하는 데 사용될 수 있습니다. 다시 말해, 이러한 인터페이스는 기록, 저장된 암호, 쿠키 등과 같은 사용자 상태를 관리하기 위해 브라우저가 제공하는 사용자 인터페이스와 유사합니다. 자격 증명 삭제와 같은 인증기 관리 작업은 그러한 사용자 인터페이스의 책임으로 간주되며 스크립트에 노출된 API에서는 의도적으로 제외됩니다.

이 API의 보안 특성은 클라이언트와 인증기가 함께 동작함으로써 제공됩니다. 자격 증명을 보유하고 관리하는 인증기는 모든 작업이 특정 기원(origin)에 범위가 지정되어 있으며, 응답에 기원을 포함시켜 다른 기원에 대해 재생(replay)될 수 없도록 보장합니다. 구체적으로는, § 6.3 Authenticator Operations에 정의된 바와 같이 요청자의 전체 기원이 포함되어 서명되며, 이는 새 자격 증명이 생성될 때 생성되는 attestation object와 WebAuthn 자격 증명이 생성하는 모든 assertion에 포함됩니다.

추가로 사용자 프라이버시를 유지하고 악의적인 Relying Party가 다른 Relying Party에 속한 공개 키 자격 증명의 존재를 탐지하는 것을 방지하기 위해, 각 자격 증명은 범위가 지정되어 Relying Party 식별자 또는 RP ID에 한정됩니다. 이 RP ID는 모든 작업에 대해 클라이언트가 인증기에 제공하며, 인증기는 Relying Party에 의해 생성된 자격 증명이 동일한 RP ID로 요청된 작업에서만 사용될 수 있도록 보장합니다. 이렇게 기원(origin)과 RP ID를 분리하면 단일 Relying Party가 여러 기원을 유지하는 경우에도 API를 사용할 수 있게 됩니다.

클라이언트는 이러한 보안 조치를 돕기 위해 각 작업에 대해 Relying Party의 기원(origin) 및 RP ID를 인증기에 제공합 니다. 이것은 WebAuthn 보안 모델의 핵심 부분이므로, 사용자 에이전트는 이 API를 보안 컨텍스트(secure contexts)에서만 호출자에게 노출합니다. 특히 웹 컨텍스트의 경우, 이는 오류 없이 설정된 보안 전송(예: TLS)을 통해 접근되는 컨텍스트만 포함합니다.

Web Authentication API는 다음 섹션에 제시된 Web IDL 조각들의 합집합으로 정의됩니다. 결합된 IDL 목록은 IDL 색인에 제공됩니다.

5.1. PublicKeyCredential 인터페이스

이 PublicKeyCredential 인터페이스는 Credential [CREDENTIAL-MANAGEMENT-1]로부터 상속되며, 새 자격 증명이 생성되거나 새 assertion이 요청될 때 호출자에게 반환되는 속성을 포함합니다.

[SecureContext, Exposed=Window]
interface PublicKeyCredential : Credential {
    [SameObject] readonly attribute ArrayBuffer              rawId;
    [SameObject] readonly attribute AuthenticatorResponse    response;
    readonly attribute DOMString?                            authenticatorAttachment;
    AuthenticationExtensionsClientOutputs getClientExtensionResults();
    static Promise<boolean> isConditionalMediationAvailable();
    PublicKeyCredentialJSON toJSON();
};

id

이 속성은 Credential로부터 상속되지만, PublicKeyCredential 은 Credential의 getter를 재정의하여 객체의 [[identifier]] 내부 슬롯에 포함된 데이터의 base64url 인코딩을 대신 반환합니다.

rawId

이 속성은 ArrayBuffer 형태로 [[identifier]] 내부 슬롯에 포함된 값을 반환합니다.

response, of type AuthenticatorResponse, readonly

이 속성은 새 공개 키 자격 증명을 생성하거나 인증 어설션을 생성하라는 클라이언트의 요청에 대한 인증기의 응답을 포함합니다. 만약 PublicKeyCredential 이 create()에 대한 응답으로 생성되었다면, 이 속성의 값은 AuthenticatorAttestationResponse가 될 것이고, 그렇지 않다면 이 PublicKeyCredential 은 get()에 대한 응답으로 생성되었으며 이 속성의 값은 AuthenticatorAssertionResponse가 됩니다.

authenticatorAttachment, of type DOMString, readonly, nullable

이 속성은 authenticator attachment modality를 보고하며, navigator.credentials.create() 또는 navigator.credentials.get() 호출이 성공적으로 완료되었을 때 적용된 값을 나타냅니다. 이 속성의 값은 AuthenticatorAttachment의 멤버여야 합니다. Relying Parties는 알 수 없는 값을 null로 처리해야 합니다.

Note: 만약 등록 절차 또는 인증 절차의 결과로 authenticatorAttachment의 값이 "cross-platform"이고 동시에 isUserVerifyingPlatformAuthenticatorAvailable 가 true를 반환한다면, 사용자는 그 절차에서 로밍 인증기를 사용했고 동시에 사용 가능한 플랫폼 인증기가 있다는 뜻입니다. 따라서 Relying Party는 사용자가 사용 가능한 플랫폼 인증기를 등록하도록 유도할 기회를 가집니다. 이는 보다 원활한 사용자 경험을 가능하게 할 수 있습니다.

인증기의 attachment modality는 시간이 지남에 따라 변경될 수 있습니다. 예를 들어, 휴대전화는 한 시점에서는 플랫폼 부착(platform attachment)만 지원할 수 있지만 이후 업데이트를 통해 크로스-플랫폼 부착(cross-platform attachment)도 지원하게 될 수 있습니다.

getClientExtensionResults()

이 연산은 [[clientExtensionsResults]]의 값을 반환합니다. 이 값은 확장의 클라이언트 확장 출력을 생성한 확장 식별자 → 출력 간의 항목들을 포함하는 맵입니다.

isConditionalMediationAvailable()

PublicKeyCredential 은 이 메서드를 재정의하여 conditional 중재가 navigator.credentials.get() 동안 사용 가능한지를 나타냅니다. WebAuthn Relying Parties는 options.mediation을 conditional로 설정하기 전에 사용 가능 여부를 확인하는 것이 권장됩니다.

이 메서드를 호출하면, true로 해석되는 경우 conditional 사용자 중재(user mediation)가 사용 가능함을 나타내며 그렇지 않으면 false로 해결되는 약속(Promise)이 반환됩니다.

이 메서드는 인수를 받지 않으며 불리언 값을 반환하는 약속을 반환합니다.

클라이언트 기능인 conditionalGet은 이 약속이 true로 해결되는 것과 동등합니다.

Note: 만약 이 메서드가 존재하지 않는다면, conditional 사용자 중재는 navigator.credentials.get()에 대해 사용 불가능한 것으로 간주됩니다.

Note: 이 메서드는 conditional 사용자 중재가 navigator.credentials.create()에 대해 사용 가능한지를 나타내지는 않습니다. 이 경우에는 conditionalCreate 기능을 getClientCapabilities()에서 확인해야 합니다.

toJSON()

이 연산은 RegistrationResponseJSON 또는 AuthenticationResponseJSON를 반환합니다. 이는 PublicKeyCredential을 반영하는 JSON 타입 표현으로, Relying Party 서버에 application/json 페이로드로 제출하기에 적합합니다. 클라이언트는 일반적인 방식으로 값을 JSON 타입으로 직렬화할 책임이 있지만, 먼저 모든 ArrayBuffer 값을 DOMString 값으로 변환하기 위해 base64url 인코딩을 반드시 수행해야 합니다.

RegistrationResponseJSON.clientExtensionResults 또는 AuthenticationResponseJSON.clientExtensionResults 멤버는 getClientExtensionResults()의 출력을 설정해야 하며, 이때 ArrayBuffer 값들은 base64url 인코딩을 사용해 DOMString 값으로 인코딩되어야 합니다. 이에는 IANA "WebAuthn Extension Identifiers" 레지스트리에 등록되어 있지만 § 9 WebAuthn Extensions에 정의되지 않은 확장으로부터의 ArrayBuffer 값이 포함될 수 있습니다.

AuthenticatorAttestationResponseJSON.transports 멤버는 getTransports()의 출력을 설정해야 합니다.

AuthenticatorAttestationResponseJSON.publicKey 멤버는 getPublicKey()의 출력을 설정해야 합니다.

AuthenticatorAttestationResponseJSON.publicKeyAlgorithm 멤버는 getPublicKeyAlgorithm()의 출력을 설정해야 합니다.

typedef DOMString Base64URLString;
// The structure of this object will be either
// RegistrationResponseJSON or AuthenticationResponseJSON
typedef object PublicKeyCredentialJSON;

dictionary RegistrationResponseJSON {
    required DOMString id;
    required Base64URLString rawId;
    required AuthenticatorAttestationResponseJSON response;
    DOMString authenticatorAttachment;
    required AuthenticationExtensionsClientOutputsJSON clientExtensionResults;
    required DOMString type;
};

dictionary AuthenticatorAttestationResponseJSON {
    required Base64URLString clientDataJSON;
    required Base64URLString authenticatorData;
    required sequence<DOMString> transports;
    // The publicKey field will be missing if pubKeyCredParams was used to
    // negotiate a public-key algorithm that the user agent doesn't
    // understand. (See section “Easily accessing credential data” for a
    // list of which algorithms user agents must support.) If using such an
    // algorithm then the public key must be parsed directly from
    // attestationObject or authenticatorData.
    Base64URLString publicKey;
    required COSEAlgorithmIdentifier publicKeyAlgorithm;
    // This value contains copies of some of the fields above. See
    // section “Easily accessing credential data”.
    required Base64URLString attestationObject;
};

dictionary AuthenticationResponseJSON {
    required DOMString id;
    required Base64URLString rawId;
    required AuthenticatorAssertionResponseJSON response;
    DOMString authenticatorAttachment;
    required AuthenticationExtensionsClientOutputsJSON clientExtensionResults;
    required DOMString type;
};

dictionary AuthenticatorAssertionResponseJSON {
    required Base64URLString clientDataJSON;
    required Base64URLString authenticatorData;
    required Base64URLString signature;
    Base64URLString userHandle;
};

dictionary AuthenticationExtensionsClientOutputsJSON {
};

[[type]]

PublicKeyCredential 인터페이스 객체의 [[type]] 내부 슬롯 값은 문자열 "public-key"입니다.

Note: 이는 type 속성 getter를 통해 반영됩니다 (Credential로부터 상속됨).

[[discovery]]

PublicKeyCredential 인터페이스 객체의 [[discovery]] 내부 슬롯 값은 "remote"입니다.

[[identifier]]

이 내부 슬롯은 인증기가 선택한 자격 증명 ID를 포함합니다. 자격 증명 ID는 자격 증명을 조회하는 데 사용되며, 동일 유형의 모든 자격 증명과 모든 인증기에서 높은 확률로 전역적으로 유일할 것으로 기대됩니다.

이 API는 이 식별자의 형식을 제약하지 않지만, 그 길이는 1023 바이트를 초과해서는 안 되며 인증기가 키를 고유하게 선택할 수 있을 만큼 충분해야 합니다. 예를 들어, 온보드 저장소가 없는 인증기는 대칭 키로 감싼 자격 증명 개인 키를 포함하는 식별자를 생성할 수 있습니다(해당 대칭 키는 인증기에 내장됨).

[[clientExtensionsResults]]

이 내부 슬롯은 내부 슬롯로, Relying Party가 navigator.credentials.create() 또는 navigator.credentials.get()를 호출할 때 요청한 클라이언트 확장 처리 결과를 포함합니다.

PublicKeyCredential의 인터페이스 객체는 Credential의 [[CollectFromCredentialStore]](origin, options, sameOriginWithAncestors) 구현을 상속하며, 자체적으로 [[Create]](origin, options, sameOriginWithAncestors), [[DiscoverFromExternalSource]](origin, options, sameOriginWithAncestors), 및 [[Store]](credential, sameOriginWithAncestors)의 자체 구현을 정의합니다.

만약 CredentialsContainer의 preventSilentAccess() 메서드를 호출하더라도 PublicKeyCredential 자격 증명에는 영향이 없습니다. 이 자격 증명은 항상 사용자 상호작용을 요구하기 때문입니다.

5.1.1. CredentialCreationOptions 사전 확장

navigator.credentials.create()를 통해 등록을 지원하기 위해, 이 문서는 CredentialCreationOptions 사전을 다음과 같이 확장합니다:

partial dictionary CredentialCreationOptions {
    PublicKeyCredentialCreationOptions      publicKey;
};

5.1.2. CredentialRequestOptions 사전 확장

navigator.credentials.get()를 통해 어설션을 얻는 것을 지원하기 위해, 이 문서는 CredentialRequestOptions 사전을 다음과 같이 확장합니다:

partial dictionary CredentialRequestOptions {
    PublicKeyCredentialRequestOptions      publicKey;
};

5.1.3. 새 자격 증명 만들기 - PublicKeyCredential의 [[Create]](origin, options, sameOriginWithAncestors) 내부 메서드

5.1.3.1. 생성 요청 예외

이 절은 규범적이지 않습니다.

WebAuthn Relying Parties는 navigator.credentials.create() 호출에서 여러 예외를 마주칠 수 있습니다. 일부 예외는 발생 원인이 여러 가지일 수 있어, WebAuthn Relying Parties가 WebAuthn 사용 상황을 바탕으로 실제 원인을 추론해야 할 수 있습니다.

참고: 이 명세 외부에서 정의된 것을 포함하여 모든 WebAuthn Extensions의 처리 중 발생할 수 있는 예외는 여기에는 나열되지 않습니다.

다음의 DOMException 예외들이 발생할 수 있습니다:

AbortError

절차가 AbortController에 의해 취소되었습니다. 자세한 내용은 § 5.6 Abort Operations with AbortSignal 및 § 1.3.4 Aborting Authentication Operations를 참조하세요.

ConstraintError

다음 중 하나입니다: residentKey 가 required 로 설정되었으나 사용 가능한 인증기가 resident key를 지원하지 않았거나, userVerification 이 required 로 설정되었으나 사용 가능한 인증기가 user verification을 수행할 수 없었던 경우입니다.

InvalidStateError

인증 과정에서 사용된 인증기가 사용자가 동의한 후에 excludeCredentials 목록에 있는 항목을 인식했을 때 발생합니다.

NotSupportedError

pubKeyCredParams 에 있는 항목 중 어떤 것도 type 이 public-key 이 아니었거나, authenticator가 pubKeyCredParams 에 명시된 서명 알고리즘 중 어느 것도 지원하지 않는 경우입니다.

SecurityError

effective domain이 유효한 domain이 아니거나, 또는 rp.id 가 effective domain과 같거나 그 등록 가능한 도메인 접미사가 아닌 경우입니다. 후자의 경우, 클라이언트는 related origin requests를 지원하지 않거나 related origins validation procedure가 실패한 것입니다.

NotAllowedError

사용자가 절차를 취소하는 등 다양한 가능한 원인을 포괄하는 포괄적 오류입니다. 이러한 원인 중 일부는 이 명세 전반에 문서화되어 있으며, 다른 것들은 클라이언트 특유의 원인일 수 있습니다.

다음의 단순 예외(simple exceptions)들도 발생할 수 있습니다:

TypeError

options 인수가 유효한 CredentialCreationOptions 값이 아니거나, user.id 의 값이 비어 있거나 64 바이트보다 긴 경우입니다.

5.1.4. 기존 자격 증명을 사용하여 어설션 생성

WebAuthn Relying Parties는 navigator.credentials.get({publicKey:..., ...}) 를 호출하여 기존의 public key credential을 검색하고 사용자 동의(user’s consent)를 얻어 사용합니다. Relying Party 스크립트는 선택적으로 어떤 public key credential sources가 허용되는지에 대한 기준을 지정할 수 있습니다. client platform은 지정된 기준에 맞는 public key credential sources를 찾아 사용자가 스크립트가 사용하도록 허용할 자격 증명을 선택하도록 안내합니다. 예를 들어 사용자는 프라이버시를 유지하기 위해 전체 상호작용을 거부할 수 있습니다. 사용자가 public key credential source를 선택하면, 사용자 에이전트는 § 6.3.3 The authenticatorGetAssertion Operation을 사용하여 Relying Party가 제공한 challenge와 다른 수집된 데이터를 서명해 authentication assertion을 생성하고, 이를 credential로 사용합니다.

navigator.credentials.get() 구현은 [CREDENTIAL-MANAGEMENT-1]에 따라 PublicKeyCredential.[[CollectFromCredentialStore]]() 를 호출하여 사용자 중재 없이 사용 가능해야 할 credentials을 수집합니다(대략적으로 이 명세의 authorization gesture). 만약 정확히 하나가 발견되지 않으면, PublicKeyCredential.[[DiscoverFromExternalSource]](origin, options, sameOriginWithAncestors) 를 호출하여 사용자가 public key credential source를 선택하도록 합니다.

이 명세는 어떤 authorization gesture이든 간에 어설션을 생성하려면 필요하므로, PublicKeyCredential 은 [[CollectFromCredentialStore]](origin, options, sameOriginWithAncestors) 의 기본 동작(빈 집합 반환)을 상속합니다. PublicKeyCredential의 [[DiscoverFromExternalSource]](origin, options, sameOriginWithAncestors) 구현은 다음 섹션에서 명세됩니다.

일반적으로 사용자 에이전트는 인증기 선택 및 승인 과정을 사용자에게 안내하기 위해 일부 UI를 표시해야 합니다. options.mediation 를 conditional 로 설정하면, Relying Parties는 자격 증명이 발견되지 않는 한 눈에 띄는 모달 UI를 표시하지 않도록 요청할 수 있습니다. Relying Party는 이 기능이 사용 가능한지 확인하기 위해 먼저 isConditionalMediationAvailable() 또는 getClientCapabilities() 를 사용하여 client가 conditionalGet 기능을 지원하는지 확인해야 합니다. 그렇지 않으면 사용자에게 보이는 오류가 발생할 수 있습니다.

모든 navigator.credentials.get() 작업은 AbortController 를 사용하여 중단될 수 있습니다; 자세한 지침은 DOM § 3.3 Using AbortController and AbortSignal objects in APIs를 참조하세요.

5.1.4.1. PublicKeyCredential의 [[DiscoverFromExternalSource]](origin, options, sameOriginWithAncestors) 내부 메서드

5.1.4.2. 인증기에게 자격 증명 요청 발행

이 [[DiscoverFromExternalSource]](origin, options, sameOriginWithAncestors)의 하위 알고리즘은 주어진 credential을 주어진 authenticator에 요청하기 위해 필요한, UI 문맥에 독립적인 구체적인 단계를 포괄합니다. 이 알고리즘은 [[DiscoverFromExternalSource]](origin, options, sameOriginWithAncestors)에서 현재의 user mediation 유형(예: conditional mediation 등)에 따라 여러 지점에서 호출됩니다.

이 알고리즘은 다음 인수들을 받습니다:

authenticator

이 값은 이 client platform에 현재 연결된 authenticator를 식별하는 플랫폼별 핸들입니다.

savedCredentialIds

이 인수는 map이며, authenticator → credential ID를 포함합니다. 이 알고리즘에서 이 인수는 수정됩니다.

pkOptions

이 인수는 PublicKeyCredentialRequestOptions 객체로, 검색할 public key credential의 원하는 속성을 지정합니다.

rpId

요청의 RP ID입니다.

clientDataHash

clientDataJSON로 표현된 직렬화된 클라이언트 데이터의 해시입니다.

authenticatorExtensions

이 인수는 map이며, extension identifiers를 키로 하고 base64url 인코딩된 client extension processing 결과(인증기 확장용)를 값으로 가집니다.

이 알고리즘은 authenticator가 요청을 처리할 수 없다고 client가 판단하면 false를 반환하고, 요청이 성공적으로 발행되면 true를 반환합니다.

인증기에게 자격 증명 요청을 발행하는 단계는 다음과 같습니다:

1. 만약 pkOptions.userVerification 가 required 로 설정되어 있고 authenticator가 user verification을 수행할 수 없다면, false를 반환합니다.

2. userVerification를 어설션에 대한 유효한 user verification 요구사항인 불리언 값으로 둡니다. 만약 pkOptions.userVerification이

   가 required로 설정된 경우

   userVerification를 true로 둡니다.

   가 preferred로 설정된 경우

   만약 해당 authenticator가

   user verification을 수행할 수 있다면

   userVerification를 true로 둡니다.

   user verification을 수행할 수 없다면

   userVerification를 false로 둡니다.

   가 discouraged로 설정된 경우

   userVerification를 false로 둡니다.

3. 만약 pkOptions.allowCredentials

   비어있지 않다면

   1. allowCredentialDescriptorList를 새 list로 둡니다.

   2. client platform별 절차를 실행하여, pkOptions.allowCredentials에 기술된 어떤 public key credentials이 이 authenticator에 bound되어 있는지를 rpId와 각 항목의 id, type과 대조하여 판단합니다. 그 필터링된 리스트를 allowCredentialDescriptorList로 설정합니다.

   3. 만약 allowCredentialDescriptorList가 비어있다면, false를 반환합니다.

   4. distinctTransports를 새 ordered set으로 둡니다.

   5. 만약 allowCredentialDescriptorList에 정확히 하나의 값이 있으면, savedCredentialIds[authenticator]를 allowCredentialDescriptorList[0].id의 값으로 설정합니다(자세한 내용은 여기와 § 6.3.3 The authenticatorGetAssertion Operation를 참조하세요).

   6. 각각의 자격 증명 디스크립터 C에 대해 각 항목의 C.transports 값을 distinctTransports에 추가합니다(있는 경우).

      참고: 이는 ordered set의 성질에 따라 distinctTransports에 중복 없이 전송 값들만 집계하게 됩니다.

   7. 만약 distinctTransports가

      비어있지 않다면

      클라이언트는 distinctTransports에서 하나의 transport 값을 선택합니다. 이 선택은 해당 authenticator에 적합한 전송 수단에 대한 로컬 구성 지식을 반영할 수 있습니다.

      그런 다음, 선택된 transport를 사용하여 authenticator에 대해 authenticatorGetAssertion 연산을 rpId, clientDataHash, allowCredentialDescriptorList, userVerification, 및 authenticatorExtensions를 인수로 호출합니다.

      비어있다면

      해당 authenticator에 적합한 전송 수단에 대한 로컬 구성 지식을 사용하여, authenticatorGetAssertion 연산을 authenticator에 대해 rpId, clientDataHash, allowCredentialDescriptorList, userVerification, 및 authenticatorExtensions를 인수로 호출합니다.

   비어 있음

   해당 authenticator에 적합한 전송 수단에 대한 로컬 구성 지식을 사용하여, authenticatorGetAssertion 연산을 authenticator에 대해 rpId, clientDataHash, userVerification, 및 authenticatorExtensions를 인수로 호출합니다.

   참고: 이 경우에는 Relying Party가 허용 가능한 자격 증명 디스크립터 목록을 제공하지 않았으므로, 인증기는 rpId로 식별되는 범위(scope)에 해당하는 어떤 자격 증명이든 사용하도록 요청받는 것입니다.

4. true를 반환합니다.

5.1.4.3. 요청 예외 처리

이 절은 규범적이지 않습니다.

WebAuthn Relying Parties는 navigator.credentials.get() 호출에서 여러 예외를 만날 수 있습니다. 일부 예외는 발생 원인이 여러 개인 경우가 있어, WebAuthn Relying Parties가 WebAuthn 사용 상황을 바탕으로 실제 원인을 추론해야 할 수 있습니다.

Note: 이 명세 외부에서 정의된 것을 포함하여 모든 WebAuthn Extensions의 처리 중 발생할 수 있는 예외는 여기에는 나열되지 않습니다.

다음의 DOMException 예외들이 발생할 수 있습니다:

AbortError

절차가 AbortController에 의해 취소되었습니다. 자세한 내용은 § 5.6 Abort Operations with AbortSignal 및 § 1.3.4 Aborting Authentication Operations를 참조하세요.

SecurityError

effective domain이 유효한 domain이 아니거나, 또는 rp.id가 effective domain과 같거나 그 등록 가능한 도메인 접미사가 아닌 경우입니다. 후자의 경우, 클라이언트는 related origin requests를 지원하지 않거나 related origins validation procedure가 실패한 것입니다.

NotAllowedError

사용자가 절차를 취소하는 등 다양한 가능한 원인을 포괄하는 포괄적 오류입니다. 이러한 원인들 중 일부는 이 명세 전반에 문서화되어 있으며, 다른 것들은 클라이언트 특유의 원인일 수 있습니다.

다음의 단순 예외들도 발생할 수 있습니다:

TypeError

options 인수가 유효한 CredentialRequestOptions 값이 아니었을 경우 발생합니다.

5.1.5. 기존 자격 증명 저장 - PublicKeyCredential의 [[Store]](credential, sameOriginWithAncestors) 내부 메서드

5.1.6. User-Verifying Platform Authenticator의 가용성 - PublicKeyCredential의 isUserVerifyingPlatformAuthenticatorAvailable() 메서드

partial interface PublicKeyCredential {
    static Promise<boolean> isUserVerifyingPlatformAuthenticatorAvailable();
};

5.1.7. 클라이언트 기능의 가용성 - PublicKeyCredential의 getClientCapabilities() 메서드

partial interface PublicKeyCredential {
    static Promise<PublicKeyCredentialClientCapabilities> getClientCapabilities();
};

typedef record<DOMString, boolean> PublicKeyCredentialClientCapabilities;

5.1.8. 등록 절차 옵션 역직렬화 - PublicKeyCredential의 parseCreationOptionsFromJSON() 메서드

partial interface PublicKeyCredential {
    static PublicKeyCredentialCreationOptions parseCreationOptionsFromJSON(PublicKeyCredentialCreationOptionsJSON options);
};

dictionary PublicKeyCredentialCreationOptionsJSON {
    required PublicKeyCredentialRpEntity                    rp;
    required PublicKeyCredentialUserEntityJSON              user;
    required Base64URLString                                challenge;
    required sequence<PublicKeyCredentialParameters>        pubKeyCredParams;
    unsigned long                                           timeout;
    sequence<PublicKeyCredentialDescriptorJSON>             excludeCredentials = [];
    AuthenticatorSelectionCriteria                          authenticatorSelection;
    sequence<DOMString>                                     hints = [];
    DOMString                                               attestation = "none";
    sequence<DOMString>                                     attestationFormats = [];
    AuthenticationExtensionsClientInputsJSON                extensions;
};

dictionary PublicKeyCredentialUserEntityJSON {
    required Base64URLString        id;
    required DOMString              name;
    required DOMString              displayName;
};

dictionary PublicKeyCredentialDescriptorJSON {
    required DOMString              type;
    required Base64URLString        id;
    sequence<DOMString>             transports;
};

dictionary AuthenticationExtensionsClientInputsJSON {
};

5.1.9. 인증 절차 옵션 역직렬화 - PublicKeyCredential의 parseRequestOptionsFromJSON() 메서드들

partial interface PublicKeyCredential {
    static PublicKeyCredentialRequestOptions parseRequestOptionsFromJSON(PublicKeyCredentialRequestOptionsJSON options);
};

dictionary PublicKeyCredentialRequestOptionsJSON {
    required Base64URLString                                challenge;
    unsigned long                                           timeout;
    DOMString                                               rpId;
    sequence<PublicKeyCredentialDescriptorJSON>             allowCredentials = [];
    DOMString                                               userVerification = "preferred";
    sequence<DOMString>                                     hints = [];
    AuthenticationExtensionsClientInputsJSON                extensions;
};

5.1.10. 인증기에게 자격 증명 변경 신호 전송 - PublicKeyCredential의 signal methods

partial interface PublicKeyCredential {
    static Promise<undefined> signalUnknownCredential(UnknownCredentialOptions options);
    static Promise<undefined> signalAllAcceptedCredentials(AllAcceptedCredentialsOptions options);
    static Promise<undefined> signalCurrentUserDetails(CurrentUserDetailsOptions options);
};

dictionary UnknownCredentialOptions {
    required DOMString                     rpId;
    required Base64URLString               credentialId;
};

dictionary AllAcceptedCredentialsOptions {
    required DOMString                     rpId;
    required Base64URLString               userId;
    required sequence<Base64URLString>     allAcceptedCredentialIds;
};

dictionary CurrentUserDetailsOptions {
    required DOMString                     rpId;
    required Base64URLString               userId;
    required DOMString                     name;
    required DOMString                     displayName;
};

WebAuthn Relying Parties는 이러한 signal methods를 사용하여 authenticators에게 public key credentials의 상태를 알릴 수 있으며, 이를 통해 잘못되었거나 폐기된 자격 증명을 업데이트, 제거 또는 숨기도록 할 수 있습니다. Clients는 인증기가 자신의 credentials map을 업데이트할 수 없거나 요청 시점에 연결되어 있지 않을 수 있으므로 이 기능을 기회에 따라 제공할 수 있습니다. 또한 사용자의 동의 없이 사용자의 자격 증명에 관한 정보를 노출하는 것을 피하기 위해, signal methods는 연산의 성공 여부를 나타내지 않습니다. 성공적으로 해결된 프라미스는 단지 options 객체가 올바르게 구성되었음을 의미할 뿐입니다.

각 signal method는 authenticator actions를 포함합니다. Authenticators는 권고된 대로 하지 않고 자체적으로 authenticator actions에서 벗어날 수 있습니다(예: 사용자의 의사에 반한다고 합리적으로 판단되는 변경을 무시하거나, 일부 변경에 대해 사용자에게 확인을 요청하는 등). 따라서 Authenticator actions는 signal methods를 처리하는 권장 방식으로 제공됩니다.

만약 어떤 authenticator가 특정 authenticator action을 처리할 능력이 없다면, clients는 동등한 효과를 달성하기 위해 [FIDO-CTAP]의 authenticatorCredentialManagement 명령과 같은 기존 인프라를 사용할 수 있습니다.

Note: Signal methods는 의도적으로 authenticators가 authenticator actions를 완료할 때까지 기다리지 않습니다. 이 조치는 요청 시간에 따른 응답 타이밍으로 사용자의 자격 증명 가용성에 관한 정보를 사용자 동의 없이 WebAuthn Relying Parties가 얻는 것을 방지합니다.

5.1.10.1. 비동기 RP ID 검증 알고리즘

비동기 RP ID 검증 알고리즘은 signal methods가 RP IDs를 병렬로 검증할 수 있게 합니다. 이 알고리즘은 DOMString rpId를 입력으로 받고, 검증이 실패하면 거절되는 프라미스를 반환합니다. 단계는 다음과 같습니다:

1. effectiveDomain을 relevant settings object의 origin의 effective domain으로 둡니다. 만약 effectiveDomain이 유효한 domain이 아니면 "SecurityError" DOMException로 거절된 프라미스를 반환합니다.

2. 만약 rpId가 effectiveDomain의 registrable domain suffix이거나 같다면, undefined로 해결된 프라미스를 반환합니다.

3. 만약 클라이언트가 related origin requests를 지원하지 않으면 "SecurityError" DOMException로 거절된 프라미스를 반환합니다.

4. p를 새 프라미스로 둡니다.

5. 다음 단계들을 병렬로 실행합니다:

   1. 만약 related origins validation procedure를 callerOrigin과 rpId로 실행한 결과가 true이면, p를 resolve 합니다.

   2. 그렇지 않으면, p를 "SecurityError" DOMException로 reject 합니다.

6. p를 반환합니다.

5.1.10.2. signalUnknownCredential(options)

signalUnknownCredential 메서드는 특정 credential id가 WebAuthn Relying Party에 의해 인식되지 않았음을(예: 사용자가 삭제했음) 알리는 용도입니다. signalAllAcceptedCredentials(options)와 달리, 이 메서드는 전체 수락된 credential IDs 목록 및 userHandle를 전달할 필요가 없으므로, 인증되지 않은 호출자에게 프라이버시 유출을 피합니다(자세한 내용은 § 14.6.3 Privacy leak via credential IDs 참조).

signalUnknownCredential(options) 호출 시 client는 다음 단계를 실행합니다:

1. 만약 base64url 디코딩 결과 options.credentialId가 오류이면, "TypeError"로 거절된 프라미스를 반환합니다.

2. p를 비동기 RP ID 검증 알고리즘을 options.rpId로 실행한 결과로 둡니다.

3. 프라미스 p가 이행되면, 다음 단계들을 병렬로 실행합니다:

   1. 현재 이 client platform에서 사용 가능한 모든 authenticator에 대해, unknownCredentialId authenticator action을 options를 입력으로 하여 호출합니다.

4. p를 반환합니다.

unknownCredentialId authenticator action은 UnknownCredentialOptions options를 받아 다음과 같이 동작합니다:

1. 각각의 해당 public key credential source credential에 대해, 그 authenticator의 credential map을 순회합니다:

   1. 만약 credential의 rpId가 options.rpId와 같고, credential의 id가 base64url 디코딩한 options.credentialId와 같다면, credential을 credentials map에서 제거하거나, 인증기별 절차를 사용해 이후의 authentication ceremonies에서 숨기도록 합니다.

PublicKeyCredential.signalUnknownCredential({
    rpId: "example.com",
    credentialId: "aabbcc"  // 사용자가 방금 시도한 credential id, base64url
});

5.1.10.3. signalAllAcceptedCredentials(options)

특정 사용자의 전체 credential ids 목록을 신호합니다. WebAuthn Relying Parties는 사용자가 인증된 상태이므로 프라이버시 유출 위험이 없는 경우(자세한 내용은 § 14.6.3 Privacy leak via credential IDs 참조) 이 메서드를 signalUnknownCredential()보다 선호해야 합니다. 전체 목록은 사용자의 public key credentials의 전체 스냅샷을 제공하며, 현재 연결된 인증기에 아직 보고되지 않은 변경 사항을 반영할 수 있습니다.

signalAllAcceptedCredentials(options) 호출 시 client는 다음 단계를 실행합니다:

1. 만약 base64url 디코딩 결과 options.userId가 오류이면, "TypeError"로 거절된 프라미스를 반환합니다.

2. 각각의 credentialId에 대해 options.allAcceptedCredentialIds:

   1. 만약 base64url 디코딩 결과 credentialId가 오류이면, "TypeError"로 거절된 프라미스를 반환합니다.

3. p를 비동기 RP ID 검증 알고리즘을 options.rpId로 실행한 결과로 둡니다.

4. 프라미스 p가 이행되면, 다음 단계들을 병렬로 실행합니다:

   1. 현재 이 client platform에서 사용 가능한 모든 authenticator에 대해, allAcceptedCredentialIds authenticator action을 options를 입력으로 하여 호출합니다.

5. p를 반환합니다.

allAcceptedCredentialIds authenticator actions는 AllAcceptedCredentialsOptions options를 입력으로 받아 다음과 같이 동작합니다:

1. userId를 base64url 디코딩한 options.userId의 결과로 둡니다.

2. 단언: userId가 오류가 아님을 보장합니다.

3. credential를 credentials map[options.rpId, userId]로 둡니다.

4. 만약 credential가 존재하지 않으면 이 단계를 중단합니다.

5. 만약 options.allAcceptedCredentialIds 가 포함하지 않는다면, credential을 credentials map에서 제거하거나 인증기별 절차를 사용해 이후 인증 절차에서 숨깁니다.

6. 그렇지 않고, 만약 credential이 인증기별 절차로 이미 숨겨져 있다면, 그 조치를 되돌려 credential이 이후의 인증 절차에서 나타나도록 합니다.

PublicKeyCredential.signalAllAcceptedCredentials({
    rpId: "example.com",
    userId: "aabbcc",  // user handle, base64url.
    allAcceptedCredentialIds: [
        "bb",
    ]
});

Note: 인증기들은 signalAllAcceptedCredentials(options)가 실행될 때 연결되어 있지 않을 수 있습니다. 따라서 WebAuthn Relying Parties는 예를 들어 매번 로그인 시마다 주기적으로 signalAllAcceptedCredentials(options)를 실행하는 것을 선택할 수 있습니다.

Note: allAcceptedCredentialIds에 포함되지 않은 자격 증명은 제거되거나 숨겨져 복구 불가능할 수 있습니다. Relying parties는 유효한 credential IDs가 목록에서 누락되지 않도록 주의해야 합니다. 만약 실수로 유효한 credential ID가 누락되었다면, 가능한 한 빨리 signalAllAcceptedCredentials(options)에 포함시켜(인증기가 지원하면) 다시 표시되게 해야 합니다.

Authenticators는 가능하면 자격 증명을 영구적으로 삭제하기보다는 일정 기간 숨기는 것을 권장합니다. 이는 Relying Party가 실수로 유효한 credential IDs를 목록에서 누락했을 때 복구에 도움이 됩니다.

5.1.10.4. signalCurrentUserDetails(options)

signalCurrentUserDetails 메서드는 사용자의 현재 name 및 displayName을 신호합니다.

signalCurrentUserDetails(options) 호출 시 client는 다음 단계를 실행합니다:

1. 만약 base64url 디코딩 결과 options.userId가 오류이면, "TypeError"로 거절된 프라미스를 반환합니다.

2. p를 비동기 RP ID 검증 알고리즘을 options.rpId로 실행한 결과로 둡니다.

3. 프라미스 p가 이행되면, 다음 단계들을 병렬로 실행합니다:

   1. 현재 이 client platform에서 사용 가능한 모든 authenticator에 대해, currentUserDetails authenticator action을 options를 입력으로 하여 호출합니다.

4. p를 반환합니다.

currentUserDetails authenticator action은 CurrentUserDetailsOptions options를 입력으로 받아 다음과 같이 동작합니다:

1. userId를 base64url 디코딩한 options.userId의 결과로 둡니다.

2. 단언: userId가 오류가 아님을 보장합니다.

3. credential를 credentials map[options.rpId, userId]로 둡니다.

4. 만약 credential가 존재하지 않으면 이 단계를 중단합니다.

5. credential의 otherUI를 options.name 및 options.displayName에 맞게 업데이트합니다.

PublicKeyCredential.signalCurrentUserDetails({
    rpId: "example.com",
    userId: "aabbcc",  // user handle, base64url.
    name: "New user name",
    displayName: "New display name"
});

Note: 인증기들은 signalCurrentUserDetails(options)가 실행될 때 연결되어 있지 않을 수 있습니다. 따라서 WebAuthn Relying Parties는 예를 들어 매번 로그인 시마다 주기적으로 signalCurrentUserDetails(options)를 실행하는 것을 선택할 수 있습니다.

5.2. Authenticator Responses (interface AuthenticatorResponse)

Authenticators는 Relying Party의 요청에 응답할 때 AuthenticatorResponse 인터페이스에서 파생된 객체를 반환합니다:

[SecureContext, Exposed=Window]
interface AuthenticatorResponse {
    [SameObject] readonly attribute ArrayBuffer      clientDataJSON;
};

5.2.1. Information About Public Key Credential (interface AuthenticatorAttestationResponse)

The AuthenticatorAttestationResponse 인터페이스는 새 public key credential 생성을 위한 클라이언트의 요청에 대한 authenticator의 응답을 나타냅니다. 이 응답은 이후에 자격 증명을 식별하는 데 사용할 수 있는 새 자격 증명에 관한 정보와, 등록 시 WebAuthn Relying Party가 자격 증명의 특성을 평가하는 데 사용할 수 있는 메타데이터를 포함합니다.

[SecureContext, Exposed=Window]
interface AuthenticatorAttestationResponse : AuthenticatorResponse {
    [SameObject] readonly attribute ArrayBuffer      attestationObject;
    sequence<DOMString>                              getTransports();
    ArrayBuffer                                      getAuthenticatorData();
    ArrayBuffer?                                     getPublicKey();
    COSEAlgorithmIdentifier                          getPublicKeyAlgorithm();
};

5.2.1.1. Easily accessing credential data

모든 [[Create]](origin, options, sameOriginWithAncestors) 메서드 사용자는 반환된 credential public key를 구문 분석하여 저장해야 하며, 이는 향후 authentication assertions을 검증하는 데 필요합니다. 그러나 credential public key는 COSE 형식으로 되어 있어 attestedCredentialData의 credentialPublicKey 멤버 안의 CBOR 구조입니다. 이것은 authenticator data 안에 있고, attestation object에 포함되어 있고, 이 attestation object는 AuthenticatorAttestationResponse의 attestationObject입니다. Relying Parties는 attestation을 사용하려면 attestationObject를 구문 분석하고 credential public key를 얻어야 합니다. 이는 인증기가 서명한 공개키 복사본이기 때문입니다. 그러나 많은 유효한 WebAuthn 사용 사례에서는 attestation을 필요로 하지 않습니다. 그런 경우 사용자 에이전트가 구문 분석 작업을 수행하고 authenticator data를 직접 노출하며 credential public key를 더 편리한 형식으로 변환할 수 있습니다.

따라서 getPublicKey() 연산은 credential public key를 SubjectPublicKeyInfo로 반환합니다. 이 ArrayBuffer는 예를 들어 Java의 java.security.spec.X509EncodedKeySpec, .NET의 System.Security.Cryptography.ECDsa.ImportSubjectPublicKeyInfo, 또는 Go의 crypto/x509.ParsePKIXPublicKey에 전달할 수 있습니다.

getPublicKey() 사용에는 몇 가지 제한이 있습니다: pubKeyCredParams를 사용하여 Relying Party는 인증기와 협상하여 사용자 에이전트가 이해하지 못할 수 있는 공개키 알고리즘을 사용할 수 있습니다. 그러나 그렇게 하는 경우 사용자 에이전트는 결과 COSE 공개키를 SubjectPublicKeyInfo 형식으로 변환할 수 없으며 getPublicKey()의 반환값은 null이 됩니다.

사용자 에이전트는 getPublicKey()에 대해 null이 아닌 값을 반환할 수 있어야 하며, 그 조건은 credential public key의 COSEAlgorithmIdentifier 값이 다음 중 하나일 때입니다:

• -7 (ES256), 여기서 kty는 2(비압축 점)이고, crv는 1 (P-256)입니다.

• -257 (RS256).

• -8 (EdDSA), 여기서 crv는 6 (Ed25519)입니다.

SubjectPublicKeyInfo는 COSE 공개키에 포함된 서명 알고리즘(예: 어떤 해시 함수를 사용할지)에 관한 정보를 포함하지 않습니다. 이를 제공하기 위해 getPublicKeyAlgorithm() 은 해당 credential public key의 COSEAlgorithmIdentifier를 반환합니다.

많은 경우 CBOR을 전혀 파싱할 필요를 제거하기 위해, getAuthenticatorData() 은 attestationObject에서 authenticator data를 반환합니다. authenticator data는 다른 필드들을 바이너리 형식으로 인코딩하여 포함하지만, 해당 필드들에 접근하기 위한 헬퍼 함수는 제공되지 않습니다. 왜냐하면 Relying Parties는 어설션을 얻을 때 이미 그런 필드를 추출해야 하기 때문입니다. credential creation과 달리 어설션에서의 서명 검증은 항상 수행되어야 하므로, Relying Parties는 서명된 authenticator data에서 필드를 추출해야 하며, 동일한 함수들이 자격 증명 생성 시에도 사용됩니다.

Relying Parties는 이러한 함수들을 사용하기 전에 기능 감지를 수행하여 'getPublicKey' in AuthenticatorAttestationResponse.prototype의 값을 확인해야 합니다.

Note: getPublicKey() 및 getAuthenticatorData() 는 본 명세의 Level 2에서만 추가되었습니다. 이러한 함수들이 존재해야 하는 Relying Parties는 오래된 사용자 에이전트와 상호운용되지 않을 수 있습니다.

5.2.2. Web Authentication Assertion (interface AuthenticatorAssertionResponse)

The AuthenticatorAssertionResponse 인터페이스는 authenticator가 Relying Party의 challenge 및 선택적 자격 증명 목록을 받고 생성한 새로운 authentication assertion에 대한 응답을 나타냅니다. 이 응답은 credential private key의 보유를 증명하는 암호화 서명과, 선택적으로 특정 거래에 대한 사용자 동의에 대한 증거를 포함합니다.

[SecureContext, Exposed=Window]
interface AuthenticatorAssertionResponse : AuthenticatorResponse {
    [SameObject] readonly attribute ArrayBuffer      authenticatorData;
    [SameObject] readonly attribute ArrayBuffer      signature;
    [SameObject] readonly attribute ArrayBuffer?     userHandle;
};

5.3. Parameters for Credential Generation (dictionary PublicKeyCredentialParameters)

dictionary PublicKeyCredentialParameters {
    required DOMString                    type;
    required COSEAlgorithmIdentifier      alg;
};

5.4. Options for Credential Creation (dictionary PublicKeyCredentialCreationOptions)

dictionary PublicKeyCredentialCreationOptions {
    required PublicKeyCredentialRpEntity         rp;
    required PublicKeyCredentialUserEntity       user;

    required BufferSource                             challenge;
    required sequence<PublicKeyCredentialParameters>  pubKeyCredParams;

    unsigned long                                timeout;
    sequence<PublicKeyCredentialDescriptor>      excludeCredentials = [];
    AuthenticatorSelectionCriteria               authenticatorSelection;
    sequence<DOMString>                          hints = [];
    DOMString                                    attestation = "none";
    sequence<DOMString>                          attestationFormats = [];
    AuthenticationExtensionsClientInputs         extensions;
};

5.4.1. 공개 키 엔터티 설명 (dictionary PublicKeyCredentialEntity)

PublicKeyCredentialEntity 딕셔너리는 사용자 계정 또는 WebAuthn Relying Party를 설명하며, 공개 키 자격 증명이 각각 연결되거나 범위 지정된 대상을 의미합니다.

dictionary PublicKeyCredentialEntity {
    required DOMString    name;
};

5.4.2. 자격 증명 생성을 위한 Relying Party 파라미터 (dictionary PublicKeyCredentialRpEntity)

PublicKeyCredentialRpEntity 딕셔너리는 새로운 자격 증명 생성시 추가 Relying Party 속성을 제공하는 데 사용됩니다.

dictionary PublicKeyCredentialRpEntity : PublicKeyCredentialEntity {
    DOMString      id;
};

5.4.3. 자격 증명 생성을 위한 사용자 계정 파라미터 (dictionary PublicKeyCredentialUserEntity)

PublicKeyCredentialUserEntity 딕셔너리는 새로운 자격 증명 생성시 추가 사용자 계정 속성을 제공하는 데 사용됩니다.

dictionary PublicKeyCredentialUserEntity : PublicKeyCredentialEntity {
    required BufferSource   id;
    required DOMString      displayName;
};

5.4.4. 인증기 선택 기준 (dictionary AuthenticatorSelectionCriteria)

WebAuthn Relying Parties는 AuthenticatorSelectionCriteria 딕셔너리를 사용하여 인증기 속성에 대한 요구사항을 지정할 수 있습니다.

dictionary AuthenticatorSelectionCriteria {
    DOMString                    authenticatorAttachment;
    DOMString                    residentKey;
    boolean                      requireResidentKey = false;
    DOMString                    userVerification = "preferred";
};

5.4.5. 인증기 연결 방식 열거형 (enum AuthenticatorAttachment)

이 열거형의 값들은 인증기의 연결 방식을 설명합니다. Relying Parties는 연결 방식 선호도를 navigator.credentials.create() 를 호출하여 자격 증명 생성할 때 지정할 수 있고, 클라이언트는 연결 방식을 등록 또는 등록이나 인증 절차 완료 시 보고합니다.

enum AuthenticatorAttachment {
    "platform",
    "cross-platform"
};

참고: AuthenticatorAttachment 열거형은 의도적으로 참조되지 않습니다. § 2.1.1 DOMString으로서의 열거형 참고.

참고: 인증기 연결 방식 선택 옵션은 [[Create]](origin, options, sameOriginWithAncestors) 작업에서만 사용할 수 있습니다. Relying Party는 예를 들어, 사용자가 로밍 자격 증명으로 다른 클라이언트 디바이스에서 인증하도록 보장하거나, 특정 클라이언트 디바이스에서 더 쉬운 재인증을 위해 플랫폼 자격 증명을 등록할 수 있습니다. [[DiscoverFromExternalSource]](origin, options, sameOriginWithAncestors) 작업에는 연결 방식 선택 옵션이 없습니다. 클라이언트와 사용자는 당시 사용 가능한 자격 증명을 사용하며, allowCredentials 옵션에 의해 제한됩니다.

5.4.6. 리던트 키 요구사항 열거형 (enum ResidentKeyRequirement)

enum ResidentKeyRequirement {
    "discouraged",
    "preferred",
    "required"
};

참고: ResidentKeyRequirement 열거형은 의도적으로 참조되지 않습니다. § 2.1.1 DOMString으로서의 열거형 참고.

이 열거형의 값들은 클라이언트 측에서 탐색 가능한 자격 증명(이전에는 리던트 자격 증명 또는 리던트 키로 알려짐)에 대해 Relying Party의 요구사항을 설명합니다:

참고: Relying Party는 인증기가 클라이언트 측에서 탐색 가능한 자격 증명을 생성했는지 여부를 resident key credential property (Credential Properties Extension)로 확인할 수 있습니다. 이는 discouraged 또는 preferred 가 options.authenticatorSelection.residentKey 에 사용된 경우, 해당 시점의 인증기가 클라이언트 측 탐색 가능 자격 증명이든 서버 측 자격 증명이든 생성 가능성이 있기 때문입니다.

5.4.7. Attestation Conveyance 선호 열거형 (enum AttestationConveyancePreference)

WebAuthn Relying Parties는 자격 증명 생성 중 attestation conveyance에 대해 선호를 지정하기 위해 AttestationConveyancePreference를 사용할 수 있습니다.

enum AttestationConveyancePreference {
    "none",
    "indirect",
    "direct",
    "enterprise"
};

참고: AttestationConveyancePreference 열거형은 의도적으로 참조되지 않았으며, § 2.1.1 DOMString 타입의 열거형을 참고하세요.

5.5. 인증 생성 옵션 (dictionary PublicKeyCredentialRequestOptions)

PublicKeyCredentialRequestOptions 딕셔너리는 get() 이 인증을 생성하는 데 필요한 데이터를 제공합니다. challenge 멤버는 반드시 포함되어야 하며, 나머지 멤버는 선택적입니다.

dictionary PublicKeyCredentialRequestOptions {
    required BufferSource                challenge;
    unsigned long                        timeout;
    DOMString                            rpId;
    sequence<PublicKeyCredentialDescriptor> allowCredentials = [];
    DOMString                            userVerification = "preferred";
    sequence<DOMString>                  hints = [];
    AuthenticationExtensionsClientInputs extensions;
};

challenge, 유형 BufferSource

이 멤버는 인증기가 authentication assertion을 생성할 때 다른 데이터와 함께 서명하는 챌린지를 지정합니다. 자세한 보안 고려사항은 § 13.4.3 암호화 챌린지를 참고하세요.

timeout, 유형 unsigned long

이 선택적 멤버는 Relying Party가 호출 완료 대기 가능 시간(밀리초)을 지정합니다. 이 값은 힌트로 취급되며, 클라이언트가 재정의할 수 있습니다.

rpId, 유형 DOMString

이 선택적 멤버는 Relying Party가 주장하는 RP ID를 지정합니다. 클라이언트는 Relying Party의 origin이 이 RP ID의 scope와 일치하는지 반드시 확인해야 합니다. 인증기는 인증에 사용할 자격 증명의 rpId와 이 RP ID가 정확히 일치하는지도 반드시 확인해야 합니다.

지정하지 않은 경우 CredentialsContainer 객체의 relevant settings object의 origin의 effective domain이 값으로 사용됩니다.

allowCredentials, 유형 sequence<PublicKeyCredentialDescriptor>, 기본값 []

이 선택적 멤버는 클라이언트가 이 인증 과정에 적합한 인증기를 찾을 때 사용됩니다. 사용 예시는 두 가지입니다:

• 인증할 사용자 계정이 이미 식별된 경우(예: 사용자가 사용자명을 입력한 경우), Relying Party는 이 멤버를 사용해 해당 사용자 계정의 크리덴셜 기록에 대한 크리덴셜 디스크립터를 나열해야 합니다. 이는 일반적으로 사용자 계정 안의 모든 크리덴셜 기록을 포함해야 합니다.

  항목은 가능한 경우 transports도 지정해야 하며, 이는 클라이언트가 상황에 최적화된 사용자 경험을 제공하는 데 도움이 됩니다. 또한, userVerification 요청 시 Relying Party가 직접 리스트를 필터링할 필요는 없으며, 클라이언트가 비적격 자격 증명을 자동으로 무시하게 됩니다. (userVerification 이 required인 경우.)

  프라이버시 관련은 § 14.6.3 자격 증명 ID를 통한 프라이버시 유출을 참고하세요.

• 인증할 사용자 계정을 사전에 알 수 없는 경우, Relying Party는 이 값을 비워두거나 아예 지정하지 않을 수 있습니다. 이 경우에는 오직 탐색 가능한 자격 증명만이 인증 과정에서 사용되며, 사용자 계정은 결과 userHandle 값으로 식별될 수 있습니다. 만약 사용 가능한 인증기가 한 Relying Party에 대해 두 개 이상의 탐색 가능한 자격 증명을 소유한 경우, 클라이언트 플랫폼 또는 인증기가 이를 사용자에게 나열하여 선택하도록 합니다. (7단계, § 6.3.3 authenticatorGetAssertion 동작 참고)

비워두지 않은 경우, 목록 내 어떤 자격 증명도 사용할 수 없다면 클라이언트는 오류를 반환해야 합니다.

목록은 선호도 순으로 내림차순 정렬되어 있습니다. 즉, 첫 번째 항목이 가장 선호되고, 마지막이 덜 선호됩니다.

userVerification, 유형 DOMString, 기본값 "preferred"

이 선택적 멤버는 get() 동작에서 Relying Party의 user verification 요구사항을 지정합니다. 값은 UserVerificationRequirement의 멤버여야 하며, 클라이언트 플랫폼은 알 수 없는 값을 무시하고 해당 멤버가 없는 것처럼 취급해야 합니다. 적합한 인증기는 오직 이 요구조건을 충족하는 것만 필터링됩니다.

UserVerificationRequirement에서 userVerification 값과 의미를 참고하세요.

hints, 유형 sequence<DOMString>, 기본값 []

이 선택적 멤버는 PublicKeyCredentialHint 에서 가져온 하나 이상의 요소로, 사용자 에이전트가 사용자와 상호작용할 때 지침으로 사용됩니다. 값이 나열형에서 유래했지만 실질 타입은 DOMString임에 주의. (§ 2.1.1 DOMString 타입의 열거형 참고)

extensions, 유형 AuthenticationExtensionsClientInputs

Relying Party는 이 선택적 멤버로 클라이언트 확장 입력값을 제공해 클라이언트와 인증기에게 추가 처리를 요청할 수 있습니다.

확장 프레임워크는 § 9 WebAuthn 확장에서 정의되어 있습니다. 일부 확장은 § 10 정의된 확장에 서술되어 있습니다. 등록된 최신 WebAuthn 확장 목록은 IANA "WebAuthn Extension Identifiers" 레지스트리 [IANA-WebAuthn-Registries]와 [RFC8809]도 참고하세요.

5.6. AbortSignal을 사용한 연산 중단

개발자는 AbortController 를 활용하여 [[Create]](origin, options, sameOriginWithAncestors) 및 [[DiscoverFromExternalSource]](origin, options, sameOriginWithAncestors) 작업을 제어할 것을 권장합니다. 상세한 사용법은 DOM § 3.3 AbortController와 AbortSignal 객체의 API 통합 부분을 참고하세요.

참고: DOM § 3.3 AbortController와 AbortSignal 객체의 API 통합에 따르면, 웹 플랫폼 API가 AbortController와 연동될 경우, AbortSignal 이 aborted 될 때 Promise를 즉시 reject 해야 합니다. [[Create]](origin, options, sameOriginWithAncestors) 및 [[DiscoverFromExternalSource]](origin, options, sameOriginWithAncestors) 메서드는 복잡한 상속과 병렬 구조로 인해, 두 API의 알고리즘은 해당 aborted 속성을 세 곳에서 점검함으로써 이 요건을 충족시킵니다. [[Create]](origin, options, sameOriginWithAncestors)의 경우, Credential Management 1 § 2.5.4 자격 증명 생성에서 [[Create]](origin, options, sameOriginWithAncestors) 호출 직전, § 5.1.3 새 자격 증명 생성 - PublicKeyCredential의 [[Create]](origin, options, sameOriginWithAncestors) 내부 메서드에서 인증기 세션 시작 직전, 그리고 마지막으로 authenticator 세션 내에서 속성을 확인합니다. [[DiscoverFromExternalSource]](origin, options, sameOriginWithAncestors)도 동일합니다.

Window 객체의 visibility와 focus 상태는 [[Create]](origin, options, sameOriginWithAncestors) 및 [[DiscoverFromExternalSource]](origin, options, sameOriginWithAncestors) 동작의 진행 여부를 결정합니다. Document와 연관된 Window 객체가 포커스를 잃으면, 위 작업들은 중단되어야 합니다.

5.7. WebAuthn 확장 입력과 출력

아래 세부 절에서는 WebAuthn 확장 입력과 출력을 전달하는 데 사용되는 데이터 타입을 정의합니다.

참고: 인증기 확장 출력은 인증기 데이터의 일부로 전달됩니다(표 1 참고).

참고: 아래에 정의된 타입인 AuthenticationExtensionsClientInputs 및 AuthenticationExtensionsClientOutputs 는 등록 확장과 인증 확장 모두에 적용됩니다. 이름의 "Authentication..." 부분은 "WebAuthentication..." 의미로 간주해야 합니다.

5.7.1. 인증 확장 클라이언트 입력 (dictionary AuthenticationExtensionsClientInputs)

dictionary AuthenticationExtensionsClientInputs {
};

이 사전은 0개 이상의 WebAuthn 확장에 대한 클라이언트 확장 입력 값을 담고 있습니다.

5.7.2. 인증 확장 클라이언트 출력 (dictionary AuthenticationExtensionsClientOutputs)

dictionary AuthenticationExtensionsClientOutputs {
};

이 사전은 0개 이상의 WebAuthn 확장에 대한 클라이언트 확장 출력 값을 담고 있습니다.

5.7.3. 인증 확장 인증기 입력 (CDDL type AuthenticationExtensionsAuthenticatorInputs)

AuthenticationExtensionsAuthenticatorInputs = {
  * $$extensionInput
} .within { * tstr => any }

CDDL 타입 AuthenticationExtensionsAuthenticatorInputs는 0개 이상의 WebAuthn 확장에 대한 인증기 확장 입력 값을 담고 있는 CBOR 맵을 정의합니다. 확장은 § 9.3 요청 파라미터 확장에 설명된 대로 멤버를 추가할 수 있습니다.

이 타입은 Relying Party에게 노출되지 않지만, 클라이언트와 인증기에서 사용됩니다.

5.7.4. 인증 확장 인증기 출력 (CDDL type AuthenticationExtensionsAuthenticatorOutputs)

AuthenticationExtensionsAuthenticatorOutputs = {
  * $$extensionOutput
} .within { * tstr => any }

CDDL 타입 AuthenticationExtensionsAuthenticatorOutputs는 0개 이상의 WebAuthn 확장에 대한 인증기 확장 출력 값을 담고 있는 CBOR 맵을 정의합니다. 확장은 § 9.3 요청 파라미터 확장에 설명된 대로 멤버를 추가할 수 있습니다.

5.8. 지원 데이터 구조

공개 키 자격 증명 타입은 지원 명세서에서 정의된 특정 데이터 구조를 사용합니다. 다음과 같습니다.

5.8.1. WebAuthn 서명에 사용되는 클라이언트 데이터 (dictionary CollectedClientData)

클라이언트 데이터는 WebAuthn Relying Party와 클라이언트 양쪽의 맥락적 바인딩을 나타냅니다. 이는 키가 문자열이고, 값은 JSON에서 유효하게 인코딩될 수 있는 어떤 타입이라도 될 수 있는 키-값 매핑입니다. 구조는 아래 Web IDL로 정의됩니다.

참고: CollectedClientData 는 향후 확장될 수 있습니다. 따라서 파싱 시 미지의 키와 키 순서 변경에 대해 유연하게 동작해야 합니다. § 5.8.1.2 제한된 검증 알고리즘도 참고하세요.

dictionary CollectedClientData {
    required DOMString           type;
    required DOMString           challenge;
    required DOMString           origin;
    boolean                      crossOrigin;
    DOMString                    topOrigin;
};

dictionary TokenBinding {
    required DOMString status;
    DOMString id;
};

enum TokenBindingStatus { "present", "supported" };

5.8.1.1. 직렬화

CollectedClientData 의 직렬화는 JSON 값을 바이트로 직렬화 알고리즘의 부분집합입니다. 즉, CollectedClientData 에 대한 유효한 JSON 인코딩을 산출하며, 또한 전체 JSON 파서를 통합하지 않고 검증자가 구조적으로 사용 가능한 추가 구조도 제공합니다. 검증자에게는 표준 JSON 구문 분석을 권장하지만, 전체 파서가 부담일 때는 아래 보다 제한적인 알고리즘을 사용할 수 있습니다. 이 검증 알고리즘은 base64url 인코딩, 바이트열 덧붙이기(고정 템플릿에 작성하는 식), 조건 분기(입력이 escape 필요 없음이 전제)만 있으면 됩니다.

직렬화 알고리즘은, 최초에는 빈 바이트열에 연속적으로 바이트열을 덧붙여 전체 결과를 완성합니다.

1. result에 빈 바이트열을 할당합니다.

2. 0x7b2274797065223a({"type":)를 result에 덧붙입니다.

3. CCDToString(type) 을 result에 덧붙입니다.

4. 0x2c226368616c6c656e6765223a(,"challenge":)를 result에 덧붙입니다.

5. CCDToString(challenge) 을 result에 덧붙입니다.

6. 0x2c226f726967696e223a(,"origin":)를 result에 덧붙입니다.

7. CCDToString(origin) 을 result에 덧붙입니다.

8. 0x2c2263726f73734f726967696e223a(,"crossOrigin":)를 result에 덧붙입니다.

9. crossOrigin 이 없거나 false일 경우:

   1. 0x66616c7365(false)를 result에 덧붙입니다.

10. 그 외의 경우:

    1. 0x74727565(true)를 result에 덧붙입니다.

11. topOrigin 이 존재할 경우:

    1. 0x2c22746f704f726967696e223a(,"topOrigin":)를 result에 덧붙입니다.

    2. CCDToString(topOrigin) 을 result에 덧붙입니다.

12. CollectedClientData 의 임시 복사본을 만들고, type, challenge, origin, crossOrigin (존재 시), topOrigin (존재 시)를 삭제합니다.

13. 임시 복사본에 남은 필드가 없는 경우:

    1. 0x7d(})를 result에 덧붙입니다.

14. 그 외의 경우:

    1. 임시 복사본에 serialize JSON to bytes를 적용해 바이트열 remainder를 만듭니다.

    2. 0x2c(,)를 result에 덧붙입니다.

    3. remainder에서 선두 바이트를 제거합니다.

    4. remainder를 result에 덧붙입니다.

15. 이 직렬화의 결과는 result의 값입니다.

위 알고리즘에서 사용하는 함수 CCDToString은 다음과 같이 정의됩니다:

1. encoded에 빈 바이트열을 할당합니다.

2. 0x22(")를 encoded에 덧붙입니다.

3. 주어진 객체에 ToString을 적용해 문자열로 변환합니다.

4. 문자열 내 각 코드포인트에 대해, 만약:

   {U+0020, U+0021, U+0023–U+005B, U+005D–U+10FFFF} 범위일 때

   해당 코드포인트의 UTF-8 바이너리를 encoded에 덧붙입니다.

   U+0022인 경우

   0x5c22(\")를 encoded에 덧붙입니다.

   U+005C인 경우

   0x5c5c(\\)를 encoded에 덧붙입니다.

   기타

   0x5c75(\u)와 해당 코드포인트 값을 16진법 4자리 소문자로 인코딩한 것을 encoded에 덧붙입니다.

5. 0x22(")를 encoded에 덧붙입니다.

6. 이 함수의 결과는 encoded의 값입니다.

5.8.1.2. 제한된 검증 알고리즘

전체 JSON 파서를 도입하기 어렵다면, 인코딩된 CollectedClientData 를 검증하기 위한 아래 알고리즘을 활용할 수 있습니다:

1. 알고리즘의 입력값:

   1. clientDataJSON: clientDataJSON (직렬화된 CollectedClientData) 바이트열

   2. type: type에 들어갈 기대 문자열

   3. challenge: PublicKeyCredentialRequestOptions 혹은 PublicKeyCredentialCreationOptions 에 사용된 챌린지 바이트열

   4. origin: 사용자 에이전트에게 요청을 전달한 origin.

   5. 옵션 topOrigin: (있다면) topOrigin 기대값

   6. requireTopOrigin: topOrigin이 정의되어 있고 topOrigin 속성이 clientDataJSON에 없으면 검증 실패로 처리할지 여부(boolean).

      이 항목 덕분에, 이 알고리즘은 requireTopOrigin이 false인 경우 WebAuthn LV2 JSON-compatible 직렬화 알고리즘 과 하위 호환됩니다.

2. expected에 빈 바이트열 할당.

3. 0x7b2274797065223a({"type":)를 expected에 덧붙임.

4. CCDToString(type) 를 expected에 덧붙임.

5. 0x2c226368616c6c656e6765223a(,"challenge":)를 expected에 덧붙임.

6. challenge에 base64url 인코딩을 적용해 challengeBase64로 저장.

7. CCDToString(challengeBase64) 를 expected에 덧붙임.

8. 0x2c226f726967696e223a(,"origin":)를 expected에 덧붙임.

9. CCDToString(origin) 을 expected에 덧붙임.

10. 0x2c2263726f73734f726967696e223a(,"crossOrigin":)를 expected에 덧붙임.

11. topOrigin이 정의되어 있다면:

    1. 0x74727565(true)를 expected에 덧붙임.

    2. requireTopOrigin이 true이거나 0x2c22746f704f726967696e223a(,"topOrigin":)이 clientDataJSON의 expected 길이 위치에서 시작하는 접두사라면…

       1. 0x2c22746f704f726967696e223a(,"topOrigin":)를 expected에 덧붙임.

       2. CCDToString(topOrigin)을 expected에 덧붙임.

12. 그 외의 경우 (topOrigin 미정의):

    1. 0x66616c7365(false)를 expected에 덧붙임.

13. expected가 clientDataJSON의 접두사가 아니라면 검증은 실패.

14. clientDataJSON이 expected보다 길지 않으면 검증 실패.

15. clientDataJSON에서 expected 길이에 해당하는 위치의 바이트 값이:

    0x7d일 때

    검증 성공.

    0x2c일 때

    검증 성공.

    그 외

    검증 실패.