From c94268d627cf9129af774b6c90f5cf1419521186 Mon Sep 17 00:00:00 2001 From: Marco van Zwetselaar Date: Fri, 20 Sep 2019 16:38:48 +0300 Subject: [PATCH 1/2] Clean up the LDAP and FreeIPA documentation --- en-US/features/authentication.md | 185 ++++++++++++++++++------------- 1 file changed, 106 insertions(+), 79 deletions(-) diff --git a/en-US/features/authentication.md b/en-US/features/authentication.md index 258bf342..a2d90a50 100644 --- a/en-US/features/authentication.md +++ b/en-US/features/authentication.md @@ -4,26 +4,41 @@ name: Authentication # Authentication -## Load authentication source from file +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 using configuration files in `custom/conf/auth.d`. -Starting from `0.11.45.0412`, you can define the authentication source in local files to help better automate setup process. +## Using configuration files -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). +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). -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. +Authentication sources defined via configuration files appear in the **Admin Panel - Authentication Sources** just like sources created via the web interface. ![](/docs/images/auth_sources.png) -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. +Configuration files are read once when Gogs starts. To edit them while Gogs is running, use the web interface. ## Configuration ### LDAP -Both the LDAP via BindDN and the simple auth LDAP share the following fields: +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. -- Authorization Name **(required)** - - A name to assign to the new method of authorization. +The Bind DN mechanism has these advantages: + +- It may be more secure than blindy attempting to bind with a possibly non-existent User DN +- It supports login with e.g. email address or phone number, as the preliminary search could look up the User DN using their `mail` or `mobile` attribute (but see the points in the FreeIPA section at the bottom of this page: features in Gogs may have obsoleted the need for this) +- A Bind DN is required when the LDAP does not allow the User DN to query its own attributes or group memberships + +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. + +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. + +**Shared configuration fields** between Bind DN and Simple Auth authentication + +- Authentication Name **(required)** + - A friendly name to assign to the new authentication source + +- Security Protocol **(required)** + - Unencrypted (0), LDAPS (1), StartTLS (2) - Host **(required)** - The address where the LDAP server can be reached. @@ -31,16 +46,25 @@ Both the LDAP via BindDN and the simple auth LDAP share the following fields: - Port **(required)** - The port to use when connecting to the server. - - Example: `636` + - Usually `389` for the LDAP and StartTLS protocols, `636` for LDAPS protocol. -- Enable TLS Encryption (optional) - - Whether to use TLS when connecting to the LDAP server. +- User Filter **(required)** + - An LDAP filter declaring which users should be allowed to log in. Used as the + initial search query in the Bind DN authenticator, applied "on top of" the + authenticated user context in Simple Authentication. The `%s` matching parameter + will be substituted with the login name given on the sign-in form. + - Example: `(&(objectClass=posixAccount)(uid=%s))` + - Can be used to filter on group membership if the User DN object has `memberOf` + attributes: + - `(&(objectClass=posixAccount)(uid=%s)(memberOf=cn=gogs_users,cn=groups,...)` + - In the Bind DN authenticator can be used to retrieve the user account using any + of a number of user attributes: + - Example: `(&(objectClass=Person)(|(uid=%s)(mail=%s)(mobile=%s)))` - Admin Filter (optional) - - An LDAP filter specifying if a user should be given administrator - privileges. If a user account passes the filter, the user will be - privileged as an administrator. - - Example: `(objectClass=adminAccount)` + - An LDAP filter which is applied to the User DN context to determine whether the + user should have Gogs administrator privileges. + - Example: `(objectClass=adminAccount)` or `(memberOf=cn=admins,cn=groups,...)` - Username attribute (optional) - 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: This will be used to populate their account information. - Example: `sn` -- E-mail attribute **(required)** +- Email attribute **(required)** - The attribute of the user's LDAP record containing the user's email address. This will be used to populate their account information. - Example: `mail` +**LDAP using Simple Auth** adds the following field: + +- User DN **(required)** + - The template to use as the user's DN. The `%s` matching parameter will be + substituted with the login name given on the sign-in form. + - Example: `cn=%s,ou=Users,dc=mydomain,dc=com` + - Example: `uid=%s,ou=Users,dc=mydomain,dc=com` + **LDAP via BindDN** adds the following fields: - Bind DN (optional) @@ -79,49 +111,30 @@ Both the LDAP via BindDN and the simple auth LDAP share the following fields: has as few privileges as possible.* - User Search Base **(required)** - - The LDAP base at which user accounts will be searched for. + - The LDAP base below which the user account will be searched. - Example: `ou=Users,dc=mydomain,dc=com` -- User Filter **(required)** - - An LDAP filter declaring how to find the record for the user that is attempting - to authenticate. The `%s` matching parameter will be substituted with login - name given on the sign-in form. - - Example: `(&(objectClass=posixAccount)(uid=%s))` - - 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. - - Example: `(&(objectClass=Person)(|(uid=%s)(mail=%s)(mobile=%s)))` - -**LDAP using simple auth** adds the following fields: - -- User DN **(required)** - - A template to use as the user's DN. The `%s` - matching parameter will be substituted with the login name given on the sign-in form. - - Example: `cn=%s,ou=Users,dc=mydomain,dc=com` - - Example: `uid=%s,ou=Users,dc=mydomain,dc=com` - -- User Filter **(required)** - - An LDAP filter declaring when a user should be allowed to log in. The `%s` - matching parameter will be substituted with the login name given on the - sign-in form. - - Example: `(&(objectClass=posixAccount)(cn=%s))` - - Example: `(&(objectClass=posixAccount)(uid=%s))` +- Fetch attributes in Bind DN context (optional) + - By default user attributes are retrieved while bound as the User DN; tick this + box to retrieve them while bound as the Bind DN **Verify group membership in LDAP** uses the following fields: -* Group Search Base (optional) - * The LDAP DN used for groups. - * Example: `ou=group,dc=mydomain,dc=com` +- Group Search Base DN (optional) + - The LDAP base below which groups will be searched + - Example: `ou=group,dc=mydomain,dc=com` -* Group Name Filter (optional) - * An LDAP filter declaring how to find valid groups in the above DN. - * Example: `(|(cn=gogs_users)(cn=admins))` +- Group Filter (optional) + - An LDAP filter declaring the groups that entitle the user to have access + - Example: `(|(cn=gogs_users)(cn=admins))` -* User Attribute in Group (optional) - * Which user LDAP attribute is listed in the group. - * Example: `uid` +- Group Attribute Containing List of users (optional) + - Which multi-valued attribute has the group's members + - Example: `memberUid` or `member` -* Group Attribute for User (optional) - * Which group LDAP attribute contains an array above user attribute names. - * Example: `memberUid` +- User Attribute Listed in Group (optional) + - Which user attribute is listed in the membership attributes on the group + - Example: `uid` or `dn` ### PAM @@ -160,31 +173,45 @@ This option allows Gogs to log in to your SMTP host as a Gogs user. To configure ### FreeIPA -- In order to log into Gogs using FreeIPA credentials, you need to create a bind account for Gogs to use: - -- On the FreeIPA server, create a `gogs.ldif` file, replacing `dc=example,dc=com` with your DN, and providing an appropriately secure password: -``` - dn: uid=gogs,cn=sysaccounts,cn=etc,dc=example,dc=com - changetype: add - objectclass: account - objectclass: simplesecurityobject - uid: gogs - userPassword: secure password - passwordExpirationTime: 20380119031407Z - nsIdleTimeout: 0 -``` - -- Import the LDIF (change `localhost` to an IPA server if needed). You will be prompted for your Directory Manager password: -``` - ldapmodify -h localhost -p 389 -x -D \ - "cn=Directory Manager" -W -f gogs.ldif -``` -- Add an IPA group for `gogs_users`: -``` - ipa group-add --desc="Gogs Users" gogs_users -``` -- Note! If you get an error about IPA credentials, run kinit admin and give your admin accound password. - -- 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: - -![](/docs/images/Freeipa-Gogs.png) +It is possible to use either Bind DN or Simple Auth with FreeIPA. Below are +the relevant parts of sample configurations. These assume that your domain is +`domain.com`, and that users must be a member of group `gogs_users` to get access. + +**Using Simple Auth** + +Setting up access using Simple Auth is trivial: + + user_dn = uid=%s,cn=users,cn=accounts,dc=domain,dc=com + filter = (&(objectClass=posixAccount)(memberOf=cn=gogs_users,cn=groups,cn=accounts,dc=domain,dc=com)) + attribute_username = uid + attribute_name = givenName + attribute_surname = sn + attribute_mail = mail + admin_filter = (memberOf=cn=admins,cn=groups,cn=accounts,dc=domain,dc=com) + group_enabled = false + +**Using Bind DN** + +If you want to allow login by email address, you run into the issue that IPA by +default does not grant anonymous search access to the `mail` attribute. This can +be changed easily in IPA: + + ipa permission-mod --includedattrs=mail 'System: Read User Standard Attributes' + +Alternatively, you could ask your LDAP administrators (who will not be keen on exposing +email addresses to unauthenticated LDAP clients) for a bind user account. + +**However** all this is probably not necessary any more, as Gogs translates email +logins to the corresponding user ID\* before it makes the authentication call to the +backend LDAP. + +All that is required is that the user's _first login_ is with their user ID. +After that they can use user ID and email address. + +--- + +**Footnotes** + +\*) To be precise: it maps their login name onto their "Authentication Login Name", + which administrators can edit on the User's "Edit Account" page. + From 0fa91fda65ee3db50691408f78773aab2cae8f7b Mon Sep 17 00:00:00 2001 From: Marco van Zwetselaar Date: Sat, 21 Sep 2019 23:46:38 +0300 Subject: [PATCH 2/2] Re-add version number when config files were introduced --- en-US/features/authentication.md | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/en-US/features/authentication.md b/en-US/features/authentication.md index a2d90a50..97b088ec 100644 --- a/en-US/features/authentication.md +++ b/en-US/features/authentication.md @@ -4,11 +4,11 @@ name: Authentication # Authentication -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 using configuration files in `custom/conf/auth.d`. +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`. ## Using configuration files -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). +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). Authentication sources defined via configuration files appear in the **Admin Panel - Authentication Sources** just like sources created via the web interface. @@ -25,14 +25,14 @@ There are two variants for LDAP authentication: with or without a separate Bind The Bind DN mechanism has these advantages: - It may be more secure than blindy attempting to bind with a possibly non-existent User DN -- It supports login with e.g. email address or phone number, as the preliminary search could look up the User DN using their `mail` or `mobile` attribute (but see the points in the FreeIPA section at the bottom of this page: features in Gogs may have obsoleted the need for this) +- 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) - A Bind DN is required when the LDAP does not allow the User DN to query its own attributes or group memberships 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. 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. -**Shared configuration fields** between Bind DN and Simple Auth authentication +**Shared configuration fields** between _Bind DN_ and _Simple Auth_ authentication - Authentication Name **(required)** - A friendly name to assign to the new authentication source @@ -42,7 +42,7 @@ In the ideal situation, the LDAP allows anonymous queries (at least in the "user - Host **(required)** - The address where the LDAP server can be reached. - - Example: `mydomain.com` + - Example: `ldap.mydomain.com` - Port **(required)** - The port to use when connecting to the server. @@ -50,7 +50,7 @@ In the ideal situation, the LDAP allows anonymous queries (at least in the "user - User Filter **(required)** - An LDAP filter declaring which users should be allowed to log in. Used as the - initial search query in the Bind DN authenticator, applied "on top of" the + initial search query in the Bind DN authenticator. Applied "on top of" the authenticated user context in Simple Authentication. The `%s` matching parameter will be substituted with the login name given on the sign-in form. - Example: `(&(objectClass=posixAccount)(uid=%s))` @@ -158,6 +158,7 @@ This option allows Gogs to log in to your SMTP host as a Gogs user. To configure - Port **(required)** - The port to use when connecting to the server. - Example: `587` + - Allowed Domains - Restrict what domains can log in if you're using a public SMTP host or an SMTP host with multiple domains. - Example: `gogs.io,mydomain.com,mydomain2.com` @@ -168,7 +169,7 @@ This option allows Gogs to log in to your SMTP host as a Gogs user. To configure - Skip TLS Verify - Disable TLS verify on authentication. -- This authentication is activate +- This authentication is activated - Enable or disable this auth method. ### FreeIPA @@ -205,7 +206,7 @@ email addresses to unauthenticated LDAP clients) for a bind user account. logins to the corresponding user ID\* before it makes the authentication call to the backend LDAP. -All that is required is that the user's _first login_ is with their user ID. +All that is required is that the user's _first login_ is with their user ID, After that they can use user ID and email address. ---