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 | 53 +++++++++++++++++++++++++++++++++++++++++------------ 1 files changed, 41 insertions(+), 12 deletions(-) diff --git a/src/site/setup_authentication.mkd b/src/site/setup_authentication.mkd index 7f60618..7113667 100644 --- a/src/site/setup_authentication.mkd +++ b/src/site/setup_authentication.mkd @@ -6,6 +6,9 @@ * LDAP authentication * Windows authentication +* PAM authentication +* Htpasswd authentication +* HTTP header authentication * Redmine auhentication * Salesforce.com authentication * Servlet container authentication @@ -13,11 +16,11 @@ ### LDAP Authentication *SINCE 1.0.0* -LDAP can be used to authenticate Users and optionally control Team memberships. When properly configured, Gitblit will delegate authentication to your LDAP server and will cache some user information in the usual users file (.conf or .properties). +LDAP can be used to authenticate Users and optionally control Team memberships. When properly configured, Gitblit will delegate authentication to your LDAP server and will cache some user information in the usual users.conf file. When using the LDAP User Service, new user accounts can not be manually created from Gitblit. Gitblit user accounts are automatically created for new users on their first succesful authentication through Gitblit against the LDAP server. It is also important to note that the LDAP User Service does not retrieve or store user passwords nor does it implement any LDAP-write functionality. -To use the *LdapUserService* set *realm.userService=com.gitblit.LdapUserService* in your `gitblit.properties` file or your `web.xml` file and then configure the *realm.ldap* settings appropriately for your LDAP environment. +To use the *LdapUserService* set *realm.authenticationProviders=ldap* in your `gitblit.properties` file and then configure the *realm.ldap* settings appropriately for your LDAP environment. #### Example LDAP Layout ![block diagram](ldapSample.png "LDAP Sample") @@ -43,10 +46,6 @@ <tr> <th>realm.ldap.password</th><td>password</td> <td>The credentials that will log into the LDAP server</td> -</tr> -<tr> - <th>realm.ldap.backingUserService</th><td>users.conf</td> - <td>Where to store all information that is used by Gitblit. All information will be synced here upon user login.</td> </tr> <tr> <th>realm.ldap.maintainTeams</th><td>true</td> @@ -80,21 +79,52 @@ Windows authentication is based on the use of Waffle and JNA. It is known to work properly for authenticating against the local Windows machine, but it is unclear if it works properly with a domain controller and Active Directory. To use this service, your Gitblit server must be installed on a Windows machine. - realm.userService = com.gitblit.WindowsUserService + realm.authenticationProviders = windows realm.windows.defaultDomain = + +### 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. + + realm.authenticationProviders = pam + 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 + +Htpasswd authentication allows you to maintain your user credentials in an Apache htpasswd file thay may be shared with other htpasswd-capable servers. + + 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 You may authenticate your users against a Redmine installation as long as your Redmine install has properly enabled [API authentication](http://www.redmine.org/projects/redmine/wiki/Rest_Api#Authentication). This user service only supports user authentication; it does not support team creation based on Redmine groups. Redmine administrators will also be Gitblit administrators. - realm.userService = com.gitblit.RedmineUserService + realm.authenticationProviders = redmine realm.redmine.url = http://example.com/redmine ### Salesforce.com Authentication You may authenticate your users against Salesforce.com. You can require that user's belong to a particular organization by specifying a non-zero organization id. - realm.userService = com.gitblit.SalesforceUserService + realm.authenticationProviders = salesforce realm.salesforce.orgId = 0 ### Container Authentication @@ -107,10 +137,9 @@ 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.GitblitUserService](https://github.com/gitblit/gitblit/blob/master/src/main/java/com/gitblit/GitblitUserService.java) and override the *setup()* and *authenticate()* methods. -Make sure to set the *serviceImpl* field in your *setup()* method. +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.userService* setting. +You may use your subclass by specifying its fully qualified classname in the *realm.authenticationProviders* setting. Your subclass must be on Gitblit's classpath and must have a public default constructor. -- Gitblit v1.9.1