QuarkusのOAuth2・JWT認証を完全ガイド！初心者でもわかるAccess TokenとID Tokenの扱い方

1. QuarkusとOAuth2・JWT認証の基本概念

1. QuarkusとOAuth2・JWT認証の基本概念

Quarkusは、Javaで高速なクラウドネイティブアプリケーションを作るためのフレームワークです。 REST APIやマイクロサービスと相性が良く、OAuth2やJWT認証を使ったセキュアなAPI開発がよく行われます。 OAuth2は認可の仕組みで、JWTはトークンの表現形式です。 Quarkusではこれらを組み合わせて、ログイン済みユーザーだけがAPIを利用できるようにします。 初心者のうちは、難しい理論よりも「トークンを受け取って、中身を確認して、APIを守る」という流れを押さえることが重要です。

2. Access TokenとID Tokenの違い

2. Access TokenとID Tokenの違い

OAuth2とOpenID Connectでは、Access TokenとID Tokenという二種類のトークンが登場します。 Access Tokenは、APIにアクセスするための鍵のような存在です。 クライアントは、このトークンをHTTPヘッダーに付けてQuarkusのAPIを呼び出します。 一方でID Tokenは、ログインしたユーザーが誰なのかを表す情報を持っています。 ユーザー名やメールアドレスなどの情報がJWT形式で入っており、主にログイン確認に使われます。 QuarkusでAPI認証を行う場合、基本的にはAccess Tokenを使うケースが多いです。

3. JWTの中身と仕組みを理解する

3. JWTの中身と仕組みを理解する

JWTは三つのパートをドットでつないだ文字列です。 ヘッダー、ペイロード、署名という構造になっています。 ペイロード部分には、ユーザーIDやロールなどの情報が含まれます。 Quarkusでは、このJWTを自動的に解析してくれる仕組みが用意されています。 開発者は、トークンの中身を自分で分解する必要はありません。 この仕組みによって、初心者でも比較的簡単にJWT認証を導入できます。

4. QuarkusでJWT認証を有効にする設定

4. QuarkusでJWT認証を有効にする設定

QuarkusでAccess Tokenを扱うには、まずJWT認証を有効にします。 application.propertiesに必要な設定を書くことで、Quarkusがトークンを検証してくれるようになります。 認証サーバーの公開鍵や、Issuerの情報を設定するのがポイントです。 これにより、不正なトークンを自動的に弾いてくれます。

quarkus.smallrye-jwt.enabled=true
mp.jwt.verify.issuer=https://example-issuer
mp.jwt.verify.publickey.location=META-INF/resources/publicKey.pem

5. Access Tokenを受け取るREST APIの作り方

5. Access Tokenを受け取るREST APIの作り方

Quarkusでは、REST APIにトークンが送られてくると、自動的にJWTとして処理されます。 認証が必要なAPIには、アノテーションを付けるだけで対応できます。 HTTPヘッダーのAuthorizationにBearerトークンが入っていれば、Quarkusが検証します。 ここでは、ログイン済みユーザーだけがアクセスできるAPIの例を見てみましょう。

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 secureApi() {
        return "認証済みユーザーだけが見えるメッセージです";
    }
}

6. JWTからユーザー情報を取得する方法

6. JWTからユーザー情報を取得する方法

Access Tokenの中には、ユーザー名や権限情報が含まれています。 Quarkusでは、これらの情報を簡単に取得できます。 ログイン中のユーザー名を表示したり、処理を分岐させたりする場面で役立ちます。 初心者でも使いやすいAPIが用意されているのが特徴です。

import org.eclipse.microprofile.jwt.JsonWebToken;
import jakarta.inject.Inject;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;

@Path("/user")
public class UserResource {

    @Inject
    JsonWebToken jwt;

    @GET
    public String getUserName() {
        return "ログインユーザー: " + jwt.getName();
    }
}

7. Access TokenとID Tokenを使い分ける考え方

7. Access TokenとID Tokenを使い分ける考え方

QuarkusでAPIを作る場合、基本的にはAccess Tokenだけを使えば問題ありません。 ID Tokenは、フロントエンド側でログイン状態を管理するために使われることが多いです。 バックエンドのQuarkusでは、APIを守る役割に集中するのが分かりやすい設計です。 この役割分担を意識すると、OAuth2やJWT認証の理解が一気に進みます。

8. 初心者がつまずきやすいポイントと考え方

8. 初心者がつまずきやすいポイントと考え方

初心者がよく混乱するのは、トークンの種類や設定項目です。 すべてを一度に理解しようとせず、「トークンを送る」「Quarkusが検証する」「APIが呼ばれる」という流れを意識してください。 Access Tokenの役割が分かれば、OAuth2やJWT認証は怖くありません。 Quarkusは設定とコードがシンプルなので、学習用にもとても向いています。