dropbox / merou

Permission management service

merou

Deprecation

The Merou/Grouper project has been deprecated. You may continue to use and maintain forks of the project, but the Dropbox team will no longer contribute to this repository.

Description

Merou is an application to allow users to create and manage memberships to their own groups. It requires Python 3.7 or later.

Note: We renamed the project to avoid a namespace conflict, but it isn't reflected in the codebase yet.

Installation

Standard Python package installation instructions apply. You will need Python 3 and development headers for MySQL.

On Debian-based systems:

apt-get install libmysqlclient-dev libpython3-dev libcurl4-openssl-dev libssl-dev python3-pip
pip3 install -e git+https://github.com/dropbox/merou#egg=grouper

Next you need to configure grouper to find a SQL-style backing database and stand up processes to serve the read-write web UI and read-only programmatic API. There's an sample configuration file, suitable for local development and testing, in config/dev.yaml.

Running a Test instance

Grouper runs behind a reverse proxy that handles authentication and so expects a valid, authenticated, user account. I've included a test proxy for running on development instances.

Creating a development instance:

export PYTHONPATH=$(pwd)
export GROUPER_SETTINGS=$(pwd)/config/dev.yaml

# Setup the database.
bin/grouper-ctl sync_db

## You can either run all the various servers and the reverse-proxy
## via a helper script:
tools/run-dev --user $[e-mail]

## Or separately:
# Run the development reverse proxy
bin/grouper-ctl -vv user_proxy $[e-mail]

# Run the frontend server
bin/grouper-fe -vv

# Run the graph/api server
bin/grouper-api -vv

Setting up the first groups and permissions

In order to bootstrap your new Grouper environment, you will want to create a user for yourself and add it to the grouper-administrators group.

export PYTHONPATH=$(pwd)
export GROUPER_SETTINGS=$(pwd)/config/dev.yaml

bin/grouper-ctl -vv\
    user create $[e-mail]

# Give the user administrative access to the Grouper instance
bin/grouper-ctl -vv \
    group add_member --owner grouper-administrators $[e-mail]

Running the tests

Some tests require a recent (>= 2.31) version of chromium-driver, which can be installed via apt or Homebrew:

apt install chromium-driver

(This may be called chromium-chromedriver in older versions.) Once chromium-driver is installed, the tests can be run using pytest:

pip install -r requirements.txt
pip install -r requirements-dev.txt
pytest
flake8
mypy .

If you see test failures and suspect incompatible library versions (e.g., an existing tornado install at a different major release than that in our requirements.txt), then you can try using a virtual environment.

$ virtualenv ~/merou-venv -p /usr/bin/python3
$ source ~/merou-venv/bin/activate
(merou-venv) $ pip install -r requirements.txt
(merou-venv) $ pip install -r requirements-dev.txt
(merou-venv) $ pytest
(merou-venv) $ deactivate
$

All Merou code is formatted with black, which is installed by the requirements-dev.txt requirements file for Python 3. After installation, you can reformat all source code with:

black .

All new code must be formatted with the version of black indicated in requirements-dev.txt in order to pass Travis CI tests.

merou's Issues

Recommended way to push identity from Merou to IdP?

Good day Dropbox crew!

Merou appears to solve some of the issues with identity that we experience within my organization (another tech company of roughly your size). In fact, I learned about it from a former Dropbox employee who had previously used it and is a big fan.

What I'm struggling with a bit is how you harness Merou as the system of record when it comes time to interface with services like AWS, cloud apps, etc. My guess is that you've (privately) built a plugin to capture events and push them to Okta, either via its API or by SCIM, and then you federate from there. That's currently how I'm considering approaching this problem, but if there's some other way that I'm just missing, or simply another practice you'd advocate for, I'd love to be corrected/learn more before I head down that path.

If you'd like to discuss in more detail in a less public setting: https://keybase.io/matthewsullivan

Thank you in advance for your time!