From c79112eb6ae56ab05f6630f6e4e02afa882052d9 Mon Sep 17 00:00:00 2001 From: Ethan Paul Date: Tue, 18 Feb 2020 22:58:03 -0500 Subject: [PATCH] Add basic project idea and overview --- README.md | 85 +++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 83 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 67d80ae..462542c 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,84 @@ -# front-desk +

keyosk

-Web application for generating, validating, and serving JSON Web Tokens over a REST API. Written in Python +

+jwt compatible +Code style: black +

+ +Keyosk is a RESTful web service that can be used to issue application-agnostic +[JSON Web Tokens](https://jwt.io/introduction/) (JWTs). + +In a [microservice based architecture](https://xkcd.com/1988/), each service only +communicates with the other services using the publicly exposed API. This promotes +more consistent and stable APIs as well as more intentionally specialized services. +However, when it comes to authentication this can present a problem: to ensure secure +authentication for a microservice-based application there are only two real options: + * Each service must re-implement an authentication system, leading to duplicated code, + nonstandard interfaces, and the potential for synchronization problems + * The services must have access to a shared resource outside of their publicly + defined APIs, which is kind of against the whole idea of microservice architectures + +**Keyosk provides a third option:** + +Users can authenticate against Keyosk and be issued a JSON Web Token, which can then +be used to authenticate against other microservices in the application. When a +microservice receives a user-submitted JWT it can verify with the Keyosk server that +the token a) is valid and b) hasn't been tampered with. + +The workflow looks something like this: + +1. User wants to submit a request to the *ToDo Service* +2. User submits username and password/API key using + [HTTP basic auth](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication) + to Keyosk +3. Keyosk validates the user's credentials and issues a JWT that encodes the users + permissions, then signs the JWT using its private-key. +4. The user takes the JWT issued by Keyosk and submits their request to the + *ToDo Service* +5. The *ToDo Service* queries Keyosk for its public-key and uses the public-key to + verify that the JWT it just received was in fact issued by Keyosk and hasn't been + tampered with. +6. The *ToDo Service* decodes the JWT and is able to read the permissions information + for the user's account directly out of the JWT itself. + +The application's accounts are stored in one location, the authentication workflow is +the same for all the application's components, and all the components communicate with +each other over their public API. + +To learn more, [read the docs!](docs/) + +## building + +This project uses [Poetry](https://poetry.eustace.io/) for its build and development +system. Please [install Poetry](https://poetry.eustace.io/docs/#installation) and run +`poetry install` to create and populate the virtual environment. + +```bash +# build python wheel and source distributions +make build + +# build sphinx documentation in HTML format +make docs + +# build sphinx documentation in another format +make docs SPHINX_FORMAT= +``` + +## developing + +```bash +# install poetry +pip3 install poetry --user --pre + +# install pre-commit +pip3 install pre-commit --user + +# install pre-commit hooks +pre-commit install + +# create virtual environment from lockfile +poetry install + +# run the tests and static analysis +poetry run tox +```