QuarkusでJWT認証をはじめよう！初心者向けquarkus-smallrye-jwt完全入門ガイド

1. QuarkusとJWT認証の全体像

1. QuarkusとJWT認証の全体像

Quarkusは、Java向けの軽量フレームワークで、クラウドネイティブやマイクロサービス開発に向いています。Quarkus JWT認証は、JSON Web Tokenを利用して利用者の認証と認可を行う仕組みです。サーバ側でセッションを保持しないため、REST APIやOAuth2連携と相性が良く、スケーラブルな設計が可能になります。quarkus-smallrye-jwtは、そのJWT認証を簡単に実装するための公式拡張機能です。

2. JWTとは何かを初心者向けに解説

2. JWTとは何かを初心者向けに解説

JWTは、署名付きの文字列データで、利用者情報や権限情報を中に含めることができます。ログイン成功時に発行され、以後のAPI呼び出し時に送信されます。JWTは改ざん検知ができるため、安全に利用者を識別できます。Quarkus JWT認証では、このJWTを検証してアクセス制御を行います。

3. quarkus-smallrye-jwtの導入手順

3. quarkus-smallrye-jwtの導入手順

Quarkusプロジェクトでは、拡張機能としてJWT認証を追加します。MavenやGradleを使っている場合でも、Quarkus拡張として追加するだけで基本設定が整います。初心者でも迷いにくいのが特徴です。

@ApplicationScoped
public class JwtConfigExample {
    public String getIssuer() {
        return "example-issuer";
    }
}

4. application.propertiesでの基本設定

4. application.propertiesでの基本設定

Quarkus JWT認証では、application.propertiesに発行者や公開鍵の場所を設定します。これにより、受信したJWTが正しいかどうかを自動で検証してくれます。設定はシンプルで、初心者でも理解しやすい構成になっています。

quarkus.smallrye-jwt.enabled=true
mp.jwt.verify.issuer=example-issuer
mp.jwt.verify.publickey.location=publicKey.pem

5. JWTを使った認証付きAPIの作成

5. JWTを使った認証付きAPIの作成

JWT認証が有効になると、特定のAPIに対して認証を必須にできます。アノテーションを付けるだけで、JWTが無い場合や不正な場合は自動的に拒否されます。Quarkus OAuth2 JWT連携の基本的な使い方として覚えておくと便利です。

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

    @GET
    @RolesAllowed("user")
    public String secureHello() {
        return "JWT認証に成功しました";
    }
}

JWT認証に成功しました

6. JWTの中身をコードで確認する方法

6. JWTの中身をコードで確認する方法

quarkus-smallrye-jwtでは、JWTに含まれる情報をコードから簡単に取得できます。利用者名や権限を取得して、処理を分岐させることも可能です。これにより、細かな認可制御が実装できます。

@Inject
JsonWebToken jwt;

public String getUserName() {
    return jwt.getName();
}

7. OAuth2とJWT認証の関係

7. OAuth2とJWT認証の関係

OAuth2は認可の仕組みで、JWTはその結果として使われるトークン形式の一つです。Quarkus OAuth2 JWT構成では、外部認証基盤と連携し、受け取ったJWTを検証する役割を担います。これにより、ログイン処理を外部に任せつつ、安全なAPIを構築できます。

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

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

Quarkus JWT認証でよくあるつまずきは、発行者設定の不一致や公開鍵の配置ミスです。また、JWTの有効期限切れにも注意が必要です。エラーメッセージを確認しながら、一つずつ設定を見直すことで解決しやすくなります。