Skip to content

/ saml-ldap-team-sync

Sync GitHub teams to groups in Active Directory when using SAML
saml ldap services-toolbox
Python Dockerfile
  1. Python 97.5%
  2. Dockerfile 2.5%
Branch: master
Find file
Clone or download

Clone with HTTPS

Use Git or checkout with SVN using the web URL.

Open in Desktop Download ZIP

Launching GitHub Desktop

If nothing happens, download GitHub Desktop and try again.

Launching GitHub Desktop

If nothing happens, download GitHub Desktop and try again.

Launching Xcode

If nothing happens, download Xcode and try again.

Launching Visual Studio

If nothing happens, download the GitHub extension for Visual Studio and try again.

Latest commit

@primetheus
primetheus Merge pull request #25 from github/primetheus/update-dockerfile 
Update Dockerfile to Python 3.x
Latest commit 994b51c Mar 31, 2020

Files

Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.gitignore Initial commit Nov 12, 2018
Dockerfile Update Dockerfile Mar 27, 2020
LICENSE Initial commit Nov 12, 2018
README.md Update README.md Mar 27, 2020
SAMLTeamSyncAD.py Added logic to support environment secrets Mar 27, 2020
requirements.txt added correct ldap3 module Jan 10, 2019
settings.yml.sample Update settings.yml.sample Mar 27, 2020

README.md

GitHub LDAP Team Sync

This utility is intended to enable synchronization between LDAP/Active Directory and GitHub when using SAML for authentication. This is particularly useful for large organizations with many teams, including nested teams. It supports GitHub.com and GitHub Enterprise

Features

This utility provides the following functionality:

Feature Supported Description
List Yes List users in Active Directory groups or GitHub Teams
Add Users Yes Add users to Teams in GitHub when they are present in the AD group and not in the GitHub Team
Remove Users Yes Remove users from Teams in GitHub when they are not present in the Active Directory group
Sync Users Yes Add or remove users from Teams in GitHub to keep in sync with Active Directory groups
Dynamic Config Yes Utilize a settings file to derive Active Directory and GitHub settings
Email Notifications No Email administrators when the script fails and, optionally, succeeds. This is a WIP
LDAP SSL No SSL or TLS connections. This is a WIP
Slack Messaging No Send a notification to Slack. This is a WIP

Getting Started

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

  • PyGithub
  • python-ldap3
  • PyYAML

Install the required libraries.

pip3 install -r requirements.txt

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

Sample settings.yml

default:
  # This section will be used for sending email alerts
  # when sync succeeds or fails. It is currently not used
  resource_owner_email: <ghe-admin@example.com>
  email_template_success: email-template-success.html
  email_template_failure: email-template-failure.html
  # Slack notifications
  slack_token: <token>
  slack_room: #general
  slack_send_as: github-sync-robot

github:
  # This server URL should be the API endpoint for
  # GitHub. To use on github.com, simply use https://api.github.com
  #server_url: https://api.github.com
  server_url: https://github.example.com/api/v3
  # This is an optional override for the environment secret
  # GITHUB_TOKEN=
  #token: <token>

ldap:
  # A list of server hostnames or IP addresses to try connecting to
  servers:
    - dc1.example.com
    - 10.10.10.10
  # The port to connect to for LDAP
  port: 389
  # If using SSL, specify that port
  ssl_port: 636
  # Specify the path to the AD cert, if using SSL
  ssl_cert:
  # Whether or not to start TLS
  start_tls: false
  # Base DN
  base_dn: DC=example,DC=com
  # The Base DN to lookup users
  user_base_dn: CN=Users,DC=example,DC=com
  # The Base DN for groups
  group_base_dn: OU=Groups,DC=example,DC=com
  # User Filter
  user_filter: (&(objectClass=USER)(sAMAccountName={username}))
  # Optional second User Filter
  user_filter2: (&(objectClass=USER)(dn={userdn}))
  # Group Filter
  group_filter: (&(objectClass=GROUP)(cn={group_name}))
  # Active Directory bind user. This must be in <user>@<domain> format
  bind_user: bind_user@example.com
  # The password to use for binding
  # This is an optional override for the environment secret
  # AD_BIND_PASSWORD=
  #bind_password: asqw!234
  # Set the page size (default is 1000)
  page_size: 1000

Usage Examples

Using the Help

$ python3 ADTeamSyncGHE.py --help
usage: ADTeamSyncGHE.py [-h] [-r] [-a] [-g AD_GROUP] [-s] [-t TEAM] [-o ORG]
                         [-l]

optional arguments:
  -h, --help            show this help message and exit
  -r, --remove          Remove users from the GitHub Team that are not in the
                        AD group
  -a, --add             Add users in the AD group to the GitHub Team
  -g AD_GROUP, --group AD_GROUP
                        The name of the Active Directory group to sync with
                        GitHub
  -s, --sync            Perform a full sync, removing users from the GitHub
                        team that are not present in the AD group, and adding
                        users to the GitHub Team that are in the AD group
                        missing in the Team
  -t TEAM, --team TEAM  The name of the GitHub Team to sync users with. 
                        This is case-sensitve, and needs quotations if the team name has spaces.
  -o ORG, --org ORG     The name of the GitHub Organization where the Teams
                        reside
  -l, --list            List users in groups/teams and exit. No changes are
                        made
  -i INITFILE, --init INITFILE
                        Full path to settings.yml file. Default is 
                        settings.yml in your current directory

Listing Active Directory Group Members

This option will list members in Active Directory groups

$ python3 SAMLTeamSyncAD.py --list --group ADGroupA
Succesfully authenticated
AD Group: ADGroupA
---------------
ghusera

Listing GitHub Team Members

This option will list members in GitHub teams

$ python3 SAMLTeamSyncAD.py --list --team GHETeamA
GitHub Team: GHETeamA
---------------
primetheus

Add Users to GitHub Teams from AD

This option will only add users to GitHub teams when they are found in Active Directory. It will not remove users from teams

$ python3 SAMLTeamSyncAD.py --add --team GHETeamA --group ADGroupA

-- OR --
$ python3 SAMLTeamSyncAD.py -a -t GHETeamA -g ADGroupA

Full User Sync from Active Directory Group to GitHub Team

This option will add users to GitHub teams when found in Active Directory, as well as remove users from GitHub teams when they don't exist in the AD group.

$ python3 SAMLTeamSyncAD.py --sync --team GHETeamA --group ADGroupA
$ python3 SAMLTeamSyncAD.py -s -t GHETeamA -g "AD Group A"
You can’t perform that action at this time.