SSO setup using Keycloak

This document explains how to configure Keycloak as a Single Sign-On (SSO) provider for Filestash. It covers all required steps to set up and connect both systems in a standard OpenID Connect (OIDC) flow and is devided onto a few sections:

Requirements

Before starting, ensure you have access to a running Keycloak instance. If you don’t already have one, you can start a local Keycloak server using Docker:

~/$ docker run --rm -p 127.0.0.1:8080:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:latest start-dev
Unable to find image 'quay.io/keycloak/keycloak:26.4.0' locally
26.4.0: Pulling from keycloak/keycloak
2c9e750a8c44: Pull complete
af6e7120698b: Pull complete
86037f5d516f: Pull complete
cb687ea46c07: Pull complete
Digest: sha256:5f3fb534cde6bf006d79f5912473e5d2c828c707cdfc52e16972803aca9d43dd
Status: Downloaded newer image for quay.io/keycloak/keycloak:26.4.0
Updating the configuration and installing your custom providers, if any. Please wait.
2025-10-09 02:08:42,723 INFO [io.quarkus.deployment.QuarkusAugmentor] (main) Quarkus augmentation completed in 6778ms
Running the server in development mode. DO NOT use this configuration in production.
2025-10-09 02:08:46,343 INFO [org.hibernate.orm.jdbc.batch] (JPA Startup Thread) HHH100501: Automatic JDBC statement batching enabled (maximum batch size 32)
2025-10-09 02:08:47,159 INFO [org.keycloak.quarkus.runtime.storage.database.liquibase.QuarkusJpaUpdaterProvide
...
...

Once the container starts, open your browser and go to: http://127.0.0.1:8080 and login with admin:admin.

IDP Configuration

Next, configure Keycloak as the Identity Provider (IDP) by creating a new client. From the Keycloak admin console, go to: http://localhost:8080/admin/master/console/#/master/clients/add-client

# General settings
Cient Type: OpenID Connect
Client ID: filestash
[keep as is]

# Capability config
[keep as is]

# Login settings
Valid redirect URIs: http://localhost:8334/api/session/auth/

Filestash Configuration

Open the Filestash admin interface and navigate to: http://localhost:8334/admin/storage and From the Authentication section, select OpenID, then configure it as follows:

OpenID Config URL: http://localhost:8080/realms/master/.well-known/openid-configuration
Client ID: filestash

To ensure the authentication flow redirects correctly, verify your host configuration under: http://localhost:8334/admin/settings If you are running locally, set the Host value to: localhost:8334 and enable / disable Force SSL depending on whether HTTPS is used in your setup.

What next?

For more details on OpenID Connect (OIDC) configuration and advanced options such as user authorisation, see the following resources: