認証処理の流れを完全解説！UsernamePasswordAuthenticationFilterの基本を初心者向けに解説

認証処理の流れ（UsernamePasswordAuthenticationFilter）

新人と先輩の会話形式で理解しよう

新人

「先輩、ログインってどうやって動いてるんですか？パスワードを入力すると勝手に画面が切り替わりますけど、裏では何をしてるんですか？」

先輩

「実は裏で認証処理が行われていて、Spring Securityがユーザー名とパスワードを検証しているんだ。特にUsernamePasswordAuthenticationFilterという仕組みがその処理を担当してるよ。」

新人

「なるほど。でもその認証処理って具体的には何をしてるんですか？」

先輩

「じゃあ、今回は認証処理の基本から、Spring Securityにおける認証の仕組みまで順番に解説していこう！」

1. 認証処理とは何か（概要とログインとの関係）

Webアプリケーションにおける認証処理とは、ユーザーが正しい人物かどうかを確認する仕組みのことです。ログイン機能はこの認証処理を使って、入力されたユーザー名とパスワードを検証し、正しい場合のみシステムにアクセスを許可します。

たとえば、ショッピングサイトで買い物をする際、自分の注文履歴を見るためにはログインが必要です。ログイン画面で入力された情報が、サーバーに保存されているユーザー情報と一致するかをチェックするのが認証処理の役割です。

Spring Securityではこの認証処理を自動化するための仕組みが用意されており、特に重要なのがUsernamePasswordAuthenticationFilterです。これは、ログインフォームから送信されたユーザー名とパスワードを読み取り、認証の処理を実行します。

つまり、ログインボタンを押すと、裏ではこのフィルターが動作して、認証処理が実行されているのです。

2. Spring Securityにおける認証の役割

Spring Securityは、Spring Frameworkに組み込まれているセキュリティ機能で、認証や認可（アクセス制御）を提供します。中でも認証は「この人は誰か？」を判断する最も基本的な機能です。

Spring Securityの認証処理の流れは以下の通りです。

ユーザーがログインフォームに情報を入力し、送信ボタンを押す。
UsernamePasswordAuthenticationFilterがその情報を受け取る。
受け取った情報を使ってAuthenticationManagerに認証を依頼する。
認証が成功すれば、セッションにユーザー情報を格納する。
その後のリクエストでは、セッションを参照してユーザーを識別できる。

これにより、ログイン後の画面では「○○さん、こんにちは」といった表示ができるようになります。

実際のコードでのUsernamePasswordAuthenticationFilterの流れを簡単に示すと次のようになります。


public class CustomSecurityConfig extends WebSecurityConfigurerAdapter {

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http
            .formLogin()
                .loginPage("/login")
                .loginProcessingUrl("/login")
                .defaultSuccessUrl("/home", true)
                .permitAll()
            .and()
            .authorizeRequests()
                .anyRequest().authenticated();
    }
}

この設定では、ログイン処理に対して/loginというURLを使い、UsernamePasswordAuthenticationFilterがこのパスでリクエストを処理するようになっています。

このように、Spring Securityは認証処理を自動的に行うための強力な仕組みを提供しており、開発者は必要な設定を行うだけで、ログイン機能を簡単に実装できます。

3. UsernamePasswordAuthenticationFilterの仕組み

UsernamePasswordAuthenticationFilterは、Spring Security フィルターの中でもログイン処理に特化したクラスです。このフィルターは、ログインフォームから送信されたusernameとpasswordの情報を受け取り、それをもとにAuthenticationオブジェクトを生成し、認証処理を開始します。

まず、ユーザーがログインフォームから情報を送信すると、HTTP POSTリクエストが/loginに送られます。このとき、Spring SecurityはUsernamePasswordAuthenticationFilterを呼び出して、リクエストの中にあるパラメータを取り出します。

このフィルターの内部では、以下のような処理が行われています。

request.getParameter("username")でユーザー名を取得
request.getParameter("password")でパスワードを取得
それらを使ってUsernamePasswordAuthenticationTokenを生成
AuthenticationManagerに渡して認証処理を委譲

コードで表すと、次のような処理になります。


@Override
public Authentication attemptAuthentication(HttpServletRequest request, HttpServletResponse response)
        throws AuthenticationException {

    String username = obtainUsername(request);
    String password = obtainPassword(request);

    UsernamePasswordAuthenticationToken authRequest = new UsernamePasswordAuthenticationToken(username, password);

    return this.getAuthenticationManager().authenticate(authRequest);
}

ここで重要なのは、フィルター自体が認証を直接行っているわけではなく、AuthenticationManagerという別のコンポーネントに処理を任せているという点です。

この設計によって、Spring Securityは認証処理の実装を柔軟にカスタマイズできるようになっています。

たとえば、カスタムの認証ロジックを組み込みたい場合は、自作のAuthenticationProviderを定義することで対応可能です。

4. フィルターが呼び出されるタイミングとその後の処理

それでは、UsernamePasswordAuthenticationFilterがどのタイミングで呼び出されるのかを確認しておきましょう。このフィルターは、Spring Securityのフィルターチェーンの中で特定の順番に配置されており、ログインリクエスト（POST /login）が来たときだけ反応します。

Spring Securityは、複数のフィルターをチェーンとして順番に実行する仕組みを持っています。その中で、UsernamePasswordAuthenticationFilterはFilterSecurityInterceptorよりも前に配置されており、認証が必要かどうかを判断する前に必ず実行されるようになっています。

このフィルターが呼び出された後、認証処理が正常に完了すると、Spring Securityは以下のような流れで処理を進めます。

SecurityContextHolderに認証済みユーザー情報を保存
AuthenticationSuccessHandlerを呼び出してリダイレクト処理
セッションにユーザー情報を格納して、ログイン状態を維持

一方、認証に失敗した場合にはAuthenticationFailureHandlerが呼び出され、ログイン画面にエラーメッセージを表示するなどの処理が行われます。

たとえば、次のようなカスタム設定を加えることで、ログイン成功時や失敗時の挙動を制御することができます。


@Override
protected void configure(HttpSecurity http) throws Exception {
    http
        .formLogin()
            .loginPage("/login")
            .loginProcessingUrl("/login")
            .successForwardUrl("/home")
            .failureUrl("/login?error=true")
        .and()
        .authorizeRequests()
            .anyRequest().authenticated();
}

この設定により、ログイン成功時には/homeに遷移し、失敗時には/login?error=trueにリダイレクトされるようになります。

このように、UsernamePasswordAuthenticationFilterは、ユーザー名とパスワードを処理する重要なポイントであり、認証処理の入口として機能します。そしてその後の処理は、成功・失敗に応じて適切なハンドラーが呼び出され、最終的な画面遷移やエラーメッセージの制御が行われます。

この仕組みによって、Spring Security フィルターの中で認証に関する処理がしっかりと分離されており、安全で拡張性の高いログイン機能を構築することが可能になります。

5. 認証成功時と失敗時の挙動（SuccessHandler、FailureHandlerの動き）

Spring Securityにおける認証成功および認証失敗の処理は、それぞれAuthenticationSuccessHandlerとAuthenticationFailureHandlerによって制御されます。これらのハンドラは、UsernamePasswordAuthenticationFilterの認証結果に応じて自動的に呼び出されます。

まず、認証成功時の処理について見てみましょう。認証が成功すると、次のような流れになります。

SecurityContextHolderにユーザー情報が格納される。
AuthenticationSuccessHandlerが呼び出される。
設定されたページにリダイレクトされる。

一方で、認証失敗時は以下のような流れになります。

認証に失敗すると例外がスローされる。
AuthenticationFailureHandlerが処理を引き継ぐ。
ログイン画面へ戻され、エラーメッセージが表示される。

これらのハンドラは、標準でも用意されていますが、独自の処理をしたい場合は自作クラスでオーバーライドすることも可能です。以下にカスタムハンドラの例を紹介します。


// 認証成功時のハンドラ
public class CustomAuthenticationSuccessHandler implements AuthenticationSuccessHandler {
    @Override
    public void onAuthenticationSuccess(HttpServletRequest request,
                                        HttpServletResponse response,
                                        Authentication authentication) throws IOException, ServletException {
        response.sendRedirect("/home");
    }
}

// 認証失敗時のハンドラ
public class CustomAuthenticationFailureHandler implements AuthenticationFailureHandler {
    @Override
    public void onAuthenticationFailure(HttpServletRequest request,
                                        HttpServletResponse response,
                                        AuthenticationException exception) throws IOException, ServletException {
        response.sendRedirect("/login?error=true");
    }
}

上記のように、Spring SecurityではUsernamePasswordAuthenticationFilterの動作に基づいて、認証の成否に応じた処理を柔軟に実装できます。設定に組み込む方法は以下のようになります。


@Override
protected void configure(HttpSecurity http) throws Exception {
    http
        .formLogin()
            .loginPage("/login")
            .successHandler(new CustomAuthenticationSuccessHandler())
            .failureHandler(new CustomAuthenticationFailureHandler())
            .permitAll();
}

このように設定することで、ログイン処理が成功したときと失敗したときのそれぞれに対して、独自の制御ができるようになります。たとえば、ログイン成功後にユーザーのロールに応じた画面に遷移させたり、失敗回数を記録したりすることも可能になります。

6. 実際のアプリケーションにおける認証処理の流れの全体像

最後に、実際のアプリケーションにおける認証処理の全体の流れを整理しましょう。ここまで解説してきた通り、UsernamePasswordAuthenticationFilterを中心にしてSpring Securityは次のようなステップでログイン処理を実行しています。

ログイン画面からユーザー名とパスワードを入力し、POST送信する。
UsernamePasswordAuthenticationFilterがそのリクエストを処理する。
ユーザー情報をもとにUsernamePasswordAuthenticationTokenを作成する。
AuthenticationManagerにトークンを渡して認証処理を行う。
認証成功の場合はAuthenticationSuccessHandlerが呼び出される。
認証失敗の場合はAuthenticationFailureHandlerが呼び出される。
ログイン成功後はSecurityContextに情報が格納され、セッションが管理される。

この一連の流れをコードと一緒に設計していくことで、安全で信頼性の高い認証機能が構築されます。

実際のSpringアプリケーションでは、以下のような構成ファイルを用意することでこの流れを制御しています。


@Configuration
@EnableWebSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter {

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http
            .formLogin()
                .loginPage("/login")
                .loginProcessingUrl("/login")
                .successHandler(new CustomAuthenticationSuccessHandler())
                .failureHandler(new CustomAuthenticationFailureHandler())
                .permitAll()
            .and()
            .authorizeRequests()
                .antMatchers("/login", "/register").permitAll()
                .anyRequest().authenticated();
    }
}

この設定により、/loginへのアクセスは自由に許可し、それ以外のURLには認証済みユーザーのみがアクセスできるようになります。

また、ログイン成功時には任意のページに遷移させることができ、失敗時にはエラーを含んだパラメータ付きでリダイレクトすることで、エラーメッセージの表示も実現できます。

このように、認証処理の流れをしっかりと理解しておくことで、ログインやセキュリティに強いWebアプリケーションを構築することが可能になります。UsernamePasswordAuthenticationFilterを起点に、Spring Security 成功ハンドラや失敗時の制御までを把握しておくことは、セキュリティ実装において非常に重要です。