LDAP lets you authenticate GitHub Enterprise against your existing accounts and centrally manage repository access.

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.

Supported LDAP services

GitHub Enterprise integrates with these LDAP services:

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

Username considerations with LDAP

GitHub Enterprise usernames can only contain alphanumeric characters and dashes (-). GitHub Enterprise 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 with a dash.

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 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:

Username Normalized username Result
Ms.Bubbles ms-bubbles This username is created successfully.
!Ms.Bubbles -ms-bubbles This username is not created, because it starts with a dash.
Ms!Bubbles ms-bubbles This username is not created. Although the normalized username is valid, it already exists.
Ms.Bubbles@example.com ms-bubbles This username is not created. Although the normalized username is valid, it already exists.

Configuring LDAP with your GitHub Enterprise 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 license 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 license seat is immediately accounted for.

Warning: Before configuring LDAP on your Enterprise instance, make sure that your LDAP service supports paged results.

  1. Access the Management Console.

  2. In the left sidebar, click Authentication. Authentication tab

  3. Under "Authentication", select LDAP. LDAP select

  4. Add your configuration settings.
Attribute name Type Description
Host Required The LDAP host, e.g. ldap.example.com or 10.0.0.30. If the hostname is only available from your internal network, you may need to configure your Enterprise instance's DNS first so it can resolve the hostname using your internal nameservers.
Port Required The port the host's LDAP services are listening on. Examples include: 389 and 636 (for LDAPS).
Encryption Required The encryption method used to secure communications to the LDAP server. Examples include plain (no encryption), SSL/LDAPS (encrypted from the start), and StartTLS (upgrade to encrypted communication once connected).
Domain search user Required The LDAP user that performs user lookups to authenticate other users when they sign in. This is typically a service account created specifically for third-party integrations. Use a fully qualified name, such as cn=Administrator,cn=Users,dc=Example,dc=com. With Active Directory, you can also use the [DOMAIN]\[USERNAME] syntax (e.g. WINDOWS\Administrator) for the domain search user with Active Directory.
Domain search password Required The password for the domain search user.
Administrators group Optional Users in this group are promoted to site administrators when signing into your appliance. If you don't configure an LDAP Administrators group, the first LDAP user account that signs into your appliance will be automatically promoted to a site administrator.
Domain base Required The fully qualified Distinguished Name (DN) of an LDAP subtree you want to search for users and groups. You can add as many as you like; however, each group must be defined in the same domain base as the users that belong to it. If you specify restricted user groups, only users that belong to those groups will be in scope. We recommend that you specify the top level of your LDAP directory tree as your domain base and use restricted user groups to control access.
Restricted user groups Optional If specified, only users in these groups will be allowed to log in. 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 will be able to sign in to your GitHub Enterprise instance.
User ID Required The LDAP attribute that identifies the LDAP user who attempts authentication. Once a mapping is established, users may change their GitHub Enterprise 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.
Profile name Optional The name that will appear on the user's GitHub Enterprise profile page. Unless LDAP Sync is enabled, users may change their profile names.
Emails Optional The email addresses for a user's GitHub Enterprise account.
SSH keys Optional The public SSH keys attached to a user's GitHub Enterprise account. The keys must be in OpenSSH format.

Enabling LDAP Sync

Select Synchronization in your LDAP settings to enable LDAP Sync.

Synchronization check box

LDAP Sync lets you synchronize GitHub Enterprise team members and team roles 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.

Note:

When LDAP Sync is enabled, any user with permission to create a team or organization can search the LDAP directory for groups to map the team to.

This has the potential to disclose sensitive organizational information to contractors or other unprivileged users, including:

  • The existence of specific LDAP Groups visible to the Domain search user.
  • Members of the LDAP group who have GitHub Enterprise user accounts, which is disclosed when creating a team synced with that LDAP group.

If disclosing such information is not desired, your company or organization should restrict the permissions of the configured Domain search user in the admin console. If such restriction isn't possible, contact GitHub Enterprise support.

Supported LDAP group object classes

GitHub Enterprise 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 from the Site Admin dashboard.

  1. As a site admin, sign in to your GitHub Enterprise instance at http(s)://[hostname]/login.

  2. In the upper-right corner of any page, click . Rocketship icon for accessing site admin settings

  3. In the left sidebar, click LDAP users. LDAP users tab

  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. LDAP search

Updating LDAP accounts

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

Manually syncing LDAP accounts

  1. As a site admin, sign in to your GitHub Enterprise instance at http(s)://[hostname]/login.

  2. In the upper-right corner of any page, click . Rocketship icon for accessing site admin settings

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

  4. In the left sidebar, click Admin. Admin Tools

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

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

Fully revoking access to your 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 account after you remove the LDAP credentials. For more information, see "Suspending and unsuspending users".