IBM Verify SaaS＋Quarkusで体験する OIDC連携

はじめに

現在のWebアプリケーション開発では、認証機能はほぼ必須の要件といえます。パスワード認証の画面をつくりこむこともありますが、業務利用では認証基盤を使用することになると思います。

この記事では、どのようにアプリケーションに認証機能を付与するかを体験するために、IBMが提供する認証基盤である IBM Verify SaaS（以下、Verify）と、ローカルのサンプルアプリケーションを連携して、関係性を理解できるようにします。

今回の記事は皆様の手元で再現可能なように、無料で利用できるライトプランを選択します。

この記事で達成すること

• IBM Verify SaaS のテナント作成からアプリ登録までの準備
• Quarkus + quarkus-oidc 拡張を使った OIDC 保護の実装
• ブラウザから認証画面が表示され、ログイン後にアプリが動作する体験

全体像

前提環境

この記事では、次の環境で検証を行っています。

項目	バージョン
OS	Windows 11
Java	GraalVM 21
Quarkus	3.33
Quarkus CLI	3.38
ブラウザ	Chrome最新版

OIDC とは？

OIDC（OpenID Connect）は、OAuth 2.0 を認証に拡張したプロトコルです。ユーザーが「誰であるか」を IdP（Identity Provider、認証プロバイダの略でこの記事ではVerifyになります）が確認し、その結果を ID トークン（JWT） としてアプリケーションに渡します。

認証基盤であるIdPを、OIDCの用語ではOP（OpenID Provider）と呼びます。

SAML との位置づけ・違い

Verify は OIDC・SAML の両方をサポートしています。どちらを選ぶかは連携先のアプリケーションや要件によって決まります。

観点	OIDC	SAML
策定年	2014 年（比較的新しい）	2002 年（歴史が長い）
トークン形式	JWT（JSON）	XML アサーション
主な用途	Web アプリ・モバイル・API	エンタープライズ SSO・レガシー連携
実装のしやすさ	ライブラリが豊富で比較的容易	XML 署名の扱いなどやや複雑
呼称	アプリ：RP (Relying Party) 認証基盤：OP(OpenID Provider)	アプリ：SP(Service Provider) 認証基盤：IdP (Identity Provider)
向いているシーン	新規開発・クラウドネイティブ	既存システムとの連携が必要な場合

この記事ではOIDC認証を試しますが、SAML 連携については LibertyとIBM Verifyで試すSAML認証 シリーズもご参照ください。

SAMLとの認証フローの違い

アプリにアクセスした際、未認証であればVerifyにリダイレクトする点は同じです。
その後のフローでは、OIDCでは認可コードを経由してバックチャネルでトークン交換を行う構成が一般的です。一方SAMLはブラウザを介してアサーションを受け渡します。どちらも適切な実装で高い安全性を実現できますが、OIDCはAPIやモバイルアプリなど現代的なアプリケーションとの親和性が高いことから広く採用されています。

VerifyとアプリをOIDCで接続するために必要なもの

OIDCを使って、IdPと自作のアプリケーション（Quarkusなど）を接続するためには、お互いの情報を事前に登録・設定して、「信頼関係」を築く必要があります。

この連携において、「何が」「どこで」「なぜ」必要なのかという全体像を理解しておくと、この後の具体的な設定手順が非常にスムーズになります。

設定に必要な「3つの要素」

接続を確立するためには、大きく以下の3点の情報をVerifyとアプリで共有します。

#	要素	役割・説明
①	リダイレクト URI (Redirect URI)	「認証成功後に戻る場所」 ユーザーがIBM Verify側でのログインに成功した後、Verifyからブラウザに対して「このURLに戻りなさい」と指示するための戻り先URLです。 アプリ側で値を決定し、Verify側に提供します。
②	クライアント ID & シークレット (Credentials)	「アプリの識別子とパスワード」 IBM Verifyにアプリケーションを登録した際に自動生成される、一対の認証資格情報です。 Verify側で生成し、アプリ側に共有します。 ・クライアント ID (Client ID): アプリを一意に識別するための公開ID。 ・クライアントシークレット (Client Secret): アプリがVerifyとバックチャネル（直接通信）で安全に通信してトークン（JWT）を取得する際に使用する、厳重に秘匿すべきパスワード。
③	Discovery URL	「仕様書の公開場所」 OIDC仕様に基づき、Verifyが自身の認証エンドポイント、トークン交換エンドポイント、鍵公開URLなどの詳細情報を公開しているURL（.well-known/openid-configuration）です。アプリケーション側にこのURLを1つ設定するだけで、ライブラリが自動的に必要なエンドポイント情報を取得してくれます。 Verify上で決定され、アプリ側に共有します。

設定の流れ

Verifyを利用可能にし、サンプルアプリをQuarkusで動かすようにします。

ステップ	作業場所	内容
【1】テナントを作成する	IBM Verify（Web）	ライトプランへの登録・テナント発行
【2】アプリを登録する	IBM Verify 管理コンソール	アプリケーションの作成・OIDC 設定 クライアント ID / シークレット / Discovery URL の取得
【3】ユーザーを登録する	IBM Verify 管理コンソール	ユーザーの作成
【4】Quarkus アプリを作成する	ローカル PC（ターミナル）	プロジェクト生成・Hello エンドポイントの実装、application.properties に Verify の接続情報を記述
【5】動作確認する	ブラウザ	認証画面へのリダイレクト → ログイン → アプリ表示

【1】IBM Verify テナントを作成する

IBM Verifyの利用にあたっては、IBMアカウント（IBM ID）を作成する必要があります。既にアカウントをお持ちの場合はそのままご利用できます。それ以外の方はガイダンスに従って作成してください。

1. ライトプランの登録ページにアクセスする

ブラウザで次の「IBM Verify」のページを開き、画面にある「無料評価版を試す」をクリックします。

ユーザー登録のガイダンスに入るため、IDの新規作成またはログインを行います。

2. テナント情報を入力する

テナントとは、Verify SaaS上であなたのアカウントが管理する環境のことです。
あなたが利用するVerifyを識別するホスト名を命名して入力します。名前はグローバルで一意とする必要があります。
無料枠で利用するデータセンターは欧州固定となります。

ホスト名の重複がなければ、テナントの初期設定が行われ、Verifyが利用可能になります。

【2】Verify にアプリケーションを登録する

1. 管理コンソールからアプリケーションを新規作成する

テナント作成後、管理コンソール（https://<テナントホスト名>.verify.ibm.com/ui/admin）にアクセスします。

左メニューから アプリケーション → アプリケーション を選択し、アプリケーション一覧画面から右上の「アプリケーションの追加」ボタンをクリックします。

アプリケーションタイプの選択で「OpenID Connect」を選択し、「アプリケーションの追加」ボタンをクリックします。

2. アプリケーションを登録する

次の設定で入力を行います。

まず、画面最上部にあるフィールドがアプリケーション名となりますので、ここに「quarkus-hello」と入力します。
各タブで次の入力を行い、最後に「保存」ボタンをクリックします。

タブ	設定項目	設定値	説明
一般	会社名	（任意）	アプリケーションを提供する企業名
サインオン	アプリケーション URL	http://localhost:8080	Quarkus アプリの URL
サインオン	リダイレクト URI	http://localhost:8080/	認証後のリダイレクト先

資格タブが追加されるため、「すべてのユーザーおよびグループに対する自動アクセス」を選択して再度「保存」ボタンをクリックします。

ワークフロー更新の警告が出る場合は「OK」を押してください。

3. クライアントID / クライアントシークレット / エンドポイントを確認する

保存後、「サインオン」タブに クライアントID と クライアント・シークレット が表示されます。
この2つの値を控えておきます。次のステップで使用します。

同タブの右側に構成の説明テキストが表示されていますが、そのなかに「IBM Verify エンドポイント」のURLが表示されています。こちらも控えておきます。

【3】Verifyユーザーの追加

アプリケーションにログインできるユーザーを追加します。

左メニューから ディレクトリー → ユーザー&グループ を選択し、ユーザー一覧画面から右上の「ユーザーの追加」ボタンをクリックします。

ユーザーの追加画面で、次の値を設定して「保存」ボタンをクリックします。

項目	設定値
アイデンティティー・プロバイダー	Cloud Directory
ユーザー名	(任意)
優先Eメール	(あなたの有効なメールアドレス)
新規アカウントにメールを送信	OFF

作成後に、登録メールアドレスに仮パスワードが届きます（これは「新規アカウントにメールを送信」をOFFにしても送信されます）。
以降のプロセスで初回ログイン時には仮パスワードを使用します。その後、パスワードの変更が促されます。

【4】Quarkus Hello World アプリを作成する

1. プロジェクトを生成する

IBM Quarkusのプロジェクトは、Code Quarkus というプロジェクト・ジェネレーターから作成することができますが、ここではQuarkus CLIによるインストールを行います。

Quarkus CLIのインストール

CLIのインストールはいくつかの手順が選択できます。

CLIをScoopを使ってインストールします。Scoopについての詳細はこちらの記事も参考にしてください。

scoop install quarkus-cli

プロジェクトの作成

以下のコマンドで、カレントフォルダの下にプロジェクトを作成します。rest と oidc の 2 つの拡張を同時に追加します。

quarkus create app com.example:hello-oidc --stream=3.33 --java=21 --extensions="rest,oidc"

以降の操作はプロジェクトフォルダで行います。

2. Hello エンドポイントを実装する

src/main/java/com/example/GreetingResource.java を以下の内容で上書きします。

GreetingResource.java

package com.example;

import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;
import io.quarkus.security.Authenticated;
import io.quarkus.security.identity.SecurityIdentity;
import jakarta.inject.Inject;

@Path("/hello")
public class GreetingResource {

    @Inject
    SecurityIdentity identity;

    @GET
    @Produces(MediaType.TEXT_PLAIN)
    @Authenticated
    public String hello() {
        String username = identity.getPrincipal().getName();
        return "Hello, " + username + "! IBM Verify で認証に成功しました。";
    }
}

ポイント：

• @Authenticated アノテーションを付けるだけで、未認証ユーザーは自動的に Verify の認証画面にリダイレクトされます
• SecurityIdentity から取得した getName() は、Quarkus OIDCがトークン内の
  upn → preferred_username → sub の順にクレームを探して決定する
  プリンシパル名です（quarkus.oidc.token.principal-claim で明示的に指定も可能）。
  Verify のIDトークンにどのクレームが含まれるかによって表示値は変わりますが、
  今回の検証環境では sub の値が表示されています。

3. quarkus-oidc の設定ファイルを編集する

src/main/resources/application.properties を以下のように編集します。
エンドポイント、クライアントID、クライアントシークレットをVerifyで確認した値に置き換えます。

エンドポイントは https://xxx.verify.ibm.com/oauth2/.well-known/openid-configuration のようなディスカバリーURLで記載されていますが、propertiesには .well-known 以下を削除した形で記載してください。
先の例ではhttps://xxx.verify.ibm.com/oauth2を指定します。

# ── OIDC 設定 ──────────────────────────────────────────
# IBM Verify の Discovery エンドポイント
quarkus.oidc.auth-server-url=<エンドポイント>

# Verify で確認したクライアント ID
quarkus.oidc.client-id=<クライアントID>

# Verify で確認したクライアントシークレット
quarkus.oidc.credentials.secret=<クライアントシークレット>

# Web アプリとして OIDC Authorization Code Flow を使用する
quarkus.oidc.application-type=web-app

# IBM Verify が PKCE を必須としている場合はtrueを指定する
quarkus.oidc.authentication.pkce-required=true

今回は疎通確認が目的のため、簡易的にクライアントシークレットをファイルに記載していますが、実際には環境変数などで管理します。

【5】 動作確認

1. アプリを起動する

quarkus dev

起動ログに以下のような出力が表示されれば、アクセス可能です。

__  ____  __  _____   ___  __ ____  ______
 --/ __ \/ / / / _ | / _ \/ //_/ / / / __/
 -/ /_/ / /_/ / __ |/ , _/ ,< / /_/ /\ \
--\___\_\____/_/ |_/_/|_/_/|_|\____/___/
2026-XX-XX 00:00:00,000 INFO  [io.quarkus.oidc.runtime.dev.ui.OidcDevUiRecorder] (Quarkus Main Thread) OIDC Dev Console: discovering the provider metadata at .../.well-known/openid-configuration

2. ブラウザでアクセスする

ブラウザで http://localhost:8080/hello にアクセスします。
未認証状態のため、アプリで準備した画面ではなく、Verifyが提供する認証画面に遷移します。

この画面で、テナントに登録しているユーザーの認証情報でログインします。ここでは登録済ユーザーである usr01 を使ってログインします。

3. アプリの画面を確認する

認証が成功すると、ブラウザにアプリの応答が表示されます。ここではログインに使用したusr01の名前が画面上に表示されています。

これでVerifyを認証基盤としたOIDC連携の挙動が確認できました。

暫くログイン状態は継続します。ログインを複数回試す場合は、シークレットウィンドウの利用をおすすめします。

まとめ

本記事では、Verifyの利用開始設定およびアプリケーション関連の設定、および接続するアプリケーションをQuarkusで実装し、連携する挙動を確認しました。

実際に手順を踏んでみると、

• Verifyの利用開始が簡単に行えること、設定も最小限のポイントで開始できること
• アプリケーションの認証連携は宣言的に実装できること

が体験できると思います。

実際の業務システムでは、さらに次のような要素が求められます。

• MFA（多要素認証）
• ソーシャルログイン
• グループ・ロールによるアクセス制御
• パスキー認証

これらの要素にもVerifyは対応しているため、ぜひ今回の実装を起点に試してみてください。

参考