You can configure GitHub Enterprise to use LDAP for authentication.

Step 1: Access the LDAP settings

  1. Access the Management Console.

  2. At the top of the page, click the Settings tab. Settings tab

  3. On the left side of the page, click Authentication. Authentication tab

  4. Under Authentication, select LDAP. LDAP option

Step 2: Set up a connection to the server

  1. Use the Host field to specify the hostname of the LDAP server itself, such as ldap.example.com or 10.0.0.30. If the hostname is only available from your internal network, you may need to configure GitHub Enterprise's DNS first so that it can resolve the hostname using your internal nameservers. Host field

  2. Use the Port field to specify the network port over which GitHub Enterprise will try to contact the LDAP server. This port will vary depending upon your specific LDAP server and the encryption method that you use. For example, port 389 is typically the default for plain authentication and port 636 is typically the default for LDAPS encryption. Port field

  3. Use the Encryption field to specify the encryption method that will be used to communicate with the LDAP server. You can choose plain-text, StartTLS, or LDAPS encryption. Encryption field

Tip: If GitHub Enterprise can't validate the SSL certificate used by your LDAP server, you can install a trusted certificate with the ghe-ssl-ca-certificate-install command-line utility.

Step 3: Set up domain search

  1. Specify the domain search user that will perform lookups to authenticate other users when they sign in. This search user is typically a service account that's created specifically for third party integrations. Use a fully qualified name, such as cn=Administrator,cn=Users,dc=example,dc=com. You can also use the [DOMAIN]\[USERNAME] syntax (e.g. WINDOWS\Administrator) for the domain search user with Active Directory. Domain search user field

  2. Specify a domain search password to authenticate the domain search user. Domain search password

  3. Specify a domain base: the fully qualified name of an LDAP subtree you want to search for users and groups. Although you can add as many domain bases as you like, each group must be defined in the same domain base as the users that belong to it. If you specify restricted user groups (as explained below), only users that belong to those groups will be in-scope. If you don't specify any restricted user groups, all users found in the domain base subtrees will be in-scope.

    We recommend that you specify the top level of your LDAP directory tree and then take advantage of user groups to control access. Domain base field

Step 4: Set up groups (optional)

  1. Specify the administrators group to automatically promote its members to site administrators on GitHub Enterprise when they sign in for the first time. Administrators group field

  2. Specify restricted user groups to limit access to GitHub Enterprise. You only need to specify the common names (CNs) of the groups, and you can add as many groups as you like. If no groups are specified, all users within the scope of the specified domain base(s) can sign into your GitHub Enterprise installation. Restricted user groups field

Step 5: Set up user fields

  1. Specify a User ID field to map each user account on GitHub Enterprise to a user entry on your LDAP server. When a user signs into GitHub Enterprise for the first time, the LDAP server is queried for an entry whose User ID attribute (specified here) matches the username. Once a mapping with an LDAP user entry has been established, users may change their usernames. This field should be sAMAccountName for most Active Directory installations but it may be uid for other LDAP solutions, such as OpenLDAP. The default value is uid. User ID field

  2. Optionally specify a Profile name field, which will be shown as the name of GitHub Enterprise users on their profile pages. Users may change their profile names. Profile name field

  3. Optionally specify an Emails field to set the email addresses for GitHub Enterprise user accounts. Emails field

  4. Optionally specify an SSH keys field to set the SSH keys for GitHub Enterprise user accounts. SSH keys field

Step 6: Test your configuration

  1. Under Authentication, click Test LDAP connection. click the Test LDAP Connection button

  2. Type a username that should be able to authenticate with your settings. This test doesn't actually authenticate the user—you don't need to provide a password—it just ensures that the user can be found for the specified domain and group settings. test dialog box

If the test was successful, you'll see a green success message appear:

a success message will appear

If the test failed, you'll see an error message describing what went wrong:

a failure message will appear

Step 7: Save your settings

At the bottom of the page, click Save settings.

Save settings button

Further reading