From a502d96a860456ec5e8c96761db70f7cabb74751 Mon Sep 17 00:00:00 2001
From: Paul Martin <paul@paulsputer.com>
Date: Sat, 30 Apr 2016 04:19:14 -0400
Subject: [PATCH] Merge pull request #1073 from gitblit/1062-DocEditorUpdates

---
 src/site/setup_authentication.mkd |   24 +++++++++++++++++++++---
 1 files changed, 21 insertions(+), 3 deletions(-)

diff --git a/src/site/setup_authentication.mkd b/src/site/setup_authentication.mkd
index 02d1be7..7113667 100644
--- a/src/site/setup_authentication.mkd
+++ b/src/site/setup_authentication.mkd
@@ -8,6 +8,7 @@
 * Windows authentication
 * PAM authentication
 * Htpasswd authentication
+* HTTP header authentication
 * Redmine auhentication
 * Salesforce.com authentication
 * Servlet container authentication
@@ -83,10 +84,16 @@
 
 ### PAM Authentication
 
-PAM authentication is based on the use of libpam4j and JNA.  To use this service, your Gitblit server must be installed on a Linux/Unix/MacOSX machine and the user that Gitblit runs-as must have root permissions.
+PAM authentication is based on the use of libpam4j and JNA.  To use this service, your Gitblit server must be installed on a Linux/Unix/MacOSX machine.
 
     realm.authenticationProviders = pam
-    realm.pam.serviceName = system-auth
+    realm.pam.serviceName = gitblit
+    
+Then define a gitblit authentication policy in `/etc/pam.d/gitblit`
+
+    # PAM configuration for the gitblit service
+    # Standard Un*x authentication.
+    @include common-auth
 
 ### Htpasswd Authentication
 
@@ -94,6 +101,17 @@
 
     realm.authenticationProviders = htpasswd
     realm.htpasswd.userFile = /path/to/htpasswd
+
+### HTTP Header Authentication
+
+HTTP header authentication allows you to use existing authentication performed by a trusted frontend, such as a reverse proxy. Ensure that when used, gitblit is ONLY availabe via the trusted frontend, otherwise it is vulnerable to a user adding the header explicitly.
+
+By default, no user or team header is defined, which results in all authentication failing this mechanism. The user header can also be defined while leaving the team header undefined, which causes users to be authenticated from the headers, but team memberships to be maintained locally.
+
+    realm.httpheader.userheader = REMOTE_USER
+    realm.httpheader.teamheader = X-GitblitExample-GroupNames
+    realm.httpheader.teamseparator = ,
+    realm.httpheader.autoCreateAccounts = false
 
 ### Redmine Authentication
 
@@ -119,7 +137,7 @@
 
 This is the simplest choice where you implement custom authentication and delegate all other standard user and team operations to one of Gitblit's user service implementations.  This choice insulates your customization from changes in User and Team model classes and additional API that may be added to IUserService.
 
-Please subclass [com.gitblit.auth.AuthenticationProvider](https://github.com/gitblit/gitblit/blob/master/src/main/java/com/gitblit/auth/AuthenticationProvider.java).
+Please subclass [com.gitblit.auth.AuthenticationProvider.UsernamePasswordAuthenticationProvider](https://github.com/gitblit/gitblit/blob/master/src/main/java/com/gitblit/auth/AuthenticationProvider.java).
 
 You may use your subclass by specifying its fully qualified classname in the *realm.authenticationProviders* setting.
 

--
Gitblit v1.9.1