OpenID ConnectによるSSO設定

概要

Fess では、OpenID Connect（OIDC）を使用したシングルサインオン（SSO）認証をサポートしています。 OpenID ConnectはOAuth 2.0を基盤とした認証プロトコルで、ID Token（JWT）を使用してユーザー認証を行います。 OpenID Connect認証を使用することで、OIDCプロバイダー（OP）で認証されたユーザー情報を Fess に連携できます。

OpenID Connect認証の仕組み

OpenID Connect認証では、Fess がRelying Party（RP）として動作し、外部のOpenIDプロバイダー（OP）と連携して認証を行います。

  1. ユーザーが Fess のSSOエンドポイント（/sso/）にアクセス

  2. Fess がOPの認可エンドポイントにリダイレクト

  3. ユーザーがOPで認証を実行

  4. OPが認可コードを Fess にリダイレクト

  5. Fess が認可コードを使用してトークンエンドポイントからID Tokenを取得

  6. Fess がID Token（JWT）からユーザー情報を取得し、ユーザーをログイン

注釈

Fess は認可コードフロー（Authorization Code Flow）を使用します。ID Tokenは、ブラウザを経由せず、Fess とOPの間のバックチャネル（サーバー間通信）でトークンエンドポイントから直接取得されます。 Fess はID Tokenをデコードしてクレーム（email や groups など）を取り出してユーザー情報を構成しますが、JWT署名の暗号的な検証は行いません。iss（発行者）、aud（対象クライアント）、exp（有効期限）の各クレームも検証しません。 このため、トークンエンドポイントとの通信は必ずHTTPSで行い、Fess とOPの間の通信経路が信頼できることを確認してください。

ロールベース検索との連携については、ロールベース検索の設定 を参照してください。

前提条件

OpenID Connect認証を設定する前に、以下の前提条件を確認してください。

  • Fess 15.8 以降がインストールされていること

  • OpenID Connect対応のプロバイダー（OP）が利用可能であること

  • Fess がHTTPSでアクセス可能であること（本番環境では必須）

  • OP側で Fess をクライアント（RP）として登録できる権限があること

対応するプロバイダーの例:

  • Microsoft Entra ID（Azure AD）

  • Google Workspace / Google Cloud Identity

  • Okta

  • Keycloak

  • Auth0

  • その他のOpenID Connect対応プロバイダー

基本設定

SSO機能の有効化

OpenID Connect認証を有効にするには、app/WEB-INF/conf/system.properties に以下の設定を追加します。

sso.type=oic

注釈

sso.type および以降で説明する oic.* の各設定は、管理画面の「システム > 全般」ページからも設定・変更できます。 管理画面で変更した設定は system.properties に保存され、再起動後も保持されます。

プロバイダー設定

OPから取得した情報を設定します。

プロパティ 説明 デフォルト
oic.auth.server.url 認可エンドポイントURL https://accounts.google.com/o/oauth2/auth
oic.token.server.url トークンエンドポイントURL https://accounts.google.com/o/oauth2/token

注釈

これらのURLは、OPのDiscoveryエンドポイント（/.well-known/openid-configuration）から取得できます。

クライアント設定

OP側で登録したクライアント情報を設定します。

プロパティ 説明 デフォルト
oic.client.id クライアントID （空文字）
oic.client.secret クライアントシークレット （空文字）
oic.scope 要求するスコープ （空文字）

注釈

スコープには少なくとも openid を含める必要があります。 ユーザーのメールアドレスを取得する場合は openid email を指定します。

リダイレクトURL設定

認証後のコールバックURLを設定します。

プロパティ 説明 デフォルト
oic.redirect.url リダイレクトURL（コールバックURL） {oic.base.url}/sso/
oic.base.url Fess のベースURL http://localhost:8080

注釈

oic.redirect.url を省略した場合、oic.base.url から自動的に構成されます。 本番環境では、oic.base.url にHTTPSのURLを設定してください。

ユーザー属性設定

OIDCで認証されたユーザーに割り当てるデフォルトのグループ・ロールを設定します。 ユーザーID・グループ・ロールは、それぞれ以下のように決定されます。

  • ユーザーID: ID Token（JWT）の email クレームから取得されます。このため、スコープには実質的に email を含める必要があります（email クレームが取得できない場合、ログインは正しく行われません）。

  • グループ: ID Tokenの groups クレームから取得されます。groups クレームが存在しない場合は oic.default.groups の値が使用されます。groups クレームが空の配列で送られてきた場合は「存在する」とみなされるため、oic.default.groups は使用されず、グループなしとして扱われます。

  • ロール: 常に oic.default.roles の値が使用されます（ID Tokenのクレームからロールを取得する仕組みはありません）。

注釈

Fess は groups クレームの値をそのまま使用し、ディレクトリへの問い合わせや ネストされたグループ（親グループ）の展開は行いません。 親グループが含まれるかどうかは、OP側のクレーム設定だけで決まります。 Microsoft Graph APIで親グループを解決する Microsoft Entra IDによるSSO設定 とは動作が異なります。 クレームの値はそのまま検索権限になります。OP側でグループのフルパスを出力する設定にしている場合は /親グループ/子グループ のような値がそのまま権限名になり、グループ名だけを付与した文書とは一致しません。

プロパティ 説明 デフォルト
oic.default.groups デフォルトグループ（カンマ区切り） （空文字）
oic.default.roles デフォルトロール（カンマ区切り） （空文字）

注釈

ロールベース検索を使用する場合は、ユーザーに適切なグループまたはロールを割り当てる必要があります。 詳細は ロールベース検索の設定 を参照してください。

OP側での設定

OP側で Fess をクライアント（RP）として登録する際に、以下の情報を設定します。

設定項目 設定値
アプリケーションの種類 Webアプリケーション
リダイレクトURI / コールバックURL https://<Fessのホスト>/sso/
許可するスコープ openid および必要なスコープ（email, profile など）

OPから取得する情報

OPの設定画面またはDiscoveryエンドポイントから以下の情報を取得し、Fess の設定に使用します。

  • 認可エンドポイント（Authorization Endpoint）: ユーザー認証を開始するURL

  • トークンエンドポイント（Token Endpoint）: トークンを取得するURL

  • クライアントID: OPで発行されたクライアント識別子

  • クライアントシークレット: クライアント認証に使用する秘密鍵

注釈

多くのOPでは、Discoveryエンドポイント（https://<OP>/.well-known/openid-configuration）から 認可エンドポイントとトークンエンドポイントのURLを確認できます。

設定例

最小構成（検証環境向け）

以下は、検証環境で動作確認を行うための最小限の設定例です。

# SSO有効化
sso.type=oic

# プロバイダー設定（OPから取得した値を設定）
oic.auth.server.url=https://op.example.com/authorize
oic.token.server.url=https://op.example.com/token

# クライアント設定
oic.client.id=your-client-id
oic.client.secret=your-client-secret
oic.scope=openid email

# リダイレクトURL（検証環境）
oic.redirect.url=http://localhost:8080/sso/

推奨構成（本番環境向け）

以下は、本番環境で使用する際の推奨設定例です。

# SSO有効化
sso.type=oic

# プロバイダー設定
oic.auth.server.url=https://op.example.com/authorize
oic.token.server.url=https://op.example.com/token

# クライアント設定
oic.client.id=your-client-id
oic.client.secret=your-client-secret
oic.scope=openid email profile

# ベースURL（本番環境ではHTTPSを使用）
oic.base.url=https://fess.example.com

トラブルシューティング

よくある問題と解決方法

認証後に Fess に戻れない

  • OP側のリダイレクトURIが正しく設定されているか確認してください

  • oic.redirect.url または oic.base.url の値がOP側の設定と一致しているか確認してください

  • プロトコル（HTTP/HTTPS）が一致しているか確認してください

認証エラーが発生する

  • クライアントIDとクライアントシークレットが正しく設定されているか確認してください

  • スコープに openid が含まれているか確認してください

  • 認可エンドポイントURLとトークンエンドポイントURLが正しいか確認してください

ユーザー情報が取得できない

  • スコープに必要な権限（email, profile など）が含まれているか確認してください

  • OP側でクライアントに必要なスコープが許可されているか確認してください

  • Microsoft Entra IDでは、ソース属性を変更しない限り groups クレームの値はグループの ObjectId （GUID）になるため、 グループ名とは一致しません

  • ユーザーが200を超えるグループに所属している場合、Microsoft Entra IDは groups クレーム自体を送信しません （ネストされたグループもこの上限に数えられます）。このとき Fess は oic.default.groups にフォールバックします

デバッグ設定

問題を調査する際は、Fess のログレベルを調整することで、OpenID Connect関連の詳細なログを出力できます。

app/WEB-INF/classes/log4j2.xml で、以下のロガーを追加してログレベルを変更できます。

<Logger name="org.codelibs.fess.sso.oic" level="DEBUG"/>

警告

このロガーをDEBUGにすると、ID Tokenのクレーム（email や groups など）がログファイルに出力されます。 調査が終わったらログレベルを元に戻し、出力されたログの取り扱いに注意してください。

参考情報