## Quickstart for users
So, your friendly neighborhood mongogranter says you know have access to a
database through your email address. What now? First, install mongogrant:
```bash
pip install mongogrant
```
Next, request a token link to be sent to your email:
```
mgrant init mcurie@espci.fr \
--endpoint https://grantmedb.materialsproject.org
```
Click the link in your email to prove you're you, copy the fetch token from the
loaded page, and then run:
```
mgrant settoken wh054900d70k3ny35y0u423
```
Finally, get credentials for your database. Here, Marie is asking mongogrant to
print out db.json and my_launchpad.yaml starter files for
[FireWorks](https://materialsproject.github.io/fireworks/) and
[atomate](https://atomate.org/):
```
mgrant db mongodb03.nersc.gov fw_mc_polonium \
--role readWrite \
--atomate-starters
```
## About mongogrant
Mongogrant is a utility to grant username and password
credentials for read and readWrite roles on various databases
on various hosts to owners of email addresses.
A server administrator has fine-grained control via
allow/deny rules for granting tokens and credentials.
People request an email that contains a one-time link. That
link gives a user a fetch token. All tokens expire and
expiration time is customizable. People then use the
mongogrant client to make requests like
```python
from mongogrant.client import Client
# config file on disk has tokens and host/db aliases
# `Client()` with no args looks to
# ~/.mongogrant.json for config
client = Client()
# No config yet? Set one up with at least one remote for fetching credentials
# See below for how to obtain <FETCH_TOKEN> for a given <ENDPOINT>.
client.set_remote("https://grantmedb.materialsproject.org", "<FETCH_TOKEN>")
# Set some aliases if you'd like:
client.set_alias("dev", "mongodb03.nersc.gov", "host")
client.set_alias("prod", "mongodb04.nersc.gov", "host")
client.set_alias("fireworks", "fw_dw_phonons", "db")
# pymongo.database.Database with read role
source_db = client.db("ro:dev/fireworks")
# readWrite role: config stores "prod" host alias and "fireworks" db alias
target_db = client.db("rw:prod/fireworks")
# ...Do database stuff!
```
One can also go entirely through a running app's API:
```bash
> # Using the HTTPie command line HTTP client (https://httpie.org/)
> # Install via `{brew,apt-get,pip,...} install httpie`
> http GET https://grantmedb.materialsproject.org/gettoken/<YOUR_EMAIL>
HTTP/1.1 200 OK
Connection: keep-alive
Content-Length: 59
Content-Type: application/json
Date: Thu, 17 May 2018 18:05:30 GMT
Server: nginx/1.10.3
{
"msg": "Sent link to <YOUR_EMAIL> to retrieve token."
}
> http GET https://grantmedb.materialsproject.org/verifytoken/<VERIFY_TOKEN>
HTTP/1.1 200 OK
Connection: keep-alive
Content-Encoding: gzip
Content-Type: text/html; charset=utf-8
Date: Thu, 17 May 2018 18:06:17 GMT
Server: nginx/1.10.3
Transfer-Encoding: chunked
Fetch token: <FETCH_TOKEN> (expires 2018-06-19 18:05:30.508000 UTC)
> # end-of-line "\" below only necessary if command spans two lines.
> http --form POST https://grantmedb.materialsproject.org/grant/<FETCH_TOKEN> \
> role=readWrite host=mongodb03.nersc.gov db=dw_phonons
HTTP/1.1 200 OK
Connection: keep-alive
Content-Length: 108
Content-Type: application/json
Date: Thu, 17 May 2018 18:11:22 GMT
Server: nginx/1.10.3
{
"password": "<PASSWORD>",
"username": "dwinston_lbl.gov_readWrite"
}
>
```
You can run a "server" on your laptop in a Jupyer notebook
and manage allow/deny rules, grant / revoke grants of
credentials, etc. A small Flask app
is included as an example for deploying a server to which
clients can connect to obtain tokens and credentials.
## Set up a server
```python
from mongogrant.config import Config
from mongogrant.server import Server, check, path, seed, Mailgun
server = Server(Config(check=check, path=path, seed=seed()))
server.set_mgdb("mongodb://mgserver:mgserverpass@my.host.com/mongogrant")
server.set_mailer(Mailgun, dict(
api_key="YOUR_KEY",
base_url="https://api.mailgun.net/v3/YOUR_DOMAIN",
from_addr="mongogrant@YOUR_DOMAIN"))
server.set_admin_client(
host="other1.host.com",
username="mongoadmin",
password="mongoadminpass")
server.set_admin_client(
host="other2.host.com",
username="mongoadmin",
password="mongoadminpass")
```
### Appointing others to set allow/deny rules
A mongogrant server admin can add "ruler" users who can set allow/deny rules for users via the `mgrant` CLI. An admin sets a ruler document in the `server.mgdb` collection, e.g.
```python
server.mgdb.rulers.replace_one(
{"email": "starlord@lbl.gov"},
{
"email": "starlord@lbl.gov",
"hosts": ["mongodb03.nersc.gov"],
"dbs": ["mp_", "fw_"],
"emails": ["@lbl.gov"],
"which": ["allow"]
},
upsert=True)
```
Allows user `starlord@lbl.gov` to set `allow` rules for any user with an "@lbl.gov" email address on the Mongo host "mongodb03.nersc.gov" for any database name prefixed with "mp_" or "fw_". Any field in a ruler document can be set to "all" rather than an array.
Raw data
{
"_id": null,
"home_page": "https://github.com/materialsproject/mongogrant/",
"name": "mongogrant",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3",
"maintainer_email": "",
"keywords": "mongodb pymongo authentication authorization",
"author": "MP Team",
"author_email": "feedback@materialsproject.org",
"download_url": "https://files.pythonhosted.org/packages/86/ea/236c569243a19bfb7097fd6b2fd09aa68af57e3d76e3ff65ea69333c0760/mongogrant-0.3.3.tar.gz",
"platform": "",
"description": "## Quickstart for users\n\nSo, your friendly neighborhood mongogranter says you know have access to a\ndatabase through your email address. What now? First, install mongogrant:\n```bash\npip install mongogrant\n```\nNext, request a token link to be sent to your email:\n```\nmgrant init mcurie@espci.fr \\\n --endpoint https://grantmedb.materialsproject.org\n```\nClick the link in your email to prove you're you, copy the fetch token from the\nloaded page, and then run:\n```\nmgrant settoken wh054900d70k3ny35y0u423\n```\nFinally, get credentials for your database. Here, Marie is asking mongogrant to\nprint out db.json and my_launchpad.yaml starter files for\n[FireWorks](https://materialsproject.github.io/fireworks/) and\n[atomate](https://atomate.org/):\n```\nmgrant db mongodb03.nersc.gov fw_mc_polonium \\\n --role readWrite \\\n --atomate-starters\n```\n## About mongogrant\n\nMongogrant is a utility to grant username and password\ncredentials for read and readWrite roles on various databases\non various hosts to owners of email addresses.\n\nA server administrator has fine-grained control via\nallow/deny rules for granting tokens and credentials.\nPeople request an email that contains a one-time link. That\nlink gives a user a fetch token. All tokens expire and\nexpiration time is customizable. People then use the\nmongogrant client to make requests like\n\n```python\nfrom mongogrant.client import Client\n\n# config file on disk has tokens and host/db aliases\n# `Client()` with no args looks to\n# ~/.mongogrant.json for config\nclient = Client()\n\n# No config yet? Set one up with at least one remote for fetching credentials\n# See below for how to obtain <FETCH_TOKEN> for a given <ENDPOINT>.\nclient.set_remote(\"https://grantmedb.materialsproject.org\", \"<FETCH_TOKEN>\")\n\n# Set some aliases if you'd like:\nclient.set_alias(\"dev\", \"mongodb03.nersc.gov\", \"host\")\nclient.set_alias(\"prod\", \"mongodb04.nersc.gov\", \"host\")\nclient.set_alias(\"fireworks\", \"fw_dw_phonons\", \"db\")\n\n# pymongo.database.Database with read role\nsource_db = client.db(\"ro:dev/fireworks\")\n# readWrite role: config stores \"prod\" host alias and \"fireworks\" db alias\ntarget_db = client.db(\"rw:prod/fireworks\")\n\n# ...Do database stuff!\n```\n\nOne can also go entirely through a running app's API:\n\n```bash\n> # Using the HTTPie command line HTTP client (https://httpie.org/)\n> # Install via `{brew,apt-get,pip,...} install httpie`\n> http GET https://grantmedb.materialsproject.org/gettoken/<YOUR_EMAIL>\nHTTP/1.1 200 OK\nConnection: keep-alive\nContent-Length: 59\nContent-Type: application/json\nDate: Thu, 17 May 2018 18:05:30 GMT\nServer: nginx/1.10.3\n\n{\n \"msg\": \"Sent link to <YOUR_EMAIL> to retrieve token.\"\n}\n\n> http GET https://grantmedb.materialsproject.org/verifytoken/<VERIFY_TOKEN>\nHTTP/1.1 200 OK\nConnection: keep-alive\nContent-Encoding: gzip\nContent-Type: text/html; charset=utf-8\nDate: Thu, 17 May 2018 18:06:17 GMT\nServer: nginx/1.10.3\nTransfer-Encoding: chunked\n\nFetch token: <FETCH_TOKEN> (expires 2018-06-19 18:05:30.508000 UTC)\n\n> # end-of-line \"\\\" below only necessary if command spans two lines.\n> http --form POST https://grantmedb.materialsproject.org/grant/<FETCH_TOKEN> \\\n> role=readWrite host=mongodb03.nersc.gov db=dw_phonons\nHTTP/1.1 200 OK\nConnection: keep-alive\nContent-Length: 108\nContent-Type: application/json\nDate: Thu, 17 May 2018 18:11:22 GMT\nServer: nginx/1.10.3\n\n{\n \"password\": \"<PASSWORD>\",\n \"username\": \"dwinston_lbl.gov_readWrite\"\n}\n\n>\n```\n\nYou can run a \"server\" on your laptop in a Jupyer notebook\nand manage allow/deny rules, grant / revoke grants of\ncredentials, etc. A small Flask app\nis included as an example for deploying a server to which\nclients can connect to obtain tokens and credentials. \n\n## Set up a server\n\n```python\nfrom mongogrant.config import Config\nfrom mongogrant.server import Server, check, path, seed, Mailgun\n\nserver = Server(Config(check=check, path=path, seed=seed()))\nserver.set_mgdb(\"mongodb://mgserver:mgserverpass@my.host.com/mongogrant\")\nserver.set_mailer(Mailgun, dict(\n api_key=\"YOUR_KEY\",\n base_url=\"https://api.mailgun.net/v3/YOUR_DOMAIN\",\n from_addr=\"mongogrant@YOUR_DOMAIN\"))\nserver.set_admin_client(\n host=\"other1.host.com\",\n username=\"mongoadmin\",\n password=\"mongoadminpass\")\nserver.set_admin_client(\n host=\"other2.host.com\",\n username=\"mongoadmin\",\n password=\"mongoadminpass\")\n```\n\n### Appointing others to set allow/deny rules\n\nA mongogrant server admin can add \"ruler\" users who can set allow/deny rules for users via the `mgrant` CLI. An admin sets a ruler document in the `server.mgdb` collection, e.g.\n```python\nserver.mgdb.rulers.replace_one(\n {\"email\": \"starlord@lbl.gov\"},\n {\n \"email\": \"starlord@lbl.gov\",\n \"hosts\": [\"mongodb03.nersc.gov\"],\n \"dbs\": [\"mp_\", \"fw_\"],\n \"emails\": [\"@lbl.gov\"],\n \"which\": [\"allow\"]\n },\n upsert=True)\n```\nAllows user `starlord@lbl.gov` to set `allow` rules for any user with an \"@lbl.gov\" email address on the Mongo host \"mongodb03.nersc.gov\" for any database name prefixed with \"mp_\" or \"fw_\". Any field in a ruler document can be set to \"all\" rather than an array.\n\n\n\n",
"bugtrack_url": null,
"license": "modified BSD",
"summary": "Generate and grant credentials for MongoDB databases",
"version": "0.3.3",
"split_keywords": [
"mongodb",
"pymongo",
"authentication",
"authorization"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "43c2711d4a1c01205e206bc7f270522254ac374a86b5e99798e2cfd3cd426d08",
"md5": "a4c2fb61f652525816c6bdd9425310f2",
"sha256": "e32ea6f07d72c7d08ab78d17c79ab7ee56373458ae79d2995c3cc6c2eb3ecbdb"
},
"downloads": -1,
"filename": "mongogrant-0.3.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a4c2fb61f652525816c6bdd9425310f2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3",
"size": 25016,
"upload_time": "2021-06-23T17:56:03",
"upload_time_iso_8601": "2021-06-23T17:56:03.222743Z",
"url": "https://files.pythonhosted.org/packages/43/c2/711d4a1c01205e206bc7f270522254ac374a86b5e99798e2cfd3cd426d08/mongogrant-0.3.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "86ea236c569243a19bfb7097fd6b2fd09aa68af57e3d76e3ff65ea69333c0760",
"md5": "c0fa7c60b5aef06465440da93b096c9e",
"sha256": "ad494b8638adfa840cdd5568af44448dd43771b58102550cf7c61402b1620ab4"
},
"downloads": -1,
"filename": "mongogrant-0.3.3.tar.gz",
"has_sig": false,
"md5_digest": "c0fa7c60b5aef06465440da93b096c9e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3",
"size": 23154,
"upload_time": "2021-06-23T17:56:04",
"upload_time_iso_8601": "2021-06-23T17:56:04.684380Z",
"url": "https://files.pythonhosted.org/packages/86/ea/236c569243a19bfb7097fd6b2fd09aa68af57e3d76e3ff65ea69333c0760/mongogrant-0.3.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2021-06-23 17:56:04",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "materialsproject",
"github_project": "mongogrant",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "Click",
"specs": [
[
"==",
"7.0"
]
]
},
{
"name": "Flask",
"specs": [
[
"==",
"1.0.3"
]
]
},
{
"name": "pymongo",
"specs": [
[
"==",
"3.8.0"
]
]
},
{
"name": "requests",
"specs": [
[
"==",
"2.22.0"
]
]
}
],
"lcname": "mongogrant"
}
JSON
