Commit 22a87c9

zwetsunknwon

authored and

committed

Clean up the LDAP and FreeIPA documentation (#239)

* Clean up the LDAP and FreeIPA documentation * Re-add version number when config files were introduced

1 parent 4b5954d commit 22a87c9Copy full SHA for 22a87c9

File tree

1 file changed

+109

-81

lines changed

en-US/features
- authentication.md

1 file changed

+109

-81

lines changed

`‎en-US/features/authentication.md‎`

Lines changed: 109 additions & 81 deletions

Original file line number	Diff line number	Diff line change
`@@ -4,43 +4,67 @@ name: Authentication`
`4`	`4`
`5`	`5`	`# Authentication`
`6`	`6`
`7`		`-## Load authentication source from file`
	`7`	+Gogs supports authentication by various external sources. Currently supported are: LDAP, SMTP, PAM, and GitHub. Sources can be configured in Admin Panel - Authentication Sources, or (starting from `0.11.45.0412`) using configuration files in `custom/conf/auth.d`.
`8`	`8`
`9`		-Starting from `0.11.45.0412`, you can define the authentication source in local files to help better automate setup process.
	`9`	`+## Using configuration files`
`10`	`10`
`11`		-Files with the suffix `.conf` under `conf/auth.d` of the custom directory will be recognized as authentication sources. For example, `custom/conf/auth.d/my_auth_source.conf`. As long as the file name ends with `.conf`, you can name it anything memorable. You can find examples of all supported types [here](https://github.com/gogs/gogs/tree/f2ecfdc96a338815ffb2be898b3114031f0da48c/conf/auth.d).
	`11`	+Since version `0.11.45.0412`, files with the suffix `.conf` under `custom/conf/auth.d` will be recognized as authentication sources. An example for each of the supported sources can be found [here](https://github.com/gogs/gogs/tree/master/conf/auth.d).
`12`	`12`
`13`		`-Once files are loaded, they will appear in the Admin Panel - Authentication Sources page as before. They also work nicely with authentication sources defined in the database.`
	`13`	`+Authentication sources defined via configuration files appear in the Admin Panel - Authentication Sources just like sources created via the web interface.`
`14`	`14`
`15`	`15`	`![](/docs/images/auth_sources.png)`
`16`	`16`
`17`		`-However, do not try to edit the file directly. Rather, edit it via the web interface because files are only read once when Gogs starts.`
	`17`	`+Configuration files are read once when Gogs starts. To edit them while Gogs is running, use the web interface.`
`18`	`18`
`19`	`19`	`## Configuration`
`20`	`20`
`21`	`21`	`### LDAP`
`22`	`22`
`23`		`-Both the LDAP via BindDN and the simple auth LDAP share the following fields:`
	`23`	`+There are two variants for LDAP authentication: with or without a separate Bind DN. In both cases authentication is performed by attempting to bind to the LDAP with the User DN and password. The difference is that with the Bind DN, a query is first performed (by the Bind DN) to find the User DN.`
`24`	`24`
`25`		`-- Authorization Name (required)`
`26`		`- - A name to assign to the new method of authorization.`
	`25`	`+The Bind DN mechanism has these advantages:`
	`26`	`+`
	`27`	`+- It may be more secure than blindy attempting to bind with a possibly non-existent User DN`
	`28`	+- It supports login with e.g. email address or phone number. The preliminary search could look up the User DN using their `mail` or `mobile` attribute (but see the FreeIPA section further down: features in Gogs may have obsoleted the need for this)
	`29`	`+- A Bind DN is required when the LDAP does not allow the User DN to query its own attributes or group memberships`
	`30`	`+`
	`31`	`+The downside to the Bind DN mechanism is that, unless the LDAP allows anonymous queries, it requires a bind DN to be defined in the LDAP, and Gogs needs to store its credentials. Gogs currently does not encrypt these.`
	`32`	`+`
	`33`	`+In the ideal situation, the LDAP allows anonymous queries (at least in the "user container") and the Bind DN mechanism can be used without a Bind DN and password. The options available to you depend on how the LDAP in your organisation has been configured.`
	`34`	`+`
	`35`	`+Shared configuration fields between _Bind DN_ and _Simple Auth_ authentication`
	`36`	`+`
	`37`	`+- Authentication Name (required)`
	`38`	`+ - A friendly name to assign to the new authentication source`
	`39`	`+`
	`40`	`+- Security Protocol (required)`
	`41`	`+ - Unencrypted (0), LDAPS (1), StartTLS (2)`
`27`	`42`
`28`	`43`	`- Host (required)`
`29`	`44`	`- The address where the LDAP server can be reached.`
`30`		- - Example: `mydomain.com`
	`45`	+ - Example: `ldap.mydomain.com`
`31`	`46`
`32`	`47`	`- Port (required)`
`33`	`48`	`- The port to use when connecting to the server.`
`34`		- - Example: `636`
	`49`	+ - Usually `389` for the LDAP and StartTLS protocols, `636` for LDAPS protocol.
`35`	`50`
`36`		`-- Enable TLS Encryption (optional)`
`37`		`- - Whether to use TLS when connecting to the LDAP server.`
	`51`	`+- User Filter (required)`
	`52`	`+ - An LDAP filter declaring which users should be allowed to log in. Used as the`
	`53`	`+ initial search query in the Bind DN authenticator. Applied "on top of" the`
	`54`	+ authenticated user context in Simple Authentication. The `%s` matching parameter
	`55`	`+ will be substituted with the login name given on the sign-in form.`
	`56`	+ - Example: `(&(objectClass=posixAccount)(uid=%s))`
	`57`	+ - Can be used to filter on group membership if the User DN object has `memberOf`
	`58`	`+ attributes:`
	`59`	+ - `(&(objectClass=posixAccount)(uid=%s)(memberOf=cn=gogs_users,cn=groups,...)`
	`60`	`+ - In the Bind DN authenticator can be used to retrieve the user account using any`
	`61`	`+ of a number of user attributes:`
	`62`	+ - Example: `(&(objectClass=Person)(\|(uid=%s)(mail=%s)(mobile=%s)))`
`38`	`63`
`39`	`64`	`- Admin Filter (optional)`
`40`		`- - An LDAP filter specifying if a user should be given administrator`
`41`		`- privileges. If a user account passes the filter, the user will be`
`42`		`- privileged as an administrator.`
`43`		- - Example: `(objectClass=adminAccount)`
	`65`	`+ - An LDAP filter which is applied to the User DN context to determine whether the`
	`66`	`+ user should have Gogs administrator privileges.`
	`67`	+ - Example: `(objectClass=adminAccount)` or `(memberOf=cn=admins,cn=groups,...)`
`44`	`68`
`45`	`69`	`- Username attribute (optional)`
`46`	`70`	`- The attribute of the user's LDAP record containing the user name. The given`
`@@ -61,11 +85,19 @@ Both the LDAP via BindDN and the simple auth LDAP share the following fields:`
`61`	`85`	`This will be used to populate their account information.`
`62`	`86`	- Example: `sn`
`63`	`87`
`64`		`-- E-mail attribute (required)`
	`88`	`+- Email attribute (required)`
`65`	`89`	`- The attribute of the user's LDAP record containing the user's email`
`66`	`90`	`address. This will be used to populate their account information.`
`67`	`91`	- Example: `mail`
`68`	`92`
	`93`	`+LDAP using Simple Auth adds the following field:`
	`94`	`+`
	`95`	`+- User DN (required)`
	`96`	+ - The template to use as the user's DN. The `%s` matching parameter will be
	`97`	`+ substituted with the login name given on the sign-in form.`
	`98`	+ - Example: `cn=%s,ou=Users,dc=mydomain,dc=com`
	`99`	+ - Example: `uid=%s,ou=Users,dc=mydomain,dc=com`
	`100`	`+`
`69`	`101`	`LDAP via BindDN adds the following fields:`
`70`	`102`
`71`	`103`	`- Bind DN (optional)`
`@@ -79,49 +111,30 @@ Both the LDAP via BindDN and the simple auth LDAP share the following fields:`
`79`	`111`	`has as few privileges as possible.*`
`80`	`112`
`81`	`113`	`- User Search Base (required)`
`82`		`- - The LDAP base at which user accounts will be searched for.`
	`114`	`+ - The LDAP base below which the user account will be searched.`
`83`	`115`	- Example: `ou=Users,dc=mydomain,dc=com`
`84`	`116`
`85`		`-- User Filter (required)`
`86`		`- - An LDAP filter declaring how to find the record for the user that is attempting`
`87`		- to authenticate. The `%s` matching parameter will be substituted with login
`88`		`- name given on the sign-in form.`
`89`		- - Example: `(&(objectClass=posixAccount)(uid=%s))`
`90`		`- - To substitute more than once, e.g. when matching a supplied login name against multiple attributes such as user identifier, email, or even phone number.`
`91`		- - Example: `(&(objectClass=Person)(\|(uid=%s)(mail=%s)(mobile=%s)))`
`92`		`-`
`93`		`-LDAP using simple auth adds the following fields:`
`94`		`-`
`95`		`-- User DN (required)`
`96`		- - A template to use as the user's DN. The `%s`
`97`		`- matching parameter will be substituted with the login name given on the sign-in form.`
`98`		- - Example: `cn=%s,ou=Users,dc=mydomain,dc=com`
`99`		- - Example: `uid=%s,ou=Users,dc=mydomain,dc=com`
`100`		`-`
`101`		`-- User Filter (required)`
`102`		- - An LDAP filter declaring when a user should be allowed to log in. The `%s`
`103`		`- matching parameter will be substituted with the login name given on the`
`104`		`- sign-in form.`
`105`		- - Example: `(&(objectClass=posixAccount)(cn=%s))`
`106`		- - Example: `(&(objectClass=posixAccount)(uid=%s))`
	`117`	`+- Fetch attributes in Bind DN context (optional)`
	`118`	`+ - By default user attributes are retrieved while bound as the User DN; tick this`
	`119`	`+ box to retrieve them while bound as the Bind DN`
`107`	`120`
`108`	`121`	`Verify group membership in LDAP uses the following fields:`
`109`	`122`
`110`		`-* Group Search Base (optional)`
`111`		`- *The LDAP DN used for groups.`
`112`		- * Example: `ou=group,dc=mydomain,dc=com`
	`123`	`+- Group Search Base DN (optional)`
	`124`	`+ -The LDAP base below which groups will be searched`
	`125`	+ - Example: `ou=group,dc=mydomain,dc=com`
`113`	`126`
`114`		`-* Group Name Filter (optional)`
`115`		`- *An LDAP filter declaring how to find valid groups in the above DN.`
`116`		- * Example: `(\|(cn=gogs_users)(cn=admins))`
	`127`	`+- Group Filter (optional)`
	`128`	`+ -An LDAP filter declaring the groups that entitle the user to have access`
	`129`	+ - Example: `(\|(cn=gogs_users)(cn=admins))`
`117`	`130`
`118`		`-* User Attribute in Group (optional)`
`119`		`- *Which user LDAP attribute is listed in the group.`
`120`		- *Example: `uid`
	`131`	`+- Group Attribute Containing List of users (optional)`
	`132`	`+ -Which multi-valued attribute has the group's members`
	`133`	+ -Example: `memberUid` or `member`
`121`	`134`
`122`		`-* Group Attribute for User (optional)`
`123`		`- *Which group LDAP attribute contains an array above user attribute names.`
`124`		- *Example: `memberUid`
	`135`	`+- User Attribute Listed in Group (optional)`
	`136`	`+ -Which user attribute is listed in the membership attributes on the group`
	`137`	+ -Example: `uid` or `dn`
`125`	`138`
`126`	`139`	`### PAM`
`127`	`140`
`@@ -145,6 +158,7 @@ This option allows Gogs to log in to your SMTP host as a Gogs user. To configure`
`145`	`158`	`- Port (required)`
`146`	`159`	`- The port to use when connecting to the server.`
`147`	`160`	- Example: `587`
	`161`	`+`
`148`	`162`	`- Allowed Domains`
`149`	`163`	`- Restrict what domains can log in if you're using a public SMTP host or an SMTP host with multiple domains.`
`150`	`164`	- Example: `gogs.io,mydomain.com,mydomain2.com`
`@@ -155,36 +169,50 @@ This option allows Gogs to log in to your SMTP host as a Gogs user. To configure`
`155`	`169`	`- Skip TLS Verify`
`156`	`170`	`- Disable TLS verify on authentication.`
`157`	`171`
`158`		`-- This authentication is activate`
	`172`	`+- This authentication is activated`
`159`	`173`	`- Enable or disable this auth method.`
`160`	`174`
`161`	`175`	`### FreeIPA`
`162`	`176`
`163`		`-- In order to log into Gogs using FreeIPA credentials, you need to create a bind account for Gogs to use:`
`164`		`-`
`165`		-- On the FreeIPA server, create a `gogs.ldif` file, replacing `dc=example,dc=com` with your DN, and providing an appropriately secure password:
`166`		-```
`167`		`- dn: uid=gogs,cn=sysaccounts,cn=etc,dc=example,dc=com`
`168`		`- changetype: add`
`169`		`- objectclass: account`
`170`		`- objectclass: simplesecurityobject`
`171`		`- uid: gogs`
`172`		`- userPassword: secure password`
`173`		`- passwordExpirationTime: 20380119031407Z`
`174`		`- nsIdleTimeout: 0`
`175`		-```
`176`		`-`
`177`		-- Import the LDIF (change `localhost` to an IPA server if needed). You will be prompted for your Directory Manager password:
`178`		-```
`179`		`- ldapmodify -h localhost -p 389 -x -D \`
`180`		`- "cn=Directory Manager" -W -f gogs.ldif`
`181`		-```
`182`		-- Add an IPA group for `gogs_users`:
`183`		-```
`184`		`- ipa group-add --desc="Gogs Users" gogs_users`
`185`		-```
`186`		`-- Note! If you get an error about IPA credentials, run kinit admin and give your admin accound password.`
`187`		`-`
`188`		`-- Now log into Gogs as admin and click on "Authentication" under the Admin Panel. Then click New LDAP Source and fill in the details, changing all appropriate fields for your own domain as shown below:`
`189`		`-`
`190`		`-![](/docs/images/Freeipa-Gogs.png)`
	`177`	`+It is possible to use either Bind DN or Simple Auth with FreeIPA. Below are`
	`178`	`+the relevant parts of sample configurations. These assume that your domain is`
	`179`	+`domain.com`, and that users must be a member of group `gogs_users` to get access.
	`180`	`+`
	`181`	`+Using Simple Auth`
	`182`	`+`
	`183`	`+Setting up access using Simple Auth is trivial:`
	`184`	`+`
	`185`	`+ user_dn = uid=%s,cn=users,cn=accounts,dc=domain,dc=com`
	`186`	`+ filter = (&(objectClass=posixAccount)(memberOf=cn=gogs_users,cn=groups,cn=accounts,dc=domain,dc=com))`
	`187`	`+ attribute_username = uid`
	`188`	`+ attribute_name = givenName`
	`189`	`+ attribute_surname = sn`
	`190`	`+ attribute_mail = mail`
	`191`	`+ admin_filter = (memberOf=cn=admins,cn=groups,cn=accounts,dc=domain,dc=com)`
	`192`	`+ group_enabled = false`
	`193`	`+`
	`194`	`+Using Bind DN`
	`195`	`+`
	`196`	`+If you want to allow login by email address, you run into the issue that IPA by`
	`197`	+default does not grant anonymous search access to the `mail` attribute. This can
	`198`	`+be changed easily in IPA:`
	`199`	`+`
	`200`	`+ ipa permission-mod --includedattrs=mail 'System: Read User Standard Attributes'`
	`201`	`+`
	`202`	`+Alternatively, you could ask your LDAP administrators (who will not be keen on exposing`
	`203`	`+email addresses to unauthenticated LDAP clients) for a bind user account.`
	`204`	`+`
	`205`	`+However all this is probably not necessary any more, as Gogs translates email`
	`206`	`+logins to the corresponding user ID\* before it makes the authentication call to the`
	`207`	`+backend LDAP.`
	`208`	`+`
	`209`	`+All that is required is that the user's _first login_ is with their user ID,`
	`210`	`+After that they can use user ID and email address.`
	`211`	`+`
	`212`	`+---`
	`213`	`+`
	`214`	`+Footnotes`
	`215`	`+`
	`216`	`+\*) To be precise: it maps their login name onto their "Authentication Login Name",`
	`217`	`+ which administrators can edit on the User's "Edit Account" page.`
	`218`	`+`

0 commit comments

Comments

(0)

Navigation Menu

Search code, repositories, users, issues, pull requests...

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Commit 22a87c9

File tree

1 file changed

1 file changed

`‎en-US/features/authentication.md‎`

0 commit comments