Authentication

Gogs supports authentication through various external sources. Currently supported backends are LDAP, SMTP, PAM, and HTTP header. Authentication sources can be configured in two ways:

Admin Panel: Navigate to Admin Panel > Authentication Sources
Configuration files: Place .conf files in the custom/conf/auth.d/ directory. Each file describes one source using INI format. Files are loaded once at startup and keyed by id. See the “Configuration file” subsection under each backend below for examples.

LDAP

Gogs supports two variants of LDAP authentication: Simple Auth and Bind DN. In both cases, authentication is performed by attempting to bind to the LDAP server with the User DN and password. The difference is that with Bind DN, a preliminary query is performed (using the Bind DN credentials) to find the User DN first.

When to use Bind DN
When to use Simple Auth

The Bind DN mechanism has these advantages:

It may be more secure than blindly attempting to bind with a possibly non-existent User DN.
It supports login with attributes such as email address or phone number. The preliminary search can look up the User DN using mail or mobile attributes.
It is required when the LDAP does not allow the User DN to query its own attributes or group memberships.

The downside is that, unless the LDAP allows anonymous queries, it requires a bind DN to be defined and Gogs needs to store its credentials. Gogs currently does not encrypt these credentials.

Shared fields

The following fields are shared between both Bind DN and Simple Auth configurations:

Field	Required	Description	Example
Authentication Name	Yes	A friendly name for the authentication source.	`My LDAP`
Security Protocol	Yes	Connection security: Unencrypted, LDAPS, or StartTLS.	`LDAPS`
Host	Yes	The address of the LDAP server.	`ldap.mydomain.com`
Port	Yes	The port for the LDAP connection. Usually `389` for LDAP/StartTLS, `636` for LDAPS.	`389`
User Filter	Yes	An LDAP filter declaring which users can log in. The `%s` parameter is substituted with the login name.	`(&(objectClass=posixAccount)(uid=%s))`
Email Attribute	Yes	The LDAP attribute containing the user’s email address.	`mail`
Admin Filter	No	An LDAP filter applied to the User DN context to determine Gogs administrator privileges.	`(memberOf=cn=admins,cn=groups,dc=mydomain,dc=com)`
Username Attribute	No	The LDAP attribute containing the username. Used for the Gogs account name after first sign-in. Leave empty to use the login name from the sign-in form.	`uid`
First Name Attribute	No	The LDAP attribute containing the user’s first name.	`givenName`
Surname Attribute	No	The LDAP attribute containing the user’s last name.	`sn`

The User Filter field can be used to filter on group membership if the User DN object has memberOf attributes. For example:

(&(objectClass=posixAccount)(uid=%s)(memberOf=cn=gogs_users,cn=groups,dc=mydomain,dc=com))

In the Bind DN authenticator, the User Filter can also match against multiple user attributes:

(&(objectClass=Person)(|(uid=%s)(mail=%s)(mobile=%s)))

Simple Auth fields

LDAP via Simple Auth adds the following field:

Field	Required	Description	Example
User DN	Yes	A template for the user’s DN. The `%s` parameter is substituted with the login name.	`cn=%s,ou=Users,dc=mydomain,dc=com` or `uid=%s,ou=Users,dc=mydomain,dc=com`

Bind DN fields

LDAP via Bind DN adds the following fields:

Field	Required	Description	Example
Bind DN	No	The DN used to bind to the LDAP server when searching for the user. Leave blank for anonymous search.	`cn=Search,dc=mydomain,dc=com`
Bind Password	No	The password for the Bind DN specified above.	—
User Search Base	Yes	The LDAP base below which user accounts will be searched.	`ou=Users,dc=mydomain,dc=com`
Fetch Attributes in Bind DN Context	No	When enabled, user attributes are retrieved while bound as the Bind DN instead of the User DN.	—

The Bind Password is stored in plaintext on the server. Ensure that your Bind DN has the minimum privileges necessary.

Group membership verification

You can optionally verify LDAP group membership using the following fields:

Field	Required	Description	Example
Group Search Base DN	No	The LDAP base below which groups will be searched.	`ou=group,dc=mydomain,dc=com`
Group Filter	No	An LDAP filter declaring the groups that grant access.	`(\|(cn=gogs_users)(cn=admins))`
Group Attribute Containing List of Users	No	The multi-valued attribute containing the group’s members.	`memberUid` or `member`
User Attribute Listed in Group	No	The user attribute referenced in the group membership attributes.	`uid` or `dn`

Configuration files

LDAP sources can also be defined as .conf files in custom/conf/auth.d/ instead of through the admin panel. Files are loaded at startup and keyed by id.

Bind DN
Simple Auth

id           = 101
type         = ldap_bind_dn
name         = LDAP BindDN
is_activated = true

[config]
host               = mydomain.com
port               = 636
# 0 - Unencrypted, 1 - LDAPS, 2 - StartTLS
security_protocol  = 0
skip_verify        = false
bind_dn            =
bind_password      =
user_base          = ou=Users,dc=mydomain,dc=com
attribute_username =
attribute_name     =
attribute_surname  =
attribute_mail     = mail
attributes_in_bind = false
filter             = (&(objectClass=posixAccount)(cn=%s))
admin_filter       =
group_enabled      = false
group_dn           =
group_filter       =
group_member_uid   =
user_uid           =

id           = 102
type         = ldap_simple_auth
name         = LDAP Simple Auth
is_activated = true

[config]
host               = mydomain.com
port               = 636
# 0 - Unencrypted, 1 - LDAPS, 2 - StartTLS
security_protocol  = 0
skip_verify        = false
bind_dn            =
bind_password      =
user_base          =
user_dn            = cn=%s,ou=Users,dc=mydomain,dc=com
attribute_username =
attribute_name     =
attribute_surname  =
attribute_mail     = mail
attributes_in_bind = false
filter             = (&(objectClass=posixAccount)(cn=%s))
admin_filter       =
group_enabled      = false
group_dn           =
group_filter       =
group_member_uid   =
user_uid           =

FreeIPA examples

It is possible to use either Bind DN or Simple Auth with FreeIPA. The examples below assume your domain is domain.com and that users must be a member of the gogs_users group to get access.

FreeIPA with Simple Auth

Setting up access using Simple Auth is straightforward:

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

FreeIPA with Bind DN

If you want to allow login by email address, note that FreeIPA by default does not grant anonymous search access to the mail attribute. This can be changed in IPA:

ipa permission-mod --includedattrs=mail 'System: Read User Standard Attributes'

Alternatively, you can ask your LDAP administrators for a dedicated bind user account.

Allowing email-based login via Bind DN may no longer be necessary. Gogs translates email logins to the corresponding user ID before making the authentication call to the backend LDAP. The only requirement is that the user’s first login is with their user ID. After that, they can use either user ID or email address.

More precisely, Gogs maps the login name onto the user’s “Authentication Login Name”, which administrators can edit on the user’s Edit Account page.

PAM

To configure PAM authentication, set the PAM Service Name to a filename in /etc/pam.d/.

If you want PAM authentication to work with normal Linux passwords, the user running Gogs must have read access to /etc/shadow.

Configuration file

id           = 104
type         = pam
name         = System Auth
is_activated = true

[config]
service_name = system-auth

SMTP

SMTP authentication allows Gogs to log in to your SMTP host to verify user credentials. Configure the following fields:

Field	Required	Description	Example
Authentication Name	Yes	A name for this authentication source.	`Company SMTP`
SMTP Authentication Type	Yes	The authentication type: `PLAIN` or `LOGIN`.	`PLAIN`
Host	Yes	The address of the SMTP server.	`smtp.mydomain.com`
Port	Yes	The port for the SMTP connection.	`587`
Allowed Domains	No	Restrict login to specific email domains. Separate multiple domains with commas.	`gogs.io,mydomain.com`
Enable TLS Encryption	No	Enable TLS encryption for the authentication connection.	—
Skip TLS Verify	No	Disable TLS certificate verification.	—
This Authentication is Activated	No	Enable or disable this authentication method.	—

Configuration file

id           = 103
type         = smtp
name         = GMail
is_activated = true

[config]
# Either "PLAIN" or "LOGIN"
auth            = PLAIN
host            = smtp.gmail.com
port            = 587
allowed_domains =
tls             = true
skip_verify     = false

HTTP header

If your reverse proxy already handles user authentication (e.g. via SSO, OAuth, or client certificates), Gogs can trust the authenticated username from an HTTP header. This is configured in custom/conf/app.ini under [auth]:

[auth]
ENABLE_REVERSE_PROXY_AUTHENTICATION = true
REVERSE_PROXY_AUTHENTICATION_HEADER = X-WEBAUTH-USER

Option	Default	Description
`ENABLE_REVERSE_PROXY_AUTHENTICATION`	`false`	Enable reading the authenticated username from a request header.
`REVERSE_PROXY_AUTHENTICATION_HEADER`	`X-WEBAUTH-USER`	The HTTP header containing the authenticated username.
`ENABLE_REVERSE_PROXY_AUTO_REGISTRATION`	`false`	Automatically create a Gogs account for users that do not yet exist.

When auto-registration is enabled, Gogs creates new accounts with an activated status and a placeholder email address. The user can update their email after first login.

Only enable this feature if Gogs is exclusively accessed through a trusted reverse proxy that sets the header. Exposing Gogs directly to the internet with this enabled would allow anyone to impersonate any user by setting the header themselves.

Getting started

Fine-tuning

Advancing

Asking

LDAP

Shared fields

Simple Auth fields

Bind DN fields

Group membership verification

Configuration files

FreeIPA examples

PAM

Configuration file

SMTP

Configuration file

HTTP header

​LDAP

​Shared fields

​Simple Auth fields

​Bind DN fields

​Group membership verification

​Configuration files

​FreeIPA examples

​PAM

​Configuration file

​SMTP

​Configuration file

​HTTP header

LDAP

Shared fields

Simple Auth fields

Bind DN fields

Group membership verification

Configuration files

FreeIPA examples

PAM

Configuration file

SMTP

Configuration file

HTTP header