github-agora

agora

This is a simple node.js app to automatically handle members of a github organization. It automates how to join to and leave from a github organization, avoiding all manual interventions from organization owners. It can be used in multi-company environments too.

Installation

git clone https://github.com/TDAF/agora.git
cd agora
npm install

Configuration

The file config.js provides the following config options:

'use strict';
 
var config = {
  port: 3000, //port where the app will be listening
  apiBaseURL: 'http://127.0.0.1:3000/agora/api/v1/members/', //base URL for members API
  realm: 'mycompany', //identify your company realm for API access authentication
  membersApiPageSize: 100, // API page size for going thru members list
  clients: { //list here the clients that will get access to app API, protected by HTTP basic auth
    cleaner: {
      secret: 'mysecret',
      company: 'A'
    },
    test: {
      secret: 'secretString',
      company: 'B'
    }
  },
  github: { //app credentials to consume github API
    clientId: '',
    clientSecret: '',
    adminToken: '', //token to act on behalf of an orga's owner
    callbackURL: 'http://localhost:3000/agora/auth/github/callback',
    orga: 'ouhyeah' //Name of the github organization to handle
  },
  email: {
    host: '',
    port: 25,
    from: '[e-mail]',
    subject: 'A new member has joined github',
    text: 'The github user {username} with validated email {email} has been invited to join your team {team} at https://github.com/{orga}'
  },
  companies: { // companies configuration
    TID: { // One company
      team: 'Telefonica I+D', // name of the team where company users will be invited to join
      adminEmail: '', // email to send notifications to on new users that are invited to join
      allowedDomains: ['gmail.com', 'telefonica.com'], // allowed email domains
      isUserValidService: { // URL of is-user-valid service to check user validity (this constrain adds to the previous one)
        url: '',
        clientId: '',
        clientSecret: ''
      }
    },
    Tokbox: { // Another company
      team: 'Tokbox',
      adminEmail: '',
      allowedDomains: ['tokbox.com']
    },
    MailCo: {
      team: 'Otro',
      adminEmail: '',
      allowedDomains: ['gmail.com']
    }
  },
  userDatabase: './members' //where the database is
};
 

Running the app

First thing you need to do is to create a Developer Application in github.com and then configure agora with:

• the name of the orga you want to manage (note you must be an owner of that orga).
• a Github personal access token identifying you. This token will provide admin access to the agora app so you have to assign admin:org scope to this token at github.
• clientId and secret of the app you have just created.
• the callback URL you want github to redirect authenticated users to. Note this must be exactly the same one configured as Authorization callback URL at github.
• the list of companies you want to manage

Now you can run the app as follows:

./bin/agora | tee -a [path_to_file_where_logs_will_be_stored] > /dev/null &

The app writes logs to standard output and with the above we redirect to a file.

How it works

Agora uses github APIs:

• on behalf of the end user to discover her email addresses, as stored in the github profile.
• on behalf of an organization's owner, to consult, invite and remove members as required.

When a user wants to join, it gets the user's validated email addresses and checks at least one of them belongs to an allowed domain. If there is additional configuration to check agains an is-user-valid service, those emails that belong to an allowed domain are validated against the company endpoint (e.g. this basically checks against LDAP behind the scenes). If all validations are correct, the users is invited to join.

Additionally, the app stores locally the list of users that have joined the orga (i.e. members), along with their valid email address and company, and exposes a REST API to GET and DELETE these members. Deleting a user through the API also removes that user from the github orga.

If you also want to automate members removal once they no longer belong to one of the allowed companies/domains, you can periodically run the agora-cleaner script. This script makes use of the REST API to go through all existing members and check if they are still valid user for their companies, as instructed from an is-valid-endpoint exposed by each company. If the user is not longer valid, it is deleted from the orga through the REST API.

To run the agora-cleaner script, simply use:

node lib/agora-cleaner.js | tee -a path_to_file_where_logs_will_be_stored > /dev/null &

Caveats

This version of the app uses nedb as members database. This greatly simplifies development and operation as we can work with regular files instead of having to install an external database. On the other hand, this has one major downside: only one process can access to the database. Thus:

• the app cannot be deployed in HA
• the app can only run on one CPU

For regular environments, to overcome the HA limitation, you can always run the app with a watch dog, such as monit. Additinally, since this is a management app, no high usage rates are expected and one core seems more than enough.

However, if you can't live with the above limitations, substituting nedb with mongodb would be really simple (open us an issues and/or PRs are wellcome!).

License

Copyright 2015 Telefónica Investigación y Desarrollo, S.A.U

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.