先生と生徒の会話形式で理解しよう

生徒

「Quarkusでログイン画面付きの認証を作りたいんですが、何から始めればいいですか？」

先生

「Quarkusには標準でフォーム認証の仕組みが用意されています。設定と簡単な実装だけでログイン機能を作れますよ。」

生徒

「Spring Securityみたいに難しくないですか？」

先生

「設定項目は少なめなので、流れを押さえれば初心者でも理解しやすいです。順番に見ていきましょう。」

1. Quarkusのフォーム認証とは何か

Quarkusのフォーム認証は、Webアプリケーションにログイン画面を用意し、ユーザー名とパスワードでアクセス制御を行うための基本的なセキュリティ機能です。ブラウザからアクセスする業務アプリや管理画面では、フォーム認証が最も一般的に使われます。 Quarkusでは、HTTPベースの認証とセキュリティ設定がシンプルに統合されており、設定ファイルと少量のJavaコードだけで実現できます。初心者がJavaフレームワークでセキュリティを学ぶ最初の一歩として、とても相性が良い仕組みです。

2. フォーム認証を導入する全体の流れ

Quarkusアプリにフォーム認証を導入する流れは、大きく分けて環境準備、セキュリティ設定、ログイン画面作成、ユーザー情報の定義、保護対象リソースの設定という順番になります。いきなりコードを書き始めるのではなく、どこで何を設定するのかを把握することが大切です。この流れを理解しておくと、認証エラーが起きたときにも原因を切り分けやすくなります。特に初心者のうちは、設定ファイルとJavaコードの役割を混同しないように意識しましょう。

3. 必要な拡張機能とプロジェクト準備

フォーム認証を使うためには、Quarkusのセキュリティ関連拡張機能をプロジェクトに追加します。基本となるのは、HTTPセキュリティと認証機能です。 MavenやGradleでプロジェクトを作成する際に拡張を追加しておくと、後から設定が楽になります。初心者は、公式のプロジェクト生成ツールを使う方法がおすすめです。


<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-security</artifactId>
</dependency>

この拡張を追加することで、Quarkusアプリケーションに認証と認可の基盤が組み込まれます。これがフォーム認証の土台になります。

4. セキュリティ設定ファイルの基本設定

Quarkusでは、セキュリティ設定の多くを設定ファイルで行います。フォーム認証の場合、ログインページのパスやエラーページの指定を行います。設定ファイルはアプリ全体の動作に影響するため、どの設定が認証に関係しているのかを意識しながら書くことが重要です。


quarkus.http.auth.form.enabled=true
quarkus.http.auth.form.login-page=/login.html
quarkus.http.auth.form.error-page=/login-error.html

この設定により、未認証のユーザーが保護されたページにアクセスすると、自動的にログイン画面へ誘導されます。フォーム認証らしい動きを実感できるポイントです。

5. ログイン画面とエラーページの作成

フォーム認証では、ユーザーが入力するログイン画面が必要です。 Quarkusでは、通常のHTMLファイルとしてログイン画面を用意します。難しいテンプレート技術を使わなくても、最低限のHTMLで動作確認ができます。初心者は、まずシンプルな画面を作り、動くことを確認してから見た目を調整すると理解しやすいです。


<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>ログイン</title>
</head>
<body>
    <form method="post" action="/j_security_check">
        <label>ユーザー名</label>
        <input type="text" name="j_username">
        <br>
        <label>パスワード</label>
        <input type="password" name="j_password">
        <br>
        <button type="submit">ログイン</button>
    </form>
</body>
</html>

このHTMLは、Quarkusのフォーム認証仕様に沿った基本形です。入力項目の名前を間違えると認証されないため、最初はそのまま使うのがおすすめです。

6. ユーザー情報と認証ロジックの考え方

フォーム認証では、入力されたユーザー名とパスワードをどこで確認するかが重要になります。学習段階では、メモリ上にユーザー情報を定義する方法が理解しやすいです。本番環境ではデータベース連携が一般的ですが、まずは仕組みを知ることを優先しましょう。認証の流れを理解すると、セキュリティの全体像が見えてきます。


@ApplicationScoped
public class SimpleUserService {

    public boolean authenticate(String username, String password) {
        return "admin".equals(username) && "password".equals(password);
    }
}

このようなシンプルな認証ロジックを通して、ユーザー確認の考え方を学ぶことができます。実際のプロジェクトでは、ここがデータベースや外部認証サービスに置き換わります。

7. 認証が必要なページの制御方法

フォーム認証を導入しただけでは、どのページが保護されるのか分かりません。 Quarkusでは、URLパスごとにアクセス制御を設定できます。管理画面や会員専用ページなど、ログイン後だけ見せたい画面を明確に分けることが重要です。初心者は、まず一つのパスを保護して動作を確認すると理解が深まります。


quarkus.http.auth.permission.admin.paths=/admin/*
quarkus.http.auth.permission.admin.policy=authenticated

この設定により、指定したパス配下はログイン済みユーザーだけがアクセスできるようになります。フォーム認証とアクセス制御が連動するポイントです。

8. 初心者がつまずきやすいポイントと対策

Quarkusのフォーム認証でよくあるつまずきポイントは、設定ファイルの記述ミス、ログインフォームの入力項目名の間違い、保護パスの指定漏れです。エラーが出ないのにログインできない場合、まず設定ファイルとHTMLを見直すのが基本です。また、ブラウザのキャッシュが影響することもあるため、動作確認時は注意しましょう。一つずつ確認していけば、フォーム認証の仕組みは必ず理解できるようになります。