QuarkusとKeycloakで始めるOAuth2・JWT認証入門｜初心者向け認証・認可の完全ガイド

1. Quarkusとは何かを初心者向けに整理

1. Quarkusとは何かを初心者向けに整理

Quarkusは、Javaで高速に動作するアプリケーションを作るためのフレームワークです。 クラウドネイティブやマイクロサービスに強く、起動が速くメモリ消費が少ない点が特徴です。 REST API開発との相性が良く、セキュリティ機能も最初から用意されています。 Quarkus 認証 認可、Quarkus セキュリティ、Quarkus OAuth2、Quarkus JWT といったキーワードで検索されることが多く、 業務システムや学習用途の両方で注目されています。 特に初心者にとっては、設定ファイル中心で実装できる点が理解しやすいポイントです。

2. OAuth2とJWT認証の基本イメージ

2. OAuth2とJWT認証の基本イメージ

OAuth2は「認証を専門のサーバーに任せる仕組み」です。 アプリケーション自身がIDやパスワードを直接管理せず、信頼できる認証サーバーにログイン処理を委ねます。 JWTは、その結果として発行されるトークン形式の一つで、ユーザー情報や有効期限をまとめた文字列です。 Quarkus JWT 認証では、このトークンを使ってアクセス制御を行います。 初心者の方は「ログイン成功の証明書のようなもの」と考えると理解しやすくなります。

3. Keycloakの役割とQuarkus連携の全体像

3. Keycloakの役割とQuarkus連携の全体像

Keycloakはオープンソースの認証・認可サーバーです。 ユーザー管理、ロール管理、パスワード管理をまとめて担当します。 QuarkusとKeycloakを連携させることで、アプリ側では難しいセキュリティ処理をほとんど書かずに済みます。 構成としては、ブラウザやクライアントがKeycloakにログインし、 発行されたJWTをQuarkusアプリに渡してAPIを呼び出す流れになります。 この構成はQuarkus Keycloak 認証連携の定番パターンです。

4. Quarkusプロジェクト作成と必要な拡張機能

4. Quarkusプロジェクト作成と必要な拡張機能

QuarkusでOAuth2やJWT認証を使うには、セキュリティ関連の拡張機能を追加します。 REST APIを作る場合、JWT拡張を入れるだけで基本的な準備は完了します。 初心者は「拡張機能を追加すると機能が使える」と覚えるとよいでしょう。

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-smallrye-jwt</artifactId>
</dependency>

5. application.propertiesでのJWT設定

5. application.propertiesでのJWT設定

Quarkusでは設定ファイルに認証情報を書きます。 Keycloakの公開鍵やトークン発行者を指定することで、 QuarkusはJWTを自動で検証します。 設定ファイル中心の設計は、初心者でも全体像を把握しやすい特徴です。

quarkus.smallrye-jwt.auth-mechanism=MP-JWT
mp.jwt.verify.publickey.location=publicKey.pem
mp.jwt.verify.issuer=http://localhost:8080/realms/sample

6. 認証付きREST APIの基本実装

6. 認証付きREST APIの基本実装

JWT認証が有効になると、トークンを持たないアクセスは拒否されます。 REST APIでは、アノテーションを使って認証必須にできます。 この方法はQuarkus 認証 実装の中でも最もシンプルです。

import jakarta.annotation.security.RolesAllowed;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;

@Path("/secure")
public class SecureResource {

    @GET
    @RolesAllowed("user")
    public String secureEndpoint() {
        return "認証されたユーザーのみアクセス可能です";
    }
}

認証されたユーザーのみアクセス可能です

7. ロールによる認可の考え方

7. ロールによる認可の考え方

認証は「誰か」を確認する仕組みで、認可は「何をしてよいか」を決める仕組みです。 Keycloakではロールをユーザーに割り当て、 Quarkus側ではそのロールを使ってアクセス制御を行います。 これにより、管理者だけが使える機能などを簡単に実装できます。 Quarkus 認可 設計を理解することで、実務レベルのAPIが作れるようになります。

@GET
@RolesAllowed("admin")
@Path("/admin")
public String adminOnly() {
    return "管理者専用APIです";
}

8. 初心者がつまずきやすいポイントと理解のコツ

8. 初心者がつまずきやすいポイントと理解のコツ

初心者が混乱しやすい点は、OAuth2、JWT、Keycloak、Quarkusの役割が混ざってしまうことです。 Keycloakは認証サーバー、QuarkusはAPIサーバー、JWTは通行証というように役割を分けて考えると理解しやすくなります。 また、最初は設定ファイルとサンプルAPIだけに集中し、細かい仕様は後回しにすると学習が進みやすくなります。 Quarkus OAuth2 JWT 初心者という検索キーワードで調べる方にも役立つ構成です。