github-starred/gitea
2
0
Fork 0
mirror of https://github.com/go-gitea/gitea.git synced 2026-03-12 10:39:38 -05:00
Code Issues 2.6k Packages Projects Releases 100 Wiki Activity

Proposal: Support Single single-on with SPNEGO and SSPI (Kerberos) on Windows #4096

New Issue
Closed
opened 2025-11-02 05:37:41 -06:00 by GiteaMirror · 4 comments
GiteaMirror commented 2025-11-02 05:37:41 -06:00
Owner
Copy Link

Originally created by @quasoft on GitHub (Oct 11, 2019).

Motivation

When using Gitea on premises in a Windows environment (with Active Directory), it would be very convenient to be able to use single sign-on authentication via Kerberos. Currently Gitea supports LDAP authentication to Active Directory (https://docs.gitea.io/en-us/authentication/), but LDAP is not single sign-on.

Short overview of proposal

The proposal is to support Single single-on authentication with Kerberos by implementing the protocol defined by RFC4559 (SPNEGO-based HTTP Authentication in Microsoft Windows) to exchange authentication data between the web browser and HTTP server, and the Security Support Provider Interface (SSPI) to perform the authentication.

Use cases

  1. When installing Gitea:

    • a configuration option named Enable SSPI authentication (Windows only) could be added to the Server and Third-Party Service Settings section:
      Install
      That option could be disabled by default.

  2. When opening the home page:

    • If the user follows any link on the home page (eg. the Register or Sign In buttons) authentication is performed and the user is automatically signed in with the Kerberos credentials he is currently using in the operating system.
      SignIn1

    SignedIn

  3. When SSPI authentication is enabled, but the user needs to temporary use another authentication method (eg. to login as local user with administrative rights):

    • The dashboard for anonymous users contains an additional button for temporary disabling single sing-on (the button Disable Single Sign-On appears only if SSPI authentication has been enabled in configuration):
      HomePage
    • The menu for users that are already signed in with SSO also have an option to temporary disable SSO:
      UserMenu

  4. The user finished his work as local user and wants to use single-sign on again (to login as the user currently signed in the operating system):

    • If SSPI authentication is enabled in configuration, but the user has temporary disabled it using the Disable Single Sign-On button, then both the anonymous dashboard and the user menu will contain a option Enable Single Sign-On, which restores SSPI authentication:
      UserMenuDisabledSSO

Configuration

The [service] section of the app.ini could contain the following additional options:

; Enable SPNEGO authentication via the built-in SSPI module in Windows.
; To use SSPI authentication you need to create suitable service principal name (SPN)
; for the user running gitea (see https://github.com/quasoft/websspi for more details)
ENABLE_SSPI = false

; Allow SSPI auth method to automatically create new users on the go
SSPI_AUTO_CREATE_USERS = true

; Allow SSPI auth method to automatically activate new users
SSPI_AUTO_ACTIVATE_USERS = true

; The character to use to replace the separators of down-level logon names (eg. the \
; in "DOMAIN\user") and user principal names (eg. the @ in "user@example.org")
SSPI_SEPARATOR_REPLACEMENT = _

; Default language for users automatically created by SSPI auth method
SSPI_DEFAULT_LANG = en-us

Those additional configuration values could be displayed in the Service configuration section of /admin/config page:
ServiceConfiguration

Design

Why SSPI and not a cross-platform kerberos library?

SSPI is chosen for verification because in Windows only environments (where both the client and server run Windows) it works without keytab files, which simplifies setup and improves security by not forcing you to store the user password in a keytab file.

How will this new authentication method be integrated into Gitea codebase?

The SignedInUser function of the auth module (https://github.com/go-gitea/gitea/blob/master/modules/auth/auth.go) is already doing authentication at the middleware level for:

SSPI authentication could be added to the same SignedInUser function, but that would increase the compexity of the file.

A better approach could be to introduce something like a plugin pattern for Single single sign-on authentication methods. A separate subpackage modules/auth/sso could be created with a common interface:

// SingleSignOn represents a SSO authentication method (plugin) for HTTP requests.
type SingleSignOn interface {
	// Init should be called exactly once before using any of the other methods,
	// in order to allow the plugin to allocate necessary resources
	Init() error

	// Free should be called exactly once before application closes, in order to
	// give chance to the plugin to free any allocated resources
	Free() error

	// IsEnabled checks if the current SSO method has been enabled in settings.
	IsEnabled() bool

	// VerifyAuthData tries to verify the SSO authentication data contained in the request.
	// If verification is successful returns either an existing user object (with id > 0)
	// or a new user object (with id = 0) populated with the information that was found
	// in the authentication data (username or email).
	// Returns nil if verification fails.
	VerifyAuthData(ctx *macaron.Context) *models.User
}

Specific implementations of that interface could be:

  • basic.go
  • oauth2.go
  • reverseproxy.go
  • sspi_windows.go

Basic, OAuth and Reverse proxy authentication will be moved from the modules/auth/auth.go file to those "plugin" implementations.

A new plugin implementing the interface will be introduced for SSPI authentication.

Authentication plugins would be used at the middleware level - inside the same SignedInUser function:

// Try to sign in with each of the enabled plugins
for _, ssoMethod := range sso.Methods() {
    if !ssoMethod.IsEnabled() {
        continue
    }
    user = ssoMethod.VerifyAuthData(ctx)
    if user != nil {
        handleSignIn(ctx, sess, user)
        _, isBasic := ssoMethod.(*sso.Basic)
        return user, isBasic
    }
}

Does it introduce new dependencies?

Yes, one additional direct dependency will be needed - github.com/quasoft/websspi (shameless plug, I am the author of this module).

Does SSPI require any complex setup in the AD environment?

No, the only configuration that is strictly required is to create a suitable Service Principal Name for the domain account that will be running the gitea.exe process.

That is usually achieved by running the following command with a priviledged user:

setspn -A HTTP/host.domain.local domain\user

There are some gotchas the user might crash into while setting it up, which will be described in the Authentication section of the documentation:

Gitea supports SPNEGO single sign-on authentication (the scheme defined by RFC4559) for the web part of the server via the Security Support Provider Interface (SSPI) built in Windows. SSPI works only in Windows environments - when both the server and the clients are running Windows.

Before activating SSPI single sign-on authentication (SSO) you have to prepare your environment:

  • Create a separate user account in active directory, under which the gitea.exe process will be running (eg. user under domain domain.local):
  • Create a service principal name for the host where gitea.exe is running with class HTTP:
  • Start Command Prompt or PowerShell as a priviledged domain user (eg. Domain Administrator)
  • Run the command below, replacing host.domain.local with the fully qualified domain name (FQDN) of the server where the web application will be running, and domain\user with the name of the account created in the previous step:
  setspn -A HTTP/host.domain.local domain\user
  • Sign in (sign out if you were already signed in) with the user created
  • Enable SSPI authentication by changing the ENABLE_SSPI value in custom/conf/app.ini to true
  • Start the web server (gitea.exe web)
  • Sign in to a client computer in the same domain with any domain user
  • If you are using Chrome, Edge or Internet Explorer, add the URL of the web app to the Local intranet sites (Internet Options -> Security -> Local intranet -> Sites)
  • Start Chrome, Edge or Internet Explorer and navigate to FQDN URL of gitea (eg. http://host.domain.local:3000)
  • Click the Sign In button on the dashboard and you should be automatically logged in with the same user that is currently logged on to the computer
  • If it does not work, make sure that:
    • You are not running the web browser on the same server where gitea is running. You should be running the web browser on a domain joined computer (client) that is different from the server
    • There is only one HTTP/... SPN for the host
    • The SPN contains only the hostname, without the port
    • You have added the URL of the web app to the Local intranet zone
    • The clocks of the server and client should not differ with more than 5 minutes (depends on group policy)
    • Integrated Windows Authentication should be enabled in Internet Explorer (under Advanced settings)
Originally created by @quasoft on GitHub (Oct 11, 2019). ## Motivation When using Gitea on premises in a Windows environment (with Active Directory), it would be very convenient to be able to use single sign-on authentication via Kerberos. Currently Gitea supports LDAP authentication to Active Directory (https://docs.gitea.io/en-us/authentication/), but LDAP is not single sign-on. ## Short overview of proposal The proposal is to support Single single-on authentication with Kerberos by implementing the protocol defined by RFC4559 (SPNEGO-based HTTP Authentication in Microsoft Windows) to exchange authentication data between the web browser and HTTP server, and the Security Support Provider Interface (SSPI) to perform the authentication. ## Use cases 1. When installing Gitea: - a configuration option named `Enable SSPI authentication (Windows only)` could be added to the `Server and Third-Party Service Settings` section: ![Install](https://user-images.githubusercontent.com/7578087/66645625-a146d200-ec2c-11e9-9911-3510fa759c04.png) That option could be disabled by default. 2. When opening the home page: - If the user follows any link on the home page (eg. the `Register` or `Sign In` buttons) authentication is performed and the user is automatically signed in with the Kerberos credentials he is currently using in the operating system. ![SignIn1](https://user-images.githubusercontent.com/7578087/66646074-cbe55a80-ec2d-11e9-97ca-41983c192366.png) --- ![SignedIn](https://user-images.githubusercontent.com/7578087/66646741-b7a25d00-ec2f-11e9-88b2-e5e03c2c8f92.png) 3. When SSPI authentication is enabled, but the user needs to temporary use another authentication method (eg. to login as local user with administrative rights): - The dashboard for anonymous users contains an additional button for temporary disabling single sing-on (the button `Disable Single Sign-On` appears only if SSPI authentication has been enabled in configuration): ![HomePage](https://user-images.githubusercontent.com/7578087/66645923-5ed1c500-ec2d-11e9-811d-82eaede5b6d4.png) - The menu for users that are already signed in with SSO also have an option to temporary disable SSO: ![UserMenu](https://user-images.githubusercontent.com/7578087/66646844-fd5f2580-ec2f-11e9-8f68-0a8a2e846d91.png) 4. The user finished his work as local user and wants to use single-sign on again (to login as the user currently signed in the operating system): - If SSPI authentication is enabled in configuration, but the user has temporary disabled it using the `Disable Single Sign-On` button, then both the anonymous dashboard and the user menu will contain a option `Enable Single Sign-On`, which restores SSPI authentication: ![UserMenuDisabledSSO](https://user-images.githubusercontent.com/7578087/66647166-d6edba00-ec30-11e9-982b-409995565c75.png) ## Configuration The `[service]` section of the `app.ini` could contain the following additional options: ```ini ; Enable SPNEGO authentication via the built-in SSPI module in Windows. ; To use SSPI authentication you need to create suitable service principal name (SPN) ; for the user running gitea (see https://github.com/quasoft/websspi for more details) ENABLE_SSPI = false ; Allow SSPI auth method to automatically create new users on the go SSPI_AUTO_CREATE_USERS = true ; Allow SSPI auth method to automatically activate new users SSPI_AUTO_ACTIVATE_USERS = true ; The character to use to replace the separators of down-level logon names (eg. the \ ; in "DOMAIN\user") and user principal names (eg. the @ in "user@example.org") SSPI_SEPARATOR_REPLACEMENT = _ ; Default language for users automatically created by SSPI auth method SSPI_DEFAULT_LANG = en-us ``` Those additional configuration values could be displayed in the `Service configuration` section of `/admin/config` page: ![ServiceConfiguration](https://user-images.githubusercontent.com/7578087/66650600-abbb9880-ec39-11e9-8efe-0a30f7eac2a4.png) ## Design ### Why SSPI and not a cross-platform kerberos library? SSPI is chosen for verification because in Windows only environments (where both the client and server run Windows) it works without keytab files, which simplifies setup and improves security by not forcing you to store the user password in a keytab file. ### How will this new authentication method be integrated into Gitea codebase? The [SignedInUser](https://github.com/go-gitea/gitea/blob/46a12f196b1742a2462259ed3dd9c33c4c2f150b/modules/auth/auth.go#L120) function of the `auth` module (https://github.com/go-gitea/gitea/blob/master/modules/auth/auth.go) is already doing authentication at the middleware level for: - **Reverse proxy authentication** via the `X-WEBAUTH-USER` header: https://github.com/go-gitea/gitea/blob/46a12f196b1742a2462259ed3dd9c33c4c2f150b/modules/auth/auth.go#L134 - **Basic authentication** with the `Authorization` header: https://github.com/go-gitea/gitea/blob/46a12f196b1742a2462259ed3dd9c33c4c2f150b/modules/auth/auth.go#L172 - **OAuth authentication** with the `Authorization` header or with the `token` and `access_token` query params: https://github.com/go-gitea/gitea/blob/46a12f196b1742a2462259ed3dd9c33c4c2f150b/modules/auth/auth.go#L44 and https://github.com/go-gitea/gitea/blob/46a12f196b1742a2462259ed3dd9c33c4c2f150b/modules/auth/auth.go#L189 SSPI authentication could be added to the same [SignedInUser](https://github.com/go-gitea/gitea/blob/46a12f196b1742a2462259ed3dd9c33c4c2f150b/modules/auth/auth.go#L120) function, but that would increase the compexity of the file. A better approach could be to introduce something like a plugin pattern for Single single sign-on authentication methods. A separate subpackage `modules/auth/sso` could be created with a common interface: ```golang // SingleSignOn represents a SSO authentication method (plugin) for HTTP requests. type SingleSignOn interface { // Init should be called exactly once before using any of the other methods, // in order to allow the plugin to allocate necessary resources Init() error // Free should be called exactly once before application closes, in order to // give chance to the plugin to free any allocated resources Free() error // IsEnabled checks if the current SSO method has been enabled in settings. IsEnabled() bool // VerifyAuthData tries to verify the SSO authentication data contained in the request. // If verification is successful returns either an existing user object (with id > 0) // or a new user object (with id = 0) populated with the information that was found // in the authentication data (username or email). // Returns nil if verification fails. VerifyAuthData(ctx *macaron.Context) *models.User } ``` Specific implementations of that interface could be: - `basic.go` - `oauth2.go` - `reverseproxy.go` - `sspi_windows.go` Basic, OAuth and Reverse proxy authentication will be moved from the `modules/auth/auth.go` file to those "plugin" implementations. A new plugin implementing the interface will be introduced for SSPI authentication. Authentication plugins would be used at the middleware level - inside the same [SignedInUser](https://github.com/go-gitea/gitea/blob/46a12f196b1742a2462259ed3dd9c33c4c2f150b/modules/auth/auth.go#L120) function: ```golang // Try to sign in with each of the enabled plugins for _, ssoMethod := range sso.Methods() { if !ssoMethod.IsEnabled() { continue } user = ssoMethod.VerifyAuthData(ctx) if user != nil { handleSignIn(ctx, sess, user) _, isBasic := ssoMethod.(*sso.Basic) return user, isBasic } } ``` ### Does it introduce new dependencies? Yes, one additional direct dependency will be needed - [github.com/quasoft/websspi](https://github.com/quasoft/websspi) (shameless plug, I am the author of this module). ### Does SSPI require any complex setup in the AD environment? No, the only configuration that is strictly required is to create a suitable Service Principal Name for the domain account that will be running the `gitea.exe` process. That is usually achieved by running the following command with a priviledged user: ```batch setspn -A HTTP/host.domain.local domain\user ``` There are some gotchas the user might crash into while setting it up, which will be described in the `Authentication` section of the documentation: >Gitea supports SPNEGO single sign-on authentication (the scheme defined by RFC4559) for the web part of the server via the Security Support Provider Interface (SSPI) built in Windows. SSPI works only in Windows environments - when both the server and the clients are running Windows. > Before activating SSPI single sign-on authentication (SSO) you have to prepare your environment: > - Create a separate user account in active directory, under which the `gitea.exe` process will be running (eg. `user` under domain `domain.local`): > - Create a service principal name for the host where `gitea.exe` is running with class `HTTP`: > - Start `Command Prompt` or `PowerShell` as a priviledged domain user (eg. Domain Administrator) > - Run the command below, replacing `host.domain.local` with the fully qualified domain name (FQDN) of the server where the web application will be running, and `domain\user` with the name of the account created in the previous step: > ``` > setspn -A HTTP/host.domain.local domain\user > ``` > - Sign in (*sign out if you were already signed in*) with the user created > - Enable SSPI authentication by changing the `ENABLE_SSPI` value in `custom/conf/app.ini` to `true` > - Start the web server (`gitea.exe web`) > - Sign in to a client computer in the same domain with any domain user > - If you are using Chrome, Edge or Internet Explorer, add the URL of the web app to the Local intranet sites (`Internet Options -> Security -> Local intranet -> Sites`) > - Start Chrome, Edge or Internet Explorer and navigate to FQDN URL of gitea (eg. `http://host.domain.local:3000`) > - Click the `Sign In` button on the dashboard and you should be automatically logged in with the same user that is currently logged on to the computer > - If it does not work, make sure that: > - You are not running the web browser on the same server where gitea is running. You should be running the web browser on a domain joined computer (client) that is different from the server > - There is only one `HTTP/...` SPN for the host > - The SPN contains only the hostname, without the port > - You have added the URL of the web app to the `Local intranet zone` > - The clocks of the server and client should not differ with more than 5 minutes (depends on group policy) > - `Integrated Windows Authentication` should be enabled in Internet Explorer (under `Advanced settings`)
GiteaMirror added the type/feature label 2025-11-02 05:37:41 -06:00
GiteaMirror commented 2025-11-02 05:37:43 -06:00
Author
Owner
Copy Link

@quasoft commented on GitHub (Oct 11, 2019):

Sample implementation of the proposed changes is submitted as Pull request https://github.com/go-gitea/gitea/pull/8463

@quasoft commented on GitHub (Oct 11, 2019): Sample implementation of the proposed changes is submitted as Pull request https://github.com/go-gitea/gitea/pull/8463
GiteaMirror commented 2025-11-02 05:37:43 -06:00
Author
Owner
Copy Link

@lafriks commented on GitHub (Oct 11, 2019):

It would be nice if it would also implement getting user details (name, surname, email) using LDAP technical user

@lafriks commented on GitHub (Oct 11, 2019): It would be nice if it would also implement getting user details (name, surname, email) using LDAP technical user
GiteaMirror commented 2025-11-02 05:37:43 -06:00
Author
Owner
Copy Link

@quasoft commented on GitHub (Oct 11, 2019):

That's an interesting idea, probably can make it get additional user attributes or membership to AD groups at a later stage. Have to think on how it will work more.

@quasoft commented on GitHub (Oct 11, 2019): That's an interesting idea, probably can make it get additional user attributes or membership to AD groups at a later stage. Have to think on how it will work more.
GiteaMirror commented 2025-11-02 05:37:43 -06:00
Author
Owner
Copy Link

@guillep2k commented on GitHub (Oct 11, 2019):

First of all, kudos for the delightfully detailed documentation!! 🎉

I'm adding my comments to the PR directly so the discussion doesn't split in two threads.

@guillep2k commented on GitHub (Oct 11, 2019): First of all, kudos for the delightfully detailed documentation!! 🎉 I'm adding my comments to the PR directly so the discussion doesn't split in two threads.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
$20
$250
$50
$500
backport/done
💎 Bounty
docs-update-needed
good first issue
hacktoberfest
issue/bounty
issue/confirmed
issue/critical
issue/duplicate
issue/needs-feedback
issue/not-a-bug
issue/regression
issue/stale
issue/workaround
lgtm/need 2
modifies/api
modifies/translation
outdated/backport/v1.18
outdated/theme/markdown
outdated/theme/timetracker
performance/bigrepo
performance/cpu
performance/memory
performance/speed
pr/breaking
proposal/accepted
proposal/rejected
pr/wip
pull-request
Mirrored from GitHub Pull Request
 reviewed/wontfix
💰 Rewarded
skip-changelog
status/blocked
topic/accessibility
topic/api
topic/authentication
topic/build
topic/code-linting
topic/commit-signing
topic/content-rendering
topic/deployment
topic/distribution
topic/federation
topic/gitea-actions
topic/issues
topic/lfs
topic/mobile
topic/moderation
topic/packages
topic/pr
topic/projects
topic/repo
topic/repo-migration
topic/security
topic/theme
topic/ui
topic/ui-interaction
topic/ux
topic/webhooks
topic/wiki
type/bug
type/deprecation
type/docs
type/enhancement
type/feature
type/miscellaneous
type/proposal
type/question
type/refactoring
type/summary
type/testing
type/upstream
No Label type/feature
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
GiteaMirror ninjasurge
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: github-starred/gitea#4096
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?