The goal of this project is to allow multiple servers to share a single OAuth login interface, removing the need for multiple access tokens across separate user databases. It also serves as an authentication microservice, enabling load balancing for a distributed system without acting as a bottleneck. Finally, the project also handles role based access control, including hierarchical groups and limited-privledge sharing with user friendly QR code support.
It is written in Flask has the simplest interface with client applications also in Flask, but also has an interface for any other Python web framework. The middleware for aiohttp, for example, will be covered below. The project doesn't have bindings for projects in languages besides Python yet, but is well equipped to handle them using the same interfaces as the ones supporting non-Flask based Python applications.
Start the login service on port 8000 with
$ sh server.sh debugIf you go to http://localhost:8000/login/view/sessions, you should see a
'test' link, which will let you specify a username, then show you the current
session.
Clearly, this isn't much of a secure login interface yet, but it does allow for
testing the process without any OAuth API keys. The 'test' option will go away
once the server is run without the debug subcommand.
You may notice that the user interfaces are very bare-bones. This is because
they are generally expected to be used through their corresponding AJAX
endpoints from a page styled by the corresponding project. Alternatively, the
templates are in src/flask_modular_login/templates.
Most applications need more state information about a user than just whether they're logged in. For example, to do a closed beta, there needs to be a distinction betweeen a user that logged in versus one of the testers. Another common example is a remote file system where users can access or share private documents.
The most general justification for a unified authentication/access control system is that any time a user accesses private data, they need to be allowed to. This by itself is a bad argument though, since, if users just need to access their own data, then their username is an easy substitute for their access group. Unfortunately, including user groups is a natural extension of the requirements in many cases.
Access groups are organized as a disjoint set of trees, with permissions flowing downwards. This is backwards from the unix groups system, where access to each of the ancestor nodes is required to interact with a node. That being said, most file system sharing software (Google Drive, Dropbox, etc) uses a top down setup for permissions: access to a parent folder gives access to the files. In cases where a disconnect in permissions is needed, the client can symlink two group trees.
The snippet below both requires a user to be logged in, as well as creates an access group the user needs to either own or join to see their profile.
import flask
from flask_modular_login import AccessNamespace
from flask_modular_login import login_required
app = flask.Flask(__name__)
login_required.prefix = "//localhost:8000"
group = AccessNamespace(
"test_group", ownership_method="test", owner_id="127.0.0.1")
@app.route("/access_profile")
@login_required(kw="user", group=group)
def access_profile(user):
return str(user)
if __name__ == "__main__":
app.run(port=8080)By logging into the 'test' option named 127.0.0.1 (which should be the
default), it is now possible to:
- Invite people to
test_group:http://localhost:8000/login/access/view/invite - Remove users from
test_group:http://localhost:8000/login/access/view/remove - Revoke an invitation to
test_group:http://localhost:8000/login/access/view/renege
Group hierarchies are created using the group method, and can be composed
using the binary operators | and & to indicate or and and respectively.
For information on more than one group, use +, and to reference a subgroup by
name, a pathlib-like / can be used. Groups can also be constructed based on
arguments passed to the endpoint, including the user dictionary.
As a brief, incomplete example to showcase the usage, consider a messaging app where images can be unsent or users can be blocked altogether
chat = AccessNamespace("chat", ownership_method="test", owner_id="127.0.0.1")
@app.route("/chats/<DMing>/images/<img>")
@login_required(kw="user", group=lambda DMing, user: \
!(chat / DMing / "blocked") & \
chat / DMing / user["id"] / img / "read_access")
def access_profile(DMing, img, user):
...This project currently relies on flask-dance for its OAuth interface, meaning that any of the providers supported there will also work here. For now, the easiest platforms to set up are Google, Facebook, and Github, for reasons that will be explained momentarily.
Add a credentials.json to the root directory of this project, in the form
{
"google|facebook|github": {"id": "username", "secret": "API key"},
}Once the user logs in, the service guarantees a username (id), display name
(name), and picture (picture).
The available platforms are defined in src/flask_modular_login/platforms.py,
which maps the OAuth response to the platform-agnostic keys given to client
projects. Remove unused providers from the methods dictionary, or add them in
both userlookup and methods.
At this point, some providers may require a public facing URL to redirect to. For notes on deployment to public facing URLs, see the Deployment section.
In the project with a login requirement ('client'), install the local copy of this repo using
$ pip install -e path/to/repoThe client can either be on the same server as the login service ('local') or on a separate one ('remote'), and the server can be either Flask ('builder') or not ('interface'). For naming purposes, the project is assumed to be on the same server and written in Flask by default.
When all the URLs are accessed via localhost loopback, the client and server
projects are served on different ports. This is in contrast to the default setup
for deployment, where only the paths differ. To run a test setup, then, the URL
prefix for the login server has to be specified as http://localhost:8000. This
will be included in the example code below, but needs to be removed or updated
when deploying to public facing URLs.
For in the server code for the client project, login requirements can now be
specified using login_required and login_optional. This login system was
demonstrated briefly above, but a more complete walkthrough of the features is
below
import flask
from flask_modular_login import login_required, login_optional
app = flask.Flask(__name__)
login_required.prefix = "//localhost:8000"
@app.route("/user_info/<kind>")
@login_required(kw="user")
def protected_or_user_info(kind, user):
# only logged in users can access this route, others redirected by flask
# user argument now contains keys id, name, picture
return user["id"]
@app.route("/profile_api")
@login_optional(kw="user")
def profile(user=None):
# login optional can be used when logged out users shouldn't see a redirect
return str(user)
@app.route("/hidden")
@login_required
def hidden():
# same as before, but the user info is now stored in flask.g.user
return profile(user={"id": flask.g.user["id"], "name": "me", "picture": ""})
# methods with optional login can also be called with a custom user argument
# but only as a keyword, since *args wrappers can make positional matching
# unreliable
bp = flask.Blueprint("private", __name__, url_prefix="/private")
login_required(bp) # returns bp, could be integrated into line above
@bp.route("/page")
def page():
# user info in flask.g.user, access limited to logged in users
return flask.g.user["name"]
app.register_blueprint(bp) # login_required call could also be here
if __name__ == "__main__":
app.run(port=8080)Because the login_required and login_optional objects refer to the same
LoginBuilder, updating one will update both. Another way to achieve this would
be
from flask_modular_login import LoginBuilder
login_config = LoginBuilder(prefix="http://localhost:8000")
login_required, login_optional = login_config.decoratorsThe other methods for connecting to the login server rely on sockets to forward request information. In general, the websocket servers should be started using subcommands of
$ sh server.sh wsPython projects using web servers other than Flask are also supported, but have to specify a way to
- get the web request's IP address
- get the HTTP cookie
login(barring config changes) - set the HTTP cookie
login(again, subject to config)
For example, a web server written in aiohttp might set up the login interface as
from aiohttp import web
from flask_modular_login import LocalLoginInterface
class LoginBuilder(LocalLoginInterface):
def remote_addr(self, request):
return request.remote
def get_cookie(self, request):
return request.cookies.get('login')
def set_cookie(self, value, request):
request["login"] = value
login = LoginBuilder()
@web.middleware
async def process_request(request, handler):
request['user'] = await login(request)
response = await handler(request)
if 'login' in request:
response.set_cookie('login', request['login'])
return response
app = web.Application(middlewares=[process_request])
async def handler(request):
return web.Response(text='Hello, ' + str(request["user"]))
app.router.add_get('/', handler)
if __name__ == '__main__':
web.run_app(app)Another important option for load balancing is being able to have the login system as a separate service, only contacted when an access token lease needs to be refreshed or revoked (eg when the user logs out). In order to connect the login service from the client server, the client needs to be able to access
- an open port on the login server
- by default, the server websocket is hosted on port 8001
- the port can be made accessable using SSH reverse tunneling to port forward
- a copy of the
secret_keyused by Flask.- by default, this is stored in
run/login_secret_session_key
- by default, this is stored in
- the base URL that the login service is hosted on
- this can be either the public URL or port forwarded
- used to coordinate shared secrets before opening the websocket connection
Using frameworks other than Flask for a remote client requires the same information as above.
Deployment requires memcached to be installed in the environment hosting the
login service. Installation is OS dependant. The python virtual environment will
be set up and started by the server script, so if it's already running in a
container, you may prefer to uncomment the early exit from the setup function in
server.sh.
With the default deployment, uwsgi.ini will serve requests from
run/uwsgi.sock, relative to this project's root directory. The other important
thing for the web server middleware is that only requests prefixed with /login
should be passed to this process.
Here is an example pulled from a working Nginx setup where socket in
uwsgi.ini has been modified to be /tmp/flask_modular_login.sock:
location = /login { rewrite ^ /login/; }
location /login { try_files $uri @login; }
location @login {
include uwsgi_params;
uwsgi_pass unix:/tmp/flask_modular_login.sock;
}
echo "$(grep TODO -r src && grep '^#\+ TODO' README.md \
-A `wc -l README.md | sed 's%[^0-9]%%g'` | tail -n +2)" | nlfind src -type f -name "*.py" | xargs wc | sortRough, slightly outdated builder/interface boxes and "client login app" doesn't
set the available platforms yet. The goal is to have the login server launched
via LoginBlueprint and use the repo as a package so it doesn't have to be
modified.
+-------------+
| access root |
+-------------+
| \\_______
| \ \_ \_______
| \ \_ \_______
| \ \_ \_______
| \ \__ \_______
| \ \ \
+-------------+ \ +-------------+ +-------------+
| oauth BP | \ |access group |____________ |local client |
| interface | \ +-------------+ | flask app |
+-------------+ \ | +-------------+
| \ \ | __/
| \ \ | __/
| \ \ | __/
| \ \ | __/
| \ \ | /
+-------------+ \ +-------------+
| platforms | \ |login builder|
+-------------+ \ +-------------+
| \ | \__
| \ | \_
| \ | \_
| \ | \_
| \ | \__
| \ | \
+-------------+ +-------------+ +-------------+
| client |_____________| login app | | remote |
| login app | +-------------+ |login builder|
+-------------+ / +-------------+
/ / |
/ / |
/ / |
/ / |
/ / |
/ +-------------+ / +-------------+
/ |local client | / |remote client|
/ | compat | / | app |
/ +-------------+ / +-------------+
/ | / |
/ | / |
/ | / |
/ | / |
/ | / |
+-------------+ +-------------+ +-------------+
| server BP | |login builder| | client BP |
+-------------+ | interface | +-------------+
\__ +-------------+ |
\_ | |
\_ | |
\_ | |
\__ | |
\ | |
+-------------+ +-------------+
| server WS |-------------| client WS |
+-------------+ +-------------+
- set the platforms via launch conditions
- other language compat
- option to auto-redirect to QR code link on first login if not at /qr
- linked accounts
- check path interface consitency (pub/sub, memcached, secret_key)
- consistent indentation between if statements and others
- purge access tokens from remote clients after they're stale
- invite option to limit sharing by total use time?
- include
X-API-Versionheader and/or version field in WS messages - alternate language bindings link
- login.gov integration might be a polite civil service
- switch to python-social-auth
- consider sql alchemy, prep database schema migration system
- horizontal scaling (maybe?)
- check SQL indicies
- caching in various places
- API docs (doxygen?)
- ...unit tests (hopefully higher up please)
- get a security audit from someone else