Using LDAP

If you want to authenticate users without adding them to your identity provider, you can configure built-in authentication. For more information, see "Allowing built-in authentication for users outside your identity provider."

In this guide:

• Supported LDAP services
• Username considerations with LDAP
• Two-factor authentication
• Configuring LDAP with your GitHub Enterprise Server instance
• LDAP attributes
• Viewing and creating LDAP users
• Updating LDAP accounts
• Revoking access to your GitHub Enterprise Server instance

Supported LDAP services

GitHub Enterprise Server integrates with these LDAP services:

• Active Directory
• FreeIPA
• Oracle Directory Server Enterprise Edition
• OpenLDAP
• Open Directory
• 389-ds

Username considerations with LDAP

GitHub Enterprise Server usernames can only contain alphanumeric characters and dashes (-). GitHub Enterprise Server will normalize any non-alphanumeric character in your account's username into a dash. For example, a username of gregory.st.john will be normalized to gregory-st-john. Note that normalized usernames also can't start or end with a dash. They also can't contain two consecutive dashes.

Usernames created from email addresses are created from the normalized characters that precede the @ character.

If multiple accounts are normalized into the same GitHub Enterprise Server username, only the first user account is created. Subsequent users with the same username won't be able to sign in.

This table gives examples of how usernames are normalized in GitHub Enterprise Server:

Two-factor authentication

When using LDAP or built-in authentication, two-factor authentication is supported. Organization administrators can require members to have two-factor authentication enabled.

Configuring LDAP with your GitHub Enterprise Server instance

After you configure LDAP, users will be able to sign into your instance with their LDAP credentials. When users sign in for the first time, their profile names, email addresses, and SSH keys will be set with the LDAP attributes from your directory.

When you configure LDAP access for users via the Management Console, your seats aren't used until the first time a user signs in to your instance. However, if you create an account manually using site admin settings, the seat is immediately accounted for.

1. In the upper-right corner of any page, click .

   

2. In the left sidebar, click Management Console.

   

3. In the left sidebar, click Authentication.

   

4. Under "Authentication", select LDAP.

   

5. Optionally, select Allow built-in authentication to invite users to use built-in authentication if they don’t belong to your GitHub Enterprise Server instance's identity provider.

   

6. Add your configuration settings.

LDAP attributes

Use these attributes to finish configuring LDAP for your GitHub Enterprise Server instance.

Disabling password authentication for Git operations

Select Disable username and password authentication for Git operations in your LDAP settings to enforce use of personal access tokens or SSH keys for Git access, which can help prevent your server from being overloaded by LDAP authentication requests. We recommend this setting because a slow-responding LDAP server, especially combined with a large number of requests due to polling, is a frequent source of performance issues and outages.

When this option is selected, if a user tries to use a password for Git operations via the command line, they will receive an error message that says, Password authentication is not allowed for Git operations. You must use a personal access token.

Enabling LDAP certificate verification

Select Enable LDAP certificate verification in your LDAP settings to validate the LDAP server certificate you use with TLS.

When this option is selected, the certificate is validated to make sure:

• If the certificate contains at least one Subject Alternative Name (SAN), one of the SANs matches the LDAP hostname. Otherwise, the Common Name (CN) matches the LDAP hostname.
• The certificate is not expired.
• The certificate is signed by a trusted certificate authority (CA).

Enabling LDAP Sync

LDAP Sync lets you synchronize GitHub Enterprise Server users and team membership against your established LDAP groups. This lets you establish role-based access control for users from your LDAP server instead of manually within GitHub Enterprise Server. For more information, see "Creating teams."

To enable LDAP Sync, in your LDAP settings, select Synchronize Emails, Synchronize SSH Keys, or Synchronize GPG Keys .

After you enable LDAP sync, a synchronization job will run at the specified time interval to perform the following operations on each user account:

• If you've allowed built-in authentication for users outside your identity provider, and the user is using built-in authentication, move on to the next user.
• If no LDAP mapping exists for the user, try to map the user to an LDAP entry in the directory. If the user cannot be mapped to an LDAP entry, suspend the user and move on to the next user.
• If there is an LDAP mapping and the corresponding LDAP entry in the directory is missing, suspend the user and move on to the next user.
• If the corresponding LDAP entry has been marked as disabled and the user is not already suspended, suspend the user and move on to the next user.
• If the corresponding LDAP entry is not marked as disabled, and the user is suspended, and Reactivate suspended users is enabled in the Admin Center, unsuspend the user.
• If the corresponding LDAP entry includes a name attribute, update the user's profile name.
• If the corresponding LDAP entry is in the Administrators group, promote the user to site administrator.
• If the corresponding LDAP entry is not in the Administrators group, demote the user to a normal account.
• If an LDAP User field is defined for emails, synchronize the user's email settings with the LDAP entry. Set the first LDAP mail entry as the primary email.
• If an LDAP User field is defined for SSH public keys, synchronize the user's public SSH keys with the LDAP entry.
• If an LDAP User field is defined for GPG keys, synchronize the user's GPG keys with the LDAP entry.

A synchronization job will also run at the specified time interval to perform the following operations on each team that has been mapped to an LDAP group:

• If a team's corresponding LDAP group has been removed, remove all members from the team.
• If LDAP member entries have been removed from the LDAP group, remove the corresponding users from the team. If the user loses access to any repositories as a result, delete any private forks the user has of those repositories.
• If LDAP member entries have been added to the LDAP group, add the corresponding users to the team. If the user regains access to any repositories as a result, restore any private forks of the repositories that were deleted because the user lost access in the past 90 days.

As part of its optimization configuration, LDAP Sync will not transfer your nested team structure. To create child and parent team relationships, you must manually recreate the nested team structure and sync it with the corresponding LDAP group. For more information, see "Creating teams"

Supported LDAP group object classes

GitHub Enterprise Server supports these LDAP group object classes. Groups can be nested.

• group
• groupOfNames
• groupOfUniqueNames
• posixGroup

Viewing and creating LDAP users

You can view the full list of LDAP users who have access to your instance and provision new users.

1. Sign in to your GitHub Enterprise Server instance at http(s)://HOSTNAME/login.

2. In the upper-right corner of any page, click .

   

3. In the left sidebar, click LDAP users.

   

4. To search for a user, type a full or partial username and click Search. Existing users will be displayed in search results. If a user doesn’t exist, click Create to provision the new user account.

   

Updating LDAP accounts

Unless LDAP Sync is enabled, changes to LDAP accounts are not automatically synchronized with GitHub Enterprise Server.

• To use a new LDAP admin group, users must be manually promoted and demoted on GitHub Enterprise Server to reflect changes in LDAP.
• To add or remove LDAP accounts in LDAP admin groups, promote or demote the accounts on GitHub Enterprise Server.
• To remove LDAP accounts, suspend the GitHub Enterprise Server accounts.

Manually syncing LDAP accounts

1. Sign in to your GitHub Enterprise Server instance at http(s)://HOSTNAME/login.

2. In the upper-right corner of any page, click .

   

3. In the search field, type the name of the user and click Search.

   

4. In the search results, click the name of the user.

   

5. In the upper-right corner of the page, click Admin.

   

6. In the left sidebar, click Admin.

   

7. Under "LDAP," click Sync now to manually update the account with data from your LDAP server.

   

You can also use the API to trigger a manual sync.

Revoking access to your GitHub Enterprise Server instance

If LDAP Sync is enabled, removing a user's LDAP credentials will suspend their account after the next synchronization run.

If LDAP Sync is not enabled, you must manually suspend the GitHub Enterprise Server account after you remove the LDAP credentials. For more information, see "Suspending and unsuspending users".