code.gitea.io/gitea@v1.21.7/services/auth/source/ldap/README.md (about)

     1  # Gitea LDAP Authentication Module
     2  
     3  ## About
     4  
     5  This authentication module attempts to authorize and authenticate a user
     6  against an LDAP server. It provides two methods of authentication: LDAP via
     7  BindDN, and LDAP simple authentication.
     8  
     9  LDAP via BindDN functions like most LDAP authentication systems. First, it
    10  queries the LDAP server using a Bind DN and searches for the user that is
    11  attempting to sign in. If the user is found, the module attempts to bind to the
    12  server using the user's supplied credentials. If this succeeds, the user has
    13  been authenticated, and his account information is retrieved and passed to the
    14  Gogs login infrastructure.
    15  
    16  LDAP simple authentication does not utilize a Bind DN. Instead, it binds
    17  directly with the LDAP server using the user's supplied credentials. If the bind
    18  succeeds and no filter rules out the user, the user is authenticated.
    19  
    20  LDAP via BindDN is recommended for most users. By using a Bind DN, the server
    21  can perform authorization by restricting which entries the Bind DN account can
    22  read. Further, using a Bind DN with reduced permissions can reduce security risk
    23  in the face of application bugs.
    24  
    25  ## Usage
    26  
    27  To use this module, add an LDAP authentication source via the Authentications
    28  section in the admin panel. Both the LDAP via BindDN and the simple auth LDAP
    29  share the following fields:
    30  
    31  * Authorization Name **(required)**
    32    * A name to assign to the new method of authorization.
    33  
    34  * Host **(required)**
    35    * The address where the LDAP server can be reached.
    36    * Example: mydomain.com
    37  
    38  * Port **(required)**
    39    * The port to use when connecting to the server.
    40    * Example: 636
    41  
    42  * Enable TLS Encryption (optional)
    43    * Whether to use TLS when connecting to the LDAP server.
    44  
    45  * Admin Filter (optional)
    46    * An LDAP filter specifying if a user should be given administrator
    47        privileges. If a user accounts passes the filter, the user will be
    48        privileged as an administrator.
    49    * Example: (objectClass=adminAccount)
    50  
    51  * First name attribute (optional)
    52    * The attribute of the user's LDAP record containing the user's first name.
    53        This will be used to populate their account information.
    54    * Example: givenName
    55  
    56  * Surname attribute (optional)
    57    * The attribute of the user's LDAP record containing the user's surname This
    58        will be used to populate their account information.
    59    * Example: sn
    60  
    61  * E-mail attribute **(required)**
    62    * The attribute of the user's LDAP record containing the user's email
    63        address. This will be used to populate their account information.
    64    * Example: mail
    65  
    66  **LDAP via BindDN** adds the following fields:
    67  
    68  * Bind DN (optional)
    69    * The DN to bind to the LDAP server with when searching for the user. This
    70        may be left blank to perform an anonymous search.
    71    * Example: cn=Search,dc=mydomain,dc=com
    72  
    73  * Bind Password (optional)
    74    * The password for the Bind DN specified above, if any. _Note: The password
    75        is stored in plaintext at the server. As such, ensure that your Bind DN
    76        has as few privileges as possible._
    77  
    78  * User Search Base **(required)**
    79    * The LDAP base at which user accounts will be searched for.
    80    * Example: ou=Users,dc=mydomain,dc=com
    81  
    82  * User Filter **(required)**
    83    * An LDAP filter declaring how to find the user record that is attempting to
    84        authenticate. The '%[1]s' matching parameter will be substituted with the
    85        user's username.
    86    * Example: (&(objectClass=posixAccount)(|(uid=%[1]s)(mail=%[1]s)))
    87  
    88  **LDAP using simple auth** adds the following fields:
    89  
    90  * User DN **(required)**
    91    * A template to use as the user's DN. The `%s` matching parameter will be
    92        substituted with the user's username.
    93    * Example: cn=%s,ou=Users,dc=mydomain,dc=com
    94    * Example: uid=%s,ou=Users,dc=mydomain,dc=com
    95  
    96  * User Search Base (optional)
    97    * The LDAP base at which user accounts will be searched for.
    98    * Example: ou=Users,dc=mydomain,dc=com
    99  
   100  * User Filter **(required)**
   101    * An LDAP filter declaring when a user should be allowed to log in. The `%[1]s`
   102        matching parameter will be substituted with the user's username.
   103    * Example: (&(objectClass=posixAccount)(|(cn=%[1]s)(mail=%[1]s)))
   104    * Example: (&(objectClass=posixAccount)(|(uid=%[1]s)(mail=%[1]s)))
   105  
   106  **Verify group membership in LDAP** uses the following fields:
   107  
   108  * Group Search Base (optional)
   109    * The LDAP DN used for groups.
   110    * Example: ou=group,dc=mydomain,dc=com
   111  
   112  * Group Name Filter (optional)
   113    * An LDAP filter declaring how to find valid groups in the above DN.
   114    * Example: (|(cn=gitea_users)(cn=admins))
   115  
   116  * User Attribute in Group (optional)
   117    * The user attribute that is used to reference a user in the group object.
   118    * Example: uid if the group objects contains a member: bender and the user object contains a uid: bender.
   119    * Example: dn if the group object contains a member: uid=bender,ou=users,dc=planetexpress,dc=com.
   120  
   121  * Group Attribute for User (optional)
   122    * The attribute of the group object that lists/contains the group members.
   123    * Example: memberUid or member
   124  
   125  * Team group map (optional)
   126    * Automatically add users to Organization teams, depending on LDAP group memberships.
   127    * Note: this function only adds users to teams, it never removes users.
   128    * Example: {"cn=MyGroup,cn=groups,dc=example,dc=org": {"MyGiteaOrganization": ["MyGiteaTeam1", "MyGiteaTeam2", ...], ...}, ...}
   129  
   130  * Team group map removal (optional)
   131    * If set to true, users will be removed from teams if they are not members of the corresponding group.