实战！为你的网站接入 Passkey 通行密钥以实现无密码安全登录

// Copyright (c) 2018, Yubico AB
// All rights reserved.
//
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions are met:
//
// 1. Redistributions of source code must retain the above copyright notice, this
//    list of conditions and the following disclaimer.
//
// 2. Redistributions in binary form must reproduce the above copyright notice,
//    this list of conditions and the following disclaimer in the documentation
//    and/or other materials provided with the distribution.
//
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
// DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
// FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
// DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
// SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
// CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
// OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package com.yubico.webauthn;

import com.yubico.webauthn.data.ByteArray;
import com.yubico.webauthn.data.PublicKeyCredentialDescriptor;
import java.util.Optional;
import java.util.Set;

/**
 * An abstraction of the database lookups needed by this library.
 *
 * <p>This is used by {@link RelyingParty} to look up credentials, usernames and user handles from
 * usernames, user handles and credential IDs.
 */
public interface CredentialRepository {

  /**
   * Get the credential IDs of all credentials registered to the user with the given username.
   *
   * <p>After a successful registration ceremony, the {@link RegistrationResult#getKeyId()} method
   * returns a value suitable for inclusion in this set.
   */
  Set<PublicKeyCredentialDescriptor> getCredentialIdsForUsername(String username);

  /**
   * Get the user handle corresponding to the given username - the inverse of {@link
   * #getUsernameForUserHandle(ByteArray)}.
   *
   * <p>Used to look up the user handle based on the username, for authentication ceremonies where
   * the username is already given.
   */
  Optional<ByteArray> getUserHandleForUsername(String username);

  /**
   * Get the username corresponding to the given user handle - the inverse of {@link
   * #getUserHandleForUsername(String)}.
   *
   * <p>Used to look up the username based on the user handle, for username-less authentication
   * ceremonies.
   */
  Optional<String> getUsernameForUserHandle(ByteArray userHandle);

  /**
   * Look up the public key and stored signature count for the given credential registered to the
   * given user.
   *
   * <p>The returned {@link RegisteredCredential} is not expected to be long-lived. It may be read
   * directly from a database or assembled from other components.
   */
  Optional<RegisteredCredential> lookup(ByteArray credentialId, ByteArray userHandle);

  /**
   * Look up all credentials with the given credential ID, regardless of what user they're
   * registered to.
   *
   * <p>This is used to refuse registration of duplicate credential IDs. Therefore, under normal
   * circumstances this method should only return zero or one credential (this is an expected
   * consequence, not an interface requirement).
   */
  Set<RegisteredCredential> lookupAll(ByteArray credentialId);
}

@NoArgsConstructor
@AllArgsConstructor
@Entity
public class WebauthnCredentialEntity {

    @Id
    @GeneratedValue(strategy = GenerationType.AUTO)
    @Column(nullable = false)
    @Getter
    @Setter
    private long id;

    @Column(nullable = false)
    @Getter
    @Setter
    private long userID;

    @Column(nullable = false, columnDefinition = "jsonb")
    @Type(JsonType.class)
    private CredentialRegistration credentialRegistration;

}

@Builder
@Data
@JsonAutoDetect(fieldVisibility = JsonAutoDetect.Visibility.NON_PRIVATE)
public class CredentialRegistration implements Serializable {

    @NotNull
    UserIdentity userIdentity;

    @Nullable
    String credentialNickname;

    @NotNull
    SortedSet<@NotNull AuthenticatorTransport> transports;
    @NotNull
    RegisteredCredential credential;
    @Nullable
    Object attestationMetadata;
    @NotNull
    private Instant registration;

    @JsonGetter("registration")
    public String getRegistration() {
        return registration.toString();
    }

    @JsonSetter("registration")
    public void setRegistration(String registration) {
        this.registration = Instant.parse(registration);
    }

    @JsonIgnore
    public String getUsername() {
        return userIdentity.getName();
    }

}

@Repository
public interface WebauthnCredentialRepository extends JpaRepository<WebauthnCredentialEntity, Long> {

    // 根据用户 ID 获取该用户的所有凭据信息
    List<WebauthnCredentialEntity> findAllByUserID(long userID);

}

@RequiredArgsConstructor
@Component
public class CredentialRepositoryImpl implements CredentialRepository {


    private final WebauthnCredentialRepository webauthnCredentialRepository;

    // 根据用户名获取凭证信息
    @Override
    public Set<PublicKeyCredentialDescriptor> getCredentialIdsForUsername(String username) {
        return webauthnCredentialRepository.findAllByUserID(getUserIDByEmail(username)).stream()
                .map(WebauthnCredentialEntity::getCredentialRegistration)
                .map(it -> PublicKeyCredentialDescriptor.builder()
                        .id(it.getCredential().getCredentialId())
                        .transports(it.getTransports())
                        .build())
                .collect(Collectors.toUnmodifiableSet());
    }

    // 根据 UserHandle 获取用户名
    @Override
    public Optional<String> getUsernameForUserHandle(ByteArray userHandle) {
        return getRegistrationsByUserHandle(userHandle).stream()
                .findAny()
                .map(CredentialRegistration::getUsername);
    }

    // 根据用户名获取 UserHandle
    @Override
    public Optional<ByteArray> getUserHandleForUsername(String username) {
        return getRegistrationsByUsername(username).stream()
                .findAny()
                .map(reg -> reg.getUserIdentity().getId());
    }

    // 根据凭证 ID 和 UserHandle 获取单个凭证信息
    @Override
    public Optional<RegisteredCredential> lookup(ByteArray credentialId, ByteArray userHandle) {
        Optional<CredentialRegistration> registrationMaybe = webauthnCredentialRepository.findAll().stream()
                .map(WebauthnCredentialEntity::getCredentialRegistration)
                .filter(it -> it.getCredential().getCredentialId().equals(credentialId))
                .findAny();

        return registrationMaybe.map(it ->
                RegisteredCredential.builder()
                        .credentialId(it.getCredential().getCredentialId())
                        .userHandle(it.getCredential().getUserHandle())
                        .publicKeyCose(it.getCredential().getPublicKeyCose())
                        .signatureCount(it.getCredential().getSignatureCount())
                        .build());
    }

    // 根据凭证 ID 获取多个凭证信息
    @Override
    public Set<RegisteredCredential> lookupAll(ByteArray credentialId) {
        return webauthnCredentialRepository.findAll().stream()
                .map(WebauthnCredentialEntity::getCredentialRegistration)
                .filter(it -> it.getCredential().getCredentialId().equals(credentialId))
                .map(it ->
                        RegisteredCredential.builder()
                                .credentialId(it.getCredential().getCredentialId())
                                .userHandle(it.getCredential().getUserHandle())
                                .publicKeyCose(it.getCredential().getPublicKeyCose())
                                .signatureCount(it.getCredential().getSignatureCount())
                                .build())
                .collect(Collectors.toUnmodifiableSet());
    }

    private long getUserIDByEmail(String email) {
        // your own implemention
    }

    private Collection<CredentialRegistration> getRegistrationsByUsername(String username) {
        return webauthnCredentialRepository.findAllByUserID(getUserIDByEmail(username)).stream()
                .map(WebauthnCredentialEntity::getCredentialRegistration)
                .toList();
    }

    private Collection<CredentialRegistration> getRegistrationsByUserHandle(ByteArray userHandle) {
        return webauthnCredentialRepository.findAll().stream()
                .map(WebauthnCredentialEntity::getCredentialRegistration)
                .filter(it -> it.getUserIdentity().getId().equals(userHandle))
                .toList();
    }
}

@RequiredArgsConstructor
@Configuration
public class WebauthnConfiguration {

    private final CredentialRepository credentialRepository;
    @Value("{webauthn.relying-party.id}")
    private String relyingPartyId;
    @Value("{webauthn.relying-party.name}")
    private String relyingPartyName;

    @Bean
    public RelyingParty relyingParty() {
        var rpIdentity = RelyingPartyIdentity.builder()
                .id(relyingPartyId)
                .name(relyingPartyName)
                .build();

        return RelyingParty.builder()
                .identity(rpIdentity)
                .credentialRepository(credentialRepository)
                .build();
    }

}

GET /api/authorization/passkey/registration/options

POST /api/authorization/passkey/registration
{
 ...
}

GET /api/authorization/passkey/assertion/options

POST /api/authorization/passkey/assertion

@RequiredArgsConstructor
@RestController
@RequestMapping("/api/authorization/passkey")
@Validated
public class PasskeyAuthorizationController {

    private final PasskeyAuthorizationService passkeyAuthorizationService;

    @GetMapping("/registration/options")
    @ResponseBody
    public String getPasskeyRegistrationOptions(@RequestHeader(BizConstants.USER_ID_HEADER) long userID) {
        if (userID == BizConstants.USER_ID_UNAUTHORIZED)
            throw new UnauthorizedException();

        return passkeyAuthorizationService.startPasskeyRegistration(userID);
    }

    @PostMapping("/registration")
    public void verifyPasskeyRegistration(@RequestHeader(BizConstants.USER_ID_HEADER) long userID, @RequestBody String credential) {
        if (userID == BizConstants.USER_ID_UNAUTHORIZED)
            throw new UnauthorizedException();

        passkeyAuthorizationService.finishPasskeyRegistration(userID, credential);
    }

    @GetMapping("/assertion/options")
    @ResponseBody
    public String getPasskeyAssertionOptions(HttpServletRequest httpServletRequest) {
        return passkeyAuthorizationService.startPasskeyAssertion(httpServletRequest.getSession().getId());
    }

    @PostMapping("/assertion")
    @ResponseBody
    public void verifyPasskeyAssertion(HttpServletRequest httpServletRequest, @RequestBody String credential) {
        var id = passkeyAuthorizationService.finishPasskeyAssertion(httpServletRequest.getSession().getId(), credential);

        // Login the user with `id`
        loginUser(id)
    }
}

import {
    create,
    CredentialCreationOptionsJSON,
    CredentialRequestOptionsJSON,
    get,
    parseCreationOptionsFromJSON,
    parseRequestOptionsFromJSON
} from "@github/webauthn-json/browser-ponyfill";

export default function usePasskey() {

    async function isSupported(): Promise<boolean> {
        // Availability of `window.PublicKeyCredential` means WebAuthn is usable.
        // `isUserVerifyingPlatformAuthenticatorAvailable` means the feature detection is usable.
        // `isConditionalMediationAvailable` means the feature detection is usable.
        if (window.PublicKeyCredential &&
            PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable &&
            PublicKeyCredential.isConditionalMediationAvailable
        ) {
            // Check if user verifying platform authenticator is available.
            const results = await Promise.all([
                PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable(),
                PublicKeyCredential.isConditionalMediationAvailable(),
            ])
            if (results.every(r => r === true)) {
                return true;
            }
        }
        return false
    }

    async function createPasskeyCredential() {
        const json = await fetch<CredentialCreationOptionsJSON>("/api/authorization/passkey/registration/options", {
            method: "GET",
            parseResponse: JSON.parse
        })

        const options = parseCreationOptionsFromJSON(json)

        // replacement of navigator.credentials.create(...)
        const response = await create(options);

        awaitfetch("/api/authorization/passkey/registration", {
            method: "POST",
            body: JSON.stringify(response),
        })
    }

    async function validatePasskeyCredential() {
        const json = await $fetch<CredentialRequestOptionsJSON>("/api/authorization/passkey/assertion/options", {
            method: "GET",
            parseResponse: JSON.parse
        })

        const options = parseRequestOptionsFromJSON(json)

        // replacement of navigator.credentials.get(...)
        const response = await get(options);

        await fetch("/api/authorization/passkey/assertion", {
            method: "POST",
            body: JSON.stringify(response),
        })
    }

    return {
        isSupported,
        createPasskeyCredential,
        validatePasskeyCredential
    }

}

@RequiredArgsConstructor
@Service
public class PasskeyAuthorizationService {

    private final WebauthnCredentialRepository webauthnCredentialRepository;
    private final RelyingParty relyingParty;
    private final StringRedisTemplate template;
    private final String REDIS_PASSKEY_REGISTRATION_KEY = "passkey:registration";
    private final String REDIS_PASSKEY_ASSERTION_KEY = "passkey:assertion";

    public PublicKeyCredentialCreationOptions startPasskeyRegistration(long userID) throws JsonProcessingException {
        var user = getUserByUserID(userID);

        var options = relyingParty.startRegistration(StartRegistrationOptions.builder()
                .user(UserIdentity.builder()
                        .name(user.getEmail())
                        .displayName(user.getUsername())
                        .id(new ByteArray(ByteUtil.longToBytes(user.getId())))
                        .build())
                .authenticatorSelection(AuthenticatorSelectionCriteria.builder()
                        .residentKey(ResidentKeyRequirement.REQUIRED)
                        .build())
                .build());

        template.opsForHash().put(REDIS_PASSKEY_REGISTRATION_KEY, String.valueOf(user.getId()), options.toJson());

        return options.toCredentialsCreateJson();
    }

    public void finishPasskeyRegistration(long userID, String credential) throws JsonProcessingException, RegistrationFailedException {
        var user = getUserByUserID(userID);
        var pkc = PublicKeyCredential.parseRegistrationResponseJson(credential)

        var request = PublicKeyCredentialCreationOptions.fromJson((String) template.opsForHash().get(REDIS_PASSKEY_REGISTRATION_KEY, String.valueOf(user.getId())));

        var result = relyingParty.finishRegistration(FinishRegistrationOptions.builder()
                .request(request)
                .response(pkc)
                .build());

        template.opsForHash().delete(REDIS_PASSKEY_REGISTRATION_KEY, String.valueOf(user.getId()));

        storeCredential(user.getId(), request, result);
    }

    public AssertionRequest startPasskeyAssertion(String identifier) throws JsonProcessingException {
        var options = relyingParty.startAssertion(StartAssertionOptions.builder().build());

        template.opsForHash().put(REDIS_PASSKEY_ASSERTION_KEY, identifier, options.toJson());

        return options.toCredentialsGetJson();
    }

    public long finishPasskeyAssertion(String identifier, String credential) throws JsonProcessingException, AssertionFailedException {
        var request = AssertionRequest.fromJson((String) template.opsForHash().get(REDIS_PASSKEY_ASSERTION_KEY, identifier));
        var pkc = PublicKeyCredential.parseAssertionResponseJson(credential)

        var result = relyingParty.finishAssertion(FinishAssertionOptions.builder()
                .request(request)
                .response(pkc)
                .build());

        template.opsForHash().delete(REDIS_PASSKEY_ASSERTION_KEY, identifier);

        if (!result.isSuccess()) {
            throw new AssertionFailedException("Verify failed");
        }

        var user = getUserByUserID(userID);

        updateCredential(user.getId(), result.getCredential().getCredentialId(), result);

        return user.getId();
    }

    private void storeCredential(long id,
                                 @NotNull PublicKeyCredentialCreationOptions request,
                                 @NotNull RegistrationResult result) {
        webauthnCredentialRepository.save(fromFinishPasskeyRegistration(id, request, result));
    }

    private void updateCredential(long id,
                                  @NotNull ByteArray credentialId,
                                  @NotNull AssertionResult result) {
        var entity = webauthnCredentialRepository.findAllByUserID(id).stream()
                .filter(it -> credentialId.equals(it.getCredentialRegistration().getCredential().getCredentialId()))
                .findAny()
                .orElseThrow();

        entity.getCredentialRegistration().setCredential(entity.getCredentialRegistration().getCredential().toBuilder().signatureCount(result.getSignatureCount()).build());

        webauthnCredentialRepository.saveAndFlush(entity);
    }

    @NotNull
    private static WebauthnCredentialEntity fromFinishPasskeyRegistration(long id,
                                                                         PublicKeyCredentialCreationOptions request,
                                                                         RegistrationResult result) {
        return new WebauthnCredentialEntity(
                -1,
                id,
                CredentialRegistration.builder()
                        .userIdentity(request.getUser())
                        .transports(result.getKeyId().getTransports().orElseGet(TreeSet::new))
                        .registration(Clock.systemUTC().instant())
                        .credential(RegisteredCredential.builder()
                                .credentialId(result.getKeyId().getId())
                                .userHandle(request.getUser().getId())
                                .publicKeyCose(result.getPublicKeyCose())
                                .signatureCount(result.getSignatureCount())
                                .build())
                        .build()
        );
    }

}