From 6e15cb51ddcf24c725633c4ab1ff71959b036eb4 Mon Sep 17 00:00:00 2001 From: James Moger Date: Tue, 24 Apr 2012 22:40:23 -0400 Subject: [PATCH] Documentation --- distrib/gitblit.properties | 52 ++++++----- docs/00_index.mkd | 6 +- docs/01_features.mkd | 3 +- docs/01_setup.mkd | 130 ++++++++++++++------------- docs/04_releases.mkd | 10 +++ src/com/gitblit/LdapUserService.java | 4 +- 6 files changed, 119 insertions(+), 86 deletions(-) diff --git a/distrib/gitblit.properties b/distrib/gitblit.properties index 527b7268..9ccd35d6 100644 --- a/distrib/gitblit.properties +++ b/distrib/gitblit.properties @@ -116,7 +116,11 @@ web.allowCookieAuthentication = true # Either the full path to a user config file (users.conf) # OR the full path to a simple user properties file (users.properties) # OR a fully qualified class name that implements the IUserService interface. -# Any custom implementation must have a public default constructor. +# +# Alternative user services: +# com.gitblit.LdapUserService +# +# Any custom user service implementation must have a public default constructor. # # SINCE 0.5.0 # RESTART REQUIRED @@ -142,9 +146,7 @@ realm.minPasswordLength = 5 realm.ldap.server = ldap://localhost # Login username for LDAP searches. -# The domain prefix may be omitted if it matches the domain specified in -# *realm.ldap.domain*. If this value is unspecified, anonymous LDAP login will -# be used. +# If this value is unspecified, anonymous LDAP login will be used. # # e.g. mydomain\\username # @@ -175,49 +177,59 @@ realm.ldap.backingUserService = users.conf # SINCE 1.0.0 realm.ldap.maintainTeams = false -# Root node that all Users sit under in LDAP +# Root node for all LDAP users # -# This is the root node that searches for user information will begin from in LDAP -# If blank, it will search ALL of ldap. +# This is the root node from which subtree user searches will begin. +# If blank, Gitblit will search ALL nodes. # # SINCE 1.0.0 realm.ldap.accountBase = OU=Users,OU=UserControl,OU=MyOrganization,DC=MyDomain -# Filter Criteria for Users in LDAP +# Filter criteria for LDAP users # # Query pattern to use when searching for a user account. This may be any valid -# LDAP query expression, including the standard (&) and (|) operators. Variables may -# be injected via the ${variableName} syntax. Recognized variables are: +# LDAP query expression, including the standard (&) and (|) operators. +# +# Variables may be injected via the ${variableName} syntax. +# Recognized variables are: # ${username} - The text entered as the user name # # SINCE 1.0.0 realm.ldap.accountPattern = (&(objectClass=person)(sAMAccountName=${username})) -# Root node that all Teams sit under in LDAP +# Root node for all LDAP groups to be used as Gitblit Teams # -# This is the node that searches for team information will begin from in LDAP -# If blank, it will search ALL of ldap. +# This is the root node from which subtree team searches will begin. +# If blank, Gitblit will search ALL nodes. # # SINCE 1.0.0 realm.ldap.groupBase = OU=Groups,OU=UserControl,OU=MyOrganization,DC=MyDomain -# Filter Criteria for Teams in LDAP +# Filter criteria for LDAP groups # # Query pattern to use when searching for a team. This may be any valid -# LDAP query expression, including the standard (&) and (|) operators. Variables may -# be injected via the ${variableName} syntax. Recognized variables are: +# LDAP query expression, including the standard (&) and (|) operators. +# +# Variables may be injected via the ${variableName} syntax. +# Recognized variables are: # ${username} - The text entered as the user name # ${dn} - The Distinguished Name of the user logged in -# All attributes on the User's record are also passed in. For example, if a user has an -# attribute "fullName" set to "John", "(fn=${fullName})" will be translated to "(fn=John)". +# +# All attributes from the LDAP User record are available. For example, if a user +# has an attribute "fullName" set to "John", "(fn=${fullName})" will be +# translated to "(fn=John)". # # SINCE 1.0.0 realm.ldap.groupMemberPattern = (&(objectClass=group)(member=${dn})) -# Users and or teams that are Admins, read from LDAP +# LDAP users or groups that should be given administrator privileges. +# +# Teams are specified with a leading '@' character. Groups with spaces in the +# name can be entered as "@team name". # -# This is a space delimited list. If it starts with @, it indicates a Team Name +# e.g. realm.ldap.admins = john @git_admins "@git admins" # +# SPACE-DELIMITED # SINCE 1.0.0 realm.ldap.admins= @Git_Admins diff --git a/docs/00_index.mkd b/docs/00_index.mkd index 7b565bda..2d137953 100644 --- a/docs/00_index.mkd +++ b/docs/00_index.mkd @@ -66,7 +66,9 @@ Administrators can create and manage all repositories, user accounts, and teams ### Integration with Your Infrastructure - Groovy push hook scripts -- Pluggable user service mechanism for custom authentication, authorization, and user management +- Pluggable user service mechanism + - LDAP authentication with optional LDAP-controlled Team memberships + - Custom authentication, authorization, and user management - Rich RSS feeds - JSON-based RPC mechanism - [Java Client RSS/JSON API library](http://code.google.com/p/gitblit/downloads/detail?name=%API%) for custom integration @@ -81,4 +83,4 @@ Gitblit requires a Java 6 Runtime Environment (JRE) or a Java 6 Development Kit [jgit]: http://eclipse.org/jgit "Eclipse JGit Site" [git]: http://git-scm.com "Official Git Site" -[rhcloud]: https://openshift.redhat.com/app "RedHat OpenShift" \ No newline at end of file +[rhcloud]: https://openshift.redhat.com/app "RedHat OpenShift" diff --git a/docs/01_features.mkd b/docs/01_features.mkd index 8adf4cf3..667a09c9 100644 --- a/docs/01_features.mkd +++ b/docs/01_features.mkd @@ -19,6 +19,7 @@ - Administrators may create, edit, rename, or delete teams through the web UI or RPC interface - Repository Owners may edit repositories through the web UI - Administrators and Repository Owners may set the default branch through the web UI or RPC interface +- LDAP authentication and optional LDAP-controlled Team memberships - Gravatar integration - Git-notes display support - gh-pages display support (Jekyll is not supported) @@ -56,4 +57,4 @@ ### Caveats - Gitblit may have security holes. Patches welcome. :) -[jgit]: http://eclipse.org/jgit "Eclipse JGit Site" \ No newline at end of file +[jgit]: http://eclipse.org/jgit "Eclipse JGit Site" diff --git a/docs/01_setup.mkd b/docs/01_setup.mkd index c2e2ef11..68c10255 100644 --- a/docs/01_setup.mkd +++ b/docs/01_setup.mkd @@ -285,9 +285,75 @@ User passwords are CASE-SENSITIVE and may be *plain*, *md5*, or *combined-md5* f #### User Roles There are two actual *roles* in Gitblit: *#admin*, which grants administrative powers to that user, and *#notfederated*, which prevents an account from being pulled by another Gitblit instance. Administrators automatically have access to all repositories. All other *roles* are repository names. If a repository is access-restricted, the user must have the repository's name within his/her roles to bypass the access restriction. This is how users are granted access to a restricted repository. -## Authentication and Authorization Customization +## Alternative Authentication and Authorization -### Customize Authentication Only +### 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). + +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. + +#### Example LDAP Layout +![block diagram](ldapSample.png "LDAP Sample") + +Please see [ldapUserServiceSampleData.ldif](https://github.com/gitblit/gitblit/blob/master/tests/com/gitblit/tests/resources/ldapUserServiceSampleData.ldif) to see the data in LDAP that reflects the above picture. + +#### Gitblit Settings for Example LDAP Layout +The following are the settings required to configure Gitblit to authenticate against the example LDAP server with LDAP-controlled team memberships. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
parametervaluedescription
realm.ldap.serverldap://localhost:389Tells Gitblit to connect to the LDAP server on localhost port 389. The URL Must be of form ldap(s)://<server>:<port> with port being optional (389 for ldap, 636 for ldaps).
realm.ldap.usernamecn=Directory ManagerThe credentials that will log into the LDAP server
realm.ldap.passwordpasswordThe credentials that will log into the LDAP server
realm.ldap.backingUserServiceusers.confWhere to store all information that is used by Gitblit. All information will be synced here upon user login.
realm.ldap.maintainTeamstrueAre team memberships maintained in LDAP (true) or manually in Gitblit (false).
realm.ldap.accountBaseOU=Users,OU=UserControl,OU=MyOrganization,DC=MyDomainWhat is the root node for all users in this LDAP system. Subtree searches will start from this node.
realm.ldap.accountPattern(&(objectClass=person)(sAMAccountName=${username}))The LDAP search filter that will match a particular user in LDAP. ${username} will be replaced with whatever the user enters as their username in the Gitblit login panel.
realm.ldap.groupBaseOU=Groups,OU=UserControl,OU=MyOrganization,DC=MyDomainWhat is the root node for all teams in this LDAP system. Subtree searches will start from this node.
realm.ldap.groupMemberPattern(&(objectClass=group)(member=${dn}))The LDAP search filter that will match all teams for the authenticating user. ${username} will be replaced with whatever the user enters as their username in the Gitblit login panel. Anything else in ${} will be replaced by Attributes from the User node.
realm.ldap.admins@Git_AdminsA space-delimited list of usernames and/or teams that indicate admin status in Gitblit. Teams are referenced with a leading @ character.
+ +#### LDAP In-Memory Server + +You can start Gitblit GO with an in-memory LDAP server by specifying the *--ldapLdifFile* command-line argument. The LDAP server will listen on localhost of the port specified in *realm.ldap.url* of `gitblit.properties`. Additionally, a root user record is automatically created for *realm.ldap.username* and *realm.ldap.password*. Please note that the ldaps:// protocol is not supported for the in-memory server. + +### Custom Authentication 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/com/gitblit/GitblitUserService.java) and override the *setup()* and *authenticate()* methods. @@ -297,7 +363,7 @@ You may use your subclass by specifying its fully qualified classname in the *re Your subclass must be on Gitblit's classpath and must have a public default constructor. -### Customize Everything +### Custom Everything Instead of maintaining a `users.conf` or `users.properties` file, you may want to integrate Gitblit into an existing environment. You may use your own custom *com.gitblit.IUserService* implementation by specifying its fully qualified classname in the *realm.userService* setting. @@ -449,61 +515,3 @@ Nothing special to configure, EGit figures out everything. My testing indicates that your username must be embedded in the url. YMMV. 
https://username@yourserver/git/your/repository
-## LDAP Support -*SINCE 1.0.0* - -LDAP can be used with Gitblit to read Users and the Teams that they belong to. If configured, LDAP will be queried upon every login to the system, and synchronize that information with the traditional Gitblit backed file (.conf or .properties). This "lazy" reading approach provides for fast reaction times, but will force a user to log in before you can maintain them (or their teams). - -### Example Diagram (with attributes) -![block diagram](ldapSample.png "LDAP Sample") - -Please see /tests/com/gitblit/tests/resources/ldapUserServiceSampleData.ldif to see the data in LDAP that reflects the above picture. - -### GitBlit Properties (See gitblit.properties for full description) -The following is are descriptions of the properties that would follow the sample layout of an LDAP (or Active Directory) setup above. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
realm.ldap.serverldap://localhost:389Tells Gitblit to connect to the LDAP server on localhost, port 389. URL Must be of form ldap(s)://: with port being optional (389 for ldap, 636 for ldaps).
realm.ldap.usernamecn=Directory ManagerThe credentials that will log into this gitblit server
realm.ldap.passwordpasswordThe credentials that will log into this gitblit server
realm.ldap.backingUserServiceusers.confWhere to store all information that is used by Gitblit. All information will be synced here upon user login.
realm.ldap.maintainTeamstrueAre users maintained in LDAP (true), or manually in Gitblit (false).
realm.ldap.accountBaseOU=Users,OU=UserControl,OU=MyOrganization,DC=MyDomainWhat is the root node for all users in this LDAP system. Searches will be subtree searches starting from this node.
realm.ldap.accountPattern(&(objectClass=person)(sAMAccountName=${username}))The LDAP Search filter that will match a particular user in LDAP. ${username} will be replaced with whatever the user types in as their user name.
realm.ldap.groupBaseOU=Groups,OU=UserControl,OU=MyOrganization,DC=MyDomainWhat is the root node for all teams in this LDAP system. Searches will be subtree searches starting from this node.
realm.ldap.groupMemberPattern(&(objectClass=group)(member=${dn}))The LDAP Search filter that will match all teams for the logging in user in LDAP. ${username} will be replaced with whatever the user types in as their user name. Anything else in ${} will be replaced by Attributes on the User node.
realm.ldap.admins@Git_AdminsA space delimited list of users and teams (if starting with @) that indicate admin status in Gitblit.
- -You may notice that there are no properties to find the password on the User record. This is intentional, and the service utilizes the LDAP login process to verify that the user credentials are correct. - -You can also start Gitblit GO with an in-memory (backed by an LDIF file) LDAP server by using the --ldapLdifFile property. It will listen where ever gitblit.settings is pointed to. However, it only supports ldap...not ldaps, so be sure to set that in gitblit.settings. It reads the user / password in gitblit.settings to create the root user login. - -Finally, writing back to LDAP is not implemented at this time, so do not worry about corrupting your corporate LDAP. Many orgnizations are likely to go through a different flow to update their LDAP, so it's unlikely that this will become a feature. \ No newline at end of file diff --git a/docs/04_releases.mkd b/docs/04_releases.mkd index 32486ab7..cf65ea04 100644 --- a/docs/04_releases.mkd +++ b/docs/04_releases.mkd @@ -4,6 +4,16 @@ **%VERSION%** ([go](http://code.google.com/p/gitblit/downloads/detail?name=%GO%) | [war](http://code.google.com/p/gitblit/downloads/detail?name=%WAR%) | [express](http://code.google.com/p/gitblit/downloads/detail?name=%EXPRESS%) | [fedclient](http://code.google.com/p/gitblit/downloads/detail?name=%FEDCLIENT%) | [manager](http://code.google.com/p/gitblit/downloads/detail?name=%MANAGER%) | [api](http://code.google.com/p/gitblit/downloads/detail?name=%API%)) based on [%JGIT%][jgit]   *released %BUILDDATE%* +#### changes + +- IUserService interface has changed to better accomodate custom authentication and/or custom authorization + +#### additions + +- Added LDAP User Service with many new *realm.ldap* keys (Github/jcrygier) + +**0.9.3** *released 2012-04-11* + #### fixes - Fixed bug where you could not remove all selections from a RepositoryModel list (permitted users, permitted teams, hook scripts, federation sets, etc) (issue 81) diff --git a/src/com/gitblit/LdapUserService.java b/src/com/gitblit/LdapUserService.java index 4634668b..ec84c956 100644 --- a/src/com/gitblit/LdapUserService.java +++ b/src/com/gitblit/LdapUserService.java @@ -219,14 +219,14 @@ public class LdapUserService extends GitblitUserService { private TeamModel createTeamFromLdap(SearchResultEntry teamEntry) { TeamModel answer = new TeamModel(teamEntry.getAttributeValue("cn")); - // If attributes other than team name ever from from LDAP, this is where to get them + // potentially retrieve other attributes here in the future return answer; } private UserModel createUserFromLdap(String simpleUserName, SearchResultEntry userEntry) { UserModel answer = new UserModel(simpleUserName); - //If attributes other than user name ever from from LDAP, this is where to get them + // potentially retrieve other attributes here in the future return answer; } -- 2.39.5