はじめに (対象読者・この記事でわかること)

この記事は、Spring BootとSpring Securityを使ってWebアプリケーションを開発している方で、特にカスタムログインページの実装に挑戦しているものの、意図せずSpring Securityのデフォルトログインページが表示されてしまい困っている開発者の方を対象にしています。また、これからSpring Securityでの認証機能実装を学ぶ方にとっても役立つでしょう。

この記事を読むことで、Spring Securityでカスタムログインページを設定する際の基本的な手順と、カスタムページが表示されない場合に考えられる主な原因、そしてその具体的な解決策を学ぶことができます。これにより、スムーズにユーザーフレンドリーなログイン画面を構築できるようになります。

前提知識

この記事を読み進める上で、以下の知識があるとスムーズです。 * Javaの基本的な文法とオブジェクト指向の概念 * Spring Bootの基本的な使い方（DI、アノテーションなど） * MavenまたはGradleの基本的な使い方 * Webアプリケーションの基本的な知識（HTTPリクエスト、レスポンスなど） * HTML/CSSの基本的な知識

Spring Securityとカスタムログインページの必要性

Spring Securityは、Javaアプリケーション、特にSpring Bootアプリケーションにおいて、認証（ユーザーが誰であるかを確認する）と認可（ユーザーが何をする権限があるかを確認する）の機能を提供する強力なフレームワークです。わずかな設定で堅牢なセキュリティ機能を提供してくれるため、多くのWebアプリケーション開発で利用されています。

Spring Securityは、設定を最小限に抑えるために、デフォルトで独自のログインページ（多くの場合、/loginエンドポイントでアクセスできる簡素なフォーム）を提供します。これはプロトタイプや開発初期段階では非常に便利ですが、実際のサービスとして提供するWebアプリケーションでは、ブランドイメージの統一、ユーザー体験の向上、特定の要件（CAPTCHAの追加、SNSログイン連携など）への対応のために、カスタムデザインのログインページが必要不可欠になります。しかし、このカスタムログインページを設定したはずなのに、なぜかデフォルトのページが表示されてしまうという問題に遭遇する開発者は少なくありません。

カスタムログインページが表示されない問題の原因と解決策

Spring Securityでカスタムログインページを設定してもデフォルトのページが表示されてしまう、またはログインがうまくいかないといった問題は、主に設定ミスや理解不足に起因することが多いです。ここでは、具体的な設定方法と、よくある原因とその解決策を詳しく見ていきましょう。

ステップ1：基本的なSpring Securityの設定とカスタムログインページの準備

まずは、Spring Securityの基本的な設定を行い、カスタムログインページを表示するための準備をします。

  1. Spring Securityの設定クラスの作成 Spring Boot 2.7以降ではWebSecurityConfigurerAdapterが非推奨となり、SecurityFilterChainをBeanとして定義する方法が推奨されています。

    ```java // SecurityConfig.java package com.example.demo.config;

    import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.security.config.annotation.web.builders.HttpSecurity; import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity; import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder; import org.springframework.security.crypto.password.PasswordEncoder; import org.springframework.security.web.SecurityFilterChain; import org.springframework.security.web.util.matcher.AntPathRequestMatcher; // Spring Security 6+ の場合

    @Configuration @EnableWebSecurity public class SecurityConfig {

    @Bean
public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
    http
        .authorizeHttpRequests(auth -> auth
            .requestMatchers("/login", "/css/**", "/js/**", "/images/**").permitAll() // ログインページと静的ファイルへのアクセスを許可
            .anyRequest().authenticated() // その他の全てのリクエストは認証が必要
        )
        .formLogin(form -> form
            .loginPage("/login") // カスタムログインページのパス
            .defaultSuccessUrl("/home", true) // ログイン成功後のリダイレクト先
            .failureUrl("/login?error") // ログイン失敗時のリダイレクト先
            .usernameParameter("username") // ログインフォームのユーザー名フィールドの名前
            .passwordParameter("password") // ログインフォームのパスワードフィールドの名前
            .permitAll() // ログインフォーム自体へのアクセスを許可
        )
        .logout(logout -> logout
            .logoutRequestMatcher(new AntPathRequestMatcher("/logout")) // ログアウト処理のURL
            .logoutSuccessUrl("/login?logout") // ログアウト成功後のリダイレクト先
            .deleteCookies("JSESSIONID") // ログアウト時にクッキーを削除
            .invalidateHttpSession(true) // HTTPセッションを無効化
            .permitAll()
        )
        .csrf(csrf -> csrf.ignoringRequestMatchers("/h2-console/**")) // H2-Console利用時はCSRF無効化（開発時のみ）
        .headers(headers -> headers.frameOptions().sameOrigin()); // H2-Console利用時にフレームオプションを許可

    return http.build();
}

@Bean
public PasswordEncoder passwordEncoder() {
    return new BCryptPasswordEncoder();
}

    } ```

  2. カスタムログインページのコントローラー

    カスタムログインページを表示するためのコントローラーを作成します。

    ```java // LoginController.java package com.example.demo.controller;

    import org.springframework.stereotype.Controller; import org.springframework.web.bind.annotation.GetMapping;

    @Controller public class LoginController {

    @GetMapping("/login")
public String showLoginPage() {
    return "login"; // src/main/resources/templates/login.html を表示
}

@GetMapping("/home")
public String showHomePage() {
    return "home"; // ログイン後のページ例
}

    } ```

  3. カスタムログインページのHTMLファイル (src/main/resources/templates/login.html)

    Thymeleafなどのテンプレートエンジンを使用する場合の例です。

    html <!DOCTYPE html> <html lang="ja" xmlns:th="http://www.thymeleaf.org"> <head> <meta charset="UTF-8"> <title>ログイン</title> <link rel="stylesheet" th:href="@{/css/style.css}"> </head> <body> <div class="container"> <h2>ログイン</h2> <div th:if="${param.error}" class="error-message"> ユーザー名またはパスワードが正しくありません。 </div> <div th:if="${param.logout}" class="success-message"> ログアウトしました。 </div> <form th:action="@{/login}" method="post"> <div> <label for="username">ユーザー名:</label> <input type="text" id="username" name="username" required> </div> <div> <label for="password">パスワード:</label> <input type="password" id="password" name="password" required> </div> <input type="hidden" th:name="${_csrf.parameterName}" th:value="${_csrf.token}" /> <button type="submit">ログイン</button> </form> </div> </body> </html>

ステップ2：カスタムログインページが表示されない一般的な原因と解決策

上記の基本的な設定を行ってもカスタムログインページが表示されない場合、以下の点を確認してください。

ハマった点やエラー解決

多くの開発者が経験する典型的な問題と、その際に発生するエラーメッセージ、または挙動について説明します。

  1. 「カスタムページを作ったはずなのに、なぜかhttp://localhost:8080/loginでSpring Securityのデフォルトページが表示される」 これは最もよくある症状です。ログインページにアクセスする際、Spring Securityが「認証されていない」と判断し、再度デフォルトのログインページへリダイレクトしてしまうために起こります。

  2. 「ログインフォームを送信すると403 Forbiddenエラーが出る」 これは主にCSRF（クロスサイトリクエストフォージェリ）保護に関連するエラーです。

  3. 「リダイレクトループが発生する」 ログインページにアクセスしようとすると、ブラウザが何度もリダイレクトを繰り返し、最終的にエラーになることがあります。これもログインページへのアクセス権限の問題が原因です。

  4. 「HTMLやCSSが正しく読み込まれない」 カスタムログインページの見た目が崩れる場合、静的リソースへのアクセス設定が不十分である可能性があります。

解決策

上記の問題に対する具体的な解決策をコード例を交えて説明します。

  1. ログインページへのpermitAll()設定の確認 最も重要なのは、カスタムログインページへのアクセスを認証なしで許可することです。http.authorizeHttpRequests()の部分で、ログインページのパス（/login）と、そのページで使用するCSSやJavaScript、画像などの静的リソースのパスをpermitAll()で許可する必要があります。

    java // SecurityConfig.java (一部抜粋) http .authorizeHttpRequests(auth -> auth .requestMatchers("/login", "/css/**", "/js/**", "/images/**").permitAll() // ★ここが重要！ .anyRequest().authenticated() ) // ... (formLogin, logoutなどの設定) /loginがpermitAll()されていないと、認証されていないユーザーが/loginにアクセスしようとすると、Spring Securityは認証が必要だと判断し、結果的にデフォルトのログインページ（または/login自身）へリダイレクトしてしまい、無限ループやデフォルトページ表示に繋がります。

  2. CSRFトークンの適切な埋め込み Spring SecurityはCSRF攻撃から保護するため、POSTリクエストにはCSRFトークンを含めることを要求します。カスタムログインフォームにもこのトークンを含める必要があります。Thymeleafを使用している場合、以下のコードをformタグ内に含めます。

    html <!-- login.html (一部抜粋) --> <form th:action="@{/login}" method="post"> <!-- ... ユーザー名、パスワードの入力フィールド ... --> <input type="hidden" th:name="${_csrf.parameterName}" th:value="${_csrf.token}" /> <!-- ★ここが重要！ --> <button type="submit">ログイン</button> </form> この_csrfオブジェクトはSpring Securityが自動的にThymeleafに提供します。トークンがない場合、フォーム送信時に403 Forbiddenエラーが発生します。

  3. フォームのaction属性とmethod属性の確認 Spring Securityのデフォルトのログイン処理は、POSTリクエストで/loginパスに送信されることを期待します。カスタムフォームのactionとmethodがこれに合致しているか確認してください。

    html <!-- login.html (一部抜粋) --> <form th:action="@{/login}" method="post"> <!-- ★th:actionとmethodが正しいか確認 --> <!-- ... --> </form> th:action="@{/login}"は、アプリケーションのコンテキストパスを考慮した正しいURLを生成します。

  4. HTMLファイルパスとコントローラーの表示設定 カスタムログインページのHTMLファイルがsrc/main/resources/templatesディレクトリに正しく配置されているか、また、コントローラーがそのファイルを正しく返すように設定されているかを確認してください。

    java // LoginController.java (一部抜粋) @GetMapping("/login") public String showLoginPage() { return "login"; // "login.html"に対応 } パスが間違っている場合、テンプレートエンジンがファイルを見つけられず、エラーになるか、フォールバックとして別のページが表示されることがあります。

  5. 静的リソース（CSS, JS, 画像）へのアクセス設定 カスタムログインページのスタイルが崩れている場合、CSSやJavaScriptファイルが読み込まれていない可能性があります。これもpermitAll()でアクセスを許可する必要があります。

    java // SecurityConfig.java (一部抜粋) http .authorizeHttpRequests(auth -> auth .requestMatchers("/login", "/css/**", "/js/**", "/images/**").permitAll() // ★静的リソースへのパスを許可 .anyRequest().authenticated() ) // ... /css/**のようにワイルドカードを使用することで、/css/style.cssや/css/components/button.cssなど、/css配下の全てのリソースを許可できます。

  6. ユーザー詳細サービスの実装 ユーザーの認証情報をSpring Securityに提供するためには、UserDetailsServiceインターフェースを実装したクラスが必要です。これは直接ログインページの表示問題とは関係ありませんが、ログイン後の認証処理に不可欠です。

    ```java // CustomUserDetailsService.java (例) package com.example.demo.service;

    import org.springframework.security.core.userdetails.User; import org.springframework.security.core.userdetails.UserDetails; import org.springframework.security.core.userdetails.UserDetailsService; import org.springframework.security.core.userdetails.UsernameNotFoundException; import org.springframework.stereotype.Service;

    import java.util.ArrayList;

    @Service public class CustomUserDetailsService implements UserDetailsService {

    @Override
public UserDetails loadUserByUsername(String username) throws UsernameNotFoundException {
    // ここでデータベースなどからユーザー情報を取得
    if ("user".equals(username)) {
        // BCryptPasswordEncoderでエンコードしたパスワードを使用
        return new User(username, "$2a$10$T53c7P4Mv0J6E5U7F9Y1Q./p2Q4/A6k0e2f3j4h5g6i7o8u9t0.C.e", new ArrayList<>()); // パスワードは "password" をBCryptでエンコードしたもの
    } else {
        throw new UsernameNotFoundException("User not found with username: " + username);
    }
}

    } ``SecurityConfigにPasswordEncoderをBeanとして登録し、CustomUserDetailsService内でユーザーのパスワードと比較する際に利用します。上記の例ではBCryptPasswordEncoder`を使用しています。

解決策まとめ

カスタムログインページが表示されない問題の多くは、以下の3つの主要な原因を解決することで解消されます。

  1. ログインページ（およびその静的リソース）へのアクセス許可
    • http.authorizeHttpRequests().requestMatchers("/login", "/css/**", "/js/**").permitAll()
  2. CSRFトークンの適切な埋め込み
    • <input type="hidden" th:name="${_csrf.parameterName}" th:value="${_csrf.token}" />
  3. ログインフォームのactionとmethodがSpring Securityの期待するものと一致しているか
    • <form th:action="@{/login}" method="post">

これらの点を一つずつ丁寧に確認することで、ほとんどの問題は解決できるはずです。

まとめ

本記事では、Spring Securityを使用してJavaアプリケーションにカスタムログインページを実装する際に、意図せずデフォルトのログインページが表示されてしまう問題に焦点を当て、その原因と具体的な解決策を解説しました。

  • ログインページへのアクセス許可: Spring Securityに、カスタムログインページ（およびその静的リソース）は認証不要でアクセス可能であることを明示的に設定することが最も重要です。
  • CSRFトークンの埋め込み: POSTリクエストを処理するフォームには、セキュリティ保護のためにCSRFトークンを含める必要があります。
  • フォーム属性の一致: ログインフォームのactionとmethodがSpring Securityが期待するパスとHTTPメソッド（通常はPOST /login）と一致しているかを確認します。

この記事を通して、これらの重要なポイントを押さえることで、Spring Securityにおけるカスタムログインページの実装で陥りやすい問題を解決し、ユーザーフレンドリーで安全な認証基盤をスムーズに構築できるようになったでしょう。今後は、多要素認証の実装、OAuth2連携、あるいはログイン成功後のより複雑な認可設定など、発展的な内容についても学習を進めることをお勧めします。

参考資料