GitHub LDAP Team Sync

This utility is intended to enable synchronization between LDAP/Active Directory and GitHub. This is particularly useful for large organizations with many teams that either do not use LDAP for authentication, or else do not use the team sync feature for one reason or another. It supports both GitHub.com and GitHub Enterprise, but it will need to live in a location that can access your LDAP servers.

Features

This utility provides the following functionality:

Permissions and Events

This application will need to be able to manage teams in GitHub, so the following events and permissions will be required. For more information on how to create a GitHub App, please visit https://developer.github.com/apps/building-github-apps/creating-a-github-app/

Getting Started

To get started, ensure that you are using Python 3.4+. The following additional libraries are required:

• Flask
• github3.py
• python-ldap3
• APScheduler
• python-dotenv
• PyYAML

Install the required libraries.

pipenv install

Once you have all of the requirements installed, be sure to edit the .env to match your environment.

Sample .env for GitHub App settings

## GitHub App settings
WEBHOOK_SECRET=development
APP_ID=12345
PRIVATE_KEY_PATH=.ssh/team-sync.pem
GHE_HOST=github.example.com

Sample .env for Active Directory

LDAP_SERVER_HOST=dc1.example.com
LDAP_SERVER_PORT=389
LDAP_BASE_DN="DC=example,DC=com"
LDAP_USER_BASE_DN="CN=Users,DC=example,DC=example"
LDAP_GROUP_BASE_DN="OU=Groups,DC=example,DC=example"
LDAP_USER_FILTER="(objectClass=person)"
LDAP_USER_ATTRIBUTE=sAMAccountName
LDAP_USER_MAIL_ATTRIBUTE=mail
LDAP_GROUP_FILTER="(&(objectClass=group)(cn={group_name}))"
LDAP_GROUP_MEMBER_ATTRIBUTE=member
LDAP_BIND_USER="bind-user@example.com"
LDAP_BIND_PASSWORD="p4$$w0rd"
LDAP_SEARCH_PAGE_SIZE=1000

Sample .env for OpenLDAP

LDAP_SERVER_HOST=dc1.example.com
LDAP_SERVER_PORT=389
LDAP_BASE_DN="dc=example,dc=com"
LDAP_USER_BASE_DN="ou=People,dc=example,dc=com"
LDAP_GROUP_BASE_DN="ou=Groups,dc=example,dc=com"
LDAP_USER_FILTER="(&(objectClass=person)({ldap_user_attribute}={username}))"
LDAP_USER_ATTRIBUTE=uid
LDAP_USER_MAIL_ATTRIBUTE=mail
LDAP_GROUP_FILTER="(&(objectClass=posixGroup)(cn={group_name}))"
LDAP_GROUP_MEMBER_ATTRIBUTE=memberUid
LDAP_BIND_USER="cn=admin,dc=example,dc=com"
LDAP_BIND_PASSWORD="p4$$w0rd"
LDAP_SEARCH_PAGE_SIZE=1000

Sample .env settings for additional settings

## Additional settings
CHANGE_THRESHOLD=25
OPEN_ISSUE_ON_FAILURE=true
REPO_FOR_ISSUES=github-demo/demo-repo
ISSUE_ASSIGNEE=githubber
SYNC_SCHEDULE=0 * * * *
TEST_MODE=false

Sample syncmap.yml custom mapping file

---
mapping:
  - github: demo-team
    ldap: ldap super users
  - github: demo-admin-2
    ldap: some other group

Usage Examples

Start the application from Pipenv

This example runs the app in a standard Flask environment

$ pipenv run flask run --host=0.0.0.0 --port=5000

Or you can run the app with Python directly

pipenv run python app.py

Credits

This project draws much from:

• Flask-GitHubApp
• github3.py