跳到主要内容

密码键

QWen Max 中英对照 Passkeys

密码键​

Spring Security 提供了对passkeys的支持。Passkeys 是一种比密码更安全的身份验证方法，它基于WebAuthn构建。

为了使用通行密钥进行身份验证，用户必须首先注册新的凭证。凭证注册后，可以通过验证身份验证断言来使用它进行身份验证。

必需的依赖项​

要开始使用，请将 webauthn4j-core 依赖项添加到您的项目中。

备注

这假设你正在使用 Spring Boot 或 Spring Security 的 BOM 来管理 Spring Security 的版本，如获取 Spring Security中所述。

<dependency>
    <groupId>org.springframework.security</groupId>
    <artifactId>spring-security-web</artifactId>
</dependency>
<dependency>
    <groupId>com.webauthn4j</groupId>
    <artifactId>webauthn4j-core</artifactId>
    <version>0.28.5.RELEASE</version>
</dependency>
xml

配置​

以下配置启用密钥认证。它提供了一种在 /webauthn/register 处注册新凭据的方法，以及一个允许使用密钥进行身份验证的默认登录页面。

@Bean
SecurityFilterChain filterChain(HttpSecurity http) {
    http
        // ...
        .formLogin(withDefaults())
        .webAuthn((webAuthn) -> webAuthn
            .rpName("Spring Security Relying Party")
            .rpId("example.com")
            .allowedOrigins("https://example.com")
        );
    return http.build();
}

@Bean
UserDetailsService userDetailsService() {
    UserDetails userDetails = User.withDefaultPasswordEncoder()
        .username("user")
        .password("password")
        .roles("USER")
        .build();

    return new InMemoryUserDetailsManager(userDetails);
}
java

注册新的凭证​

为了使用通行密钥，用户必须首先注册一个新的凭证。

注册新的凭证包括两个步骤：

  1. 请求注册选项

  2. 注册凭证

请求注册选项​

注册新凭据的第一步是请求注册选项。在 Spring Security 中，通常使用 JavaScript 来请求注册选项，如下所示：

备注

Spring Security 提供了一个默认的注册页面，可以用作如何注册凭证的参考。

POST /webauthn/register/options
X-CSRF-TOKEN: 4bfd1575-3ad1-4d21-96c7-4ef2d9f86721
http

上述请求将获取当前已认证用户的身份验证选项。由于挑战会被持久化（状态会发生变化）以便在注册时进行比较，因此请求必须是POST请求，并且必须包含CSRF令牌。

{
  "rp": {
    "name": "SimpleWebAuthn Example",
    "id": "example.localhost"
  },
  "user": {
    "name": "user@example.localhost",
    "id": "oWJtkJ6vJ_m5b84LB4_K7QKTCTEwLIjCh4tFMCGHO4w",
    "displayName": "user@example.localhost"
  },
  "challenge": "q7lCdd3SVQxdC-v8pnRAGEn1B2M-t7ZECWPwCAmhWvc",
  "pubKeyCredParams": [
    {
      "type": "public-key",
      "alg": -8
    },
    {
      "type": "public-key",
      "alg": -7
    },
    {
      "type": "public-key",
      "alg": -257
    }
  ],
  "timeout": 300000,
  "excludeCredentials": [],
  "authenticatorSelection": {
    "residentKey": "required",
    "userVerification": "preferred"
  },
  "attestation": "none",
  "extensions": {
    "credProps": true
  }
}
json

注册凭证​

在获取到注册选项后，它们将被用于创建要注册的凭据。要注册一个新的凭据，应用程序应在对二进制值（如 user.id、challenge 和 excludeCredentials[].id）进行 base64url 解码后，将这些选项传递给 navigator.credentials.create。

返回的值随后可以作为 JSON 请求发送到服务器。下面是一个注册请求的示例：

POST /webauthn/register
X-CSRF-TOKEN: 4bfd1575-3ad1-4d21-96c7-4ef2d9f86721

{
  "publicKey": { // <1>
    "credential": {
      "id": "dYF7EGnRFFIXkpXi9XU2wg",
      "rawId": "dYF7EGnRFFIXkpXi9XU2wg",
      "response": {
        "attestationObject": "o2NmbXRkbm9uZWdhdHRTdG10oGhhdXRoRGF0YViUy9GqwTRaMpzVDbXq1dyEAXVOxrou08k22ggRC45MKNhdAAAAALraVWanqkAfvZZFYZpVEg0AEHWBexBp0RRSF5KV4vV1NsKlAQIDJiABIVggQjmrekPGzyqtoKK9HPUH-8Z2FLpoqkklFpFPQVICQ3IiWCD6I9Jvmor685fOZOyGXqUd87tXfvJk8rxj9OhuZvUALA",
        "clientDataJSON": "eyJ0eXBlIjoid2ViYXV0aG4uY3JlYXRlIiwiY2hhbGxlbmdlIjoiSl9RTi10SFJYRWVKYjlNcUNrWmFPLUdOVmlibXpGVGVWMk43Z0ptQUdrQSIsIm9yaWdpbiI6Imh0dHBzOi8vZXhhbXBsZS5sb2NhbGhvc3Q6ODQ0MyIsImNyb3NzT3JpZ2luIjpmYWxzZX0",
        "transports": [
          "internal",
          "hybrid"
        ]
      },
      "type": "public-key",
      "clientExtensionResults": {},
      "authenticatorAttachment": "platform"
    },
    "label": "1password" // <2>
  }
}
http

  • 调用 navigator.credentials.create 并将二进制值 base64url 编码后的结果。

  • 用户选择的一个标签，用于与此凭证关联，以帮助用户区分该凭证。

HTTP/1.1 200 OK

{
  "success": true
}
http

验证身份验证断言​

在注册新的凭证后，可以对通行密钥进行验证（认证）。

验证凭证由两个步骤组成：

  1. 请求验证选项

  2. 验证凭证

请求验证选项​

验证凭证的第一步是请求验证选项。在 Spring Security 中，通常使用 JavaScript 请求验证选项，如下所示：

备注

Spring Security 提供了一个默认的登录页面，可以作为验证凭证的参考。

POST /webauthn/authenticate/options
X-CSRF-TOKEN: 4bfd1575-3ad1-4d21-96c7-4ef2d9f86721
http

上述请求将获取验证选项。由于挑战会被持久化（状态会发生改变）以便在身份验证时进行比较，因此该请求必须是POST请求，并且需要包含CSRF令牌。

响应将包含用于获取凭据的选项，其中包含二进制值（如 challenge），这些值采用 base64url 编码。

{
  "challenge": "cQfdGrj9zDg3zNBkOH3WPL954FTOShVy0-CoNgSewNM",
  "timeout": 300000,
  "rpId": "example.localhost",
  "allowCredentials": [],
  "userVerification": "preferred",
  "extensions": {}
}
json

验证凭据​

在获取验证选项后，它们将用于获取凭证。要获取凭证，应用程序应在对二进制值（如 challenge）进行 base64url 解码后，将这些选项传递给 navigator.credentials.get。

navigator.credentials.get 的返回值可以作为 JSON 请求发送到服务器。诸如 rawId 和 response.* 之类的二进制值必须进行 base64url 编码。下面是一个认证请求的示例：

POST /login/webauthn
X-CSRF-TOKEN: 4bfd1575-3ad1-4d21-96c7-4ef2d9f86721

{
  "id": "dYF7EGnRFFIXkpXi9XU2wg",
  "rawId": "dYF7EGnRFFIXkpXi9XU2wg",
  "response": {
    "authenticatorData": "y9GqwTRaMpzVDbXq1dyEAXVOxrou08k22ggRC45MKNgdAAAAAA",
    "clientDataJSON": "eyJ0eXBlIjoid2ViYXV0aG4uZ2V0IiwiY2hhbGxlbmdlIjoiRFVsRzRDbU9naWhKMG1vdXZFcE9HdUk0ZVJ6MGRRWmxUQmFtbjdHQ1FTNCIsIm9yaWdpbiI6Imh0dHBzOi8vZXhhbXBsZS5sb2NhbGhvc3Q6ODQ0MyIsImNyb3NzT3JpZ2luIjpmYWxzZX0",
    "signature": "MEYCIQCW2BcUkRCAXDmGxwMi78jknenZ7_amWrUJEYoTkweldAIhAMD0EMp1rw2GfwhdrsFIeDsL7tfOXVPwOtfqJntjAo4z",
    "userHandle": "Q3_0Xd64_HW0BlKRAJnVagJTpLKLgARCj8zjugpRnVo"
  },
  "clientExtensionResults": {},
  "authenticatorAttachment": "platform"
}
http
HTTP/1.1 200 OK

{
  "redirectUrl": "/", // <1>
  "authenticated": true // <2>
}
http

  • 要重定向到的 URL

  • 表示用户已认证

HTTP/1.1 401 OK
http