Windows統合認証によるSSO設定

概要

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

Windows統合認証の仕組み

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

1. ユーザーがWindowsドメインにログイン

2. ユーザーが Fess にアクセス

3. Fess がSPNEGOチャレンジを送信

4. ブラウザがKerberosチケットを取得してサーバーに送信

5. Fess がチケットを検証し、ユーザー名を取得

6. LDAPを使用してユーザーのグループ情報を取得

7. ユーザーがログイン状態になり、グループ情報がロールベース検索に適用される

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

前提条件

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

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

• Active Directory（AD）サーバーが利用可能

• Fess サーバーがADドメインからアクセス可能

• ADでサービスプリンシパル名（SPN）を設定する権限がある

• LDAPでユーザー情報を取得するためのアカウントがある

Active Directory側の設定

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

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

setspn -S HTTP/<Fessサーバーのホスト名> <ADアクセス用ユーザー>

例：

setspn -S HTTP/fess-server.example.local svc_fess

登録を確認するには：

setspn -L <ADアクセス用ユーザー>

注釈

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

基本設定

SSOの有効化

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

sso.type=spnego

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ログイン設定を記述します。

spnego-client {
    com.sun.security.auth.module.Krb5LoginModule required;
};

spnego-server {
    com.sun.security.auth.module.Krb5LoginModule required
    storeKey=true
    isInitiator=false;
};

注釈

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 の再起動が必要です。

警告

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

1. インターネットオプションを開く

2. 「セキュリティ」タブを選択

3. 「ローカル イントラネット」ゾーンの「サイト」をクリック

4. 「詳細設定」をクリックし、FessのURLを追加

5. 「ローカル イントラネット」ゾーンの「レベルのカスタマイズ」をクリック

6. 「ユーザー認証」→「ログオン」→「イントラネット ゾーンでのみ自動的にログオンする」を選択

7. 「詳細設定」タブで「統合Windows認証を使用する」にチェック

Google Chrome

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

Mozilla Firefox

1. アドレスバーに about:config と入力

2. network.negotiate-auth.trusted-uris を検索

3. FessサーバーのURLまたはドメインを設定（例：https://fess-server.example.local）

設定例

最小構成（検証用）

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

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

# SSO有効化
sso.type=spnego

# SPNEGO設定
spnego.preauth.username=svc_fess
spnego.preauth.password=your-password

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:

spnego-client {
    com.sun.security.auth.module.Krb5LoginModule required;
};

spnego-server {
    com.sun.security.auth.module.Krb5LoginModule required
    storeKey=true
    isInitiator=false;
};

推奨構成（本番用）

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

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 で上限を引き上げてください。

tomcat.maxHttpHeaderSize=65536

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

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

デバッグ設定

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

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

spnego.logger.level=1

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

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

注釈

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設定