Skip to content

Navigation Menu

Sign in
Appearance settings

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

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

Clean up the LDAP and FreeIPA documentation #239

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
unknwon merged 2 commits into gogs:master from zwets:improve-ldap-freeipa-docs
Sep 22, 2019
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
190 changes: 109 additions & 81 deletions en-US/features/authentication.md
View file Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,43 +4,67 @@ 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 (starting from `0.11.45.0412`) 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).
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).

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. 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

- 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.
- Example: `mydomain.com`
- Example: `ldap.mydomain.com`

- 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
Expand All @@ -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)
Expand All @@ -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

Expand All @@ -145,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`
Expand All @@ -155,36 +169,50 @@ 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

- 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.

AltStyle によって変換されたページ (->オリジナル) /