SSO Configuration with OpenID Connect

Overview

Fess supports Single Sign-On (SSO) authentication using OpenID Connect (OIDC). OpenID Connect is an authentication protocol built on top of OAuth 2.0 that uses ID Tokens (JWT) for user authentication. By using OpenID Connect authentication, user information authenticated by an OpenID Provider (OP) can be integrated with Fess.

How OpenID Connect Authentication Works

In OpenID Connect authentication, Fess operates as a Relying Party (RP) and collaborates with an external OpenID Provider (OP) for authentication.

User accesses the Fess SSO endpoint (/sso/)
Fess redirects to the OP’s authorization endpoint
User authenticates at the OP
OP redirects the authorization code to Fess
Fess uses the authorization code to obtain an ID Token from the token endpoint
Fess decodes the ID Token (JWT) to extract user information and logs in the user

Note

Fess uses the Authorization Code Flow. The ID Token is obtained directly from the token endpoint via a back-channel (server-to-server communication) between Fess and the OP, without passing through the browser. Fess decodes the ID Token and extracts claims (such as email and groups) to construct user information, but does NOT cryptographically verify the JWT signature. For this reason, ensure that all communication with the token endpoint uses HTTPS and that the communication path between Fess and the OP is trusted.

For integration with role-based search, see Role-Based Search Configuration.

Prerequisites

Before configuring OpenID Connect authentication, verify the following prerequisites:

Fess 15.7 or later is installed
An OpenID Connect-compatible provider (OP) is available
Fess is accessible via HTTPS (required for production environments)
You have permission to register Fess as a client (RP) on the OP side

Examples of supported providers:

Microsoft Entra ID (Azure AD)
Google Workspace / Google Cloud Identity
Okta
Keycloak
Auth0
Other OpenID Connect-compatible providers

Basic Configuration

Enabling SSO

To enable OpenID Connect authentication, add the following setting to app/WEB-INF/conf/system.properties:

Note

The sso.type setting and all oic.* settings described below can also be configured and changed from the admin “System > General” page. Settings changed through the admin page are saved to system.properties and persist after restart.

Provider Configuration

Configure the information obtained from your OP.

Property	Description	Default
`oic.auth.server.url`	Authorization endpoint URL	`https://accounts.google.com/o/oauth2/auth`
`oic.token.server.url`	Token endpoint URL	`https://accounts.google.com/o/oauth2/token`

Note

These URLs can be obtained from the OP’s Discovery endpoint (/.well-known/openid-configuration).

Client Configuration

Configure the client information registered with the OP.

Property	Description	Default
`oic.client.id`	Client ID	(empty)
`oic.client.secret`	Client secret	(empty)
`oic.scope`	Requested scopes	(empty)

Note

The scope must include at least openid. To retrieve the user’s email address, specify openid email.

Redirect URL Configuration

Configure the callback URL after authentication.

Property	Description	Default
`oic.redirect.url`	Redirect URL (callback URL)	`{oic.base.url}/sso/`
`oic.base.url`	Fess base URL	`http://localhost:8080`

Note

If oic.redirect.url is omitted, it is automatically constructed from oic.base.url. For production environments, set oic.base.url to an HTTPS URL.

User Attribute Configuration

Configure the default groups and roles to assign to users authenticated via OIDC. The user ID, groups, and roles are determined as follows:

User ID: Obtained from the email claim of the ID Token (JWT). For this reason, the email scope is effectively required (if the email claim cannot be obtained, login will not work correctly).
Groups: Obtained from the groups claim of the ID Token. If the groups claim is not present, the value of oic.default.groups is used.
Roles: Always taken from the value of oic.default.roles (there is no mechanism to obtain roles from ID Token claims).

Property	Description	Default
`oic.default.groups`	Default groups (comma-separated)	(empty)
`oic.default.roles`	Default roles (comma-separated)	(empty)

Note

When using role-based search, you must assign appropriate groups or roles to users. See Role-Based Search Configuration for details.

OP-Side Configuration

When registering Fess as a client (RP) on the OP side, configure the following information:

Setting	Value
Application type	Web application
Redirect URI / Callback URL	`https://<Fess host>/sso/`
Allowed scopes	`openid` and required scopes (`email`, `profile`, etc.)

Information to Obtain from OP

Obtain the following information from the OP’s configuration screen or Discovery endpoint for use in Fess configuration:

Authorization Endpoint: URL to initiate user authentication
Token Endpoint: URL to obtain tokens
Client ID: Client identifier issued by the OP
Client Secret: Secret key used for client authentication

Note

Most OPs allow you to check the authorization and token endpoint URLs from the Discovery endpoint (https://<OP>/.well-known/openid-configuration).

Configuration Examples

Minimal Configuration (for Testing)

The following is a minimal configuration example for verification in a test environment.

# Enable SSO
sso.type=oic

# Provider configuration (set values obtained from OP)
oic.auth.server.url=https://op.example.com/authorize
oic.token.server.url=https://op.example.com/token

# Client configuration
oic.client.id=your-client-id
oic.client.secret=your-client-secret
oic.scope=openid email

# Redirect URL (test environment)
oic.redirect.url=http://localhost:8080/sso/

Recommended Configuration (for Production)

The following is a recommended configuration example for production environments.

# Enable SSO
sso.type=oic

# Provider configuration
oic.auth.server.url=https://op.example.com/authorize
oic.token.server.url=https://op.example.com/token

# Client configuration
oic.client.id=your-client-id
oic.client.secret=your-client-secret
oic.scope=openid email profile

# Base URL (use HTTPS for production)
oic.base.url=https://fess.example.com

Troubleshooting

Common Problems and Solutions

Cannot Return to Fess After Authentication

Verify that the redirect URI is correctly configured on the OP side
Ensure that the oic.redirect.url or oic.base.url value matches the OP configuration
Verify that the protocol (HTTP/HTTPS) matches

Authentication Errors Occur

Verify that the client ID and client secret are correctly configured
Ensure that the scope includes openid
Verify that the authorization endpoint URL and token endpoint URL are correct

Cannot Retrieve User Information

Ensure that the scope includes the required permissions (email, profile, etc.)
Verify that the required scopes are allowed for the client on the OP side

Debug Configuration

To investigate problems, you can output detailed OpenID Connect-related logs by adjusting the Fess log level.

In app/WEB-INF/classes/log4j2.xml, add the following logger to change the log level:

Reference

Role-Based Search Configuration - Role-based search configuration
SAML Authentication SSO Setup - SSO configuration with SAML authentication
SSO Configuration with Entra ID - SSO configuration for Microsoft Entra ID (if you are using Entra ID, you may use this dedicated configuration instead of the generic OpenID Connect settings)