LDAP is a popular application protocol for accessing and maintaining directory information services, and is one of the most common protocols used to integrate third-party software with large company user directories. Any company using Microsoft's Active Directory will likely have used LDAP to integrate with other products.
GitHub Enterprise supports LDAP for authentication.
Overview
Once you have successfully configured LDAP authentication, users will sign into your GitHub Enterprise appliance with their LDAP credentials. Users will have their profile names, email addresses, and SSH keys set with user field values from your LDAP server when they sign in for the first time.
GitHub Enterprise saves the distinguished name of the LDAP entry that corresponds to each user account. In other words, LDAP users can change their usernames and still authenticate with your LDAP server correctly.
You can see the full list of LDAP users that can sign into your appliance at any time. Note that the actual user accounts on GitHub Enterprise will not be created until someone has signed into the accounts or a site administrator has manually created them. You may wish to manually create LDAP user accounts in advance (from the list of LDAP users) so that you don't have to wait for them to sign in for the first time before you add them to teams and set up project permissions.
Account synchronization
GitHub Enterprise only uses LDAP during the initial account creation process; changes to LDAP accounts are not automatically synchronized with their corresponding user accounts on your GitHub Enterprise instance. Specifically:
- When you change the LDAP admin group configured with your GitHub Enterprise instance, you will need to promote the Enterprise accounts in the new admin group and demote the Enterprise accounts in the old admin group.
- When you add LDAP accounts to LDAP admin groups, you will need to promote the corresponding Enterprise accounts.
- When you remove LDAP accounts from LDAP admin groups, you will need to demote the corresponding Enterprise accounts.
- When you remove LDAP accounts, you will need to suspend the corresponding Enterprise accounts.
License seats
An LDAP user account does not take up a license seat until someone signs into it at least once or it is created by a site administrator (from the list of LDAP users).
Paged results
GitHub Enterprise requires directory services to support paged results.
Valid usernames
If your LDAP unique IDs contain any non-alphanumeric characters other than hyphens, GitHub Enterprise will automatically replace those characters with hyphens. For example, an LDAP unique ID of firstname.lastname will be converted—or "normalized"—into a GitHub Enterprise username of firstname-lastname. Note that this may cause multiple LDAP account names (such as firstname.lastname and firstname_lastname) to be normalized into the same Enterprise account name.
Group definitions
GitHub Enterprise supports LDAP group definitions that use groupOfNames, groupOfUniqueNames, or posixGroup. Group definitions can be nested.
Site administrators
If you don't configure an LDAP admin group, the first LDAP user account that signs into your appliance will be automatically promoted to a site administrator. Otherwise, every account in the LDAP admin group will be automatically promoted to a site administrator when signing into your appliance for the first time.
