put all docs into README

This commit is contained in:
Son NK 2019-12-19 22:19:16 +02:00
parent 47923f3c62
commit 482887a0cf
4 changed files with 147 additions and 125 deletions

152
README.md
View File

@ -12,6 +12,15 @@ In some way yes ... However SimpleLogin is a bit different because:
- plenty of features: custom domain, browser extension, OAuth libraries, etc. - plenty of features: custom domain, browser extension, OAuth libraries, etc.
- written in Python 🐍 😅 this is not a difference per se but hey I never found a Python email server so feel free to tweak this one if you want to use Python for handling emails. - written in Python 🐍 😅 this is not a difference per se but hey I never found a Python email server so feel free to tweak this one if you want to use Python for handling emails.
# Table of Contents
[1. General Architecture](#general-architecture)
[2. Self Hosting](#self-hosting)
[3. Contributing Guide](#contributing)
## General Architecture ## General Architecture
![](docs/archi.png) ![](docs/archi.png)
@ -315,6 +324,22 @@ If all the steps are successful, open http://app.mydomain.com/ and create your f
## Contributing ## Contributing
All work on SimpleLogin happens directly on GitHub.
### Run code locally
The project uses Python 3.6+. First, install all dependencies by running the following command. Feel free to use `virtualenv` or similar tools to isolate development environment.
```bash
pip3 install -r requirements.txt
```
Then make sure all tests pass
```bash
pytest
```
To run the code locally, please create a local setting file based on `.env.example`: To run the code locally, please create a local setting file based on `.env.example`:
``` ```
@ -336,13 +361,130 @@ then open http://localhost:7777, you should be able to login with the following
john@wick.com / password john@wick.com / password
``` ```
## Other topics ### API
Please go to the following pages for different topics: For now the only API client is the Chrome/Firefox extension. This extension relies on `API Code` for authentication.
- [api](docs/api.md) In every request the extension sends
- [database migration](docs/db-migration.md)
- [oauth](docs/oauth.md) - the `API Code` is set in `Authentication` header. The check is done via the `verify_api_key` wrapper, implemented in `app/api/base.py`
- the current website `hostname` which is the website subdomain name + domain name. For ex, if user is on `http://dashboard.example.com/path1/path2?query`, the subdomain is `dashboard.example.com`. This information is important to know where an alias is used in order to proposer to user the same alias if they want to create on alias on the same website in the future. The `hostname` is passed in the request query `?hostname=`, see `app/api/views/alias_options.py` for an example.
Currently the latest extension uses 2 endpoints:
- `/alias/options`: that returns what to suggest to user when they open the extension.
```
GET /alias/options hostname?="www.groupon.com"
Response: a json with following structure. ? means optional field.
recommendation?:
alias: www_groupon_com@simplelogin.co
hostname: www.groupon.com
custom:
suggestion: groupon
suffix: [@my_domain.com, .abcde@simplelogin.co]
can_create_custom: true
existing:
[email1, email2, ...]
```
- `/alias/custom/new`: allows user to create a new custom alias.
```
POST /alias/custom/new
prefix: www_groupon_com
suffix: @my_domain.com
Response:
201 -> OK {alias: "www_groupon_com@my_domain.com"}
409 -> duplicated
```
### Database migration
The database migration is handled by `alembic`
Whenever the model changes, a new migration needs to be created
Set the database connection to use a current database (i.e. the one without the model changes you just made), for ex if you have a staging config at `~/config/simplelogin/staging.env`, you can do:
> ln -sf ~/config/simplelogin/staging.env .env
Generate the migration script and make sure to review it before commit it. Sometimes (very rarely though), the migration generation can go wrong.
> flask db migrate
### OAuth flow
SL currently supports code and implicit flow.
#### Code flow
To trigger the code flow locally, you can go to the following url after running `python server.py`:
```
http://localhost:7777/oauth/authorize?client_id=client-id&state=123456&response_type=code&redirect_uri=http%3A%2F%2Flocalhost%3A7000%2Fcallback&state=random_string
```
You should see there the authorization page where user is asked for permission to share their data. Once user approves, user is redirected to this url with an `authorization code`: `http://localhost:7000/callback?state=123456&code=the_code`
Next, exchange the code to get the token with `{code}` replaced by the code obtained in previous step. The `http` tool used here is https://httpie.org
```
http -f -a client-id:client-secret http://localhost:7777/oauth/token grant_type=authorization_code code={code}
```
This should return an `access token` that allow to get user info via the following command. Again, `http` tool is used.
```
http http://localhost:7777/oauth/user_info 'Authorization:Bearer {token}'
```
#### Implicit flow
Similar to code flow, except we get the `access token` back with the redirection.
For implicit flow, the url is
```
http://localhost:7777/oauth/authorize?client_id=client-id&state=123456&response_type=token&redirect_uri=http%3A%2F%2Flocalhost%3A7000%2Fcallback&state=random_string
```
#### OpenID, OAuth2 response_type & scope
According to https://medium.com/@darutk/diagrams-of-all-the-openid-connect-flows-6968e3990660
- `response_type` can be either `code, token, id_token` or any combination.
- `scope` can contain `openid` or not
Below is the different combinations that are taken into account in SL until now:
```
response_type=code
scope:
with `openid` in scope, return `id_token` at /token: OK
without: OK
response_type=token
scope:
with and without `openid`, nothing to do: OK
response_type=id_token
return `id_token` in /authorization endpoint
response_type=id_token token
return `id_token` in addition to `access_token` in /authorization endpoint
response_type=id_token code
return `id_token` in addition to `authorization_code` in /authorization endpoint
```

View File

@ -1,45 +0,0 @@
# API
For now the only API client is the Chrome/Firefox extension. This extension relies on `API Code` for authentication.
In every request the extension sends
- the `API Code` is set in `Authentication` header. The check is done via the `verify_api_key` wrapper, implemented in `app/api/base.py`
- the current website `hostname` which is the website subdomain name + domain name. For ex, if user is on `http://dashboard.example.com/path1/path2?query`, the subdomain is `dashboard.example.com`. This information is important to know where an alias is used in order to proposer to user the same alias if they want to create on alias on the same website in the future. The `hostname` is passed in the request query `?hostname=`, see `app/api/views/alias_options.py` for an example.
Currently the latest extension uses 2 endpoints:
- `/alias/options`: that returns what to suggest to user when they open the extension.
```
GET /alias/options hostname?="www.groupon.com"
Response: a json with following structure. ? means optional field.
recommendation?:
alias: www_groupon_com@simplelogin.co
hostname: www.groupon.com
custom:
suggestion: groupon
suffix: [@my_domain.com, .abcde@simplelogin.co]
can_create_custom: true
existing:
[email1, email2, ...]
```
- `/alias/custom/new`: allows user to create a new custom alias.
```
POST /alias/custom/new
prefix: www_groupon_com
suffix: @my_domain.com
Response:
201 -> OK {alias: "www_groupon_com@my_domain.com"}
409 -> duplicated
```

View File

@ -1,13 +0,0 @@
## How to create new migration
The database migration is handled by `alembic`
Whenever the model changes, a new migration needs to be created
Set the database connection to use staging environment, for ex if you have a staging config at `~/config/simplelogin/staging.env`, you can do:
> ln -sf ~/config/simplelogin/staging.env .env
Generate the migration script and make sure to review it before commit it. Sometimes (very rarely though), the migration generation can go wrong.
> flask db migrate

View File

@ -1,62 +0,0 @@
# OAuth flow
SL currently supports code and implicit flow.
## Code flow
To trigger the code flow locally, you can go to the following url after running `python server.py`:
```
http://localhost:7777/oauth/authorize?client_id=client-id&state=123456&response_type=code&redirect_uri=http%3A%2F%2Flocalhost%3A7000%2Fcallback&state=random_string
```
You should see there the authorization page where user is asked for permission to share their data. Once user approves, user is redirected to this url with an `authorization code`: `http://localhost:7000/callback?state=123456&code=the_code`
Next, exchange the code to get the token with `{code}` replaced by the code obtained in previous step. The `http` tool used here is https://httpie.org
```
http -f -a client-id:client-secret http://localhost:7777/oauth/token grant_type=authorization_code code={code}
```
This should return an `access token` that allow to get user info via the following command. Again, `http` tool is used.
```
http http://localhost:7777/oauth/user_info 'Authorization:Bearer {token}'
```
## Implicit flow
Similar to code flow, except we get the `access token` back with the redirection.
For implicit flow, the url is
```
http://localhost:7777/oauth/authorize?client_id=client-id&state=123456&response_type=token&redirect_uri=http%3A%2F%2Flocalhost%3A7000%2Fcallback&state=random_string
```
## OpenID, OAuth2 response_type & scope
According to https://medium.com/@darutk/diagrams-of-all-the-openid-connect-flows-6968e3990660
- `response_type` can be either `code, token, id_token` or any combination.
- `scope` can contain `openid` or not
Below is the different combinations that are taken into account in SL until now:
response_type=code
scope:
with `openid` in scope, return `id_token` at /token: OK
without: OK
response_type=token
scope:
with and without `openid`, nothing to do: OK
response_type=id_token
return `id_token` in /authorization endpoint
response_type=id_token token
return `id_token` in addition to `access_token` in /authorization endpoint
response_type=id_token code
return `id_token` in addition to `authorization_code` in /authorization endpoint