GitHub Active Directory Connector
GitHub Connector is a simple application for connecting GitHub.com organizations to internal Active Directory accounts. It grants access to new hires, removes access from terminated employees, and enforces a set of GitHub membership rules.
GitHub Connector is a simple application for managing GitHub.com organizations using your internal Active Directory server. The Connector, an app which runs internally, allows you to:
- Automatically remove terminated employees from GitHub organization
- Audit each GiHub account for compliance with policies such as:
- Enable one-step GitHub organization invite & acceptance for approved employees
Future feature ideas:
- Use AD group membership to control GitHub Organization and GitHub Team membership assignment
- Detect duplicate/weak SSH keys across all accounts
Table of contents
- Quick Start
- Copyright and License
- Clone the repo:
git clone git://github.com/rapid7/github-connector.git
- Run bundler:
- Create database:
rake db:create db:migrate
- Start application:
- Navigate to http://localhost:5000
GitHub Connector is a Rails 4 application. It runs on Ruby > 2.0. All settings are stored in a PostgreSQL database.
- Install Ruby 2.x. We recommend RVM.
- If using RVM, create a gemset:
rvm gemset create github-connector && rvm gemset use github-connector.
- Install required gem dependencies:
- Copy the
config/secrets.yml. Generate new random secrets with
rake secretand paste them in
- Copy the
config/database.yml. Update the file with your database settings.
- Create the database:
rake db:create db:migrate
To ease development, GitHub Connector emulates Active Directory using OpenLDAP. In development, OpenLDAP will automatically be populated with fake data.
OpenLDAP is pre-installed on OSX. On Linux, install OpenLDAP. For example, on Ubuntu use:
- Install OpenLDAP:
sudo apt-get install slapd ldap-utils
slapdas we will run our own copy:
service slapd stop
- Apparmor prevents us from running the OpenLDAP server with custom a configuration. To get around this, put apparmor into complain mode:
sudo apt-get install apparmor-utils && sudo aa-complain /usr/sbin/slapd
There are several ways to run a Rails application in production. We include a chef cookbook that installs and configures the GitHub Active Directory Connector.
In a development environment, use
foreman to start Rails (via Puma) and LDAP:
Visit http://localhost:5000 in your favorite browser.
The first time you access the application you will be greeted with the Setup Wizard. Please prevent others from accessing the application until you complete the Setup Wizard, as there is no authentication/authorization until the wizard is complete.
The Setup Wizard defaults to the built-in LDAP configuration. Continue with the test configuration, or update the settings to use your Active Directory server.
Development user accounts
When using the built-in LDAP configuration, the following accounts exist (username / password):
- hsimpson / 123456
- msimpson / 123456
- bsimpson / 123456
- lsimpson / 123456
Connecting to GitHub
Visit the Settings page (/settings) to configure your connection with GitHub.com.
TODO - More information on configuring GitHub.
GitHub Connector syncs information from Active Directory and the GitHub API to the local database. Synchronization is triggered with:
GitHub Connector disables organization access based on rules. Rules are configured via the Settings page. New rules can be added by extending the
Rules::Base class in the
Run tests with:
Coverage reports are generated in the
Generate documentation with:
doc/index.html with your favorite browser.
GitHub Connector supports customization via rails engines. If you need to make modifications specific to your organization that don't make sense in an open source repo, use a rails engine.
Creating a new engine is easy:
rails plugin new vendor/engines/github_connector_custom_ext --full
All engines in the
Pull requests welcome!
Copyright and License
Copyright 2014 Rapid7, Inc.
Released under the MIT License.