From fb6760aacce100409bc2faf80cb2b1abcba51d55 Mon Sep 17 00:00:00 2001 From: ynojima Date: Sat, 13 Jul 2024 03:48:43 +0000 Subject: [PATCH] Update docs --- docs/en/configuration.html | 806 ++++++++++++ .../en/images/authenticatorLogin.png | Bin .../en/images/login-with-popup.png | Bin .../asciidoc => }/en/images/login.png | Bin .../images/signup-with-authenticator-form.png | Bin .../en/images/signup-with-popup.png | Bin .../asciidoc => }/en/images/signup.png | Bin docs/en/index.html | 1089 +++++++++++++++++ docs/en/introduction.html | 575 +++++++++ docs/en/quick-start.html | 485 ++++++++ docs/en/sample-app.html | 587 +++++++++ docs/en/spring-boot.html | 468 +++++++ docs/internal/angular-update-procedure.md | 15 - docs/internal/release-procedure.md | 111 -- docs/ja/configuration.html | 805 ++++++++++++ .../ja/images/authenticatorLogin.png | Bin .../ja/images/login-with-popup.png | Bin .../asciidoc => }/ja/images/login.png | Bin .../images/signup-with-authenticator-form.png | Bin .../ja/images/signup-with-popup.png | Bin .../asciidoc => }/ja/images/signup.png | Bin docs/ja/index.html | 1075 ++++++++++++++++ docs/ja/introduction.html | 573 +++++++++ docs/ja/quick-start.html | 484 ++++++++ docs/ja/sample-app.html | 577 +++++++++ docs/ja/spring-boot.html | 468 +++++++ .../reference/asciidoc/en/configuration.adoc | 288 ----- docs/src/reference/asciidoc/en/index.adoc | 19 - .../reference/asciidoc/en/introduction.adoc | 57 - .../reference/asciidoc/en/quick-start.adoc | 16 - .../src/reference/asciidoc/en/sample-app.adoc | 72 -- .../reference/asciidoc/en/spring-boot.adoc | 4 - docs/src/reference/asciidoc/index-docinfo.xml | 29 - .../reference/asciidoc/ja/configuration.adoc | 289 ----- docs/src/reference/asciidoc/ja/index.adoc | 19 - .../reference/asciidoc/ja/introduction.adoc | 56 - .../reference/asciidoc/ja/quick-start.adoc | 15 - .../src/reference/asciidoc/ja/sample-app.adoc | 62 - .../reference/asciidoc/ja/spring-boot.adoc | 5 - 39 files changed, 7992 insertions(+), 1057 deletions(-) create mode 100644 docs/en/configuration.html rename docs/{src/reference/asciidoc => }/en/images/authenticatorLogin.png (100%) rename docs/{src/reference/asciidoc => }/en/images/login-with-popup.png (100%) rename docs/{src/reference/asciidoc => }/en/images/login.png (100%) rename docs/{src/reference/asciidoc => }/en/images/signup-with-authenticator-form.png (100%) rename docs/{src/reference/asciidoc => }/en/images/signup-with-popup.png (100%) rename docs/{src/reference/asciidoc => }/en/images/signup.png (100%) create mode 100644 docs/en/index.html create mode 100644 docs/en/introduction.html create mode 100644 docs/en/quick-start.html create mode 100644 docs/en/sample-app.html create mode 100644 docs/en/spring-boot.html delete mode 100644 docs/internal/angular-update-procedure.md delete mode 100644 docs/internal/release-procedure.md create mode 100644 docs/ja/configuration.html rename docs/{src/reference/asciidoc => }/ja/images/authenticatorLogin.png (100%) rename docs/{src/reference/asciidoc => }/ja/images/login-with-popup.png (100%) rename docs/{src/reference/asciidoc => }/ja/images/login.png (100%) rename docs/{src/reference/asciidoc => }/ja/images/signup-with-authenticator-form.png (100%) rename docs/{src/reference/asciidoc => }/ja/images/signup-with-popup.png (100%) rename docs/{src/reference/asciidoc => }/ja/images/signup.png (100%) create mode 100644 docs/ja/index.html create mode 100644 docs/ja/introduction.html create mode 100644 docs/ja/quick-start.html create mode 100644 docs/ja/sample-app.html create mode 100644 docs/ja/spring-boot.html delete mode 100644 docs/src/reference/asciidoc/en/configuration.adoc delete mode 100644 docs/src/reference/asciidoc/en/index.adoc delete mode 100644 docs/src/reference/asciidoc/en/introduction.adoc delete mode 100644 docs/src/reference/asciidoc/en/quick-start.adoc delete mode 100644 docs/src/reference/asciidoc/en/sample-app.adoc delete mode 100644 docs/src/reference/asciidoc/en/spring-boot.adoc delete mode 100644 docs/src/reference/asciidoc/index-docinfo.xml delete mode 100644 docs/src/reference/asciidoc/ja/configuration.adoc delete mode 100644 docs/src/reference/asciidoc/ja/index.adoc delete mode 100644 docs/src/reference/asciidoc/ja/introduction.adoc delete mode 100644 docs/src/reference/asciidoc/ja/quick-start.adoc delete mode 100644 docs/src/reference/asciidoc/ja/sample-app.adoc delete mode 100644 docs/src/reference/asciidoc/ja/spring-boot.adoc diff --git a/docs/en/configuration.html b/docs/en/configuration.html new file mode 100644 index 000000000..9607cc24b --- /dev/null +++ b/docs/en/configuration.html @@ -0,0 +1,806 @@ + + + + + + + +Configuration + + + + + + + +
+
+

1. Configuration

+
+
+

1.1. Applications integration

+
+

1.1.1. Maven dependency

+
+

Please add following to pom.xml to introduce WebAuthn4J Spring Security and its dependencies.

+
+
+
+
<properties>
+  ...
+  <!-- Use the latest version whenever possible. -->
+  <webauthn4j-spring-security.version>0.7.6.RELEASE</webauthn4j-spring-security.version>
+  ...
+</properties>
+
+<dependency>
+	<groupId>com.webauthn4j</groupId>
+	<artifactId>webauthn4j-spring-security-core</artifactId>
+	<version>${webauthn4j-spring-security.version}</version>
+</dependency>
+
+
+
+
+

1.1.2. Java Config

+
+

WebAuthn4J Spring Security can be configured through the Spring Security Java Config DSL. +Please define the SecurityFilterChain bean as follows and apply the WebAuthnLoginConfigurer to the HttpSecurity bean. +Through WebAuthnLoginConfigurer, you can set various options of the WebAuthnProcessingFilter, Attestation options endpoint, and Assertion options endpoint.

+
+
+
+
@Configuration
+public class WebSecurityConfig {
+
+    @Bean
+    public SecurityFilterChain filterChain(HttpSecurity http, AuthenticationManager authenticationManager) throws Exception {
+
+        http.authenticationManager(authenticationManager);
+        // WebAuthn Login
+        http.with(WebAuthnLoginConfigurer.webAuthnLogin(), (customizer) ->{
+            customizer
+                    .loginPage("/login")
+                    .usernameParameter("username")
+                    .passwordParameter("password")
+                    .credentialIdParameter("credentialId")
+                    .clientDataJSONParameter("clientDataJSON")
+                    .authenticatorDataParameter("authenticatorData")
+                    .signatureParameter("signature")
+                    .clientExtensionsJSONParameter("clientExtensionsJSON")
+                    .loginProcessingUrl("/login")
+                    .attestationOptionsEndpoint()
+                        .rp()
+                            .name("WebAuthn4J Spring Security Sample")
+                        .and()
+                        .pubKeyCredParams(
+                                new PublicKeyCredentialParameters(PublicKeyCredentialType.PUBLIC_KEY, COSEAlgorithmIdentifier.RS256), // Windows Hello
+                                new PublicKeyCredentialParameters(PublicKeyCredentialType.PUBLIC_KEY, COSEAlgorithmIdentifier.ES256) // FIDO U2F Key, etc
+                        )
+                        .extensions()
+                            .credProps(true)
+                    .and()
+                    .assertionOptionsEndpoint()
+                    .and()
+                    .successHandler(authenticationSuccessHandler)
+                    .failureHandler(authenticationFailureHandler);
+        });
+    }
+}
+
+
+
+
Integrating WebAuthnAuthenticationProvider
+
+

WebAuthnAuthenticationProvider, an AuthenticationProvider for Web Authentication, need to be defined as a Bean. +If you set up two-step authentication combined with password authentication, you also need a Bean definition for DaoAuthenticationProvider.

+
+
+
+
    @Bean
+    public WebAuthnAuthenticationProvider webAuthnAuthenticationProvider(WebAuthnAuthenticatorService authenticatorService, WebAuthnManager webAuthnManager){
+        return new WebAuthnAuthenticationProvider(authenticatorService, webAuthnManager);
+    }
+
+    @Bean
+    public DaoAuthenticationProvider daoAuthenticationProvider(UserDetailsService userDetailsService){
+        DaoAuthenticationProvider daoAuthenticationProvider = new DaoAuthenticationProvider();
+        daoAuthenticationProvider.setUserDetailsService(userDetailsService);
+        daoAuthenticationProvider.setPasswordEncoder(new BCryptPasswordEncoder());
+        return daoAuthenticationProvider;
+    }
+
+    @Bean
+    public AuthenticationManager authenticationManager(List<AuthenticationProvider> providers){
+        return new ProviderManager(providers);
+    }
+
+
+
+
+
+

1.1.3. Persistence layer integration

+
+

WebAuthn4J Spring Security looks up an authenticator through the WebAuthnCredentialRecordService interface. +Please set a class implementing WebAuthnCredentialRecordService to the WebAuthnAuthenticationProvider. +Speaking of Java Config, it can be set through a constructor of WebAuthnAuthenticationProviderConfigurer.

+
+
+
+
+

1.2. Client interface

+
+

W3C Web Authentication specification defines web browser JavaScript APIs only. It is up to implementation how to send a generated credential.

+
+
+

1.2.1. WebAuthn authentication request processing

+
+

Regarding WebAuthn4J Spring Security, WebAuthnProcessingFilter retrieves credentialId, clientData, authenticatorData, signature, and clientExtensionsJSON from the request sent to login processing url. +credentialId, clientData, authenticatorData and signature are binary data, please send them as Base64 strings.

+
+
+
+

1.2.2. WebAuthn registration request processing

+
+

In contrast to authentication request processing, Servlet filter is not provided for registration request processing +because in most cases, data other than WebAuthn like user’s first name, last name, or email address are sent at the same time.

+
+
+

While it is basically application’s responsibility to handle an authenticator registration process, WebAuthn4J Spring Security provides converters and validators to examine the received credential. +Base64StringToCollectedClientDataConverter converts Base64 string to a CollectedClientData. +Base64StringToAttestationObjectConverter converts Base64 string to a AttestationObject.

+
+
+

WebAuthnRegistrationRequestValidator validates an authenticator registration request.

+
+
+
+

1.2.3. Options endpoints

+
+

Web Authentication needs to obtain a challenge from the server prior to registration and authentication. +When using the FIDO-U2F token as an authentication device, the CredentialIds associated with the user identified by the first authentication factor also need to be obtained from the server. +To retrieve these data, WebAuthn4J Spring Security offers AttestationOptionsEndpointFilter and AssertionOptionsEndpointFilter.

+
+
+
+
+

1.3. Customization

+
+

1.3.1. WebAuthnProcessingFilter

+
+

WebAuthnProcessingFilter retrieves credentialId, clientData, authenticatorData, signature, and clientExtensionsJSON from the request and build WebAuthnAssertionAuthenticationToken. +If credentialId does not exist, it retrieves username and password to build UsernamePasswordAuthenticationToken. +To change request parameter names, configure properties of WebAuthnProcessingFilter or corresponding Java Config method of WebAuthnLoginConfigurer.

+
+
+
+

1.3.2. WebAuthnAuthenticationProvider

+
+

WebAuthnAuthenticationProvider is an AuthenticationProvider implementation to process a WebAuthnAssertionAuthenticationToken. +For WebAuthn assertion verification, WebAuthnManager is used. See WebAuthn4J reference for more details of WebAuthnManager.

+
+
+
+

1.3.3. Attestation options endpoint, Assertion options endpoint

+
+

WebAuthn4J Spring Security provides AttestationOptionsEndpointFilter for WebAuthn JS Credential Creation API parameters serving, and AssertionOptionsEndpointFilter for WebAuthn JS Credential Get API parameter serving. +As these Parameters generation are delegated through AttestationOptionsProvider and AssertionOptionsProvider interfaces, they can be customized by implementing these interfaces.

+
+
+

These can be customized through Java Config. Method chains from WebAuthnLoginConfigurer 's attestationOptionsEndpoint method or assertionOptionsEndpoint method are configuration point for that.

+
+
+
+
@Configuration
+public class WebSecurityConfig {
+
+    @Bean
+    public SecurityFilterChain filterChain(HttpSecurity http, AuthenticationManager authenticationManager) throws Exception {
+        http.authenticationManager(authenticationManager);
+        // WebAuthn Login
+        http.with(WebAuthnLoginConfigurer.webAuthnLogin(), (customizer) ->{
+            customizer
+            .rpId("example.com")
+            .attestationOptionsEndpoint()
+                .attestationOptionsProvider(attestationOptionsProvider)
+                .processingUrl("/webauthn/attestation/options")
+                .rp()
+                    .name("example")
+                    .and()
+                .pubKeyCredParams(
+                        new PublicKeyCredentialParameters(PublicKeyCredentialType.PUBLIC_KEY, COSEAlgorithmIdentifier.ES256),
+                        new PublicKeyCredentialParameters(PublicKeyCredentialType.PUBLIC_KEY, COSEAlgorithmIdentifier.RS1)
+                )
+                .authenticatorSelection()
+                    .authenticatorAttachment(AuthenticatorAttachment.CROSS_PLATFORM)
+                    .residentKey(ResidentKeyRequirement.PREFERRED)
+                    .userVerification(UserVerificationRequirement.PREFERRED)
+                    .and()
+                .attestation(AttestationConveyancePreference.DIRECT)
+                .extensions()
+                    .credProps(true)
+                    .uvm(true)
+                .and()
+            .assertionOptionsEndpoint()
+                .assertionOptionsProvider(assertionOptionsProvider)
+                .processingUrl("/webauthn/assertion/options")
+                .rpId("example.com")
+                .userVerification(UserVerificationRequirement.PREFERRED)
+            .and();
+        });
+    }
+}
+
+
+
+
Dynamic generation of PublicKeyCredentialUserEntity
+
+

Attestation options endpoint can generate PublicKeyCredentialUserEntity to be returned dynamically based on the Authentication object associated with logged-in user. +To generate PublicKeyCredentialUserEntity, PublicKeyCredentialUserEntityProvider is provided.

+
+
+

Speaking of Java Config, it can be set in this way:

+
+
+
+
@Configuration
+public class WebSecurityConfig {
+
+    @Bean
+    public SecurityFilterChain filterChain(HttpSecurity http, AuthenticationManager authenticationManager) throws Exception {
+
+        // WebAuthn Login
+        http.with(WebAuthnLoginConfigurer.webAuthnLogin(), (customizer) ->{
+            customizer
+            .attestationOptionsEndpoint()
+                .attestationOptionsProvider(attestationOptionsProvider)
+                .processingUrl("/webauthn/attestation/options")
+                .processingUrl("/webauthn/attestation/options")
+                .user(new MyPublicKeyCredentialUserEntityProvider()); // put your PublicKeyCredentialUserEntityProvider implementation
+        });
+    }
+}
+
+
+
+

If PublicKeyCredentialUserEntityProvider is not set explicitly, WebAuthn4J Spring Security Java Config looks it up from Spring Application Context. +Registering its bean to the application context is another way to set it.

+
+
+
+
+

1.3.4. Selecting authentication method

+
+

WebAuthn4J Spring Security supports "Password-less multi-factor authentication with a user-verifying authenticator", "Multi-factor authentication with password and authenticator" and "Single-factor authentication like password". +If you put value on adoption, you may allow password authentication in your web system, or if you give greater importance to security, you may restrict password authentication.

+
+
+
How to realize password authentication
+
+

To realize "Multi-factor authentication with password and authenticator" and "Single-factor authentication like password", configure not only WebAuthnAuthenticationProvider but also DaoAuthenticationProvider to process UsernamePasswordAuthenticationToken. +"Multi-factor authentication with password and authenticator" can be realized by including additional authorization requirement to check a user is authenticated by WebAuthn.

+
+
+

Whether it is authenticated by WebAuthn can be checked with the WebAuthnSecurityExpression#isWebAuthnAuthenticated method. +Register a bean of WebAuthnSecurityExpression instance and call it from JavaConfig. WebAuthn4J Spring Security Sample MPA is a good example for it.

+
+
+
+
+
+

1.4. Advanced topics

+
+

1.4.1. Distinction of a user in the middle of multi-factor authentication

+
+

In the case where it is needed to show a different view based on authentication level, one way is to switch the view based on the type of the current Authentication instance.

+
+
+
+
@RequestMapping(value = "/login", method = RequestMethod.GET)
+public String login() {
+    Authentication authentication = SecurityContextHolder.getContext().getAuthentication();
+    if (authenticationTrustResolver.isAnonymous(authentication)) {
+        return VIEW_LOGIN_LOGIN;
+    } else {
+        return VIEW_LOGIN_AUTHENTICATOR_LOGIN;
+    }
+}
+
+
+
+
+

1.4.2. Configuring a credential scope (rpId)

+
+

In Web Authentication specification, the scope of a creating credential can be configured through the parameter named "rpId" while creating the credential i.e. registering authenticator. +"rpId" accepts effective domain. +For example, in the case where the domain of the site is webauthn.example.com, and webauthn.example.com is set to +rpId, the credential is only available in webauthn.example.com and its sub-domain, but if example.com +is set to rpId, the scope of the credential is relaxed to example.com and its sub-domain.

+
+
+

WebAuthn4J Spring Security supports rpId configuration through the rpId property of ServerPropertyProviderImpl, which can be configured through WebAuthnConfigurer in JavaConfig. +If you would like to change rpId dynamically based on request, set RpIdProvider.

+
+
+
+

1.4.3. Attestation statement verification

+
+

Web Authentication specification allows the relying party to retrieve an attestation statement from an authenticator if it is requested during authenticator registration. +By verifying attestation statement, the relying party can exclude authenticators not conforming its security requirements. +It’s to be noted that the attestation statement contains information that can be used to track user across web sites, it is discouraged to request an attestation statement unnecessarily. +It is also to be noted that the browser shows an additional dialog to confirm the user consent, lowering usability. +Except for enterprise applications that require strict verification of authenticators, most sites should not request attestation statements.

+
+
+

WebAuthnRegistrationContextValidator from WebAuthn4J validates an authenticator registration request, and it delegates attestation statement signature and trustworthiness validation to WebAuthnManager and +CertPathTrustworthinessValidator interface implementation respectively.

+
+
+

WebAuthnRegistrationContextValidator.createNonStrictRegistrationContextValidator factory method can create the +WebAuthnRegistrationContextValidator instance that contains AttestationStatementValidator and +CertPathTrustworthinessValidator configured for web sites not requiring strict attestation verification.

+
+
+
+

1.4.4. TrustAnchorProvider using Spring Resource

+
+

While validating an authenticator attestation certificate path on registration, +TrustAnchorCertPathTrustworthinessValidator class uses TrustAnchor retrieved through TrustAnchorProvider interface implementation. +WebAuthn4J Spring Security offers KeyStoreResourceTrustAnchorProvider class, which retrieves a +TrustAnchor from a Java Key Store file loaded as Spring Resource.

+
+
+
+
+
+
+ + + + \ No newline at end of file diff --git a/docs/src/reference/asciidoc/en/images/authenticatorLogin.png b/docs/en/images/authenticatorLogin.png similarity index 100% rename from docs/src/reference/asciidoc/en/images/authenticatorLogin.png rename to docs/en/images/authenticatorLogin.png diff --git a/docs/src/reference/asciidoc/en/images/login-with-popup.png b/docs/en/images/login-with-popup.png similarity index 100% rename from docs/src/reference/asciidoc/en/images/login-with-popup.png rename to docs/en/images/login-with-popup.png diff --git a/docs/src/reference/asciidoc/en/images/login.png b/docs/en/images/login.png similarity index 100% rename from docs/src/reference/asciidoc/en/images/login.png rename to docs/en/images/login.png diff --git a/docs/src/reference/asciidoc/en/images/signup-with-authenticator-form.png b/docs/en/images/signup-with-authenticator-form.png similarity index 100% rename from docs/src/reference/asciidoc/en/images/signup-with-authenticator-form.png rename to docs/en/images/signup-with-authenticator-form.png diff --git a/docs/src/reference/asciidoc/en/images/signup-with-popup.png b/docs/en/images/signup-with-popup.png similarity index 100% rename from docs/src/reference/asciidoc/en/images/signup-with-popup.png rename to docs/en/images/signup-with-popup.png diff --git a/docs/src/reference/asciidoc/en/images/signup.png b/docs/en/images/signup.png similarity index 100% rename from docs/src/reference/asciidoc/en/images/signup.png rename to docs/en/images/signup.png diff --git a/docs/en/index.html b/docs/en/index.html new file mode 100644 index 000000000..f24490e96 --- /dev/null +++ b/docs/en/index.html @@ -0,0 +1,1089 @@ + + + + + + + +WebAuthn4J Spring Security Reference + + + + + + + +
+
+

1. Introduction

+
+
+

1.1. Web Authentication

+
+

Web Authentication is a new, secure web application authentication specification standardizing under W3C. +By combining local authentication, public-key authentication, per-origin key management, it provides strong authentication to web sites against authentication process attacks like phishing. +Implementation is in progress in major browsers, the specification offers excellent choices for users who place importance on security and convenience. +Initially, the specification was developed as "FIDO 2.0: Web API for accessing FIDO 2.0 credentials" by the FIDO Alliance, but it has been transferred to W3C.

+
+
+
+

1.2. WebAuthn4J Spring Security

+
+

WebAuthn4J Spring Security is a Spring Security extension module to provide Web Authentication specification support for your Spring web application.

+
+
+

1.2.1. WebAuthn4J

+
+

WebAuthn4J Spring Security uses WebAuthn4J for WebAuthn attestation and assertion verification. +WebAuthn4J is a portable Java library that supports all the attestation statements, but has minimal dependencies on external libraries.

+
+
+
+

1.2.2. Spring Security WebAuthn

+
+

There is also a sister project called Spring Security WebAuthn. Spring Security WebAuthn is developed according to Spring Security project’s policy, aiming to be merged into Spring Security upstream. +WebAuthn4J Spring Security is developed as a WebAuthn4J project with the aim of maximizing the functions of the WebAuthn4J library.

+
+
+
+
+

1.3. Requirements

+
+

1.3.1. Language & Framework

+
+
    +
  • +

    Java8 or later

    +
    • +
  • +

    Spring Framework 5 or later

    +
    • +
  • +

    Spring Security 5 or later

    +
    • +
+
+
+
+

1.3.2. Environment

+
+
    +
  • +

    SecureContext

    +
    • +
  • +

    Browsers

    +
    +
      +
    • +

      Google Chrome 70 or later

      +
      • +
    • +

      Mozilla Firefox 60 or later

      +
      • +
    • +

      Microsoft Edge bundled with Windows 10 October 2018 Update or later

      +
      • +
    • +

      Safari 14 or later

      +
      • +
    +
    +
    • +
+
+
+
SecureContext
+
+

Web Authentication API is only available in SecureContext, which means only HTTPS connection is permitted while a user accessing web sites. +Browsers rejects Web Authentication API call if the web site is served through HTTP connection except localhost. +For more details about SecureContext, please see MDN.

+
+
+
+
+
+

1.4. Source code

+
+

Source code for this project is hosted on Github.

+
+
+
+
git clone https://github.com/webauthn4j/webauthn4j-spring-security
+
+
+
+
+

1.5. License

+
+

WebAuthn4J Spring Security is an open source software licensed under Apache 2.0 license.

+
+
+
+
+
+

2. Quick start

+
+
+

WebAuthn4J Spring Security contains a sample application which demonstrates its major functionality.

+
+
+

It can be launched with the following command.

+
+
+
+
./gradlew samples:spa:bootRun
+
+
+
+
+login view +
+
+
+

Sample application is documented in a dedicated chapter. +Please refer Sample application.

+
+
+
+
+

3. Configuration

+
+
+

3.1. Applications integration

+
+

3.1.1. Maven dependency

+
+

Please add following to pom.xml to introduce WebAuthn4J Spring Security and its dependencies.

+
+
+
+
<properties>
+  ...
+  <!-- Use the latest version whenever possible. -->
+  <webauthn4j-spring-security.version>0.7.6.RELEASE</webauthn4j-spring-security.version>
+  ...
+</properties>
+
+<dependency>
+	<groupId>com.webauthn4j</groupId>
+	<artifactId>webauthn4j-spring-security-core</artifactId>
+	<version>${webauthn4j-spring-security.version}</version>
+</dependency>
+
+
+
+
+

3.1.2. Java Config

+
+

WebAuthn4J Spring Security can be configured through the Spring Security Java Config DSL. +Please define the SecurityFilterChain bean as follows and apply the WebAuthnLoginConfigurer to the HttpSecurity bean. +Through WebAuthnLoginConfigurer, you can set various options of the WebAuthnProcessingFilter, Attestation options endpoint, and Assertion options endpoint.

+
+
+
+
@Configuration
+public class WebSecurityConfig {
+
+    @Bean
+    public SecurityFilterChain filterChain(HttpSecurity http, AuthenticationManager authenticationManager) throws Exception {
+
+        http.authenticationManager(authenticationManager);
+        // WebAuthn Login
+        http.with(WebAuthnLoginConfigurer.webAuthnLogin(), (customizer) ->{
+            customizer
+                    .loginPage("/login")
+                    .usernameParameter("username")
+                    .passwordParameter("password")
+                    .credentialIdParameter("credentialId")
+                    .clientDataJSONParameter("clientDataJSON")
+                    .authenticatorDataParameter("authenticatorData")
+                    .signatureParameter("signature")
+                    .clientExtensionsJSONParameter("clientExtensionsJSON")
+                    .loginProcessingUrl("/login")
+                    .attestationOptionsEndpoint()
+                        .rp()
+                            .name("WebAuthn4J Spring Security Sample")
+                        .and()
+                        .pubKeyCredParams(
+                                new PublicKeyCredentialParameters(PublicKeyCredentialType.PUBLIC_KEY, COSEAlgorithmIdentifier.RS256), // Windows Hello
+                                new PublicKeyCredentialParameters(PublicKeyCredentialType.PUBLIC_KEY, COSEAlgorithmIdentifier.ES256) // FIDO U2F Key, etc
+                        )
+                        .extensions()
+                            .credProps(true)
+                    .and()
+                    .assertionOptionsEndpoint()
+                    .and()
+                    .successHandler(authenticationSuccessHandler)
+                    .failureHandler(authenticationFailureHandler);
+        });
+    }
+}
+
+
+
+
Integrating WebAuthnAuthenticationProvider
+
+

WebAuthnAuthenticationProvider, an AuthenticationProvider for Web Authentication, need to be defined as a Bean. +If you set up two-step authentication combined with password authentication, you also need a Bean definition for DaoAuthenticationProvider.

+
+
+
+
    @Bean
+    public WebAuthnAuthenticationProvider webAuthnAuthenticationProvider(WebAuthnAuthenticatorService authenticatorService, WebAuthnManager webAuthnManager){
+        return new WebAuthnAuthenticationProvider(authenticatorService, webAuthnManager);
+    }
+
+    @Bean
+    public DaoAuthenticationProvider daoAuthenticationProvider(UserDetailsService userDetailsService){
+        DaoAuthenticationProvider daoAuthenticationProvider = new DaoAuthenticationProvider();
+        daoAuthenticationProvider.setUserDetailsService(userDetailsService);
+        daoAuthenticationProvider.setPasswordEncoder(new BCryptPasswordEncoder());
+        return daoAuthenticationProvider;
+    }
+
+    @Bean
+    public AuthenticationManager authenticationManager(List<AuthenticationProvider> providers){
+        return new ProviderManager(providers);
+    }
+
+
+
+
+
+

3.1.3. Persistence layer integration

+
+

WebAuthn4J Spring Security looks up an authenticator through the WebAuthnCredentialRecordService interface. +Please set a class implementing WebAuthnCredentialRecordService to the WebAuthnAuthenticationProvider. +Speaking of Java Config, it can be set through a constructor of WebAuthnAuthenticationProviderConfigurer.

+
+
+
+
+

3.2. Client interface

+
+

W3C Web Authentication specification defines web browser JavaScript APIs only. It is up to implementation how to send a generated credential.

+
+
+

3.2.1. WebAuthn authentication request processing

+
+

Regarding WebAuthn4J Spring Security, WebAuthnProcessingFilter retrieves credentialId, clientData, authenticatorData, signature, and clientExtensionsJSON from the request sent to login processing url. +credentialId, clientData, authenticatorData and signature are binary data, please send them as Base64 strings.

+
+
+
+

3.2.2. WebAuthn registration request processing

+
+

In contrast to authentication request processing, Servlet filter is not provided for registration request processing +because in most cases, data other than WebAuthn like user’s first name, last name, or email address are sent at the same time.

+
+
+

While it is basically application’s responsibility to handle an authenticator registration process, WebAuthn4J Spring Security provides converters and validators to examine the received credential. +Base64StringToCollectedClientDataConverter converts Base64 string to a CollectedClientData. +Base64StringToAttestationObjectConverter converts Base64 string to a AttestationObject.

+
+
+

WebAuthnRegistrationRequestValidator validates an authenticator registration request.

+
+
+
+

3.2.3. Options endpoints

+
+

Web Authentication needs to obtain a challenge from the server prior to registration and authentication. +When using the FIDO-U2F token as an authentication device, the CredentialIds associated with the user identified by the first authentication factor also need to be obtained from the server. +To retrieve these data, WebAuthn4J Spring Security offers AttestationOptionsEndpointFilter and AssertionOptionsEndpointFilter.

+
+
+
+
+

3.3. Customization

+
+

3.3.1. WebAuthnProcessingFilter

+
+

WebAuthnProcessingFilter retrieves credentialId, clientData, authenticatorData, signature, and clientExtensionsJSON from the request and build WebAuthnAssertionAuthenticationToken. +If credentialId does not exist, it retrieves username and password to build UsernamePasswordAuthenticationToken. +To change request parameter names, configure properties of WebAuthnProcessingFilter or corresponding Java Config method of WebAuthnLoginConfigurer.

+
+
+
+

3.3.2. WebAuthnAuthenticationProvider

+
+

WebAuthnAuthenticationProvider is an AuthenticationProvider implementation to process a WebAuthnAssertionAuthenticationToken. +For WebAuthn assertion verification, WebAuthnManager is used. See WebAuthn4J reference for more details of WebAuthnManager.

+
+
+
+

3.3.3. Attestation options endpoint, Assertion options endpoint

+
+

WebAuthn4J Spring Security provides AttestationOptionsEndpointFilter for WebAuthn JS Credential Creation API parameters serving, and AssertionOptionsEndpointFilter for WebAuthn JS Credential Get API parameter serving. +As these Parameters generation are delegated through AttestationOptionsProvider and AssertionOptionsProvider interfaces, they can be customized by implementing these interfaces.

+
+
+

These can be customized through Java Config. Method chains from WebAuthnLoginConfigurer 's attestationOptionsEndpoint method or assertionOptionsEndpoint method are configuration point for that.

+
+
+
+
@Configuration
+public class WebSecurityConfig {
+
+    @Bean
+    public SecurityFilterChain filterChain(HttpSecurity http, AuthenticationManager authenticationManager) throws Exception {
+        http.authenticationManager(authenticationManager);
+        // WebAuthn Login
+        http.with(WebAuthnLoginConfigurer.webAuthnLogin(), (customizer) ->{
+            customizer
+            .rpId("example.com")
+            .attestationOptionsEndpoint()
+                .attestationOptionsProvider(attestationOptionsProvider)
+                .processingUrl("/webauthn/attestation/options")
+                .rp()
+                    .name("example")
+                    .and()
+                .pubKeyCredParams(
+                        new PublicKeyCredentialParameters(PublicKeyCredentialType.PUBLIC_KEY, COSEAlgorithmIdentifier.ES256),
+                        new PublicKeyCredentialParameters(PublicKeyCredentialType.PUBLIC_KEY, COSEAlgorithmIdentifier.RS1)
+                )
+                .authenticatorSelection()
+                    .authenticatorAttachment(AuthenticatorAttachment.CROSS_PLATFORM)
+                    .residentKey(ResidentKeyRequirement.PREFERRED)
+                    .userVerification(UserVerificationRequirement.PREFERRED)
+                    .and()
+                .attestation(AttestationConveyancePreference.DIRECT)
+                .extensions()
+                    .credProps(true)
+                    .uvm(true)
+                .and()
+            .assertionOptionsEndpoint()
+                .assertionOptionsProvider(assertionOptionsProvider)
+                .processingUrl("/webauthn/assertion/options")
+                .rpId("example.com")
+                .userVerification(UserVerificationRequirement.PREFERRED)
+            .and();
+        });
+    }
+}
+
+
+
+
Dynamic generation of PublicKeyCredentialUserEntity
+
+

Attestation options endpoint can generate PublicKeyCredentialUserEntity to be returned dynamically based on the Authentication object associated with logged-in user. +To generate PublicKeyCredentialUserEntity, PublicKeyCredentialUserEntityProvider is provided.

+
+
+

Speaking of Java Config, it can be set in this way:

+
+
+
+
@Configuration
+public class WebSecurityConfig {
+
+    @Bean
+    public SecurityFilterChain filterChain(HttpSecurity http, AuthenticationManager authenticationManager) throws Exception {
+
+        // WebAuthn Login
+        http.with(WebAuthnLoginConfigurer.webAuthnLogin(), (customizer) ->{
+            customizer
+            .attestationOptionsEndpoint()
+                .attestationOptionsProvider(attestationOptionsProvider)
+                .processingUrl("/webauthn/attestation/options")
+                .processingUrl("/webauthn/attestation/options")
+                .user(new MyPublicKeyCredentialUserEntityProvider()); // put your PublicKeyCredentialUserEntityProvider implementation
+        });
+    }
+}
+
+
+
+

If PublicKeyCredentialUserEntityProvider is not set explicitly, WebAuthn4J Spring Security Java Config looks it up from Spring Application Context. +Registering its bean to the application context is another way to set it.

+
+
+
+
+

3.3.4. Selecting authentication method

+
+

WebAuthn4J Spring Security supports "Password-less multi-factor authentication with a user-verifying authenticator", "Multi-factor authentication with password and authenticator" and "Single-factor authentication like password". +If you put value on adoption, you may allow password authentication in your web system, or if you give greater importance to security, you may restrict password authentication.

+
+
+
How to realize password authentication
+
+

To realize "Multi-factor authentication with password and authenticator" and "Single-factor authentication like password", configure not only WebAuthnAuthenticationProvider but also DaoAuthenticationProvider to process UsernamePasswordAuthenticationToken. +"Multi-factor authentication with password and authenticator" can be realized by including additional authorization requirement to check a user is authenticated by WebAuthn.

+
+
+

Whether it is authenticated by WebAuthn can be checked with the WebAuthnSecurityExpression#isWebAuthnAuthenticated method. +Register a bean of WebAuthnSecurityExpression instance and call it from JavaConfig. WebAuthn4J Spring Security Sample MPA is a good example for it.

+
+
+
+
+
+

3.4. Advanced topics

+
+

3.4.1. Distinction of a user in the middle of multi-factor authentication

+
+

In the case where it is needed to show a different view based on authentication level, one way is to switch the view based on the type of the current Authentication instance.

+
+
+
+
@RequestMapping(value = "/login", method = RequestMethod.GET)
+public String login() {
+    Authentication authentication = SecurityContextHolder.getContext().getAuthentication();
+    if (authenticationTrustResolver.isAnonymous(authentication)) {
+        return VIEW_LOGIN_LOGIN;
+    } else {
+        return VIEW_LOGIN_AUTHENTICATOR_LOGIN;
+    }
+}
+
+
+
+
+

3.4.2. Configuring a credential scope (rpId)

+
+

In Web Authentication specification, the scope of a creating credential can be configured through the parameter named "rpId" while creating the credential i.e. registering authenticator. +"rpId" accepts effective domain. +For example, in the case where the domain of the site is webauthn.example.com, and webauthn.example.com is set to +rpId, the credential is only available in webauthn.example.com and its sub-domain, but if example.com +is set to rpId, the scope of the credential is relaxed to example.com and its sub-domain.

+
+
+

WebAuthn4J Spring Security supports rpId configuration through the rpId property of ServerPropertyProviderImpl, which can be configured through WebAuthnConfigurer in JavaConfig. +If you would like to change rpId dynamically based on request, set RpIdProvider.

+
+
+
+

3.4.3. Attestation statement verification

+
+

Web Authentication specification allows the relying party to retrieve an attestation statement from an authenticator if it is requested during authenticator registration. +By verifying attestation statement, the relying party can exclude authenticators not conforming its security requirements. +It’s to be noted that the attestation statement contains information that can be used to track user across web sites, it is discouraged to request an attestation statement unnecessarily. +It is also to be noted that the browser shows an additional dialog to confirm the user consent, lowering usability. +Except for enterprise applications that require strict verification of authenticators, most sites should not request attestation statements.

+
+
+

WebAuthnRegistrationContextValidator from WebAuthn4J validates an authenticator registration request, and it delegates attestation statement signature and trustworthiness validation to WebAuthnManager and +CertPathTrustworthinessValidator interface implementation respectively.

+
+
+

WebAuthnRegistrationContextValidator.createNonStrictRegistrationContextValidator factory method can create the +WebAuthnRegistrationContextValidator instance that contains AttestationStatementValidator and +CertPathTrustworthinessValidator configured for web sites not requiring strict attestation verification.

+
+
+
+

3.4.4. TrustAnchorProvider using Spring Resource

+
+

While validating an authenticator attestation certificate path on registration, +TrustAnchorCertPathTrustworthinessValidator class uses TrustAnchor retrieved through TrustAnchorProvider interface implementation. +WebAuthn4J Spring Security offers KeyStoreResourceTrustAnchorProvider class, which retrieves a +TrustAnchor from a Java Key Store file loaded as Spring Resource.

+
+
+
+
+
+
+

4. Spring Boot

+
+
+

Spring Boot Auto-Configuration for WebAuthn4J Spring Security is planned to be provided in the future version.

+
+
+
+
+

5. Sample application

+
+
+

WebAuthn4J Spring Security contains a sample application demonstrating its major functionalities. +Sample SPA is a demo of Single Page Application. Sample MPA is a demo of traditional Multi Page Application. +Sample SPA is explained below.

+
+
+

5.1. Sample application execution

+
+

Sample application can be executed by following command.

+
+
+
+
./gradlew samples:spa:bootRun
+
+
+
+
+

5.2. User and authenticator registration

+
+
+signup view +
+
+
+

The signup page can be accessed with http://localhost:8080/angular/signup. +Please fill user information and register user and authentication device.

+
+
+
+authenticator request popup +
+
+
+

Click the "Add" button in the "Authenticators" table, it will show a pop-up asking you to give a gesture to the authenticator to acknowledge the registration. +In case of an accident or device loss, Multiple authenticators can be registered for backup. +If you would like to allow single-factor authentication, Please check "Allow password authentication".

+
+
+
+

5.3. User authentication

+
+

Login page can be accessed with http://localhost:8080/angular/login. +Sample application supports three authentication flow.

+
+
+
    +
  • +

    Multi-factor authentication with password and authenticator

    +
    • +
  • +

    Password-less multi-factor authentication with a user-verifying authenticator

    +
    • +
  • +

    Single-factor authentication only with a password

    +
    • +
+
+
+

Each of three authentication flows are explained below.

+
+
+

5.3.1. Multi-factor authentication with password and authenticator

+
+

If you register a non user-verifying authenticator like FIDO-U2F token, you can login with multi-factor authentication with password and authenticator.

+
+
+
+login view +
+
+
+

Please fill the username (email address) and password on the login view and click the login button.

+
+
+
+authenticator login view +
+
+
+

If the password authentication succeeds, an authenticator is asked in the next authenticator login view. +When the pop-up opens, please give a gesture to the authenticator to finish the authentication. +You will be automatically redirected to the dashboard.

+
+
+
+

5.3.2. Password-less multi-factor authentication with a user-verifying authenticator

+
+

If you register a user-verifying authenticator like that supports FIDO-CTAP2, you can login without password.

+
+
+
+login view (password-less login) +
+
+
+

Click the "Password-less login" button on the login view and the pop-up asking an authenticator will be opened. +Please give a gesture to the authenticator to finish the authentication. +You will be automatically redirected to the dashboard.

+
+
+
+

5.3.3. Password authentication

+
+

If you checked "Allow password authentication" at user registration, standard password authentication is available.

+
+
+
+login view +
+
+
+

Please fill the username (email address) and password on the login view and click the login button. +If the authentication succeeds, you will be automatically redirected to the dashboard.

+
+
+
+
+
+
+ + + + \ No newline at end of file diff --git a/docs/en/introduction.html b/docs/en/introduction.html new file mode 100644 index 000000000..b57cd6cb5 --- /dev/null +++ b/docs/en/introduction.html @@ -0,0 +1,575 @@ + + + + + + + +Introduction + + + + + + + +
+
+

1. Introduction

+
+
+

1.1. Web Authentication

+
+

Web Authentication is a new, secure web application authentication specification standardizing under W3C. +By combining local authentication, public-key authentication, per-origin key management, it provides strong authentication to web sites against authentication process attacks like phishing. +Implementation is in progress in major browsers, the specification offers excellent choices for users who place importance on security and convenience. +Initially, the specification was developed as "FIDO 2.0: Web API for accessing FIDO 2.0 credentials" by the FIDO Alliance, but it has been transferred to W3C.

+
+
+
+

1.2. WebAuthn4J Spring Security

+
+

WebAuthn4J Spring Security is a Spring Security extension module to provide Web Authentication specification support for your Spring web application.

+
+
+

1.2.1. WebAuthn4J

+
+

WebAuthn4J Spring Security uses WebAuthn4J for WebAuthn attestation and assertion verification. +WebAuthn4J is a portable Java library that supports all the attestation statements, but has minimal dependencies on external libraries.

+
+
+
+

1.2.2. Spring Security WebAuthn

+
+

There is also a sister project called Spring Security WebAuthn. Spring Security WebAuthn is developed according to Spring Security project’s policy, aiming to be merged into Spring Security upstream. +WebAuthn4J Spring Security is developed as a WebAuthn4J project with the aim of maximizing the functions of the WebAuthn4J library.

+
+
+
+
+

1.3. Requirements

+
+

1.3.1. Language & Framework

+
+
    +
  • +

    Java8 or later

    +
    • +
  • +

    Spring Framework 5 or later

    +
    • +
  • +

    Spring Security 5 or later

    +
    • +
+
+
+
+

1.3.2. Environment

+
+
    +
  • +

    SecureContext

    +
    • +
  • +

    Browsers

    +
    +
      +
    • +

      Google Chrome 70 or later

      +
      • +
    • +

      Mozilla Firefox 60 or later

      +
      • +
    • +

      Microsoft Edge bundled with Windows 10 October 2018 Update or later

      +
      • +
    • +

      Safari 14 or later

      +
      • +
    +
    +
    • +
+
+
+
SecureContext
+
+

Web Authentication API is only available in SecureContext, which means only HTTPS connection is permitted while a user accessing web sites. +Browsers rejects Web Authentication API call if the web site is served through HTTP connection except localhost. +For more details about SecureContext, please see MDN.

+
+
+
+
+
+

1.4. Source code

+
+

Source code for this project is hosted on Github.

+
+
+
+
git clone https://github.com/webauthn4j/webauthn4j-spring-security
+
+
+
+
+

1.5. License

+
+

WebAuthn4J Spring Security is an open source software licensed under Apache 2.0 license.

+
+
+
+
+
+ + + + \ No newline at end of file diff --git a/docs/en/quick-start.html b/docs/en/quick-start.html new file mode 100644 index 000000000..a89b658a2 --- /dev/null +++ b/docs/en/quick-start.html @@ -0,0 +1,485 @@ + + + + + + + +Quick start + + + + + + + +
+
+

1. Quick start

+
+
+

WebAuthn4J Spring Security contains a sample application which demonstrates its major functionality.

+
+
+

It can be launched with the following command.

+
+
+
+
./gradlew samples:spa:bootRun
+
+
+
+
+login view +
+
+
+

Sample application is documented in a dedicated chapter. +Please refer Sample application.

+
+
+
+
+ + + + \ No newline at end of file diff --git a/docs/en/sample-app.html b/docs/en/sample-app.html new file mode 100644 index 000000000..81dab2c9f --- /dev/null +++ b/docs/en/sample-app.html @@ -0,0 +1,587 @@ + + + + + + + +Sample application + + + + + + + +
+
+

1. Sample application

+
+
+

WebAuthn4J Spring Security contains a sample application demonstrating its major functionalities. +Sample SPA is a demo of Single Page Application. Sample MPA is a demo of traditional Multi Page Application. +Sample SPA is explained below.

+
+
+

1.1. Sample application execution

+
+

Sample application can be executed by following command.

+
+
+
+
./gradlew samples:spa:bootRun
+
+
+
+
+

1.2. User and authenticator registration

+
+
+signup view +
+
+
+

The signup page can be accessed with http://localhost:8080/angular/signup. +Please fill user information and register user and authentication device.

+
+
+
+authenticator request popup +
+
+
+

Click the "Add" button in the "Authenticators" table, it will show a pop-up asking you to give a gesture to the authenticator to acknowledge the registration. +In case of an accident or device loss, Multiple authenticators can be registered for backup. +If you would like to allow single-factor authentication, Please check "Allow password authentication".

+
+
+
+

1.3. User authentication

+
+

Login page can be accessed with http://localhost:8080/angular/login. +Sample application supports three authentication flow.

+
+
+
    +
  • +

    Multi-factor authentication with password and authenticator

    +
    • +
  • +

    Password-less multi-factor authentication with a user-verifying authenticator

    +
    • +
  • +

    Single-factor authentication only with a password

    +
    • +
+
+
+

Each of three authentication flows are explained below.

+
+
+

1.3.1. Multi-factor authentication with password and authenticator

+
+

If you register a non user-verifying authenticator like FIDO-U2F token, you can login with multi-factor authentication with password and authenticator.

+
+
+
+login view +
+
+
+

Please fill the username (email address) and password on the login view and click the login button.

+
+
+
+authenticator login view +
+
+
+

If the password authentication succeeds, an authenticator is asked in the next authenticator login view. +When the pop-up opens, please give a gesture to the authenticator to finish the authentication. +You will be automatically redirected to the dashboard.

+
+
+
+

1.3.2. Password-less multi-factor authentication with a user-verifying authenticator

+
+

If you register a user-verifying authenticator like that supports FIDO-CTAP2, you can login without password.

+
+
+
+login view (password-less login) +
+
+
+

Click the "Password-less login" button on the login view and the pop-up asking an authenticator will be opened. +Please give a gesture to the authenticator to finish the authentication. +You will be automatically redirected to the dashboard.

+
+
+
+

1.3.3. Password authentication

+
+

If you checked "Allow password authentication" at user registration, standard password authentication is available.

+
+
+
+login view +
+
+
+

Please fill the username (email address) and password on the login view and click the login button. +If the authentication succeeds, you will be automatically redirected to the dashboard.

+
+
+
+
+
+
+ + + + \ No newline at end of file diff --git a/docs/en/spring-boot.html b/docs/en/spring-boot.html new file mode 100644 index 000000000..fe8855cbf --- /dev/null +++ b/docs/en/spring-boot.html @@ -0,0 +1,468 @@ + + + + + + + +Spring Boot + + + + + + + +
+
+

1. Spring Boot

+
+
+

Spring Boot Auto-Configuration for WebAuthn4J Spring Security is planned to be provided in the future version.

+
+
+
+
+ + + + \ No newline at end of file diff --git a/docs/internal/angular-update-procedure.md b/docs/internal/angular-update-procedure.md deleted file mode 100644 index cc5c50b59..000000000 --- a/docs/internal/angular-update-procedure.md +++ /dev/null @@ -1,15 +0,0 @@ -# Angular update procedure - -This document describes how to update Angular in spa-angular-client module - -```$bash -./gradlew npm_update -``` - -```$bash -./gradlew npm_run_ng_update -``` - -```$bash -./gradlew npm_run_ngUpdate -``` diff --git a/docs/internal/release-procedure.md b/docs/internal/release-procedure.md deleted file mode 100644 index 3f9a2f729..000000000 --- a/docs/internal/release-procedure.md +++ /dev/null @@ -1,111 +0,0 @@ -# Release procedure - -This document describes WebAuthn4J Spring Security release procedure. - -### Prepare a release commit - -##### Create a release branch - -``` -git checkout -b release- -``` - -##### Update version variables in build.gradle - -gradle.properties -``` -webAuthn4JSpringSecurityVersion=.RELEASE -latestReleasedWebAuthn4JSpringSecurity=.RELEASE -``` - -##### Update versions in documents - -``` -./gradlew updateVersionsInDocuments -``` - -##### Create a release commit - -``` -git commit -a -m "Release .RELEASE" -``` - -##### Push the release branch - -``` -git push origin release- -``` - -##### Create a pull request - -create a pull request with following title: `Release .RELEASE` - -##### Check the build status & Merge the pull request - -Check the build status & merge the pull request. - -### Prepare a release tag - -##### Prepare a release note - -generate a release note draft - -``` -./gradlew generateReleaseNote -``` - -update the release note draft (`build/release-note.md`) properly with your editor. - -##### Create a release tag - -``` -git tag .RELEASE -``` - -### Ship the release - -##### Push the release tag - -``` -git push origin .RELEASE -``` - -##### Update the release note on GitHub - -Update the release note on GitHub - -### Declare new version development start - -##### Create a branch - -``` -git checkout -b -development -``` - -##### Update version variables in build.gradle - -gradle.properties -``` -webAuthn4JSpringSecurityVersion=-SNAPSHOT -latestReleasedWebAuthn4JSpringSecurity=.RELEASE -``` - -##### Commit the change - - ``` -git commit -a -m "Start development" - ``` - -##### Push the release branch - -``` -git push origin -development -``` - -##### Check the build status - -Check the build status before continue. - -##### Merge the pull request - -merge the pull request and delete the branch. diff --git a/docs/ja/configuration.html b/docs/ja/configuration.html new file mode 100644 index 000000000..821837461 --- /dev/null +++ b/docs/ja/configuration.html @@ -0,0 +1,805 @@ + + + + + + + +設定 + + + + + + + +
+
+

1. 設定

+
+
+

1.1. アプリケーションへの組込

+
+

1.1.1. Maven依存関係

+
+

ライブラリとその依存関係を導入するために、以下をpom.xmlファイルに追加してください。

+
+
+
+
<properties>
+  ...
+  <!-- Use the latest version whenever possible. -->
+  <webauthn4j-spring-security.version>0.7.0.RELEASE</webauthn4j-spring-security.version>
+  ...
+</properties>
+
+<dependency>
+	<groupId>com.webauthn4j</groupId>
+	<artifactId>webauthn4j-spring-security-core</artifactId>
+	<version>${webauthn4j-spring-security.version}</version>
+</dependency>
+
+
+
+
+

1.1.2. Java Config

+
+

WebAuthn4J Spring Securityは、Security SecurityのJava Config DSLで設定することが可能です。 +SecurityFilterChain Beanを以下のように定義し、HttpSecurity Beanに対して WebAuthnLoginConfigurer を適用して下さい。 +WebAuthnLoginConfigurer を通じて WebAuthnProcessingFilter やWebAuthn JS APIのリクエストパラメータを返却するAttestation Optionsエンドポイント、Assertion Optionsエンドポイントの各種設定が可能です。

+
+
+
+
@Configuration
+public class WebSecurityConfig {
+
+    @Bean
+    public SecurityFilterChain filterChain(HttpSecurity http, AuthenticationManager authenticationManager) throws Exception {
+
+        http.authenticationManager(authenticationManager);
+        // WebAuthn Login
+        http.with(WebAuthnLoginConfigurer.webAuthnLogin(), (customizer) ->{
+            customizer
+                    .loginPage("/login")
+                    .usernameParameter("username")
+                    .passwordParameter("password")
+                    .credentialIdParameter("credentialId")
+                    .clientDataJSONParameter("clientDataJSON")
+                    .authenticatorDataParameter("authenticatorData")
+                    .signatureParameter("signature")
+                    .clientExtensionsJSONParameter("clientExtensionsJSON")
+                    .loginProcessingUrl("/login")
+                    .attestationOptionsEndpoint()
+                        .rp()
+                            .name("WebAuthn4J Spring Security Sample")
+                        .and()
+                        .pubKeyCredParams(
+                                new PublicKeyCredentialParameters(PublicKeyCredentialType.PUBLIC_KEY, COSEAlgorithmIdentifier.RS256), // Windows Hello
+                                new PublicKeyCredentialParameters(PublicKeyCredentialType.PUBLIC_KEY, COSEAlgorithmIdentifier.ES256) // FIDO U2F Key, etc
+                        )
+                        .extensions()
+                            .credProps(true)
+                    .and()
+                    .assertionOptionsEndpoint()
+                    .and()
+                    .successHandler(authenticationSuccessHandler)
+                    .failureHandler(authenticationFailureHandler);
+        });
+    }
+}
+
+
+
+
WebAuthnAuthenticationProviderの組込
+
+

Web Authentication用の AuthenticationProvider である WebAuthnAuthenticationProvider はBeanとして定義して下さい。 +パスワード認証と組み合わせた二段階認証とする場合は、 DaoAuthenticationProvider のBean定義も必要です。

+
+
+
+
    @Bean
+    public WebAuthnAuthenticationProvider webAuthnAuthenticationProvider(WebAuthnAuthenticatorService authenticatorService, WebAuthnManager webAuthnManager){
+        return new WebAuthnAuthenticationProvider(authenticatorService, webAuthnManager);
+    }
+
+    @Bean
+    public DaoAuthenticationProvider daoAuthenticationProvider(UserDetailsService userDetailsService){
+        DaoAuthenticationProvider daoAuthenticationProvider = new DaoAuthenticationProvider();
+        daoAuthenticationProvider.setUserDetailsService(userDetailsService);
+        daoAuthenticationProvider.setPasswordEncoder(new BCryptPasswordEncoder());
+        return daoAuthenticationProvider;
+    }
+
+    @Bean
+    public AuthenticationManager authenticationManager(List<AuthenticationProvider> providers){
+        return new ProviderManager(providers);
+    }
+
+
+
+
+
+

1.1.3. 永続化層との統合

+
+

WebAuthn4J Spring Securityは WebAuthnCredentialRecordService インタフェースを通じて認証デバイスを検索します。 +WebAuthnCredentialRecordService を実装したクラスを用意し、 WebAuthnAuthenticationProvider にセットして下さい。

+
+
+
+
+

1.2. クライアントサイドとのインタフェース仕様

+
+

Web Authentication仕様では、ブラウザのJavaScript APIが規定されており、取得した資格情報をサーバーに対して送信する インタフェースについては規定がありません。

+
+
+

1.2.1. WebAuthn認証リクエストの処理

+
+

WebAuthn4J Spring Securityでは、認証処理に関しては、ログインURLに対して送信されたリクエストから WebAuthnProcessingFilter がリクエストパラメータとして +credentialId 、clientData 、 authenticatorData 、signature 、clientExtensionsJSON を取得して認証を行います。 +credentialId 、clientData 、 authenticatorData 、signature はバイナリデータの為、クライアントサイドはBase64URLエンコードして送信して下さい。

+
+
+
+

1.2.2. 認証デバイス登録時の処理

+
+

認証処理と異なり、登録処理については、通常WebAuthn以外のデータ、例えばユーザーの氏名やメールアドレスなども一緒に登録する必要があることから、 +WebAuthn4J Security Securityとして一律のエンドポイントを設けることは難しく、登録処理用のServlet Filterの提供は行っていません。 +認証デバイス登録操作のハンドリングは、基本的にはアプリケーション側の責務ですが、登録しようとしている資格情報が +認証時に使用できるものであるか検証する為に、WebAuthn4J Spring Securityはコンバータおよびバリデータを提供します。 +Base64StringToCollectedClientDataConverter はBase64URL文字列を CollectedClientData に変換します。 +Base64StringToAttestationObjectConverter はBase64URL文字列を AttestationObject に変換します。 +WebAuthnRegistrationRequestValidator は、認証デバイスの登録リクエストの検証に用いることが出来ます。

+
+
+
オプションエンドポイント
+
+

Web Authentication仕様では、WebAuthn JS APIで資格情報の作成、認証を行う際にAPIの引数としてサーバーから取得したチャレンジ渡す必要があります。 +また、FIDO-U2Fトークンを認証デバイスとして使用する場合も、第一認証要素によって特定されたユーザーに紐づけられた CredentialIdをサーバーから取得して渡す必要があります。 +これらのWebAuthn JS APIの引数をサーバーから取得するためのエンドポイントとして、 WebAuthn4J Spring Securityでは AttestationOptionsEndpointFilter と AssertionOptionsEndpointFilter を用意しています。

+
+
+
+
+
+

1.3. カスタマイズ

+
+

1.3.1. WebAuthnProcessingFilter

+
+

WebAuthnProcessingFilter は、受信したリクエストから credentialId 、clientData 、 authenticatorData 、signature 、clientExtensionsJSON +といったパラメータを取得して WebAuthnAssertionAuthenticationToken の組立を行います。 +credentialId パラメータが受信したリクエストに存在しない場合は、 username 、 password パラメータを読み取り、 +UsernamePasswordAuthenticationToken を組み立てます。 リクエストパラメータ名を変更したい場合は、 +WebAuthnProcessingFilter のプロパティ、あるいは WebAuthnLoginConfigurer の対応するJava Configメソッドから設定可能です。

+
+
+
+

1.3.2. WebAuthnAuthenticationProvider

+
+

WebAuthnAuthenticationProvider は WebAuthnAssertionAuthenticationToken を処理するための AuthenticationProvider +インタフェースの実装です。WebAuthnのアサーションの検証には WebAuthnManager を使用します。 +WebAuthnManager については WebAuthn4Jのリファレンス を参照して下さい。

+
+
+
+

1.3.3. Attestation Optionsエンドポイント、Assertion optionsエンドポイント

+
+

WebAuthn4J Spring Securityは、WebAuthn JS APIで資格情報の作成を行う際のパラメータを返却するエンドポイントとして AttestationOptionsEndpointFilter を、 +認証を行う際のパラメータを返却する際のエンドポイントとして AssertionOptionsEndpointFilter を用意しています。 +返却する値の生成は、それぞれ AttestationOptionsProvider インタフェース、 AssertionOptionsProvider インタフェースを通じて委譲されているので、 +これらのカスタム実装を行うことで、返却値を自由にカスタマイズすることが可能です。

+
+
+

Java Configからカスタマイズも可能です。 WebAuthnLoginConfigurer の attestationOptionsEndpoint メソッドあるいは assertionOptionsEndpoint からのチェーンを用いて +カスタマイズすることが出来ます。

+
+
+
+
@Configuration
+public class WebSecurityConfig {
+
+    @Bean
+    public SecurityFilterChain filterChain(HttpSecurity http, AuthenticationManager authenticationManager) throws Exception {
+        http.authenticationManager(authenticationManager);
+        // WebAuthn Login
+        http.with(WebAuthnLoginConfigurer.webAuthnLogin(), (customizer) ->{
+            customizer
+            .rpId("example.com")
+            .attestationOptionsEndpoint()
+                .attestationOptionsProvider(attestationOptionsProvider)
+                .processingUrl("/webauthn/attestation/options")
+                .rp()
+                    .name("example")
+                    .and()
+                .pubKeyCredParams(
+                        new PublicKeyCredentialParameters(PublicKeyCredentialType.PUBLIC_KEY, COSEAlgorithmIdentifier.ES256),
+                        new PublicKeyCredentialParameters(PublicKeyCredentialType.PUBLIC_KEY, COSEAlgorithmIdentifier.RS1)
+                )
+                .authenticatorSelection()
+                    .authenticatorAttachment(AuthenticatorAttachment.CROSS_PLATFORM)
+                    .residentKey(ResidentKeyRequirement.PREFERRED)
+                    .userVerification(UserVerificationRequirement.PREFERRED)
+                    .and()
+                .attestation(AttestationConveyancePreference.DIRECT)
+                .extensions()
+                    .credProps(true)
+                    .uvm(true)
+                .and()
+            .assertionOptionsEndpoint()
+                .assertionOptionsProvider(assertionOptionsProvider)
+                .processingUrl("/webauthn/assertion/options")
+                .rpId("example.com")
+                .userVerification(UserVerificationRequirement.PREFERRED)
+            .and();
+        });
+    }
+}
+
+
+
+
PublicKeyCredentialUserEntityの動的な生成
+
+

Attestation Optionsエンドポイントは、返却する PublicKeyCredentialUserEntity をログイン中のユーザーの Authentication に基づいて +動的に生成することが可能です。動的に生成する為のハンドラとして PublicKeyCredentialUserEntityProvider インタフェースが用意されています。 +AttestationOptionsProviderImpl クラスの setPublicKeyCredentialUserEntityProvider メソッドからセットしてください。

+
+
+

Java Configの場合は、以下のようにセット可能です。

+
+
+
+
@Configuration
+public class WebSecurityConfig {
+
+    @Bean
+    public SecurityFilterChain filterChain(HttpSecurity http, AuthenticationManager authenticationManager) throws Exception {
+
+        // WebAuthn Login
+        http.with(WebAuthnLoginConfigurer.webAuthnLogin(), (customizer) ->{
+            customizer
+            .attestationOptionsEndpoint()
+                .attestationOptionsProvider(attestationOptionsProvider)
+                .processingUrl("/webauthn/attestation/options")
+                .processingUrl("/webauthn/attestation/options")
+                .user(new MyPublicKeyCredentialUserEntityProvider()); // put your PublicKeyCredentialUserEntityProvider implementation
+        });
+    }
+}
+
+
+
+

WebAuthn4J Spring SecurityのJava Configは、明示的に指定されていない場合、SpringのApplicationContextから PublicKeyCredentialUserEntityProvider を検索しますので、 +Bean登録することでも PublicKeyCredentialUserEntityProvider のセットが可能です。

+
+
+
+
+

1.3.4. 認証方法の選択

+
+

WebAuthn4J Spring Securityでは、認証方法として「ユーザー検証機能付き認証デバイスによるパスワードレス多要素認証」、 「パスワード＋認証デバイスによる多要素認証」、「パスワード等による単一要素認証」をサポートしています。 +パスワード認証をサポートし、ユーザーへの間口を広げることも出来ますし、パスワード認証を制限することで、 セキュリティを高めることも出来ます。

+
+
+
パスワード認証の実装
+
+

「パスワード＋認証デバイスによる多要素認証」、「パスワード等による単一要素認証」をサポートする場合、 WebAuthnAuthenticationProvider に加えて、 DaoAuthenticationProvider を構成し、 UsernamePasswordAuthenticationToken を処理できるようにする必要があります。 +「パスワード＋認証デバイスによる多要素認証」が必要なページは、WebAuthnで認証されているかを認可要件に含めることで実装出来ます。

+
+
+

WebAuthnで認証されているかは、 WebAuthnSecurityExpression#isWebAuthnAuthenticated メソッドでチェック可能です。WebAuthnSecurityExpressionのインスタンスをBean登録し、JavaConfigから呼び出してください。 +WebAuthn4J Spring Security Sample MPA で実装例を示しているので、参考にして下さい。

+
+
+
+
+
+

1.4. 高度なトピック

+
+

1.4.1. 多要素認証で第一要素のみ認証完了したユーザーの識別

+
+

ユーザーの認証レベルによって異なるページを表示したい場合、以下のように現在の Authentication インスタンスの型で画面を切り替えるのが一つの方法です。

+
+
+
+
@RequestMapping(value = "/login", method = RequestMethod.GET)
+public String login() {
+    Authentication authentication = SecurityContextHolder.getContext().getAuthentication();
+    if (authenticationTrustResolver.isAnonymous(authentication)) {
+        return VIEW_LOGIN_LOGIN;
+    } else {
+        return VIEW_LOGIN_AUTHENTICATOR_LOGIN;
+    }
+}
+
+
+
+
+

1.4.2. 資格情報の有効範囲（RpId）設定

+
+

Web Authentication仕様では、資格情報の作成時、即ち認証デバイスの登録時、その資格情報の有効範囲を制限するための パラメータとして、 rpId を指定します。 +rpId には、 effective domain を指定することが出来ます。 +例えば、資格情報の作成を行った ページのドメインが dev.example.com だった場合に、RpIdを dev.example.com と指定すれば、その資格情報は dev.example.com とそのサブドメインの範囲だけで利用できますが、 rpId を example.com とすることで、 資格情報が利用可能な範囲を example.com およびそのサブドメインに広げることが出来ます。

+
+
+

WebAuthn4J Spring Securityでは、 rpId は ServerPropertyProviderImpl のプロパティとして設定可能で、JavaConfigでは、 WebAuthnConfigurer を通じて設定可能です。 +リクエストに応じて動的に変更したい場合、`RpIdProvider`をセットしてください。

+
+
+
+

1.4.3. 構成証明ステートメントの検証

+
+

Web Authentication仕様では、認証デバイスの登録時に要求すれば認証デバイスの構成証明ステートメントを取得することが出来ます。 +Relying Partyは取得した構成証明ステートメントを検証することで、セキュリティ要件に合致しない認証デバイスの受け入れを拒否することが可能です。 +但し、構成証明ステートメントにはユーザーのサイトを跨いだトラッキングに利用できる情報が含まれていることから、無闇に 要求するべきではありません。また、構成証明ステートメントを要求した場合、ブラウザはユーザーに対して追加のダイアログを 表示するため、ユーザビリティが低下することも注意が必要です。認証デバイスの厳密な検証が必要なエンタープライズ用途以外、 通常のB2Cサイトでは、構成証明ステートメントの要求を行うべきではないでしょう。

+
+
+

WebAuthn4Jでは、WebAuthnRegistrationContextValidator が認証デバイスの登録リクエストの検証を行いますが、 取得した構成証明ステートメントの署名と信頼性の検証は、それぞれ AttestationStatementValidator と +CertPathTrustworthinessValidator インタフェースの実装に委譲します。

+
+
+

厳密な構成証明ステートメントの検証を必要としないサイト向けに、AttestationStatementValidator と +CertPathTrustworthinessValidator を構成した WebAuthnRegistrationContextValidator のインスタンスは、 +WebAuthnRegistrationContextValidator.createNonStrictRegistrationContextValidator ファクトリメソッドで作成出来ます。

+
+
+
+

1.4.4. SpringのResourceを活用したTrustAnchorProvider

+
+

認証デバイスを登録時に証明書パスから検証する場合、 TrustAnchorCertPathTrustworthinessValidator クラスは +TrustAnchorProvider インタフェースの実装クラスから取得した TrustAnchor を使用します。WebAuthn4J Spring Securityでは、 SpringのResourceとして読み込んだJava Key Storeファイルを TrustAnchor として使用する TrustAnchorProvider として、 +KeyStoreResourceTrustAnchorProvider クラスを提供します。

+
+
+
+
+
+
+ + + + \ No newline at end of file diff --git a/docs/src/reference/asciidoc/ja/images/authenticatorLogin.png b/docs/ja/images/authenticatorLogin.png similarity index 100% rename from docs/src/reference/asciidoc/ja/images/authenticatorLogin.png rename to docs/ja/images/authenticatorLogin.png diff --git a/docs/src/reference/asciidoc/ja/images/login-with-popup.png b/docs/ja/images/login-with-popup.png similarity index 100% rename from docs/src/reference/asciidoc/ja/images/login-with-popup.png rename to docs/ja/images/login-with-popup.png diff --git a/docs/src/reference/asciidoc/ja/images/login.png b/docs/ja/images/login.png similarity index 100% rename from docs/src/reference/asciidoc/ja/images/login.png rename to docs/ja/images/login.png diff --git a/docs/src/reference/asciidoc/ja/images/signup-with-authenticator-form.png b/docs/ja/images/signup-with-authenticator-form.png similarity index 100% rename from docs/src/reference/asciidoc/ja/images/signup-with-authenticator-form.png rename to docs/ja/images/signup-with-authenticator-form.png diff --git a/docs/src/reference/asciidoc/ja/images/signup-with-popup.png b/docs/ja/images/signup-with-popup.png similarity index 100% rename from docs/src/reference/asciidoc/ja/images/signup-with-popup.png rename to docs/ja/images/signup-with-popup.png diff --git a/docs/src/reference/asciidoc/ja/images/signup.png b/docs/ja/images/signup.png similarity index 100% rename from docs/src/reference/asciidoc/ja/images/signup.png rename to docs/ja/images/signup.png diff --git a/docs/ja/index.html b/docs/ja/index.html new file mode 100644 index 000000000..01df9ac3e --- /dev/null +++ b/docs/ja/index.html @@ -0,0 +1,1075 @@ + + + + + + + +WebAuthn4J Spring Security Reference + + + + + + + +
+
+

1. 導入

+
+
+

1.1. Web Authenticationとは

+
+

Web Authenticationは、W3Cで仕様策定が進められている、Webアプリケーションの新しいセキュアな認証方式仕様です。 ローカル認証や公開鍵認証、Origin別の鍵管理を組み合わせることで、フィッシングなど認証プロセスに対する攻撃に対して堅固な認証を実現しています。 主要ブラウザでの実装が進みつつあり、セキュリティ、利便性を重視するユーザーに対して優れた選択肢を提供します。 当初はFIDO AllianceでFIDO 2.0: Web API for accessing FIDO 2.0 credentialsとして仕様策定が進められていましたが、 現在はW3Cに移管され、仕様策定が行われています。

+
+
+
+

1.2. WebAuthn4J Spring Securityとは

+
+

Spring Securityで保護されたWebアプリケーションに対して、Web Authentication仕様に基づく認証機能を提供するための Spring Security拡張です。

+
+
+

1.2.1. WebAuthn4Jとは

+
+

WebAuthnのアサーションの検証に関わるコアの処理は WebAuthn4J という別のプロジェクトで開発を進めています。 +WebAuthn4Jは、 全ての構成証明ステートメント（Attestation）をサポートしながら、外部ライブラリへの依存関係は最小限に抑えたポータブルなJavaライブラリです。

+
+
+
+

1.2.2. Spring Security WebAuthnとの関係

+
+

Spring Security WebAuthnという姉妹プロジェクトも存在します。Spring Security WebAuthnは、Spring Security本体へのマージを目指してSpring Securityプロジェクトの方針に則って開発されている一方、 +WebAuthn4J Spring Securityは、WebAuthn4Jのプロジェクトとして、WebAuthn4Jライブラリの機能を最大限に、またより早く取り込むことを目的に開発を進めています。

+
+
+
+
+

1.3. 要件

+
+

1.3.1. 言語・フレームワーク

+
+
    +
  • +

    Java8以降

    +
    • +
  • +

    Spring Framework 5以降

    +
    • +
  • +

    Spring Security 5以降

    +
    • +
+
+
+
+

1.3.2. 動作環境

+
+

WebAuthn4J Spring Securityの動作環境は、以下の要件を満たす必要があります。

+
+
+
    +
  • +

    SecureContext

    +
    • +
  • +

    ブラウザ

    +
    +
      +
    • +

      Google Chrome 70以降

      +
      • +
    • +

      Mozilla Firefox 60以降

      +
      • +
    • +

      Microsoft Edge Windows 10 October 2018 Update同梱版 以降

      +
      • +
    • +

      Safari 14以降

      +
      • +
    +
    +
    • +
+
+
+
SecureContext
+
+

Web Authentication仕様では、動作環境がSecureContextであることを要求しています。 これは、ユーザーがサイトに接続する際、HTTPS接続でなければならないことを意味します。HTTP接続環境下では、ブラウザはWebAuthnに関連した要求を拒否するため、利用できません。 但し、 localhost では例外的にHTTP接続が認められています。SecureContextについて詳しくは MDN を参照ください。

+
+
+
+
+
+

1.4. ソースコード

+
+

ソースコードは Github で管理されています。

+
+
+
+
git clone https://github.com/webauthn4j/webauthn4j-spring-security
+
+
+
+
+

1.5. ライセンス

+
+

WebAuthn4J Spring Securityは Apache 2.0 license ライセンスの オープンソースソフトウェアです。

+
+
+
+
+
+

2. クイックスタート

+
+
+

WebAuthn4J Spring Securityは主要機能をデモするサンプルアプリケーションを含みます。

+
+
+

サンプルアプリケーションは以下のコマンドで実行することが出来ます。

+
+
+
+
./gradlew samples:spa:bootRun
+
+
+
+
+ログイン画面 +
+
+
+

サンプルアプリケーションについては、 サンプルアプリケーション で詳しく説明していますので、そちらを参照下さい。

+
+
+
+
+

3. 設定

+
+
+

3.1. アプリケーションへの組込

+
+

3.1.1. Maven依存関係

+
+

ライブラリとその依存関係を導入するために、以下をpom.xmlファイルに追加してください。

+
+
+
+
<properties>
+  ...
+  <!-- Use the latest version whenever possible. -->
+  <webauthn4j-spring-security.version>0.7.0.RELEASE</webauthn4j-spring-security.version>
+  ...
+</properties>
+
+<dependency>
+	<groupId>com.webauthn4j</groupId>
+	<artifactId>webauthn4j-spring-security-core</artifactId>
+	<version>${webauthn4j-spring-security.version}</version>
+</dependency>
+
+
+
+
+

3.1.2. Java Config

+
+

WebAuthn4J Spring Securityは、Security SecurityのJava Config DSLで設定することが可能です。 +SecurityFilterChain Beanを以下のように定義し、HttpSecurity Beanに対して WebAuthnLoginConfigurer を適用して下さい。 +WebAuthnLoginConfigurer を通じて WebAuthnProcessingFilter やWebAuthn JS APIのリクエストパラメータを返却するAttestation Optionsエンドポイント、Assertion Optionsエンドポイントの各種設定が可能です。

+
+
+
+
@Configuration
+public class WebSecurityConfig {
+
+    @Bean
+    public SecurityFilterChain filterChain(HttpSecurity http, AuthenticationManager authenticationManager) throws Exception {
+
+        http.authenticationManager(authenticationManager);
+        // WebAuthn Login
+        http.with(WebAuthnLoginConfigurer.webAuthnLogin(), (customizer) ->{
+            customizer
+                    .loginPage("/login")
+                    .usernameParameter("username")
+                    .passwordParameter("password")
+                    .credentialIdParameter("credentialId")
+                    .clientDataJSONParameter("clientDataJSON")
+                    .authenticatorDataParameter("authenticatorData")
+                    .signatureParameter("signature")
+                    .clientExtensionsJSONParameter("clientExtensionsJSON")
+                    .loginProcessingUrl("/login")
+                    .attestationOptionsEndpoint()
+                        .rp()
+                            .name("WebAuthn4J Spring Security Sample")
+                        .and()
+                        .pubKeyCredParams(
+                                new PublicKeyCredentialParameters(PublicKeyCredentialType.PUBLIC_KEY, COSEAlgorithmIdentifier.RS256), // Windows Hello
+                                new PublicKeyCredentialParameters(PublicKeyCredentialType.PUBLIC_KEY, COSEAlgorithmIdentifier.ES256) // FIDO U2F Key, etc
+                        )
+                        .extensions()
+                            .credProps(true)
+                    .and()
+                    .assertionOptionsEndpoint()
+                    .and()
+                    .successHandler(authenticationSuccessHandler)
+                    .failureHandler(authenticationFailureHandler);
+        });
+    }
+}
+
+
+
+
WebAuthnAuthenticationProviderの組込
+
+

Web Authentication用の AuthenticationProvider である WebAuthnAuthenticationProvider はBeanとして定義して下さい。 +パスワード認証と組み合わせた二段階認証とする場合は、 DaoAuthenticationProvider のBean定義も必要です。

+
+
+
+
    @Bean
+    public WebAuthnAuthenticationProvider webAuthnAuthenticationProvider(WebAuthnAuthenticatorService authenticatorService, WebAuthnManager webAuthnManager){
+        return new WebAuthnAuthenticationProvider(authenticatorService, webAuthnManager);
+    }
+
+    @Bean
+    public DaoAuthenticationProvider daoAuthenticationProvider(UserDetailsService userDetailsService){
+        DaoAuthenticationProvider daoAuthenticationProvider = new DaoAuthenticationProvider();
+        daoAuthenticationProvider.setUserDetailsService(userDetailsService);
+        daoAuthenticationProvider.setPasswordEncoder(new BCryptPasswordEncoder());
+        return daoAuthenticationProvider;
+    }
+
+    @Bean
+    public AuthenticationManager authenticationManager(List<AuthenticationProvider> providers){
+        return new ProviderManager(providers);
+    }
+
+
+
+
+
+

3.1.3. 永続化層との統合

+
+

WebAuthn4J Spring Securityは WebAuthnCredentialRecordService インタフェースを通じて認証デバイスを検索します。 +WebAuthnCredentialRecordService を実装したクラスを用意し、 WebAuthnAuthenticationProvider にセットして下さい。

+
+
+
+
+

3.2. クライアントサイドとのインタフェース仕様

+
+

Web Authentication仕様では、ブラウザのJavaScript APIが規定されており、取得した資格情報をサーバーに対して送信する インタフェースについては規定がありません。

+
+
+

3.2.1. WebAuthn認証リクエストの処理

+
+

WebAuthn4J Spring Securityでは、認証処理に関しては、ログインURLに対して送信されたリクエストから WebAuthnProcessingFilter がリクエストパラメータとして +credentialId 、clientData 、 authenticatorData 、signature 、clientExtensionsJSON を取得して認証を行います。 +credentialId 、clientData 、 authenticatorData 、signature はバイナリデータの為、クライアントサイドはBase64URLエンコードして送信して下さい。

+
+
+
+

3.2.2. 認証デバイス登録時の処理

+
+

認証処理と異なり、登録処理については、通常WebAuthn以外のデータ、例えばユーザーの氏名やメールアドレスなども一緒に登録する必要があることから、 +WebAuthn4J Security Securityとして一律のエンドポイントを設けることは難しく、登録処理用のServlet Filterの提供は行っていません。 +認証デバイス登録操作のハンドリングは、基本的にはアプリケーション側の責務ですが、登録しようとしている資格情報が +認証時に使用できるものであるか検証する為に、WebAuthn4J Spring Securityはコンバータおよびバリデータを提供します。 +Base64StringToCollectedClientDataConverter はBase64URL文字列を CollectedClientData に変換します。 +Base64StringToAttestationObjectConverter はBase64URL文字列を AttestationObject に変換します。 +WebAuthnRegistrationRequestValidator は、認証デバイスの登録リクエストの検証に用いることが出来ます。

+
+
+
オプションエンドポイント
+
+

Web Authentication仕様では、WebAuthn JS APIで資格情報の作成、認証を行う際にAPIの引数としてサーバーから取得したチャレンジ渡す必要があります。 +また、FIDO-U2Fトークンを認証デバイスとして使用する場合も、第一認証要素によって特定されたユーザーに紐づけられた CredentialIdをサーバーから取得して渡す必要があります。 +これらのWebAuthn JS APIの引数をサーバーから取得するためのエンドポイントとして、 WebAuthn4J Spring Securityでは AttestationOptionsEndpointFilter と AssertionOptionsEndpointFilter を用意しています。

+
+
+
+
+
+

3.3. カスタマイズ

+
+

3.3.1. WebAuthnProcessingFilter

+
+

WebAuthnProcessingFilter は、受信したリクエストから credentialId 、clientData 、 authenticatorData 、signature 、clientExtensionsJSON +といったパラメータを取得して WebAuthnAssertionAuthenticationToken の組立を行います。 +credentialId パラメータが受信したリクエストに存在しない場合は、 username 、 password パラメータを読み取り、 +UsernamePasswordAuthenticationToken を組み立てます。 リクエストパラメータ名を変更したい場合は、 +WebAuthnProcessingFilter のプロパティ、あるいは WebAuthnLoginConfigurer の対応するJava Configメソッドから設定可能です。

+
+
+
+

3.3.2. WebAuthnAuthenticationProvider

+
+

WebAuthnAuthenticationProvider は WebAuthnAssertionAuthenticationToken を処理するための AuthenticationProvider +インタフェースの実装です。WebAuthnのアサーションの検証には WebAuthnManager を使用します。 +WebAuthnManager については WebAuthn4Jのリファレンス を参照して下さい。

+
+
+
+

3.3.3. Attestation Optionsエンドポイント、Assertion optionsエンドポイント

+
+

WebAuthn4J Spring Securityは、WebAuthn JS APIで資格情報の作成を行う際のパラメータを返却するエンドポイントとして AttestationOptionsEndpointFilter を、 +認証を行う際のパラメータを返却する際のエンドポイントとして AssertionOptionsEndpointFilter を用意しています。 +返却する値の生成は、それぞれ AttestationOptionsProvider インタフェース、 AssertionOptionsProvider インタフェースを通じて委譲されているので、 +これらのカスタム実装を行うことで、返却値を自由にカスタマイズすることが可能です。

+
+
+

Java Configからカスタマイズも可能です。 WebAuthnLoginConfigurer の attestationOptionsEndpoint メソッドあるいは assertionOptionsEndpoint からのチェーンを用いて +カスタマイズすることが出来ます。

+
+
+
+
@Configuration
+public class WebSecurityConfig {
+
+    @Bean
+    public SecurityFilterChain filterChain(HttpSecurity http, AuthenticationManager authenticationManager) throws Exception {
+        http.authenticationManager(authenticationManager);
+        // WebAuthn Login
+        http.with(WebAuthnLoginConfigurer.webAuthnLogin(), (customizer) ->{
+            customizer
+            .rpId("example.com")
+            .attestationOptionsEndpoint()
+                .attestationOptionsProvider(attestationOptionsProvider)
+                .processingUrl("/webauthn/attestation/options")
+                .rp()
+                    .name("example")
+                    .and()
+                .pubKeyCredParams(
+                        new PublicKeyCredentialParameters(PublicKeyCredentialType.PUBLIC_KEY, COSEAlgorithmIdentifier.ES256),
+                        new PublicKeyCredentialParameters(PublicKeyCredentialType.PUBLIC_KEY, COSEAlgorithmIdentifier.RS1)
+                )
+                .authenticatorSelection()
+                    .authenticatorAttachment(AuthenticatorAttachment.CROSS_PLATFORM)
+                    .residentKey(ResidentKeyRequirement.PREFERRED)
+                    .userVerification(UserVerificationRequirement.PREFERRED)
+                    .and()
+                .attestation(AttestationConveyancePreference.DIRECT)
+                .extensions()
+                    .credProps(true)
+                    .uvm(true)
+                .and()
+            .assertionOptionsEndpoint()
+                .assertionOptionsProvider(assertionOptionsProvider)
+                .processingUrl("/webauthn/assertion/options")
+                .rpId("example.com")
+                .userVerification(UserVerificationRequirement.PREFERRED)
+            .and();
+        });
+    }
+}
+
+
+
+
PublicKeyCredentialUserEntityの動的な生成
+
+

Attestation Optionsエンドポイントは、返却する PublicKeyCredentialUserEntity をログイン中のユーザーの Authentication に基づいて +動的に生成することが可能です。動的に生成する為のハンドラとして PublicKeyCredentialUserEntityProvider インタフェースが用意されています。 +AttestationOptionsProviderImpl クラスの setPublicKeyCredentialUserEntityProvider メソッドからセットしてください。

+
+
+

Java Configの場合は、以下のようにセット可能です。

+
+
+
+
@Configuration
+public class WebSecurityConfig {
+
+    @Bean
+    public SecurityFilterChain filterChain(HttpSecurity http, AuthenticationManager authenticationManager) throws Exception {
+
+        // WebAuthn Login
+        http.with(WebAuthnLoginConfigurer.webAuthnLogin(), (customizer) ->{
+            customizer
+            .attestationOptionsEndpoint()
+                .attestationOptionsProvider(attestationOptionsProvider)
+                .processingUrl("/webauthn/attestation/options")
+                .processingUrl("/webauthn/attestation/options")
+                .user(new MyPublicKeyCredentialUserEntityProvider()); // put your PublicKeyCredentialUserEntityProvider implementation
+        });
+    }
+}
+
+
+
+

WebAuthn4J Spring SecurityのJava Configは、明示的に指定されていない場合、SpringのApplicationContextから PublicKeyCredentialUserEntityProvider を検索しますので、 +Bean登録することでも PublicKeyCredentialUserEntityProvider のセットが可能です。

+
+
+
+
+

3.3.4. 認証方法の選択

+
+

WebAuthn4J Spring Securityでは、認証方法として「ユーザー検証機能付き認証デバイスによるパスワードレス多要素認証」、 「パスワード＋認証デバイスによる多要素認証」、「パスワード等による単一要素認証」をサポートしています。 +パスワード認証をサポートし、ユーザーへの間口を広げることも出来ますし、パスワード認証を制限することで、 セキュリティを高めることも出来ます。

+
+
+
パスワード認証の実装
+
+

「パスワード＋認証デバイスによる多要素認証」、「パスワード等による単一要素認証」をサポートする場合、 WebAuthnAuthenticationProvider に加えて、 DaoAuthenticationProvider を構成し、 UsernamePasswordAuthenticationToken を処理できるようにする必要があります。 +「パスワード＋認証デバイスによる多要素認証」が必要なページは、WebAuthnで認証されているかを認可要件に含めることで実装出来ます。

+
+
+

WebAuthnで認証されているかは、 WebAuthnSecurityExpression#isWebAuthnAuthenticated メソッドでチェック可能です。WebAuthnSecurityExpressionのインスタンスをBean登録し、JavaConfigから呼び出してください。 +WebAuthn4J Spring Security Sample MPA で実装例を示しているので、参考にして下さい。

+
+
+
+
+
+

3.4. 高度なトピック

+
+

3.4.1. 多要素認証で第一要素のみ認証完了したユーザーの識別

+
+

ユーザーの認証レベルによって異なるページを表示したい場合、以下のように現在の Authentication インスタンスの型で画面を切り替えるのが一つの方法です。

+
+
+
+
@RequestMapping(value = "/login", method = RequestMethod.GET)
+public String login() {
+    Authentication authentication = SecurityContextHolder.getContext().getAuthentication();
+    if (authenticationTrustResolver.isAnonymous(authentication)) {
+        return VIEW_LOGIN_LOGIN;
+    } else {
+        return VIEW_LOGIN_AUTHENTICATOR_LOGIN;
+    }
+}
+
+
+
+
+

3.4.2. 資格情報の有効範囲（RpId）設定

+
+

Web Authentication仕様では、資格情報の作成時、即ち認証デバイスの登録時、その資格情報の有効範囲を制限するための パラメータとして、 rpId を指定します。 +rpId には、 effective domain を指定することが出来ます。 +例えば、資格情報の作成を行った ページのドメインが dev.example.com だった場合に、RpIdを dev.example.com と指定すれば、その資格情報は dev.example.com とそのサブドメインの範囲だけで利用できますが、 rpId を example.com とすることで、 資格情報が利用可能な範囲を example.com およびそのサブドメインに広げることが出来ます。

+
+
+

WebAuthn4J Spring Securityでは、 rpId は ServerPropertyProviderImpl のプロパティとして設定可能で、JavaConfigでは、 WebAuthnConfigurer を通じて設定可能です。 +リクエストに応じて動的に変更したい場合、`RpIdProvider`をセットしてください。

+
+
+
+

3.4.3. 構成証明ステートメントの検証

+
+

Web Authentication仕様では、認証デバイスの登録時に要求すれば認証デバイスの構成証明ステートメントを取得することが出来ます。 +Relying Partyは取得した構成証明ステートメントを検証することで、セキュリティ要件に合致しない認証デバイスの受け入れを拒否することが可能です。 +但し、構成証明ステートメントにはユーザーのサイトを跨いだトラッキングに利用できる情報が含まれていることから、無闇に 要求するべきではありません。また、構成証明ステートメントを要求した場合、ブラウザはユーザーに対して追加のダイアログを 表示するため、ユーザビリティが低下することも注意が必要です。認証デバイスの厳密な検証が必要なエンタープライズ用途以外、 通常のB2Cサイトでは、構成証明ステートメントの要求を行うべきではないでしょう。

+
+
+

WebAuthn4Jでは、WebAuthnRegistrationContextValidator が認証デバイスの登録リクエストの検証を行いますが、 取得した構成証明ステートメントの署名と信頼性の検証は、それぞれ AttestationStatementValidator と +CertPathTrustworthinessValidator インタフェースの実装に委譲します。

+
+
+

厳密な構成証明ステートメントの検証を必要としないサイト向けに、AttestationStatementValidator と +CertPathTrustworthinessValidator を構成した WebAuthnRegistrationContextValidator のインスタンスは、 +WebAuthnRegistrationContextValidator.createNonStrictRegistrationContextValidator ファクトリメソッドで作成出来ます。

+
+
+
+

3.4.4. SpringのResourceを活用したTrustAnchorProvider

+
+

認証デバイスを登録時に証明書パスから検証する場合、 TrustAnchorCertPathTrustworthinessValidator クラスは +TrustAnchorProvider インタフェースの実装クラスから取得した TrustAnchor を使用します。WebAuthn4J Spring Securityでは、 SpringのResourceとして読み込んだJava Key Storeファイルを TrustAnchor として使用する TrustAnchorProvider として、 +KeyStoreResourceTrustAnchorProvider クラスを提供します。

+
+
+
+
+
+
+

4. Spring Boot

+
+
+

WebAuthn4J Spring Securityに対するSpring Boot Auto-Configurationは将来のバージョンで提供される予定です。

+
+
+
+
+

5. サンプルアプリケーション

+
+
+

webauthn4j-spring-securityは主要機能をデモするサンプルアプリケーションを含みます。 +Single Page Applicationのデモである、Sample SPAと、従来型のMulti Page Applicationである、Sample MPAです。以下ではSample SPAについて説明します。

+
+
+

5.1. サンプルアプリケーションの実行

+
+

サンプルアプリケーションは以下のコマンドで実行することが出来ます。

+
+
+
+
./gradlew samples:spa:bootRun
+
+
+
+
+

5.2. ユーザーおよび認証デバイスの登録

+
+
+サインアップ画面 +
+
+
+

サインアップ画面は、 http://localhost:8080/angular/signup でアクセスすることが出来ます。 ユーザー情報を入力し、ユーザーと認証デバイスの登録を行ってください。

+
+
+
+認証デバイス要求ポップアップ +
+
+
+

「認証デバイス」欄の「追加」ボタンを押下すると認証デバイスでの操作を促すポップアップが表示され、 認証デバイスの登録モードになりますので、ポップアップに従い登録を済ませてください。 認証デバイスは紛失・故障に備え、バックアップとして複数登録することが出来ます。 パスワードのみによる単一要素認証を許可する場合は、「パスワード認証を許可」にチェックを入れてください。

+
+
+
+

5.3. ユーザー認証

+
+

ログイン画面は、 http://localhost:/8080/angular/login でアクセスすることが出来ます。 サンプルアプリケーションではユーザー認証について、三つの認証フローをサポートしています。

+
+
+
    +
  • +

    パスワード＋認証デバイスによる多要素認証

    +
    • +
  • +

    ユーザー検証機能付き認証デバイスによるパスワードレス多要素認証

    +
    • +
  • +

    パスワードのみによる単一要素認証

    +
    • +
+
+
+

以下、三つの認証フローについてそれぞれ説明していきます。

+
+
+

5.3.1. パスワード＋認証デバイスによる多要素認証

+
+

ユーザー検証機能が付いていないFIDO-U2Fのトークンのような認証デバイスを登録した場合は、パスワード＋認証デバイスによる 多要素認証が可能です。

+
+
+
+ログイン画面 +
+
+
+

ログイン画面でユーザー名（Emailアドレス）とパスワードを入力し、ログインボタンを押下してください。

+
+
+
+認証デバイスログイン画面 +
+
+
+

パスワード認証に成功した場合、第二認証要素として認証デバイスを用いた認証を求める、認証デバイスログイン画面が開きます。 認証を求めるポップアップが開いたら、認証デバイスを操作し、認証を完了してください。認証に成功すると、画面が自動的に遷移します。

+
+
+
+

5.3.2. ユーザー検証機能付き認証デバイスによるパスワードレス多要素認証

+
+

ユーザー検証機能が付いている認証デバイスを登録した場合、パスワードレス認証が可能です。

+
+
+
+ログイン画面（パスワードレスログイン） +
+
+
+

ログイン画面の「パスワードレスログイン」ボタンを押下すると、認証デバイスを用いた認証を求めるポップアップが開きます。 認証デバイスを操作し、認証を完了してください。認証に成功すると、画面が自動的に遷移します。

+
+
+
+

5.3.3. パスワード認証

+
+

ユーザー登録時に「パスワード認証を許可」にチェックを入れていた場合、 通常のパスワード認証が利用可能です。

+
+
+
+ログイン画面 +
+
+
+

ログイン画面でユーザー名とパスワードを入力し、「ログイン」ボタンを押下して認証を完了してください。 認証に成功すると、画面は自動的に遷移します。

+
+
+
+
+
+
+ + + + \ No newline at end of file diff --git a/docs/ja/introduction.html b/docs/ja/introduction.html new file mode 100644 index 000000000..249b91975 --- /dev/null +++ b/docs/ja/introduction.html @@ -0,0 +1,573 @@ + + + + + + + +導入 + + + + + + + +
+
+

1. 導入

+
+
+

1.1. Web Authenticationとは

+
+

Web Authenticationは、W3Cで仕様策定が進められている、Webアプリケーションの新しいセキュアな認証方式仕様です。 ローカル認証や公開鍵認証、Origin別の鍵管理を組み合わせることで、フィッシングなど認証プロセスに対する攻撃に対して堅固な認証を実現しています。 主要ブラウザでの実装が進みつつあり、セキュリティ、利便性を重視するユーザーに対して優れた選択肢を提供します。 当初はFIDO AllianceでFIDO 2.0: Web API for accessing FIDO 2.0 credentialsとして仕様策定が進められていましたが、 現在はW3Cに移管され、仕様策定が行われています。

+
+
+
+

1.2. WebAuthn4J Spring Securityとは

+
+

Spring Securityで保護されたWebアプリケーションに対して、Web Authentication仕様に基づく認証機能を提供するための Spring Security拡張です。

+
+
+

1.2.1. WebAuthn4Jとは

+
+

WebAuthnのアサーションの検証に関わるコアの処理は WebAuthn4J という別のプロジェクトで開発を進めています。 +WebAuthn4Jは、 全ての構成証明ステートメント（Attestation）をサポートしながら、外部ライブラリへの依存関係は最小限に抑えたポータブルなJavaライブラリです。

+
+
+
+

1.2.2. Spring Security WebAuthnとの関係

+
+

Spring Security WebAuthnという姉妹プロジェクトも存在します。Spring Security WebAuthnは、Spring Security本体へのマージを目指してSpring Securityプロジェクトの方針に則って開発されている一方、 +WebAuthn4J Spring Securityは、WebAuthn4Jのプロジェクトとして、WebAuthn4Jライブラリの機能を最大限に、またより早く取り込むことを目的に開発を進めています。

+
+
+
+
+

1.3. 要件

+
+

1.3.1. 言語・フレームワーク

+
+
    +
  • +

    Java8以降

    +
    • +
  • +

    Spring Framework 5以降

    +
    • +
  • +

    Spring Security 5以降

    +
    • +
+
+
+
+

1.3.2. 動作環境

+
+

WebAuthn4J Spring Securityの動作環境は、以下の要件を満たす必要があります。

+
+
+
    +
  • +

    SecureContext

    +
    • +
  • +

    ブラウザ

    +
    +
      +
    • +

      Google Chrome 70以降

      +
      • +
    • +

      Mozilla Firefox 60以降

      +
      • +
    • +

      Microsoft Edge Windows 10 October 2018 Update同梱版 以降

      +
      • +
    • +

      Safari 14以降

      +
      • +
    +
    +
    • +
+
+
+
SecureContext
+
+

Web Authentication仕様では、動作環境がSecureContextであることを要求しています。 これは、ユーザーがサイトに接続する際、HTTPS接続でなければならないことを意味します。HTTP接続環境下では、ブラウザはWebAuthnに関連した要求を拒否するため、利用できません。 但し、 localhost では例外的にHTTP接続が認められています。SecureContextについて詳しくは MDN を参照ください。

+
+
+
+
+
+

1.4. ソースコード

+
+

ソースコードは Github で管理されています。

+
+
+
+
git clone https://github.com/webauthn4j/webauthn4j-spring-security
+
+
+
+
+

1.5. ライセンス

+
+

WebAuthn4J Spring Securityは Apache 2.0 license ライセンスの オープンソースソフトウェアです。

+
+
+
+
+
+ + + + \ No newline at end of file diff --git a/docs/ja/quick-start.html b/docs/ja/quick-start.html new file mode 100644 index 000000000..8642a7991 --- /dev/null +++ b/docs/ja/quick-start.html @@ -0,0 +1,484 @@ + + + + + + + +クイックスタート + + + + + + + +
+
+

1. クイックスタート

+
+
+

WebAuthn4J Spring Securityは主要機能をデモするサンプルアプリケーションを含みます。

+
+
+

サンプルアプリケーションは以下のコマンドで実行することが出来ます。

+
+
+
+
./gradlew samples:spa:bootRun
+
+
+
+
+ログイン画面 +
+
+
+

サンプルアプリケーションについては、 サンプルアプリケーション で詳しく説明していますので、そちらを参照下さい。

+
+
+
+
+ + + + \ No newline at end of file diff --git a/docs/ja/sample-app.html b/docs/ja/sample-app.html new file mode 100644 index 000000000..b17f5fca2 --- /dev/null +++ b/docs/ja/sample-app.html @@ -0,0 +1,577 @@ + + + + + + + +サンプルアプリケーション + + + + + + + +
+
+

1. サンプルアプリケーション

+
+
+

webauthn4j-spring-securityは主要機能をデモするサンプルアプリケーションを含みます。 +Single Page Applicationのデモである、Sample SPAと、従来型のMulti Page Applicationである、Sample MPAです。以下ではSample SPAについて説明します。

+
+
+

1.1. サンプルアプリケーションの実行

+
+

サンプルアプリケーションは以下のコマンドで実行することが出来ます。

+
+
+
+
./gradlew samples:spa:bootRun
+
+
+
+
+

1.2. ユーザーおよび認証デバイスの登録

+
+
+サインアップ画面 +
+
+
+

サインアップ画面は、 http://localhost:8080/angular/signup でアクセスすることが出来ます。 ユーザー情報を入力し、ユーザーと認証デバイスの登録を行ってください。

+
+
+
+認証デバイス要求ポップアップ +
+
+
+

「認証デバイス」欄の「追加」ボタンを押下すると認証デバイスでの操作を促すポップアップが表示され、 認証デバイスの登録モードになりますので、ポップアップに従い登録を済ませてください。 認証デバイスは紛失・故障に備え、バックアップとして複数登録することが出来ます。 パスワードのみによる単一要素認証を許可する場合は、「パスワード認証を許可」にチェックを入れてください。

+
+
+
+

1.3. ユーザー認証

+
+

ログイン画面は、 http://localhost:/8080/angular/login でアクセスすることが出来ます。 サンプルアプリケーションではユーザー認証について、三つの認証フローをサポートしています。

+
+
+
    +
  • +

    パスワード＋認証デバイスによる多要素認証

    +
    • +
  • +

    ユーザー検証機能付き認証デバイスによるパスワードレス多要素認証

    +
    • +
  • +

    パスワードのみによる単一要素認証

    +
    • +
+
+
+

以下、三つの認証フローについてそれぞれ説明していきます。

+
+
+

1.3.1. パスワード＋認証デバイスによる多要素認証

+
+

ユーザー検証機能が付いていないFIDO-U2Fのトークンのような認証デバイスを登録した場合は、パスワード＋認証デバイスによる 多要素認証が可能です。

+
+
+
+ログイン画面 +
+
+
+

ログイン画面でユーザー名（Emailアドレス）とパスワードを入力し、ログインボタンを押下してください。

+
+
+
+認証デバイスログイン画面 +
+
+
+

パスワード認証に成功した場合、第二認証要素として認証デバイスを用いた認証を求める、認証デバイスログイン画面が開きます。 認証を求めるポップアップが開いたら、認証デバイスを操作し、認証を完了してください。認証に成功すると、画面が自動的に遷移します。

+
+
+
+

1.3.2. ユーザー検証機能付き認証デバイスによるパスワードレス多要素認証

+
+

ユーザー検証機能が付いている認証デバイスを登録した場合、パスワードレス認証が可能です。

+
+
+
+ログイン画面（パスワードレスログイン） +
+
+
+

ログイン画面の「パスワードレスログイン」ボタンを押下すると、認証デバイスを用いた認証を求めるポップアップが開きます。 認証デバイスを操作し、認証を完了してください。認証に成功すると、画面が自動的に遷移します。

+
+
+
+

1.3.3. パスワード認証

+
+

ユーザー登録時に「パスワード認証を許可」にチェックを入れていた場合、 通常のパスワード認証が利用可能です。

+
+
+
+ログイン画面 +
+
+
+

ログイン画面でユーザー名とパスワードを入力し、「ログイン」ボタンを押下して認証を完了してください。 認証に成功すると、画面は自動的に遷移します。

+
+
+
+
+
+
+ + + + \ No newline at end of file diff --git a/docs/ja/spring-boot.html b/docs/ja/spring-boot.html new file mode 100644 index 000000000..af6b81d7e --- /dev/null +++ b/docs/ja/spring-boot.html @@ -0,0 +1,468 @@ + + + + + + + +Spring Boot + + + + + + + +
+
+

1. Spring Boot

+
+
+

WebAuthn4J Spring Securityに対するSpring Boot Auto-Configurationは将来のバージョンで提供される予定です。

+
+
+
+
+ + + + \ No newline at end of file diff --git a/docs/src/reference/asciidoc/en/configuration.adoc b/docs/src/reference/asciidoc/en/configuration.adoc deleted file mode 100644 index afa72d8fc..000000000 --- a/docs/src/reference/asciidoc/en/configuration.adoc +++ /dev/null @@ -1,288 +0,0 @@ - -== Configuration - -=== Applications integration - -==== Maven dependency - -Please add following to pom.xml to introduce WebAuthn4J Spring Security and its dependencies. - -[source,xml] ----- - - ... - - 0.7.6.RELEASE - ... - - - - com.webauthn4j - webauthn4j-spring-security-core - ${webauthn4j-spring-security.version} - ----- - -==== Java Config - -WebAuthn4J Spring Security can be configured through the Spring Security Java Config DSL. -Please define the `SecurityFilterChain` bean as follows and apply the `WebAuthnLoginConfigurer` to the `HttpSecurity` bean. -Through `WebAuthnLoginConfigurer`, you can set various options of the `WebAuthnProcessingFilter`, Attestation options endpoint, and Assertion options endpoint. - -[source,java] ----- -@Configuration -public class WebSecurityConfig { - - @Bean - public SecurityFilterChain filterChain(HttpSecurity http, AuthenticationManager authenticationManager) throws Exception { - - http.authenticationManager(authenticationManager); - // WebAuthn Login - http.with(WebAuthnLoginConfigurer.webAuthnLogin(), (customizer) ->{ - customizer - .loginPage("/login") - .usernameParameter("username") - .passwordParameter("password") - .credentialIdParameter("credentialId") - .clientDataJSONParameter("clientDataJSON") - .authenticatorDataParameter("authenticatorData") - .signatureParameter("signature") - .clientExtensionsJSONParameter("clientExtensionsJSON") - .loginProcessingUrl("/login") - .attestationOptionsEndpoint() - .rp() - .name("WebAuthn4J Spring Security Sample") - .and() - .pubKeyCredParams( - new PublicKeyCredentialParameters(PublicKeyCredentialType.PUBLIC_KEY, COSEAlgorithmIdentifier.RS256), // Windows Hello - new PublicKeyCredentialParameters(PublicKeyCredentialType.PUBLIC_KEY, COSEAlgorithmIdentifier.ES256) // FIDO U2F Key, etc - ) - .extensions() - .credProps(true) - .and() - .assertionOptionsEndpoint() - .and() - .successHandler(authenticationSuccessHandler) - .failureHandler(authenticationFailureHandler); - }); - } -} ----- - -===== Integrating WebAuthnAuthenticationProvider - -`WebAuthnAuthenticationProvider`, an `AuthenticationProvider` for Web Authentication, need to be defined as a Bean. -If you set up two-step authentication combined with password authentication, you also need a Bean definition for `DaoAuthenticationProvider`. - -[source,java] ----- - @Bean - public WebAuthnAuthenticationProvider webAuthnAuthenticationProvider(WebAuthnAuthenticatorService authenticatorService, WebAuthnManager webAuthnManager){ - return new WebAuthnAuthenticationProvider(authenticatorService, webAuthnManager); - } - - @Bean - public DaoAuthenticationProvider daoAuthenticationProvider(UserDetailsService userDetailsService){ - DaoAuthenticationProvider daoAuthenticationProvider = new DaoAuthenticationProvider(); - daoAuthenticationProvider.setUserDetailsService(userDetailsService); - daoAuthenticationProvider.setPasswordEncoder(new BCryptPasswordEncoder()); - return daoAuthenticationProvider; - } - - @Bean - public AuthenticationManager authenticationManager(List providers){ - return new ProviderManager(providers); - } ----- - -==== Persistence layer integration - -WebAuthn4J Spring Security looks up an authenticator through the `WebAuthnCredentialRecordService` interface. -Please set a class implementing `WebAuthnCredentialRecordService` to the `WebAuthnAuthenticationProvider`. -Speaking of Java Config, it can be set through a constructor of `WebAuthnAuthenticationProviderConfigurer`. - -=== Client interface - -W3C Web Authentication specification defines web browser JavaScript APIs only. It is up to implementation how to send a generated credential. - -==== WebAuthn authentication request processing - -Regarding WebAuthn4J Spring Security, `WebAuthnProcessingFilter` retrieves `credentialId`, `clientData`, `authenticatorData`, `signature`, and `clientExtensionsJSON` from the request sent to login processing url. -`credentialId`, `clientData`, `authenticatorData` and `signature` are binary data, please send them as Base64 strings. - -==== WebAuthn registration request processing - -In contrast to authentication request processing, Servlet filter is not provided for registration request processing -because in most cases, data other than WebAuthn like user's first name, last name, or email address are sent at the same time. - -While it is basically application's responsibility to handle an authenticator registration process, WebAuthn4J Spring Security provides converters and validators to examine the received credential. -`Base64StringToCollectedClientDataConverter` converts Base64 string to a `CollectedClientData`. -`Base64StringToAttestationObjectConverter` converts Base64 string to a `AttestationObject`. - -`WebAuthnRegistrationRequestValidator` validates an authenticator registration request. - -==== Options endpoints - -Web Authentication needs to obtain a challenge from the server prior to registration and authentication. -When using the FIDO-U2F token as an authentication device, the CredentialIds associated with the user identified by the first authentication factor also need to be obtained from the server. -To retrieve these data, WebAuthn4J Spring Security offers `AttestationOptionsEndpointFilter` and `AssertionOptionsEndpointFilter`. - -=== Customization - -==== WebAuthnProcessingFilter - -`WebAuthnProcessingFilter` retrieves `credentialId`, `clientData`, `authenticatorData`, `signature`, and `clientExtensionsJSON` from the request and build `WebAuthnAssertionAuthenticationToken`. -If `credentialId` does not exist, it retrieves `username` and `password` to build `UsernamePasswordAuthenticationToken`. -To change request parameter names, configure properties of `WebAuthnProcessingFilter` or corresponding Java Config method of `WebAuthnLoginConfigurer`. - -==== WebAuthnAuthenticationProvider - -`WebAuthnAuthenticationProvider` is an `AuthenticationProvider` implementation to process a `WebAuthnAssertionAuthenticationToken`. -For WebAuthn assertion verification, `WebAuthnManager` is used. See https://webauthn4j.github.io/webauthn4j/en/[WebAuthn4J reference] for more details of `WebAuthnManager`. - -==== Attestation options endpoint, Assertion options endpoint - -WebAuthn4J Spring Security provides `AttestationOptionsEndpointFilter` for WebAuthn JS Credential Creation API parameters serving, and `AssertionOptionsEndpointFilter` for WebAuthn JS Credential Get API parameter serving. -As these Parameters generation are delegated through `AttestationOptionsProvider` and `AssertionOptionsProvider` interfaces, they can be customized by implementing these interfaces. - -These can be customized through Java Config. Method chains from `WebAuthnLoginConfigurer` 's `attestationOptionsEndpoint` method or `assertionOptionsEndpoint` method are configuration point for that. - -[source,java] ----- -@Configuration -public class WebSecurityConfig { - - @Bean - public SecurityFilterChain filterChain(HttpSecurity http, AuthenticationManager authenticationManager) throws Exception { - http.authenticationManager(authenticationManager); - // WebAuthn Login - http.with(WebAuthnLoginConfigurer.webAuthnLogin(), (customizer) ->{ - customizer - .rpId("example.com") - .attestationOptionsEndpoint() - .attestationOptionsProvider(attestationOptionsProvider) - .processingUrl("/webauthn/attestation/options") - .rp() - .name("example") - .and() - .pubKeyCredParams( - new PublicKeyCredentialParameters(PublicKeyCredentialType.PUBLIC_KEY, COSEAlgorithmIdentifier.ES256), - new PublicKeyCredentialParameters(PublicKeyCredentialType.PUBLIC_KEY, COSEAlgorithmIdentifier.RS1) - ) - .authenticatorSelection() - .authenticatorAttachment(AuthenticatorAttachment.CROSS_PLATFORM) - .residentKey(ResidentKeyRequirement.PREFERRED) - .userVerification(UserVerificationRequirement.PREFERRED) - .and() - .attestation(AttestationConveyancePreference.DIRECT) - .extensions() - .credProps(true) - .uvm(true) - .and() - .assertionOptionsEndpoint() - .assertionOptionsProvider(assertionOptionsProvider) - .processingUrl("/webauthn/assertion/options") - .rpId("example.com") - .userVerification(UserVerificationRequirement.PREFERRED) - .and(); - }); - } -} - ----- - -===== Dynamic generation of PublicKeyCredentialUserEntity - -Attestation options endpoint can generate `PublicKeyCredentialUserEntity` to be returned dynamically based on the `Authentication` object associated with logged-in user. -To generate `PublicKeyCredentialUserEntity`, `PublicKeyCredentialUserEntityProvider` is provided. - -Speaking of Java Config, it can be set in this way: - ----- -@Configuration -public class WebSecurityConfig { - - @Bean - public SecurityFilterChain filterChain(HttpSecurity http, AuthenticationManager authenticationManager) throws Exception { - - // WebAuthn Login - http.with(WebAuthnLoginConfigurer.webAuthnLogin(), (customizer) ->{ - customizer - .attestationOptionsEndpoint() - .attestationOptionsProvider(attestationOptionsProvider) - .processingUrl("/webauthn/attestation/options") - .processingUrl("/webauthn/attestation/options") - .user(new MyPublicKeyCredentialUserEntityProvider()); // put your PublicKeyCredentialUserEntityProvider implementation - }); - } -} ----- - -If `PublicKeyCredentialUserEntityProvider` is not set explicitly, WebAuthn4J Spring Security Java Config looks it up from Spring Application Context. -Registering its bean to the application context is another way to set it. - -==== Selecting authentication method - -WebAuthn4J Spring Security supports "Password-less multi-factor authentication with a user-verifying authenticator", "Multi-factor authentication with password and authenticator" and "Single-factor authentication like password". -If you put value on adoption, you may allow password authentication in your web system, or if you give greater importance to security, you may restrict password authentication. - -===== How to realize password authentication - -To realize "Multi-factor authentication with password and authenticator" and "Single-factor authentication like password", configure not only `WebAuthnAuthenticationProvider` but also `DaoAuthenticationProvider` to process `UsernamePasswordAuthenticationToken`. -"Multi-factor authentication with password and authenticator" can be realized by including additional authorization requirement to check a user is authenticated by WebAuthn. - -Whether it is authenticated by WebAuthn can be checked with the `WebAuthnSecurityExpression#isWebAuthnAuthenticated` method. -Register a bean of `WebAuthnSecurityExpression` instance and call it from JavaConfig. WebAuthn4J Spring Security Sample MPA is a good example for it. - -=== Advanced topics - -==== Distinction of a user in the middle of multi-factor authentication - -In the case where it is needed to show a different view based on authentication level, one way is to switch the view based on the type of the current `Authentication` instance. - -[source,java] ----- -@RequestMapping(value = "/login", method = RequestMethod.GET) -public String login() { - Authentication authentication = SecurityContextHolder.getContext().getAuthentication(); - if (authenticationTrustResolver.isAnonymous(authentication)) { - return VIEW_LOGIN_LOGIN; - } else { - return VIEW_LOGIN_AUTHENTICATOR_LOGIN; - } -} ----- - -==== Configuring a credential scope (rpId) - -In Web Authentication specification, the scope of a creating credential can be configured through the parameter named "rpId" while creating the credential i.e. registering authenticator. -"rpId" accepts https://html.spec.whatwg.org/multipage/origin.html#concept-origin-effective-domain[effective domain]. -For example, in the case where the domain of the site is `webauthn.example.com`, and `webauthn.example.com` is set to -`rpId`, the credential is only available in `webauthn.example.com` and its sub-domain, but if `example.com` -is set to `rpId`, the scope of the credential is relaxed to `example.com` and its sub-domain. - -WebAuthn4J Spring Security supports `rpId` configuration through the `rpId` property of `ServerPropertyProviderImpl`, which can be configured through `WebAuthnConfigurer` in JavaConfig. -If you would like to change `rpId` dynamically based on request, set `RpIdProvider`. - -==== Attestation statement verification - -Web Authentication specification allows the relying party to retrieve an attestation statement from an authenticator if it is requested during authenticator registration. -By verifying attestation statement, the relying party can exclude authenticators not conforming its security requirements. -It's to be noted that the attestation statement contains information that can be used to track user across web sites, it is discouraged to request an attestation statement unnecessarily. -It is also to be noted that the browser shows an additional dialog to confirm the user consent, lowering usability. -Except for enterprise applications that require strict verification of authenticators, most sites should not request attestation statements. - -`WebAuthnRegistrationContextValidator` from WebAuthn4J validates an authenticator registration request, and it delegates attestation statement signature and trustworthiness validation to `WebAuthnManager` and -`CertPathTrustworthinessValidator` interface implementation respectively. - -`WebAuthnRegistrationContextValidator.createNonStrictRegistrationContextValidator` factory method can create the -`WebAuthnRegistrationContextValidator` instance that contains `AttestationStatementValidator` and -`CertPathTrustworthinessValidator` configured for web sites not requiring strict attestation verification. - -==== TrustAnchorProvider using Spring Resource - -While validating an authenticator attestation certificate path on registration, -`TrustAnchorCertPathTrustworthinessValidator` class uses `TrustAnchor` retrieved through `TrustAnchorProvider` interface implementation. -WebAuthn4J Spring Security offers `KeyStoreResourceTrustAnchorProvider` class, which retrieves a -`TrustAnchor` from a Java Key Store file loaded as Spring `Resource`. diff --git a/docs/src/reference/asciidoc/en/index.adoc b/docs/src/reference/asciidoc/en/index.adoc deleted file mode 100644 index 853d79ada..000000000 --- a/docs/src/reference/asciidoc/en/index.adoc +++ /dev/null @@ -1,19 +0,0 @@ -:java-ClassLoader: http://docs.oracle.com/javase/7/docs/api/java/lang/ClassLoader.html -:core-ApplicationContext: http://docs.spring.io/spring/docs/{spring-version}/javadoc-api/org/springframework/context/ApplicationContext.html -:core-beans-factory-placeholderconfigurer: http://docs.spring.io/spring/docs/{spring-version}/spring-framework-reference/html/beans.html#beans-factory-placeholderconfigurer -:core-beans-environment: http://docs.spring.io/spring/docs/{spring-version}/spring-framework-reference/html/beans.html#beans-environment -:core-ResourcePatternResolver: http://docs.spring.io/spring/docs/{spring-version}/javadoc-api/org/springframework/core/io/support/ResourcePatternResolver.html -:core-ref-util: http://docs.spring.io/spring/docs/{spring-version}/spring-framework-reference/html/xsd-config.html#xsd-config-body-schemas-util-properties -:core-aop-schema-advisors: http://docs.spring.io/spring/docs/{spring-version}/spring-framework-reference/html/aop.html#aop-schema-advisors -:core-dao: http://docs.spring.io/spring/docs/{spring-version}/spring-framework-reference/html/dao.html -:core-dao-exceptions: http://docs.spring.io/spring/docs/{spring-version}/spring-framework-reference/html/dao.html#dao-exceptions -:core-jdbc: http://docs.spring.io/spring/docs/{spring-version}/spring-framework-reference/html/jdbc.html -:core-jdbc-JdbcTemplate: http://docs.spring.io/spring/docs/{spring-version}/spring-framework-reference/html/jdbc.html#jdbc-JdbcTemplate - -= WebAuthn4J Spring Security Reference - -include::introduction.adoc[] -include::quick-start.adoc[] -include::configuration.adoc[] -include::spring-boot.adoc[] -include::sample-app.adoc[] \ No newline at end of file diff --git a/docs/src/reference/asciidoc/en/introduction.adoc b/docs/src/reference/asciidoc/en/introduction.adoc deleted file mode 100644 index 414af985c..000000000 --- a/docs/src/reference/asciidoc/en/introduction.adoc +++ /dev/null @@ -1,57 +0,0 @@ -== Introduction - -=== Web Authentication - -Web Authentication is a new, secure web application authentication specification standardizing under W3C. -By combining local authentication, public-key authentication, per-origin key management, it provides strong authentication to web sites against authentication process attacks like phishing. -Implementation is in progress in major browsers, the specification offers excellent choices for users who place importance on security and convenience. -Initially, the specification was developed as "FIDO 2.0: Web API for accessing FIDO 2.0 credentials" by the FIDO Alliance, but it has been transferred to W3C. - -=== WebAuthn4J Spring Security - -WebAuthn4J Spring Security is a Spring Security extension module to provide Web Authentication specification support for your Spring web application. - -==== WebAuthn4J - -WebAuthn4J Spring Security uses https://github.com/webauthn4j/webauthn4j[WebAuthn4J] for WebAuthn attestation and assertion verification. -WebAuthn4J is a portable Java library that supports all the attestation statements, but has minimal dependencies on external libraries. - -==== Spring Security WebAuthn - -There is also a sister project called Spring Security WebAuthn. Spring Security WebAuthn is developed according to Spring Security project's policy, aiming to be merged into Spring Security upstream. -WebAuthn4J Spring Security is developed as a WebAuthn4J project with the aim of maximizing the functions of the WebAuthn4J library. - -=== Requirements - -==== Language & Framework - -* Java8 or later -* Spring Framework 5 or later -* Spring Security 5 or later - -==== Environment - -* SecureContext -* Browsers -** Google Chrome 70 or later -** Mozilla Firefox 60 or later -** Microsoft Edge bundled with Windows 10 October 2018 Update or later -** Safari 14 or later - -===== SecureContext - -Web Authentication API is only available in SecureContext, which means only HTTPS connection is permitted while a user accessing web sites. -Browsers rejects Web Authentication API call if the web site is served through HTTP connection except `localhost`. -For more details about SecureContext, please see https://developer.mozilla.org/ja/docs/Web/Security/Secure_Contexts[MDN]. - -=== Source code - -Source code for this project is hosted on https://github.com/webauthn4j/webauthn4j-spring-security[Github]. - ----- -git clone https://github.com/webauthn4j/webauthn4j-spring-security ----- - -=== License - -WebAuthn4J Spring Security is an open source software licensed under http://www.apache.org/licenses/LICENSE-2.0.html[Apache 2.0 license]. diff --git a/docs/src/reference/asciidoc/en/quick-start.adoc b/docs/src/reference/asciidoc/en/quick-start.adoc deleted file mode 100644 index f605b53f7..000000000 --- a/docs/src/reference/asciidoc/en/quick-start.adoc +++ /dev/null @@ -1,16 +0,0 @@ - -== Quick start - -WebAuthn4J Spring Security contains a sample application which demonstrates its major functionality. - -It can be launched with the following command. - -[source,bash] ----- -./gradlew samples:spa:bootRun ----- - -image::images/login.png[login view] - -Sample application is documented in a dedicated chapter. -Please refer link:./sample-app[Sample application]. diff --git a/docs/src/reference/asciidoc/en/sample-app.adoc b/docs/src/reference/asciidoc/en/sample-app.adoc deleted file mode 100644 index accf4cd9e..000000000 --- a/docs/src/reference/asciidoc/en/sample-app.adoc +++ /dev/null @@ -1,72 +0,0 @@ - -== Sample application - -WebAuthn4J Spring Security contains a sample application demonstrating its major functionalities. -Sample SPA is a demo of Single Page Application. Sample MPA is a demo of traditional Multi Page Application. -Sample SPA is explained below. - -=== Sample application execution - -Sample application can be executed by following command. - -[source,bash] ----- -./gradlew samples:spa:bootRun ----- - -=== User and authenticator registration - -image::images/signup.png[signup view] - -The signup page can be accessed with `http://localhost:8080/angular/signup`. -Please fill user information and register user and authentication device. - -image::images/signup-with-popup.png[authenticator request popup] - -Click the "Add" button in the "Authenticators" table, it will show a pop-up asking you to give a gesture to the authenticator to acknowledge the registration. -In case of an accident or device loss, Multiple authenticators can be registered for backup. -If you would like to allow single-factor authentication, Please check "Allow password authentication". - -=== User authentication - -Login page can be accessed with `http://localhost:8080/angular/login`. -Sample application supports three authentication flow. - -* Multi-factor authentication with password and authenticator -* Password-less multi-factor authentication with a user-verifying authenticator -* Single-factor authentication only with a password - -Each of three authentication flows are explained below. - -==== Multi-factor authentication with password and authenticator - -If you register a non user-verifying authenticator like FIDO-U2F token, you can login with multi-factor authentication with password and authenticator. - -image::images/login.png[login view] - -Please fill the username (email address) and password on the login view and click the login button. - -image::images/authenticatorLogin.png[authenticator login view] - -If the password authentication succeeds, an authenticator is asked in the next authenticator login view. -When the pop-up opens, please give a gesture to the authenticator to finish the authentication. -You will be automatically redirected to the dashboard. - -==== Password-less multi-factor authentication with a user-verifying authenticator - -If you register a user-verifying authenticator like that supports FIDO-CTAP2, you can login without password. - -image::images/login-with-popup.png[login view (password-less login)] - -Click the "Password-less login" button on the login view and the pop-up asking an authenticator will be opened. -Please give a gesture to the authenticator to finish the authentication. -You will be automatically redirected to the dashboard. - -==== Password authentication - -If you checked "Allow password authentication" at user registration, standard password authentication is available. - -image::images/login.png[login view] - -Please fill the username (email address) and password on the login view and click the login button. -If the authentication succeeds, you will be automatically redirected to the dashboard. diff --git a/docs/src/reference/asciidoc/en/spring-boot.adoc b/docs/src/reference/asciidoc/en/spring-boot.adoc deleted file mode 100644 index 404612145..000000000 --- a/docs/src/reference/asciidoc/en/spring-boot.adoc +++ /dev/null @@ -1,4 +0,0 @@ - -== Spring Boot - -Spring Boot Auto-Configuration for WebAuthn4J Spring Security is planned to be provided in the future version. \ No newline at end of file diff --git a/docs/src/reference/asciidoc/index-docinfo.xml b/docs/src/reference/asciidoc/index-docinfo.xml deleted file mode 100644 index 46a665179..000000000 --- a/docs/src/reference/asciidoc/index-docinfo.xml +++ /dev/null @@ -1,29 +0,0 @@ - - -{revnumber} -WebAuthn4J Spring Security - - - Yoshikazu - Nojima - - - - -2018 -Yoshikazu Nojima - diff --git a/docs/src/reference/asciidoc/ja/configuration.adoc b/docs/src/reference/asciidoc/ja/configuration.adoc deleted file mode 100644 index 3677155b4..000000000 --- a/docs/src/reference/asciidoc/ja/configuration.adoc +++ /dev/null @@ -1,289 +0,0 @@ - -== 設定 - -=== アプリケーションへの組込 - -==== Maven依存関係 - -ライブラリとその依存関係を導入するために、以下をpom.xmlファイルに追加してください。 - -[source,xml] ----- - - ... - - 0.7.0.RELEASE - ... - - - - com.webauthn4j - webauthn4j-spring-security-core - ${webauthn4j-spring-security.version} - ----- - -==== Java Config - -WebAuthn4J Spring Securityは、Security SecurityのJava Config DSLで設定することが可能です。 -`SecurityFilterChain` Beanを以下のように定義し、`HttpSecurity` Beanに対して `WebAuthnLoginConfigurer` を適用して下さい。 -`WebAuthnLoginConfigurer` を通じて `WebAuthnProcessingFilter` やWebAuthn JS APIのリクエストパラメータを返却するAttestation Optionsエンドポイント、Assertion Optionsエンドポイントの各種設定が可能です。 - -[source,java] ----- -@Configuration -public class WebSecurityConfig { - - @Bean - public SecurityFilterChain filterChain(HttpSecurity http, AuthenticationManager authenticationManager) throws Exception { - - http.authenticationManager(authenticationManager); - // WebAuthn Login - http.with(WebAuthnLoginConfigurer.webAuthnLogin(), (customizer) ->{ - customizer - .loginPage("/login") - .usernameParameter("username") - .passwordParameter("password") - .credentialIdParameter("credentialId") - .clientDataJSONParameter("clientDataJSON") - .authenticatorDataParameter("authenticatorData") - .signatureParameter("signature") - .clientExtensionsJSONParameter("clientExtensionsJSON") - .loginProcessingUrl("/login") - .attestationOptionsEndpoint() - .rp() - .name("WebAuthn4J Spring Security Sample") - .and() - .pubKeyCredParams( - new PublicKeyCredentialParameters(PublicKeyCredentialType.PUBLIC_KEY, COSEAlgorithmIdentifier.RS256), // Windows Hello - new PublicKeyCredentialParameters(PublicKeyCredentialType.PUBLIC_KEY, COSEAlgorithmIdentifier.ES256) // FIDO U2F Key, etc - ) - .extensions() - .credProps(true) - .and() - .assertionOptionsEndpoint() - .and() - .successHandler(authenticationSuccessHandler) - .failureHandler(authenticationFailureHandler); - }); - } -} ----- - -===== WebAuthnAuthenticationProviderの組込 - -Web Authentication用の `AuthenticationProvider` である `WebAuthnAuthenticationProvider` はBeanとして定義して下さい。 -パスワード認証と組み合わせた二段階認証とする場合は、 `DaoAuthenticationProvider` のBean定義も必要です。 - -[source,java] ----- - @Bean - public WebAuthnAuthenticationProvider webAuthnAuthenticationProvider(WebAuthnAuthenticatorService authenticatorService, WebAuthnManager webAuthnManager){ - return new WebAuthnAuthenticationProvider(authenticatorService, webAuthnManager); - } - - @Bean - public DaoAuthenticationProvider daoAuthenticationProvider(UserDetailsService userDetailsService){ - DaoAuthenticationProvider daoAuthenticationProvider = new DaoAuthenticationProvider(); - daoAuthenticationProvider.setUserDetailsService(userDetailsService); - daoAuthenticationProvider.setPasswordEncoder(new BCryptPasswordEncoder()); - return daoAuthenticationProvider; - } - - @Bean - public AuthenticationManager authenticationManager(List providers){ - return new ProviderManager(providers); - } ----- - -==== 永続化層との統合 - -WebAuthn4J Spring Securityは `WebAuthnCredentialRecordService` インタフェースを通じて認証デバイスを検索します。 -`WebAuthnCredentialRecordService` を実装したクラスを用意し、 `WebAuthnAuthenticationProvider` にセットして下さい。 - -=== クライアントサイドとのインタフェース仕様 - -Web Authentication仕様では、ブラウザのJavaScript APIが規定されており、取得した資格情報をサーバーに対して送信する インタフェースについては規定がありません。 - -==== WebAuthn認証リクエストの処理 - -WebAuthn4J Spring Securityでは、認証処理に関しては、ログインURLに対して送信されたリクエストから `WebAuthnProcessingFilter` がリクエストパラメータとして -`credentialId` 、`clientData` 、 `authenticatorData` 、`signature` 、`clientExtensionsJSON` を取得して認証を行います。 -`credentialId` 、`clientData` 、 `authenticatorData` 、`signature` はバイナリデータの為、クライアントサイドはBase64URLエンコードして送信して下さい。 - -==== 認証デバイス登録時の処理 - -認証処理と異なり、登録処理については、通常WebAuthn以外のデータ、例えばユーザーの氏名やメールアドレスなども一緒に登録する必要があることから、 -WebAuthn4J Security Securityとして一律のエンドポイントを設けることは難しく、登録処理用のServlet Filterの提供は行っていません。 -認証デバイス登録操作のハンドリングは、基本的にはアプリケーション側の責務ですが、登録しようとしている資格情報が -認証時に使用できるものであるか検証する為に、WebAuthn4J Spring Securityはコンバータおよびバリデータを提供します。 -`Base64StringToCollectedClientDataConverter` はBase64URL文字列を `CollectedClientData` に変換します。 -`Base64StringToAttestationObjectConverter` はBase64URL文字列を `AttestationObject` に変換します。 -`WebAuthnRegistrationRequestValidator` は、認証デバイスの登録リクエストの検証に用いることが出来ます。 - -===== オプションエンドポイント - -Web Authentication仕様では、WebAuthn JS APIで資格情報の作成、認証を行う際にAPIの引数としてサーバーから取得したチャレンジ渡す必要があります。 -また、FIDO-U2Fトークンを認証デバイスとして使用する場合も、第一認証要素によって特定されたユーザーに紐づけられた CredentialIdをサーバーから取得して渡す必要があります。 -これらのWebAuthn JS APIの引数をサーバーから取得するためのエンドポイントとして、 WebAuthn4J Spring Securityでは `AttestationOptionsEndpointFilter` と `AssertionOptionsEndpointFilter` を用意しています。 - -=== カスタマイズ - -==== WebAuthnProcessingFilter - -`WebAuthnProcessingFilter` は、受信したリクエストから `credentialId` 、`clientData` 、 `authenticatorData` 、`signature` 、`clientExtensionsJSON` -といったパラメータを取得して `WebAuthnAssertionAuthenticationToken` の組立を行います。 -`credentialId` パラメータが受信したリクエストに存在しない場合は、 `username` 、 `password` パラメータを読み取り、 -`UsernamePasswordAuthenticationToken` を組み立てます。 リクエストパラメータ名を変更したい場合は、 -`WebAuthnProcessingFilter` のプロパティ、あるいは `WebAuthnLoginConfigurer` の対応するJava Configメソッドから設定可能です。 - -==== WebAuthnAuthenticationProvider - -`WebAuthnAuthenticationProvider` は `WebAuthnAssertionAuthenticationToken` を処理するための `AuthenticationProvider` -インタフェースの実装です。WebAuthnのアサーションの検証には `WebAuthnManager` を使用します。 -`WebAuthnManager` については https://webauthn4j.github.io/webauthn4j/ja/[WebAuthn4Jのリファレンス] を参照して下さい。 - -==== Attestation Optionsエンドポイント、Assertion optionsエンドポイント - -WebAuthn4J Spring Securityは、WebAuthn JS APIで資格情報の作成を行う際のパラメータを返却するエンドポイントとして `AttestationOptionsEndpointFilter` を、 -認証を行う際のパラメータを返却する際のエンドポイントとして `AssertionOptionsEndpointFilter` を用意しています。 -返却する値の生成は、それぞれ `AttestationOptionsProvider` インタフェース、 `AssertionOptionsProvider` インタフェースを通じて委譲されているので、 -これらのカスタム実装を行うことで、返却値を自由にカスタマイズすることが可能です。 - -Java Configからカスタマイズも可能です。 `WebAuthnLoginConfigurer` の `attestationOptionsEndpoint` メソッドあるいは `assertionOptionsEndpoint` からのチェーンを用いて -カスタマイズすることが出来ます。 - -[source,java] ----- -@Configuration -public class WebSecurityConfig { - - @Bean - public SecurityFilterChain filterChain(HttpSecurity http, AuthenticationManager authenticationManager) throws Exception { - http.authenticationManager(authenticationManager); - // WebAuthn Login - http.with(WebAuthnLoginConfigurer.webAuthnLogin(), (customizer) ->{ - customizer - .rpId("example.com") - .attestationOptionsEndpoint() - .attestationOptionsProvider(attestationOptionsProvider) - .processingUrl("/webauthn/attestation/options") - .rp() - .name("example") - .and() - .pubKeyCredParams( - new PublicKeyCredentialParameters(PublicKeyCredentialType.PUBLIC_KEY, COSEAlgorithmIdentifier.ES256), - new PublicKeyCredentialParameters(PublicKeyCredentialType.PUBLIC_KEY, COSEAlgorithmIdentifier.RS1) - ) - .authenticatorSelection() - .authenticatorAttachment(AuthenticatorAttachment.CROSS_PLATFORM) - .residentKey(ResidentKeyRequirement.PREFERRED) - .userVerification(UserVerificationRequirement.PREFERRED) - .and() - .attestation(AttestationConveyancePreference.DIRECT) - .extensions() - .credProps(true) - .uvm(true) - .and() - .assertionOptionsEndpoint() - .assertionOptionsProvider(assertionOptionsProvider) - .processingUrl("/webauthn/assertion/options") - .rpId("example.com") - .userVerification(UserVerificationRequirement.PREFERRED) - .and(); - }); - } -} ----- - -===== PublicKeyCredentialUserEntityの動的な生成 - -Attestation Optionsエンドポイントは、返却する `PublicKeyCredentialUserEntity` をログイン中のユーザーの `Authentication` に基づいて -動的に生成することが可能です。動的に生成する為のハンドラとして `PublicKeyCredentialUserEntityProvider` インタフェースが用意されています。 -`AttestationOptionsProviderImpl` クラスの `setPublicKeyCredentialUserEntityProvider` メソッドからセットしてください。 - -Java Configの場合は、以下のようにセット可能です。 - ----- -@Configuration -public class WebSecurityConfig { - - @Bean - public SecurityFilterChain filterChain(HttpSecurity http, AuthenticationManager authenticationManager) throws Exception { - - // WebAuthn Login - http.with(WebAuthnLoginConfigurer.webAuthnLogin(), (customizer) ->{ - customizer - .attestationOptionsEndpoint() - .attestationOptionsProvider(attestationOptionsProvider) - .processingUrl("/webauthn/attestation/options") - .processingUrl("/webauthn/attestation/options") - .user(new MyPublicKeyCredentialUserEntityProvider()); // put your PublicKeyCredentialUserEntityProvider implementation - }); - } -} ----- - -WebAuthn4J Spring SecurityのJava Configは、明示的に指定されていない場合、SpringのApplicationContextから `PublicKeyCredentialUserEntityProvider` を検索しますので、 -Bean登録することでも `PublicKeyCredentialUserEntityProvider` のセットが可能です。 - -==== 認証方法の選択 - -WebAuthn4J Spring Securityでは、認証方法として「ユーザー検証機能付き認証デバイスによるパスワードレス多要素認証」、 「パスワード＋認証デバイスによる多要素認証」、「パスワード等による単一要素認証」をサポートしています。 -パスワード認証をサポートし、ユーザーへの間口を広げることも出来ますし、パスワード認証を制限することで、 セキュリティを高めることも出来ます。 - -===== パスワード認証の実装 - -「パスワード＋認証デバイスによる多要素認証」、「パスワード等による単一要素認証」をサポートする場合、 `WebAuthnAuthenticationProvider` に加えて、 `DaoAuthenticationProvider` を構成し、 `UsernamePasswordAuthenticationToken` を処理できるようにする必要があります。 -「パスワード＋認証デバイスによる多要素認証」が必要なページは、WebAuthnで認証されているかを認可要件に含めることで実装出来ます。 - -WebAuthnで認証されているかは、 `WebAuthnSecurityExpression#isWebAuthnAuthenticated` メソッドでチェック可能です。WebAuthnSecurityExpressionのインスタンスをBean登録し、JavaConfigから呼び出してください。 -WebAuthn4J Spring Security Sample MPA で実装例を示しているので、参考にして下さい。 - -=== 高度なトピック - -==== 多要素認証で第一要素のみ認証完了したユーザーの識別 - -ユーザーの認証レベルによって異なるページを表示したい場合、以下のように現在の `Authentication` インスタンスの型で画面を切り替えるのが一つの方法です。 - -[source,java] ----- -@RequestMapping(value = "/login", method = RequestMethod.GET) -public String login() { - Authentication authentication = SecurityContextHolder.getContext().getAuthentication(); - if (authenticationTrustResolver.isAnonymous(authentication)) { - return VIEW_LOGIN_LOGIN; - } else { - return VIEW_LOGIN_AUTHENTICATOR_LOGIN; - } -} ----- - -==== 資格情報の有効範囲（RpId）設定 - -Web Authentication仕様では、資格情報の作成時、即ち認証デバイスの登録時、その資格情報の有効範囲を制限するための パラメータとして、 `rpId` を指定します。 -`rpId` には、 https://html.spec.whatwg.org/multipage/origin.html#concept-origin-effective-domain[effective domain] を指定することが出来ます。 -例えば、資格情報の作成を行った ページのドメインが `dev.example.com` だった場合に、RpIdを `dev.example.com` と指定すれば、その資格情報は `dev.example.com` とそのサブドメインの範囲だけで利用できますが、 `rpId` を `example.com` とすることで、 資格情報が利用可能な範囲を `example.com` およびそのサブドメインに広げることが出来ます。 - -WebAuthn4J Spring Securityでは、 `rpId` は `ServerPropertyProviderImpl` のプロパティとして設定可能で、JavaConfigでは、 `WebAuthnConfigurer` を通じて設定可能です。 -リクエストに応じて動的に変更したい場合、`RpIdProvider`をセットしてください。 - -==== 構成証明ステートメントの検証 - -Web Authentication仕様では、認証デバイスの登録時に要求すれば認証デバイスの構成証明ステートメントを取得することが出来ます。 -Relying Partyは取得した構成証明ステートメントを検証することで、セキュリティ要件に合致しない認証デバイスの受け入れを拒否することが可能です。 -但し、構成証明ステートメントにはユーザーのサイトを跨いだトラッキングに利用できる情報が含まれていることから、無闇に 要求するべきではありません。また、構成証明ステートメントを要求した場合、ブラウザはユーザーに対して追加のダイアログを 表示するため、ユーザビリティが低下することも注意が必要です。認証デバイスの厳密な検証が必要なエンタープライズ用途以外、 通常のB2Cサイトでは、構成証明ステートメントの要求を行うべきではないでしょう。 - -WebAuthn4Jでは、`WebAuthnRegistrationContextValidator` が認証デバイスの登録リクエストの検証を行いますが、 取得した構成証明ステートメントの署名と信頼性の検証は、それぞれ `AttestationStatementValidator` と -`CertPathTrustworthinessValidator` インタフェースの実装に委譲します。 - -厳密な構成証明ステートメントの検証を必要としないサイト向けに、`AttestationStatementValidator` と -`CertPathTrustworthinessValidator` を構成した `WebAuthnRegistrationContextValidator` のインスタンスは、 -`WebAuthnRegistrationContextValidator.createNonStrictRegistrationContextValidator` ファクトリメソッドで作成出来ます。 - -==== SpringのResourceを活用したTrustAnchorProvider - -認証デバイスを登録時に証明書パスから検証する場合、 `TrustAnchorCertPathTrustworthinessValidator` クラスは -`TrustAnchorProvider` インタフェースの実装クラスから取得した `TrustAnchor` を使用します。WebAuthn4J Spring Securityでは、 SpringのResourceとして読み込んだJava Key Storeファイルを `TrustAnchor` として使用する `TrustAnchorProvider` として、 -`KeyStoreResourceTrustAnchorProvider` クラスを提供します。 - diff --git a/docs/src/reference/asciidoc/ja/index.adoc b/docs/src/reference/asciidoc/ja/index.adoc deleted file mode 100644 index 4eef0ca13..000000000 --- a/docs/src/reference/asciidoc/ja/index.adoc +++ /dev/null @@ -1,19 +0,0 @@ -:java-ClassLoader: http://docs.oracle.com/javase/7/docs/api/java/lang/ClassLoader.html -:core-ApplicationContext: http://docs.spring.io/spring/docs/{spring-version}/javadoc-api/org/springframework/context/ApplicationContext.html -:core-beans-factory-placeholderconfigurer: http://docs.spring.io/spring/docs/{spring-version}/spring-framework-reference/html/beans.html#beans-factory-placeholderconfigurer -:core-beans-environment: http://docs.spring.io/spring/docs/{spring-version}/spring-framework-reference/html/beans.html#beans-environment -:core-ResourcePatternResolver: http://docs.spring.io/spring/docs/{spring-version}/javadoc-api/org/springframework/core/io/support/ResourcePatternResolver.html -:core-ref-util: http://docs.spring.io/spring/docs/{spring-version}/spring-framework-reference/html/xsd-config.html#xsd-config-body-schemas-util-properties -:core-aop-schema-advisors: http://docs.spring.io/spring/docs/{spring-version}/spring-framework-reference/html/aop.html#aop-schema-advisors -:core-dao: http://docs.spring.io/spring/docs/{spring-version}/spring-framework-reference/html/dao.html -:core-dao-exceptions: http://docs.spring.io/spring/docs/{spring-version}/spring-framework-reference/html/dao.html#dao-exceptions -:core-jdbc: http://docs.spring.io/spring/docs/{spring-version}/spring-framework-reference/html/jdbc.html -:core-jdbc-JdbcTemplate: http://docs.spring.io/spring/docs/{spring-version}/spring-framework-reference/html/jdbc.html#jdbc-JdbcTemplate - -= WebAuthn4J Spring Security Reference - -include::introduction.adoc[] -include::quick-start.adoc[] -include::configuration.adoc[] -include::spring-boot.adoc[] -include::sample-app.adoc[] diff --git a/docs/src/reference/asciidoc/ja/introduction.adoc b/docs/src/reference/asciidoc/ja/introduction.adoc deleted file mode 100644 index 70e9b28e8..000000000 --- a/docs/src/reference/asciidoc/ja/introduction.adoc +++ /dev/null @@ -1,56 +0,0 @@ -== 導入 - -=== Web Authenticationとは - -Web Authenticationは、W3Cで仕様策定が進められている、Webアプリケーションの新しいセキュアな認証方式仕様です。 ローカル認証や公開鍵認証、Origin別の鍵管理を組み合わせることで、フィッシングなど認証プロセスに対する攻撃に対して堅固な認証を実現しています。 主要ブラウザでの実装が進みつつあり、セキュリティ、利便性を重視するユーザーに対して優れた選択肢を提供します。 当初はFIDO AllianceでFIDO 2.0: Web API for accessing FIDO 2.0 credentialsとして仕様策定が進められていましたが、 現在はW3Cに移管され、仕様策定が行われています。 - -=== WebAuthn4J Spring Securityとは - -Spring Securityで保護されたWebアプリケーションに対して、Web Authentication仕様に基づく認証機能を提供するための Spring Security拡張です。 - -==== WebAuthn4Jとは - -WebAuthnのアサーションの検証に関わるコアの処理は https://github.com/webauthn4j/webauthn4j[WebAuthn4J] という別のプロジェクトで開発を進めています。 -WebAuthn4Jは、 全ての構成証明ステートメント（Attestation）をサポートしながら、外部ライブラリへの依存関係は最小限に抑えたポータブルなJavaライブラリです。 - -==== Spring Security WebAuthnとの関係 - -Spring Security WebAuthnという姉妹プロジェクトも存在します。Spring Security WebAuthnは、Spring Security本体へのマージを目指してSpring Securityプロジェクトの方針に則って開発されている一方、 -WebAuthn4J Spring Securityは、WebAuthn4Jのプロジェクトとして、WebAuthn4Jライブラリの機能を最大限に、またより早く取り込むことを目的に開発を進めています。 - -=== 要件 - -==== 言語・フレームワーク - -* Java8以降 -* Spring Framework 5以降 -* Spring Security 5以降 - -==== 動作環境 - -WebAuthn4J Spring Securityの動作環境は、以下の要件を満たす必要があります。 - -* SecureContext -* ブラウザ -** Google Chrome 70以降 -** Mozilla Firefox 60以降 -** Microsoft Edge Windows 10 October 2018 Update同梱版 以降 -** Safari 14以降 - -===== SecureContext - -Web Authentication仕様では、動作環境がSecureContextであることを要求しています。 これは、ユーザーがサイトに接続する際、HTTPS接続でなければならないことを意味します。HTTP接続環境下では、ブラウザはWebAuthnに関連した要求を拒否するため、利用できません。 但し、 `localhost` では例外的にHTTP接続が認められています。SecureContextについて詳しくは https://developer.mozilla.org/ja/docs/Web/Security/Secure_Contexts[MDN] を参照ください。 - -=== ソースコード - -ソースコードは https://github.com/webauthn4j/webauthn4j-spring-security[Github] で管理されています。 - -[source,bash] ----- -git clone https://github.com/webauthn4j/webauthn4j-spring-security ----- - -=== ライセンス - -WebAuthn4J Spring Securityは http://www.apache.org/licenses/LICENSE-2.0.html[Apache 2.0 license] ライセンスの オープンソースソフトウェアです。 - diff --git a/docs/src/reference/asciidoc/ja/quick-start.adoc b/docs/src/reference/asciidoc/ja/quick-start.adoc deleted file mode 100644 index 5058a0156..000000000 --- a/docs/src/reference/asciidoc/ja/quick-start.adoc +++ /dev/null @@ -1,15 +0,0 @@ - -== クイックスタート - -WebAuthn4J Spring Securityは主要機能をデモするサンプルアプリケーションを含みます。 - -サンプルアプリケーションは以下のコマンドで実行することが出来ます。 - -[source,bash] ----- -./gradlew samples:spa:bootRun ----- - -image::images/login.png[ログイン画面] - -サンプルアプリケーションについては、 link:./sample-app[サンプルアプリケーション] で詳しく説明していますので、そちらを参照下さい。 diff --git a/docs/src/reference/asciidoc/ja/sample-app.adoc b/docs/src/reference/asciidoc/ja/sample-app.adoc deleted file mode 100644 index 72bc659cf..000000000 --- a/docs/src/reference/asciidoc/ja/sample-app.adoc +++ /dev/null @@ -1,62 +0,0 @@ - -== サンプルアプリケーション - -webauthn4j-spring-securityは主要機能をデモするサンプルアプリケーションを含みます。 -Single Page Applicationのデモである、Sample SPAと、従来型のMulti Page Applicationである、Sample MPAです。以下ではSample SPAについて説明します。 - -=== サンプルアプリケーションの実行 - -サンプルアプリケーションは以下のコマンドで実行することが出来ます。 - -[source,bash] ----- -./gradlew samples:spa:bootRun ----- - -=== ユーザーおよび認証デバイスの登録 - -image::images/signup.png[サインアップ画面] - -サインアップ画面は、 `http://localhost:8080/angular/signup` でアクセスすることが出来ます。 ユーザー情報を入力し、ユーザーと認証デバイスの登録を行ってください。 - -image::images/signup-with-popup.png[認証デバイス要求ポップアップ] - -「認証デバイス」欄の「追加」ボタンを押下すると認証デバイスでの操作を促すポップアップが表示され、 認証デバイスの登録モードになりますので、ポップアップに従い登録を済ませてください。 認証デバイスは紛失・故障に備え、バックアップとして複数登録することが出来ます。 パスワードのみによる単一要素認証を許可する場合は、「パスワード認証を許可」にチェックを入れてください。 - -=== ユーザー認証 - -ログイン画面は、 `http://localhost:/8080/angular/login` でアクセスすることが出来ます。 サンプルアプリケーションではユーザー認証について、三つの認証フローをサポートしています。 - -- パスワード＋認証デバイスによる多要素認証 -- ユーザー検証機能付き認証デバイスによるパスワードレス多要素認証 -- パスワードのみによる単一要素認証 - -以下、三つの認証フローについてそれぞれ説明していきます。 - -==== パスワード＋認証デバイスによる多要素認証 - -ユーザー検証機能が付いていないFIDO-U2Fのトークンのような認証デバイスを登録した場合は、パスワード＋認証デバイスによる 多要素認証が可能です。 - -image::images/login.png[ログイン画面] - -ログイン画面でユーザー名（Emailアドレス）とパスワードを入力し、ログインボタンを押下してください。 - -image::images/authenticatorLogin.png[認証デバイスログイン画面] - -パスワード認証に成功した場合、第二認証要素として認証デバイスを用いた認証を求める、認証デバイスログイン画面が開きます。 認証を求めるポップアップが開いたら、認証デバイスを操作し、認証を完了してください。認証に成功すると、画面が自動的に遷移します。 - -==== ユーザー検証機能付き認証デバイスによるパスワードレス多要素認証 - -ユーザー検証機能が付いている認証デバイスを登録した場合、パスワードレス認証が可能です。 - -image::images/login-with-popup.png[ログイン画面（パスワードレスログイン）] - -ログイン画面の「パスワードレスログイン」ボタンを押下すると、認証デバイスを用いた認証を求めるポップアップが開きます。 認証デバイスを操作し、認証を完了してください。認証に成功すると、画面が自動的に遷移します。 - -==== パスワード認証 - -ユーザー登録時に「パスワード認証を許可」にチェックを入れていた場合、 通常のパスワード認証が利用可能です。 - -image::images/login.png[ログイン画面] - -ログイン画面でユーザー名とパスワードを入力し、「ログイン」ボタンを押下して認証を完了してください。 認証に成功すると、画面は自動的に遷移します。 diff --git a/docs/src/reference/asciidoc/ja/spring-boot.adoc b/docs/src/reference/asciidoc/ja/spring-boot.adoc deleted file mode 100644 index 4b62cfae8..000000000 --- a/docs/src/reference/asciidoc/ja/spring-boot.adoc +++ /dev/null @@ -1,5 +0,0 @@ - -== Spring Boot - -WebAuthn4J Spring Securityに対するSpring Boot Auto-Configurationは将来のバージョンで提供される予定です。 -