This application introduces "push-style" management of permissions for github and google apps (todo). The goal is to store yaml files that define our github teams and users, and apply the permissions once some changes are pushed to those files.
This makes managing permissions very easy, and also makes it possible for your users to propose changes (via commit to permissions repo or pull request).
Sample permissions directory looks like this: https://github.com/netguru/access-permissions-sample
- [Setup] (#setup)
- [Github] (#github)
- [Adding new user] (#adding-new-user)
- [Adding / editing github teams] (#adding--editing-github-teams)
- [User naming within permissions repo] (#user-naming-within-permissions-repo)
- [Adding new repositories] (#adding-new-repositories)
- [Deleting users] (#deleting-users)
- [Deleting teams] (#deleting-teams)
- [Rollbar] (#rollbar)
- [Google apps] (#google-apps)
- [Adding groups] (#adding-groups)
- [Adding group aliases] (#adding-group-aliases)
- [Group settings] (#group-settings)
- [Privacy] (#privacy)
- [Archive] (#archive)
- [Default config] (#default-config)
- [Removing groups] (#removing-groups)
- [Creating google accounts] (#creating-google-accounts)
- [Service Account authorization] (#service-account-authorization)
- [Flow for applying the changes.] (#flow-for-applying-the-changes)
- [FAQ] (#faq)
Please, see at development documentation.
In order to create new github user, create a file in members
directory.
The file should be named using this pattern first_name.last_name.yml
.
More details, and some example here
Team data files include:
- team name
- team permission level
- team members list
Sample team file: https://github.com/netguru/access-permissions-sample/blob/master/github_teams/team-a.yml
Once such file is pushed to the permissions repository a team-a will be created with jane and john as members. All members are going to be given push access to ‘sample-repo’.
Users in teams files are referenced by their data file name (first_name.last_name) instead of being referenced by github handles. This makes it’s easy to read the team file and actually see who has access where without confusion - this is also very useful from security perspective in larger organizations.
Remember you have to first add user to users directory before adding him to a team
Adding a repository that does not exist in to the team file will create an empty repository with that name.
- remove john.doe from every group file and github teams file
- remove john.doe file from users directory
Delete team file from repository and go to github/diff screen. It should display teams that do not have their files in permissions repository any more. You can confirm and delete them by pressing delete button under 'stranded' teams.
We need organization token in order to perform teams management with Rollbar. You can find the token here
In order to add new rollbar team, please create a file in rollbar_teams/
directory. It should look like this:
---
name: cool name for a foo project
members:
- john.doe
- jane.doe
projects:
- foo-project
Adding google group is very similar to adding github team - just create group file in google_groups
directory and sync your changes. The file name will be the name of the group.
You can find sample group here: https://github.com/netguru/access-permissions-sample/blob/master/google_groups/sample-group.yml
Remember that anywhere within the app, users are referenced by their data file name and not emails or logins.
Special aliases
key in group file allows you to controll group aliases.
See example here: https://github.com/netguru/access-permissions-sample/blob/master/google_groups/sample-group.yml#L6
Define the level of privacy for your groups. There are two settings:
private: true
or
private: false
when a google group is set to open (private: false
) it means that:
- all in domain can view this group
- it is shown in a group directory
when a google group is set to closed (private: true
) it means that:
- only members of the group can view it
- it is hidden from a group directory
Define if messages in a group should be archived
archive: true/false
you can define the default behavior of privacy and archive by creating a file in your permissions repo google_defaults.yml
.
group:
private: false
archive: false
To remove google group just remove it's file from the google groups folder. The application should display "stranded" groups on diff screen. You can confirm the deletion there.
To create a new google account you need to add new yaml file with user. The file should be created inside of directory named the same like company from config.yml
(e.g. permissions/users/company_name/firstname.lastname.yml
).
Filename will be an account login (e.g. if your main_domain is company_name.com
created email will look like firstname.lastname@company_name.com
).
Remember to include in the yml file following attributes:
name:
which should be a full name of the persongithub
which is github login of the person (if you use that service)
You can find sample user file here: https://github.com/netguru/access-permissions-sample/blob/master/users/user_group/jane.kowalski.yml
Since the file is added you will see it under header 'Missing user's account' in google show diff google/show_diff
action. Then to create missing accounts just click button 'Create accounts'.
The application will:
- create missing accounts,
- generate 2step codes,
- reset password (user will be asked to change it while first login),
- will post gmail filters
- and finally will send email to email specified in
AppConfig.office_email
containing details necessary to login, 2step codes and short instruction (fromAppConfig.google.email.account_using_instruction
).
You might want to authorize more people to apply changes to some google groups but you are reluctant to provide them with admin rights. In that case you can enable a feature use_service_account: true
to use a Service Account as an authorization strategy.
Then you set who and what can sync: (in sec_config.yml)
- what google groups can manage sync:
google:
managers:
groups:
- 'support'
- 'managers'
- 'founders'
- what group emails can they manage (these are turned into regexp later on):
google:
groups:
- .*-supported@.*
- special-group-managed-by-support.*
Now you also need to activate a service account on google and configure it properly:
- go to console.google.com
- go to credentials - and create a new client id http://screencast.com/t/PjRw88ySI
- copy service account email to sec_config.yml (google.service_account_email)
- copy p12 file to server
- set p12_key_path and secret in sec config
- go to admin.google.com
- go to security/show more/advanced/Manage API client access
- http://screencast.com/t/5gIEyb0vtl
- setup groups whitelists (which groups can be managed by the support?)
The way how service accounts work is that it authenticates through p12 key and then can use google API as another user. So to have this working we need to create a google account with admin rights that the service account could use. You set that account in sec_config.yml
as a supporter_email
key.
Once you are done editing / creating the files you should apply new permissions:
- push the changes to permissions directory
- have somebody from owners team visit the access app and review the changes
- once the review it’s done she/he can press “Confirm changes” link
- access app will pull the permissions repo and apply the changes to github.
A good idea is to use rake notify
in your CI to notify the owners that changes to the permissions repo were made.
- check
access/config/config
google: main_domain: netguru.org if domain is really used in setup project. - check
access/config/sec_config
google: client_id: and client_secret: if equals settings from console.developers.google.com, tabs: Apis -> Credentials -> OAuth. - check if you try to login with the proper user. You must login with administrator of the account.
- remember to restart server and clean session after each attempt to fix from above steps.
- to mitigate this problem you should change quotas - per-user limit:
- go to
https://console.google.com
and and find the app you're using for access - go to APIs/EnabledAPIs/Groups Settings API/Quotas
- edit
Per-user limit
setting, and rise the request limit to something more reasonable (eg. 1000) - do the same for Admin SDK
- go to