Windows統合認証によるSSO設定

概要

Fess はWindows統合認証（SPNEGO/Kerberos）を使用したシングルサインオン（SSO）認証をサポートしています。 Windows統合認証を使用することで、Active Directoryドメインに参加しているWindowsにログインしたユーザーは、追加のログイン操作なしで Fess にアクセスできます。

Windows統合認証の仕組み

Windows統合認証では、 Fess はSPNEGO（Simple and Protected GSSAPI Negotiation Mechanism）プロトコルを使用してKerberos認証を行います。

ユーザーがWindowsドメインにログイン
ユーザーが Fess にアクセス
Fess がSPNEGOチャレンジを送信
ブラウザがKerberosチケットを取得してサーバーに送信
Fess がチケットを検証し、ユーザー名を取得
LDAPを使用してユーザーのグループ情報を取得
ユーザーがログイン状態になり、グループ情報がロールベース検索に適用される

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

前提条件

Windows統合認証を設定する前に、以下の前提条件を確認してください：

Fess 15.8以降がインストールされている
Active Directory（AD）サーバーが利用可能
Fess サーバーがADドメインからアクセス可能
ADでサービスプリンシパル名（SPN）を設定する権限がある
LDAPでユーザー情報を取得するためのアカウントがある

Active Directory側の設定

サービスプリンシパル名（SPN）の登録

Fess 用のSPNをActive Directoryに登録する必要があります。 ADドメインに参加しているWindowsでコマンドプロンプトを開き、 setspn コマンドを実行します。

例：

登録を確認するには：

注釈

SPNの登録後、Fessサーバーで実行した場合は一度Windowsからログアウトし、再ログインしてください。

基本設定

SSOの有効化

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

Kerberos設定ファイル

app/WEB-INF/classes/krb5.conf を作成し、Kerberos設定を記述します。

[libdefaults]
    default_realm = EXAMPLE.LOCAL
    default_tkt_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128
    default_tgs_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128
    permitted_enctypes   = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128

[realms]
    EXAMPLE.LOCAL = {
        kdc = AD-SERVER.EXAMPLE.LOCAL
        default_domain = EXAMPLE.LOCAL
    }

[domain_realm]
    example.local = EXAMPLE.LOCAL
    .example.local = EXAMPLE.LOCAL

注釈

EXAMPLE.LOCAL はお使いのADドメイン名（大文字）に、 AD-SERVER.EXAMPLE.LOCAL はADサーバーのホスト名に置き換えてください。

警告

permitted_enctypes に含まれていない暗号化方式のサービスチケットは、Kerberos の受け入れ側で encryption type not in permitted_enctypes list として拒否されます。 Active Directory は通常 AES256 のサービスチケットを発行するため、AES256 を必ず含めてください。

注釈

Java 17 以降では RC4（ rc4-hmac ）、3DES、DES が既定で無効化されているため、これらを列挙しても使用されません。上記の例では AES のみを指定しています。 aes256-cts-hmac-sha384-192 と aes128-cts-hmac-sha256-128 は、Windows Server 2025 が対応する AES-SHA2（RFC 8009）の暗号化方式です。 RC4 の鍵しか持たないサービスアカウントでは Kerberos 認証に失敗するため、パスワードを再設定して AES の鍵を生成してください。

ログイン設定ファイル

app/WEB-INF/classes/auth_login.conf を作成し、JAASログイン設定を記述します。

注釈

krb5.conf と auth_login.conf は、 spnego.krb5.conf / spnego.login.conf でデフォルトのファイル名が設定されますが、ファイル自体は必ず作成しておく必要があります。 SPNEGO の初期化は最初のログイン時に行われるため、これらのファイルが存在しなくても Fess 自体は起動しますが、SSO ログインが失敗します。

必須設定

app/WEB-INF/conf/system.properties に以下の設定を追加します。

プロパティ	説明	デフォルト値
`spnego.preauth.username`	AD接続用ユーザー名	（keytabを使用しない場合は必須）
`spnego.preauth.password`	AD接続用パスワード	（keytabを使用しない場合は必須）
`spnego.krb5.conf`	Kerberos設定ファイルパス	`krb5.conf`
`spnego.login.conf`	ログイン設定ファイルパス	`auth_login.conf`

注釈

spnego.preauth.username と spnego.preauth.password を両方とも空にすると、サーバー側のログインモジュールが keytab を使用します。 AD のサービスアカウントのパスワードを Fess の設定ファイルに保存したくない場合は、 keytab を作成して auth_login.conf の spnego-server を次のように設定してください。

spnego-server {
    com.sun.security.auth.module.Krb5LoginModule required
    useKeyTab=true
    keyTab="/var/lib/fess/fess.keytab"
    principal="HTTP/fess-server.example.local@EXAMPLE.LOCAL"
    storeKey=true
    isInitiator=false;
};

オプション設定

必要に応じて以下の設定を追加できます。

プロパティ	説明	デフォルト値
`spnego.login.client.module`	クライアントモジュール名	`spnego-client`
`spnego.login.server.module`	サーバーモジュール名	`spnego-server`
`spnego.allow.basic`	Basic認証を許可	`true`
`spnego.allow.unsecure.basic`	非セキュアなBasic認証を許可	`false`
`spnego.prompt.ntlm`	NTLMトークン受信時にBasic認証へフォールバックする	`true`
`spnego.allow.localhost`	localhostからのアクセスを許可	`false`
`spnego.allow.delegation`	委任を許可	`false`
`spnego.allowed.realms`	サーバーのレルムに加えて許可する Kerberos レルム（カンマ区切り）	（なし）
`spnego.logger.level`	SPNEGOライブラリ内部のログレベル（`1` =FINEST、 `2` =FINER、 `3` =FINE、 `4` =CONFIG、 `6` =WARNING、 `7` =SEVERE。これら以外の値（ `0` 、 `5` を含む）はINFO扱い）	（自動）

警告

spnego.allow.unsecure.basic=true は、Base64エンコードされた認証情報を暗号化されていない接続で送信する可能性があります。本番環境では false に設定し、HTTPSを使用することを強く推奨します。

注釈

spnego.allow.unsecure.basic=false （デフォルト）の場合、Basic認証は HttpServletRequest#isSecure() が true を返すリクエストにのみ提示されます。 TLSをリバースプロキシで終端して Fess へHTTPで転送している構成ではこの値が false になるため、 Kerberosチケットを取得できずNTLMにフォールバックしたクライアントはログインできません。 tomcat_config.properties で tomcat.secure=true を設定し、リクエストがHTTPS由来であることを Fess に伝えてください。このファイルはZIP版では lib/classes/ 、DEB/RPM版では /etc/fess/ に配置されています。変更後は Fess の再起動が必要です。

注釈

spnego.allow.delegation=true の場合、SPNEGOライブラリはクライアントが委任したKerberosの資格情報を受け取り、認証済みのプリンシパルに関連付けます。ただし現在の Fess はこの資格情報をどこでも利用しておらず、クロール・検索・LDAPの参照はいずれもユーザー名のみを使用します。 SPNEGOのハンドシェイク自体にも影響せず、アクセプター側の資格情報やGSSコンテキストのフラグは変わりません。資格情報を委任するかどうかは、クライアント側（ブラウザーの設定と、Active Directory でそのアカウントが委任に対して信頼されているかどうか）だけで決まります。デフォルトの false のままにしてください。有効にしても、認証済みリクエストごとにJDKが制約付き委任を試みる処理が増えるだけで、利点はありません。

警告

Fess 15.8 では、クライアントのプリンシパルのレルムがサーバーのレルムと異なる場合、そのログインは既定で拒否されます。ADのドメインツリーの子ドメインや、信頼関係を結んだフォレストのユーザーがログインする構成では、 spnego.allowed.realms に該当するレルムをカンマ区切りで列挙してください。列挙しない場合、15.7 まではログインできていたユーザーが Kerberos realm is not allowed として拒否されます。

警告

Fess はプリンシパルの @ より前の部分をユーザー名として扱うため、ユーザー名にレルムは含まれません。 spnego.allowed.realms にレルムを追加すると、複数のレルムに同じアカウント名を持つユーザー（例: alice@CORP.EXAMPLE.COM と alice@PARTNER.EXAMPLE.COM ）は同一の Fess ユーザーとして扱われ、そのユーザーのグループ・ロール・文書の権限を共有します。列挙するすべてのレルムを通じてアカウント名が一意に個人を特定できる場合にのみ追加してください。

注釈

許可リストは Basic 認証のフォールバックにも適用されます。ユーザーが user@REALM の形式で入力した場合、そのレルムが spnego.allowed.realms と照合され、許可されていなければログインは拒否されます。単純なアカウント名や DOMAIN\user の形式はレルムを指定しないため、 krb5.conf の既定レルムで認証されます。Basic 認証はユーザーが入力したレルムに対して直接認証を行うため、許可リストは必要最小限にとどめ、これをセキュリティ境界として利用する場合は spnego.allow.basic を false に設定することを検討してください。

注釈

spnego.prompt.ntlm=true （デフォルト）の場合、 spnego.allow.basic も true である必要があります。 spnego.allow.basic=false に設定する場合は、 spnego.prompt.ntlm=false も併せて設定してください。この条件を満たさない場合、SPNEGOの初期化時にエラーが発生します。

注釈

spnego.logger.level は、SPNEGOライブラリ内部のロガー（ java.util.logging の Spnego という名前のロガー）のログレベルを制御します。未設定の場合は、 Fess のログレベルに応じて自動的に決定されます。

LDAP設定

Windows統合認証でログインしたユーザーのグループ情報を取得するために、LDAP設定が必要です。 Fess 管理画面の「システム」→「全般」でLDAP設定を行います。

項目	設定例
LDAP URL	`ldap://AD-SERVER.example.local:389`
Base DN	`dc=example,dc=local`
Bind DN	`svc_fess@example.local`
パスワード	AD接続用ユーザーのパスワード
User DN	`%s@example.local`
アカウントフィルタ	`(&(objectClass=user)(sAMAccountName=%s))`
memberOf属性	`memberOf`

注釈

Fess はユーザーの memberOf 属性を1段だけ読むため、既定では入れ子になったグループ（グループのメンバーであるグループ）は展開されません。ADの入れ子グループを反映するには、管理画面「システム」→「全般」の「グループフィルター」（ ldap.group.filter ）に (member:1.2.840.113556.1.4.1941:=%s) を設定してください。この展開はログイン後に非同期で実行されるため、監査ログのログイン行には展開前のグループだけが記録されます。

ブラウザ設定

Windows統合認証を使用するには、クライアント側のブラウザ設定が必要です。

Internet Explorer / Microsoft Edge

インターネットオプションを開く
「セキュリティ」タブを選択
「ローカルイントラネット」ゾーンの「サイト」をクリック
「詳細設定」をクリックし、FessのURLを追加
「ローカルイントラネット」ゾーンの「レベルのカスタマイズ」をクリック
「ユーザー認証」→「ログオン」→「イントラネットゾーンでのみ自動的にログオンする」を選択
「詳細設定」タブで「統合Windows認証を使用する」にチェック

Google Chrome

Chromeは通常、Windowsのインターネットオプション設定を使用します。追加設定が必要な場合は、グループポリシーまたはレジストリで AuthServerAllowlist を設定します。

Mozilla Firefox

アドレスバーに about:config と入力
network.negotiate-auth.trusted-uris を検索
FessサーバーのURLまたはドメインを設定（例：https://fess-server.example.local）

設定例

最小構成（検証用）

以下は検証環境での最小構成例です。

app/WEB-INF/conf/system.properties:

app/WEB-INF/classes/krb5.conf:

[libdefaults]
    default_realm = EXAMPLE.LOCAL
    default_tkt_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128
    default_tgs_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128
    permitted_enctypes   = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128

[realms]
    EXAMPLE.LOCAL = {
        kdc = AD-SERVER.EXAMPLE.LOCAL
        default_domain = EXAMPLE.LOCAL
    }

[domain_realm]
    example.local = EXAMPLE.LOCAL
    .example.local = EXAMPLE.LOCAL

app/WEB-INF/classes/auth_login.conf:

推奨構成（本番用）

以下は本番環境での推奨構成例です。

app/WEB-INF/conf/system.properties:

# SSO有効化
sso.type=spnego

# SPNEGO設定
spnego.preauth.username=svc_fess
spnego.preauth.password=your-secure-password
spnego.krb5.conf=krb5.conf
spnego.login.conf=auth_login.conf

# セキュリティ設定（本番環境）
spnego.allow.basic=false
spnego.allow.unsecure.basic=false
spnego.prompt.ntlm=false
spnego.allow.localhost=false

注釈

spnego.allow.basic=false を設定する場合は、 spnego.prompt.ntlm=false も必ず設定してください。 spnego.prompt.ntlm はデフォルトで true のため、この設定を省略すると初期化時にエラーが発生します。

トラブルシューティング

よくある問題と解決方法

認証ダイアログが表示される

ブラウザの設定でFessサーバーがイントラネットゾーンに追加されているか確認
「統合Windows認証を使用する」が有効になっているか確認
SPNが正しく登録されているか確認（ setspn -L <ユーザー名> ）

認証エラーが発生する

krb5.conf のドメイン名（大文字）とADサーバー名が正しいか確認
spnego.preauth.username と spnego.preauth.password が正しいか確認
ADサーバーへのネットワーク接続を確認

グループ情報が取得できない

LDAP設定が正しいか確認
Bind DNとパスワードが正しいか確認
ユーザーがADでグループに所属しているか確認

ログインがHTTP 400になる

所属グループが多いユーザーはKerberosチケット（PAC）が大きくなり、 Authorization ヘッダーが Tomcatの既定の上限（8KB）を超えて400が返されることがあります。このときリクエストは Fess に届かないため、ログには何も記録されません。 tomcat_config.properties で上限を引き上げてください。

サービスアカウントのパスワード変更後に認証できない

サーバーの資格情報は最初のログイン時に一度だけ取得され、以後プロセスが終了するまでキャッシュされます。 AD側でサービスアカウントのパスワードを変更した場合やkeytabを差し替えた場合は、 Fess を再起動してください。 spnego.* の設定を変更した場合も同様に再起動が必要です。

デバッグ設定

問題を調査するために、SPNEGO関連の詳細ログを出力できます。

SPNEGOライブラリ内部の詳細ログを出力するには、 app/WEB-INF/conf/system.properties に以下を追加します。 spnego.logger.level=1 は最も詳細なログ（FINEST）を出力します。

Fess 側のSPNEGO連携処理（org.codelibs.fess.sso.spnego パッケージ）の詳細ログを出力するには、 app/WEB-INF/classes/log4j2.xml に以下のロガーを追加します。

注釈

SPNEGOライブラリ自体のログは java.util.logging で出力されるため、 log4j2.xml ではなく spnego.logger.level で制御します。 Fess 側の連携処理のログは log4j2.xml のロガーで制御します。

参考情報

ロールベース検索の設定 - ロールベース検索の設定
SAML認証によるSSO設定 - SAML認証によるSSO設定
OpenID ConnectによるSSO設定 - OpenID Connect認証によるSSO設定
Microsoft Entra IDによるSSO設定 - Microsoft Entra IDによるSSO設定