【ITニュース解説】How to secure an Undertow client application with OIDC (using pac4j)

Webアプリケーションを開発する際、ユーザーの認証は非常に重要な要素だ。本解説では、Javaの軽量Webサーバー「Undertow」で構築されたアプリケーションに、「OpenID Connect（OIDC）」という標準的な認証プロトコルを導入し、セキュリティを強化する方法を説明する。この仕組みを実現するために「pac4j」という認証ライブラリと、それをUndertowで使うための「undertow-pac4j」ライブラリを利用する。システムエンジニアを目指す上で、このような認証の仕組みを理解し、実装できることは大きな強みとなる。

OIDCは、インターネット上でユーザーの身元を確認するための認証プロトコルだ。簡単に言えば、ユーザーが「自分は誰であるか」をWebアプリケーションに安全に伝えるためのルール集だ。ユーザーは、アプリケーションに直接IDやパスワードを入力する代わりに、Google、Microsoft Entra ID（旧Azure AD）、Keycloakなどの信頼できる「OIDCプロバイダー」にログインする。プロバイダーがユーザーを認証すると、その認証情報をアプリケーションに安全に渡し、アプリケーションはユーザーが認証済みであることを確認できる。これにより、アプリケーション開発者はユーザー認証の複雑な処理を自前で実装する必要がなくなり、セキュリティリスクも低減できる。アプリケーションはOIDCプロバイダーの「クライアント」として機能し、認証の仲介役となるのだ。

pac4jは、OIDC、SAML、CAS、OAuthなど、様々な認証プロトコルを統一的に扱えるJavaの認証・認可ライブラリだ。Webアプリケーションフレームワークに依存せず、柔軟に認証機能を組み込める点が特徴である。undertow-pac4jは、そのpac4jをUndertowアプリケーションで簡単に利用できるようにするための連携ライブラリだ。これにより、UndertowのHTTPリクエスト処理の仕組み（ハンドラー）に、pac4jの認証ロジックをスムーズに組み込むことが可能となる。

まず、Java 17以降のバージョンを使用し、Mavenと呼ばれるJavaプロジェクト管理ツールでプロジェクトを作成する。Mavenは、プロジェクトに必要なライブラリを自動的にダウンロードし、コードのコンパイルやアプリケーションの実行を助けてくれるツールだ。プロジェクトのルートにpom.xmlという設定ファイルを作成し、Java 17でコンパイルすること、そして作成するアプリケーションのメインクラスを実行するように設定する。次に、pom.xml内にアプリケーションが利用するライブラリ（これを「依存関係」と呼ぶ）を追加する。具体的には、Undertow本体のundertow-core、pac4jとUndertowを連携させるundertow-pac4j、そしてOIDCプロトコルを扱うためのpac4j-oidcライブラリが必要となる。これらのライブラリを記述することで、Mavenが自動的にこれらをプロジェクトに組み込んでくれる。

OIDCプロバイダーとの接続情報を設定する部分だ。SecurityConfigFactoryというクラスを作成し、pac4jの設定オブジェクトであるConfigを構築する。この中でOidcConfigurationオブジェクトを生成し、OIDCプロバイダーの情報を設定する。例えば、OIDCプロバイダーがどこにあるかを示すDiscoveryURI、アプリケーションを識別するためのClientId、そして秘密鍵であるSecretなどを設定する。setAllowUnsignedIdTokens(true)という設定は、開発用のデモプロバイダーで必要となる特殊な設定であり、本番環境では通常はfalseに設定するか、削除することが推奨される。また、認証後にユーザーがアプリケーションに戻ってくるためのcallback（コールバック）URLもここで指定する。この設定は、Undertowに固有のものではなく、pac4jが提供する汎用的な設定方法であり、他のフレームワークでも同じように利用できるというpac4jの利点を示している。

Undertowアプリケーションの核となるApp.javaクラスで、Webサーバーを起動し、OIDC認証を実現するための主要な「ハンドラー」を組み込む。Undertowでは、リクエストが来ると様々な処理を段階的に行う「ハンドラー」を連鎖させていく構造になっている。PathHandlerは、特定のリクエストパス（URL）に対してどのハンドラーを適用するかをマッピングする役割を持つ。例えば、/protectedというパスには認証が必要なハンドラーを、/callbackというパスには認証結果を受け取るハンドラーを割り当てる。

SecurityHandlerは、指定されたパス（例: /protected）へのアクセスを保護する。もしユーザーがまだ認証されていない場合、このハンドラーはOIDCプロバイダーのログインページにリダイレクトする。認証済みのユーザーに対しては、保護されたページの内容を表示する処理を実行する。CallbackHandlerは、OIDCプロバイダーでユーザーがログインを完了した後、プロバイダーはこのハンドラーが設定されたURL（例: /callback）に認証結果を返す。CallbackHandlerは、その結果（認証コードなど）を受け取り、OIDCプロバイダーとやり取りしてアクセストークンやIDトークンを取得し、それらを検証する。そして、認証されたユーザーの情報をアプリケーションのセッションに保存し、ユーザーを元々アクセスしようとしていたページやデフォルトのページにリダイレクトする。セッション固定攻撃を防ぐために、セッションIDを更新する機能も持つ。LogoutHandlerは、アプリケーションからのログアウト処理を担当する。これにより、アプリケーションに保存されていたユーザーの認証情報（プロファイル）が削除され、必要であればUndertowのセッションも無効化される。

これらのハンドラーは、SessionAttachmentHandlerによってラップされる。SessionAttachmentHandlerは、Undertowのセッション管理機能（InMemorySessionManagerなど）をHTTPリクエストに紐付ける役割を果たす。これにより、pac4jがユーザー認証情報をセッションに保存したり読み出したりできるようになる。特に、InMemorySessionManagerはサーバーのメモリ上にセッション情報を保持するため、複数のサーバーでアプリケーションを動かす場合は、セッション情報を共有するための仕組み（例: データベースや分散キャッシュ）が必要となる点に注意が必要だ。

protectedPageというメソッドで、認証されたユーザーの情報を取得し、表示する例が示されている。ユーザーがログインすると、pac4jはPac4jAccountというオブジェクトをリクエストのセキュリティコンテキストに登録する。このPac4jAccountからOidcProfileというオブジェクトを取得できる。OidcProfileには、ユーザーの名前（getDisplayName()）やメールアドレス（getEmail()）など、OIDCプロバイダーから提供された様々な情報が含まれており、これらの情報を利用してユーザー向けのコンテンツをカスタマイズできる。

ログアウトには主に二つの種類がある。一つはアプリケーション自身のセッションからユーザー情報を削除し、ログアウトさせる「ローカルログアウト」だ。これはLogoutHandlerの基本的な機能で実現できる。もう一つは、アプリケーションからのログアウトに加えて、OIDCプロバイダー（例えばGoogle）からもログアウトさせる「セントラルログアウト」だ。これにより、ユーザーは同じOIDCプロバイダーを利用している他のアプリケーションからもログアウトされることになる。セントラルログアウトを設定するには、LogoutHandlerに特定のオプション（setCentralLogout(true)など）を設定し、プロバイダーに登録されたログアウト後のリダイレクトURLを指定する必要がある。

上記の設定とコードが完了したら、Mavenコマンドmvn clean compile exec:javaを実行してUndertowアプリケーションを起動する。Webブラウザでhttp://localhost:8080/protectedにアクセスすると、OIDCプロバイダーのログインページにリダイレクトされるはずだ。そこでログインを完了すると、元のアプリケーションに戻り、保護されたページが表示され、ユーザーの名前で挨拶されることを確認できる。もしリダイレクトURIが拒否される場合は、OIDCプロバイダー側に正しいコールバックURLを登録しているか確認する必要がある。セッション関連のエラーが発生した場合は、SessionAttachmentHandlerが正しく設定され、すべての保護されたパスやコールバックパスをラップしているかを確認する。

pac4jの大きな利点は、認証プロトコルの切り替えが容易な点だ。OIDCではなくSAMLやCASといった他の認証プロトコルを利用したい場合でも、pom.xmlで適切なpac4jモジュールを追加し、SecurityConfigFactory内のOidcClientを対応するクライアント（例: Saml2Client）に置き換えるだけで、比較的簡単に認証システムを変更できる。これは、将来的にシステムの要件が変わった場合でも、柔軟に対応できることを意味する。

このように、Undertowとpac4j、OIDCを組み合わせることで、堅牢で柔軟な認証システムを効率的に構築できる。システムエンジニアとして、このようなセキュリティ実装の基礎を学ぶことは、今後のキャリアにおいて非常に価値のある経験となるだろう。