Magpie documentation

Magpie: A RestFul AuthN/AuthZ service

Magpie (the smart-bird)
a very smart bird who knows everything about you.

Magpie is service for AuthN/AuthZ accessible via a RestAPI implemented with the Pyramid web framework. It allows you to manage User/Group/Resource/permission with a postgres database. Behind the scene, it uses Ziggurat-Foundations and Authomatic.

REST API Documentation

The documentation is auto-generated and served under {HOSTNAME}/magpie/api/ using Swagger-UI with tag latest. For convenience, older API versions are also provided.

Build package

At the command line:

$ conda create -n magpie
$ source activate magpie
$ make install

Installation

At the command line:

$ pip install magpie

Usage

To use Magpie in a project:

import magpie

Installation

At the command line:

$ easy_install magpie

Or, if you have virtualenvwrapper installed:

$ mkvirtualenv magpie
$ pip install magpie

Contributing

Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.

You can contribute in many ways:

Types of Contributions

Report Bugs

Report bugs at francois-xavier.derue@crim.ca.

If you are reporting a bug, please include:

  • Your operating system name and version.
  • Any details about your local setup that might be helpful in troubleshooting.
  • Detailed steps to reproduce the bug.

Write Documentation

Magpie could always use more documentation, whether as part of the official Magpie docs, in docstrings, or even on the web in blog posts, articles, and such.

Submit Feedback

The best way to send feedback is to file an issue at francois-xavier.derue@crim.ca.

If you are proposing a feature:

  • Explain in detail how it would work.
  • Keep the scope as narrow as possible, to make it easier to implement.
  • Remember that this is a volunteer-driven project, and that contributions are welcome :)

Get Started!

Ready to contribute? Here’s how to set up magpie for local development.

  1. Clone the keyword_worker_refcom repo from the Mercurial repository.

    hg clone <repo_location>

  2. Install your local copy and use a virtualenv. Assuming you have virtualenv installed, this is how you set up your fork for local development:

    $ cd magpie/
$ virtualenv -p python 3.5 env
$ source env/bin/activate.csh
$ python setup.py develop

    Now you can make your changes locally.

  3. When you’re done making changes, check that your changes pass flake8 and the tests, including testing other Python versions with tox:

    $ flake8 magpie tests
$ python setup.py test
$ tox

    To get flake8 and tox, just pip install them into your virtualenv.

  4. Commit your changes and push your branch to GitHub:

    $ hg commit -m "Your detailed description of your changes."

  5. Submit a pull request to the author.

Pull Request Guidelines

Before you submit a pull request, check that it meets these guidelines:

  1. The pull request should include tests.
  2. If the pull request adds functionality, the docs should be updated. Put your new functionality into a function with a docstring, and add the feature to the list in README.rst.
  3. The tests should work for the specifid version of Python for this project.

Tips

To run a subset of tests:

$ python -m unittest tests.test_magpie

Credits

Development Lead

Contributors

History

0.7.x

Magpie REST API latest documentation

  • add service resource auto-sync feature
  • return user/group services if any sub-resource has permissions
  • add inherited resource permission with querystring (deprecate inherited_<> routes warnings)
  • add flag to return effective permissions from user resource permissions requests
  • hide service private URL on non administrator level requests
  • fix external providers login support (validated for DKRZ, GitHub and WSO2)
  • make cookies expire-able by setting MAGPIE_COOKIE_EXPIRE and provide cookie only on http (JS CSRF attack protection)
  • update MagpieAdapter.MagpieOWSSecurity for WSO2 seamless integration with Authentication header token
  • update MagpieAdapter.MagpieProcess for automatic handling of REST-API WPS process route access permissions
  • update MagpieAdapter.MagpieService accordingly to inherited resources and service URL changes
  • bug fixes related to postgres DB entry conflicting inserts and validations

0.6.x

Magpie REST API 0.6.x documentation

  • add /magpie/api/ route to locally display the Magpie REST API documentation
  • move many source files around to regroup by API/UI functionality
  • auto-generation of swagger REST API documentation
  • unit tests
  • validation of permitted resource types children under specific parent service or resource
  • ServiceAPI to filter read/write of specific GET,POST,etc on route parts
  • ServiceAccess to filter top-level route ‘access’ permission of a generic service URL
  • properly return values of field permission_names under /services/.* routes
  • update make procedures and postgres variables specific to magpie

0.5.x

Magpie REST API 0.5.x documentation

  • independent user/group permissions, no more ‘personal’ group to reflect user permissions
  • service specific resources with service*-typed* resource permissions
  • more verification of resources permissions under specific services
  • reference to root service from each sub-resource
  • inheritance of user and group permissions with different routes
  • improve some routes returned codes, inputs check, and requests formats (JSON)

0.4.x

Magpie REST API 0.4.x documentation

  • default admin permissions
  • block UI view permissions of all pages if not logged in
  • signout clear header to forget user
  • push to Phoenix adjustments and new push button option

0.3.x

Magpie REST API 0.3.x documentation

  • ncWMS support for getmap, getcapabilities, getmetadata on thredds resource
  • ncWMS2 added to default providers
  • add geoserverwms
  • remove load balanced Malleefowl and Catalog
  • push service provider updates to phoenix on service modification or initial setup with getcapabilities for anonymous
  • major update of Magpie REST API 0.2.x documentation to match returned codes/messages from 0.2.0 changes
  • normalise additional HTTP request responses omitted from 0.2.0 (404, 500, and other missed responses)
  • remove internal api call, separate login external from local, direct access to ziggurat login
  • fixes UI “Magpie Administration” to redirect toward home page instead of PAVICS platform
  • fix bug during user creation against preemptive checks
  • bug fixes from 0.2.x series

0.2.0

Magpie REST API 0.2.0 documentation

0.1.1

Magpie REST API 0.1.1 documentation

  • Add edition of service URL via PUT/{service_name}.

0.1.0

Magpie REST API 0.1.0 documentation

  • First structured release.

Indices and tables