The GitHub Active Directory Connector allows managing GitHub organizations with Active Directory.
Ruby HTML Other
Latest commit b674ce2 Jan 24, 2017 @wwalker-r7 wwalker-r7 committed on GitHub Fixing README typo
Permalink
Failed to load latest commit information.
app
bin
config
cookbook
db
ldap
lib
log
public
spec
vendor/assets
.gitignore
.rspec
.ruby-gemset
.ruby-version
.travis.yml
.yardopts
CHANGELOG.md
Gemfile
Gemfile.lock
LICENSE
Procfile
README.md
Rakefile
config.ru

README.md

GitHub Active Directory Connector

Build Status

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:

Table of contents

Quick start

  • Clone the repo: git clone git://github.com/rapid7/github-connector.git
  • Run bundler: bundle install
  • Copy config/secrets.yml.example to config/secrets.yml
  • Copy config/database.yml.example to config/database.yml and update
  • Create database: rake db:create db:migrate
  • Start application: foreman start
  • Navigate to http://localhost:5000

Installation

GitHub Connector is a Rails 4 application. It runs on Ruby > 2.0. All settings are stored in a PostgreSQL database.

  1. Install Ruby 2.x. We recommend RVM.
  2. If using RVM, create a gemset: rvm gemset create github-connector && rvm gemset use github-connector.
  3. Install required gem dependencies: bundle install
  4. Copy the config/secrets.yml.example file to config/secrets.yml. Generate new random secrets with rake secret and paste them in config/secrets.yml
  5. Copy the config/database.yml.example file to config/database.yml. Update the file with your database settings.
  6. Create the database: rake db:create db:migrate

Development Environment

OpenLDAP

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:

  1. Install OpenLDAP: sudo apt-get install slapd ldap-utils
  2. Stop slapd as we will run our own copy: service slapd stop
  3. 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

Running

Production

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.

Development

In a development environment, use foreman to start Rails (via Puma) and LDAP:

foreman start

Visit http://localhost:5000 in your favorite browser.

Configuration

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.

Synchronization

GitHub Connector syncs information from Active Directory and the GitHub API to the local database. Synchronization is triggered with:

rake sync

Rules

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 lib/rules directory.

Tests

Run tests with:

rspec

Coverage reports are generated in the coverage directory.

Documentation

Generate documentation with:

yard

Open doc/index.html with your favorite browser.

Customizing

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 vendor/engine directory will be automatically loaded. An engine's javascript and CSS will be included in application.js and application.css.

Contributing

Pull requests welcome!

Copyright and License

Copyright 2014 Rapid7, Inc.

Released under the MIT License.