put all docs into README
This commit is contained in:
Son NK
parent
47923f3c62
commit
482887a0cf
152
README.md
152
README.md
|
|
@ -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.
|
||||
- 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
|
||||
|
||||
|
||||
|
|
@ -315,6 +324,22 @@ If all the steps are successful, open http://app.mydomain.com/ and create your f
|
|||
|
||||
## 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`:
|
||||
|
||||
```
|
||||
|
|
@ -336,13 +361,130 @@ then open http://localhost:7777, you should be able to login with the following
|
|||
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)
|
||||
- [database migration](docs/db-migration.md)
|
||||
- [oauth](docs/oauth.md)
|
||||
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
|
||||
|
||||
```
|
||||
|
||||
### 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
|
||||
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
45
docs/api.md
45
docs/api.md
|
|
@ -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
|
||||
|
||||
```
|
||||
|
||||
|
|
@ -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
|
||||
|
|
@ -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
|
||||
|
||||
Loading…
Reference in New Issue