Skip to content

Kerberos SSO setup

This guide explains how to configure Kerberos SSO for Easy.

Easy does not authenticate Kerberos directly. Apache, Nginx, or another reverse proxy must handle Kerberos or SPNEGO first. Easy then reads authenticated user from request.env.

Key fact

  • SSO login env variable in Easy means key in request.env
  • Not necessarily raw HTTP header name
  • Common value: REMOTE_USER
  • Typical content: user@REALM
  • Easy strips realm, uses user as local login

If proxy sends custom header, map header to key visible in request.env before request reaches Rails.

Required routes

  • /sso_autologin Main Kerberos SSO entry point. Must be protected by Kerberos-capable proxy configuration.
  • /sso_variables Debug page. Shows configured env key, current value, parsed login, matched user.
  • /sso_login Separate SSO login form (EasySsoLoginController). Not part of Kerberos autologin flow.

Requirements

  • Working Kerberos or SPNEGO on Apache, Nginx, or another reverse proxy
  • Authenticated username exposed to Rails in request.env
  • Easy local users pre-created, or LDAP auto-provisioning configured

User provisioning

Two supported models:

  • Pre-create users in Easy
  • Easy login must match Kerberos username without realm
  • Create users from LDAP
  • Configure LDAP Auth Source
  • Enable on-the-fly registration

Important:

  • If Kerberos succeeds but user does not exist in Easy, login fails unless LDAP on-the-fly registration is enabled.

Configuration steps

1. Configure Kerberos on proxy

Configure Apache, Nginx, or another reverse proxy to:

  • authenticate user with Kerberos or SPNEGO
  • protect /sso_autologin
  • pass authenticated username to upstream app in request.env
  • use stable env key, ideally REMOTE_USER

Recommended:

  • expose same identity on /sso_variables for troubleshooting

Not required:

  • protecting whole application with Kerberos

Critical route:

  • /sso_autologin

2. Configure SSO in Easy

Navigation:

  • Administration -> Settings -> Authentication

Set:

  • Enable SSO = enabled
  • SSO login env variable = exact key available in request.env

Example:

  • Proxy exposes user as REMOTE_USER
  • Set SSO login env variable to REMOTE_USER

3. Configure LDAP if users are not pre-created

Navigation:

  • Administration -> LDAP authentication

If Easy should create missing users automatically:

  • create or edit LDAP Auth Source
  • enable on-the-fly registration

Use LDAP provisioning when:

  • Kerberos identity reaches Easy correctly
  • local Easy user does not exist yet

Test procedure

1. Check debug route

Open:

  • /sso_variables

Verify:

  • SSO enabled? = true
  • ENV variable = expected key
  • Current value = Kerberos identity, usually user@REALM
  • Current login = username without realm
  • Current user in DB = matched existing user or LDAP-resolved user (display only; save happens via /sso_autologin)

2. Check login flow

  • log out from Easy
  • open page that requires authentication
  • confirm redirect to /sso_autologin
  • confirm Kerberos authentication happens on proxy
  • confirm Easy logs user in
  • confirm redirect back to original page

Troubleshooting

Symptom

  • Easy shows Cannot login through single sign on.

Check list

  • Enable SSO enabled
  • SSO login env variable exactly matches key in request.env
  • Kerberos works on /sso_autologin
  • proxy forwards authenticated username to Rails
  • username format is expected, usually user@REALM
  • Easy local login matches parsed username without realm
  • if user missing, LDAP Auth Source exists and on-the-fly registration is enabled

Common causes

  • wrong env key configured in Easy
  • proxy sends header but value never reaches request.env
  • REMOTE_USER or chosen env key empty on /sso_autologin
  • Easy user missing
  • LDAP auto-provisioning not configured

Expected flow

  1. User opens protected Easy page.
  2. Easy redirects anonymous user to /sso_autologin.
  3. Proxy authenticates user with Kerberos or SPNEGO.
  4. Proxy exposes identity in request.env.
  5. Easy reads configured env key.
  6. Easy strips realm from user@REALM.
  7. Easy logs existing user in (respects 2FA if enabled), or creates user through LDAP on-the-fly registration.
  8. Easy redirects user back to original page.

Technical section

Key source locations:

  • easy_engines/easy_extensions/config/routes.rb Defines SSO routes:
  • GET /sso_autologin -> AccountController#sso_autologin
  • GET /sso_variables -> AccountController#sso_variables

  • GET|POST /sso_login -> EasySsoLoginController#sso_login

  • app/controllers/account_controller.rb Kerberos SSO entry points:

  • AccountController#sso_autologin (app/controllers/account_controller.rb:261)
  • AccountController#sso_variables (app/controllers/account_controller.rb:284)
  • AccountController#handle_active_user (app/controllers/account_controller.rb:448)

  • AccountController#handle_active_twofa (app/controllers/account_controller.rb:457)

  • app/utils/easy_extensions/sso.rb Core SSO helper. Reads configured env key from request.env, strips realm (user@REALM -> user), finds local user, or creates unsaved user from LDAP attrs.

  • app/models/auth_source_ldap.rb LDAP lookup for on-the-fly provisioning:

  • AuthSourceLdap#authenticate_without_password (app/models/auth_source_ldap.rb:151)

  • easy_engines/easy_extensions/easy_patch/redmine/controllers/application_controller_patch.rb Redirects anonymous users to /sso_autologin when SSO is enabled:

  • ApplicationController#require_login_with_easy_extensions (easy_engines/easy_extensions/easy_patch/redmine/controllers/application_controller_patch.rb:854)

  • easy_engines/easy_extensions/app/views/account/sso_variables.html.erb Debug page: renders configured env key, current value, parsed login, matched/LDAP-resolved user, plus additional request env variables.

  • app/controllers/easy_sso_login_controller.rb Separate SSO login form flow (/sso_login); not Kerberos autologin.