With the increasing demand for passwordless authentication, passkeys have emerged as a modern, secure alternative. Let us delve into understanding how to integrate passkeys in Spring Security.<\/p>\n
Passkeys are a modern, passwordless authentication method designed to replace traditional passwords with a more secure and user-friendly alternative. Passkeys are based on public-key cryptography<\/a>, where each user\u2019s device generates a unique key pair consisting of a public key<\/em> and a private key<\/em>.<\/p>\n When a user registers with a service using a passkey, the public key is sent to the server and stored, while the private key never leaves the user\u2019s device. During authentication, the server sends a challenge that is signed by the private key, and the signature is verified using the stored public key.<\/p>\n This method makes passkeys inherently resistant to phishing, credential stuffing, and brute-force attacks, since there’s no shared secret that can be reused or stolen. It also eliminates the need to remember complex passwords or use third-party password managers.<\/p>\n Passkeys are built on top of the Web Authentication API (WebAuthn)<\/a> and the FIDO2 standard<\/a>, developed by the FIDO Alliance<\/a>. These standards enable strong, cryptographic authentication on the web and across devices.<\/p>\n Support for passkeys is rapidly growing across major ecosystems. They are natively supported by:<\/p>\n Because passkeys are synced via cloud providers (e.g., iCloud Keychain or Google Password Manager), they can also be used seamlessly across multiple devices, enhancing both convenience and security.<\/p>\n To integrate passkeys, we use the WebAuthn4J library that enables WebAuthn\/FIDO2 support for Spring Boot applications.<\/p>\n To start using passkeys in your Spring Boot application, you need to include the necessary dependency for WebAuthn support. The This is the entry point of your Spring Boot application. The The security configuration class integrates WebAuthn into Spring Security by applying the The The This controller handles user registration using passkeys. It receives the client\u2019s credential data, validates it with the WebAuthn registration manager, and stores the generated public key and related metadata in the database.<\/p>\n This code implements passkey-based user registration using Spring Boot and the WebAuthn4J library. The The authentication controller verifies login attempts by validating the credentials against stored data. It uses the WebAuthn authentication manager to parse and validate the incoming credential, updating the signature count upon successful authentication.<\/p>\n This code defines a passkey-based authentication workflow using Spring Boot and WebAuthn4J. The This is the application\u2019s configuration file using Spring Boot\u2019s \n
<\/a>2. Adding Passkeys to Spring Boot Applications<\/h2>\n
2.1 Add Dependencies<\/h3>\n
webauthn-spring-security<\/code> library integrates WebAuthn into Spring Security, enabling secure passwordless authentication using public-key cryptography.<\/p>\n<dependency>\n <groupId>com.webauthn4j.springframework.security<\/groupId>\n <artifactId>webauthn-spring-security<\/artifactId>\n <version>latest__jar__version<\/version>\n<\/dependency>\n<\/pre>\n
2.2 Main File<\/h3>\n
PasskeyApplication<\/code> class contains the main<\/code> method that launches the application using Spring Boot\u2019s auto-configuration mechanism.<\/p>\npackage com.example.passkey;\n\nimport org.springframework.boot.SpringApplication;\nimport org.springframework.boot.autoconfigure.SpringBootApplication;\n\n@SpringBootApplication\npublic class PasskeyApplication {\n public static void main(String[] args) {\n SpringApplication.run(PasskeyApplication.class, args);\n }\n}\n<\/pre>\n2.3 Security Configuration File<\/h3>\n
WebAuthnSecurityFilterChainConfigurer<\/code>. It configures CSRF protection, defines open endpoints (like register and authenticate), and ensures authenticated access to other routes.<\/p>\npackage com.example.passkey.config;\n\nimport com.webauthn4j.springframework.security.WebAuthnSecurityConfigurer;\nimport com.webauthn4j.springframework.security.WebAuthnSecurityFilterChainConfigurer;\nimport org.springframework.context.annotation.Bean;\nimport org.springframework.context.annotation.Configuration;\nimport org.springframework.security.config.annotation.web.builders.HttpSecurity;\nimport org.springframework.security.web.SecurityFilterChain;\n\n@Configuration\npublic class WebAuthnSecurityConfig {\n\n @Bean\n public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {\n WebAuthnSecurityFilterChainConfigurer webAuthnConfigurer = new WebAuthnSecurityFilterChainConfigurer();\n http\n .csrf().disable()\n .authorizeHttpRequests(authz -> authz\n .requestMatchers(\"\/register\", \"\/authenticate\").permitAll()\n .anyRequest().authenticated())\n .apply(webAuthnConfigurer);\n\n return http.build();\n }\n}\n<\/pre>\n2.4 Entity File<\/h3>\n
CredentialEntity<\/code> class represents a persisted user credential. It stores essential fields such as the credential ID, user ID, public key, and signature count, and maps to a database table using JPA annotations.package com.example.passkey.entity;\n\nimport jakarta.persistence.Entity;\nimport jakarta.persistence.Id;\nimport lombok.*;\n\n@Entity\n@Getter @Setter @NoArgsConstructor @AllArgsConstructor\npublic class CredentialEntity {\n @Id\n private String credentialId;\n private String userId;\n private byte[] publicKey;\n private long signatureCount;\n}\n<\/pre>\n2.5 Repository File<\/h3>\n
CredentialRepository<\/code> interface provides data access methods for managing CredentialEntity<\/code> objects using Spring Data JPA. It includes a custom finder method to retrieve credentials by user ID.<\/p>\npackage com.example.passkey.repository;\n\nimport com.example.passkey.entity.CredentialEntity;\nimport org.springframework.data.jpa.repository.JpaRepository;\n\nimport java.util.Optional;\n\npublic interface CredentialRepository extends JpaRepository<CredentialEntity, String> {\n Optional<CredentialEntity> findByUserId(String userId);\n}\n<\/pre>\n2.6 Register Controller<\/h3>\n
package com.example.passkey.controller;\n\nimport com.example.passkey.entity.CredentialEntity;\nimport com.example.passkey.repository.CredentialRepository;\nimport com.webauthn4j.data.RegistrationRequest;\nimport com.webauthn4j.data.RegistrationData;\nimport com.webauthn4j.data.RegistrationParameters;\nimport com.webauthn4j.springframework.security.WebAuthnRegistrationManager;\nimport org.springframework.beans.factory.annotation.Autowired;\nimport org.springframework.http.HttpStatus;\nimport org.springframework.http.ResponseEntity;\nimport org.springframework.web.bind.annotation.*;\n\nimport java.util.Base64;\n\n@Data\nclass RegistrationRequestDTO {\n private String userId;\n private CredentialDTO credential;\n}\n\n@RestController\n@RequestMapping(\"\/register\")\npublic class RegisterController {\n\n @Autowired\n private WebAuthnRegistrationManager registrationManager;\n\n @Autowired\n private CredentialRepository credentialRepository;\n\n @PostMapping\n public ResponseEntity<?> register(@RequestBody RegistrationRequestDTO request) {\n try {\n RegistrationRequest registrationRequest = new RegistrationRequest(\n request.getCredential().getClientDataJSON(),\n request.getCredential().getAttestationObject()\n );\n\n RegistrationData registrationData = registrationManager.parse(registrationRequest);\n RegistrationParameters registrationParameters = new RegistrationParameters(\n registrationData.getAttestationObject().getAuthenticatorData().getRpIdHash(),\n false\n );\n registrationManager.validate(registrationData, registrationParameters);\n\n String credentialId = Base64.getEncoder().encodeToString(registrationData.getAttestationObject().getAuthenticatorData().getAttestedCredentialData().getCredentialId());\n byte[] publicKeyCose = registrationData.getAttestationObject().getAuthenticatorData().getAttestedCredentialData().getCredentialPublicKey().getBytes();\n\n CredentialEntity credential = new CredentialEntity();\n credential.setCredentialId(credentialId);\n credential.setUserId(request.getUserId());\n credential.setPublicKey(publicKeyCose);\n credential.setSignatureCount(registrationData.getAttestationObject().getAuthenticatorData().getSignCount());\n\n credentialRepository.save(credential);\n\n return ResponseEntity.ok(\"Registration successful\");\n } catch (Exception e) {\n return ResponseEntity.status(HttpStatus.BAD_REQUEST).body(\"Registration failed: \" + e.getMessage());\n }\n }\n}\n<\/pre>\n2.6.1 Code Explanation<\/h4>\n
RegistrationRequestDTO<\/code> class encapsulates the user ID and credential information required for registration. The RegisterController<\/code> exposes a POST endpoint at \/register<\/code> that receives a WebAuthn registration payload from the client. It creates a RegistrationRequest<\/code> object using the clientDataJSON<\/code> and attestationObject<\/code> received, and parses it into RegistrationData<\/code> using the WebAuthnRegistrationManager<\/code>. The controller then validates the registration data against expected parameters, such as relying party ID hash. Upon successful validation, it extracts the credential ID and public key, encodes them appropriately, and stores them in a CredentialEntity<\/code> object along with the user ID and signature count. This credential is then saved in the database via the CredentialRepository<\/code>. If any exception occurs during parsing or validation, it returns a 400 Bad Request with an appropriate error message; otherwise, it confirms successful registration.<\/p>\n2.7 Authentication Controller<\/h3>\n
package com.example.passkey.controller;\n\nimport com.example.passkey.entity.CredentialEntity;\nimport com.example.passkey.repository.CredentialRepository;\nimport com.webauthn4j.data.AuthenticationData;\nimport com.webauthn4j.data.AuthenticationParameters;\nimport com.webauthn4j.data.AuthenticationRequest;\nimport com.webauthn4j.springframework.security.WebAuthnAuthenticationManager;\nimport org.springframework.beans.factory.annotation.Autowired;\nimport org.springframework.http.HttpStatus;\nimport org.springframework.http.ResponseEntity;\nimport org.springframework.web.bind.annotation.*;\n\n@Data\nclass CredentialDTO {\n private String id;\n private byte[] clientDataJSON;\n private byte[] attestationObject;\n private byte[] authenticatorData;\n private byte[] signature;\n}\n\n@Data\nclass AuthenticationRequestDTO {\n private CredentialDTO credential;\n}\n\n@RestController\n@RequestMapping(\"\/authenticate\")\npublic class AuthController {\n\n @Autowired\n private WebAuthnAuthenticationManager authenticationManager;\n\n @Autowired\n private CredentialRepository credentialRepository;\n\n @PostMapping\n public ResponseEntity<?> authenticate(@RequestBody AuthenticationRequestDTO request) {\n try {\n String credentialId = request.getCredential().getId();\n CredentialEntity storedCredential = credentialRepository.findById(credentialId)\n .orElseThrow(() -> new RuntimeException(\"Credential not found\"));\n\n AuthenticationRequest authenticationRequest = new AuthenticationRequest(\n credentialId,\n request.getCredential().getClientDataJSON(),\n request.getCredential().getAuthenticatorData(),\n request.getCredential().getSignature()\n );\n\n AuthenticationParameters authenticationParameters = new AuthenticationParameters(\n storedCredential.getPublicKey(),\n storedCredential.getSignatureCount()\n );\n\n AuthenticationData authenticationData = authenticationManager.parse(authenticationRequest);\n authenticationManager.validate(authenticationData, authenticationParameters);\n\n \/\/ Update signature counter\n storedCredential.setSignatureCount(authenticationData.getAuthenticatorData().getSignCount());\n credentialRepository.save(storedCredential);\n\n return ResponseEntity.ok(\"Authentication successful\");\n } catch (Exception e) {\n return ResponseEntity.status(HttpStatus.UNAUTHORIZED).body(\"Authentication failed: \" + e.getMessage());\n }\n }\n}\n<\/pre>\n2.7.1 Code Explanation<\/h4>\n
CredentialDTO<\/code> class acts as a data carrier for WebAuthn credential fields received from the client, including the credential ID, client data, attestation object, authenticator data, and signature\u2014all in byte array form. The AuthenticationRequestDTO<\/code> wraps this credential for incoming requests. The AuthController<\/code> exposes a POST endpoint \/authenticate<\/code> that receives these credentials, locates the corresponding stored credential in the database via CredentialRepository<\/code>, and constructs an AuthenticationRequest<\/code> to parse and validate the incoming WebAuthn data using the WebAuthnAuthenticationManager<\/code>. If validation succeeds, it updates the signature counter in the database to prevent replay attacks and responds with a success message. If validation fails due to incorrect or tampered data, it returns a 401 Unauthorized error with the failure reason.<\/p>\n2.8 Configuration File<\/h3>\n
application.yml<\/code> style in plain format. It sets up an in-memory H2 database for development, enables SQL logging, and exposes the H2 console for easy inspection.<\/p>\nspring:\n datasource:\n url: jdbc:h2:mem:testdb\n driver-class-name: org.h2.Driver\n username: sa\n password:\n jpa:\n hibernate:\n ddl-auto: update\n show-sql: true\n h2:\n console:\n enabled: true\n<\/pre>\n
2.9 Code Output<\/h3>\n