re-organize docs
This commit is contained in:
Son NK
parent
8d60ebd456
commit
7f96538741
128
README.md
128
README.md
|
|
@ -1,109 +1,35 @@
|
|||
|
||||
## OAuth flow
|
||||
|
||||
Authorization code flow:
|
||||
|
||||
http://localhost:7777/oauth/authorize?client_id=client-id&state=123456&response_type=code&redirect_uri=http%3A%2F%2Flocalhost%3A7000%2Fcallback&state=dvoQ6Jtv0PV68tBUgUMM035oFiZw57
|
||||
|
||||
Implicit flow:
|
||||
http://localhost:7777/oauth/authorize?client_id=client-id&state=123456&response_type=token&redirect_uri=http%3A%2F%2Flocalhost%3A7000%2Fcallback&state=dvoQ6Jtv0PV68tBUgUMM035oFiZw57
|
||||
|
||||
Exchange the code to get the token with `{code}` replaced by the code obtained in previous step.
|
||||
|
||||
http -f -a client-id:client-secret http://localhost:7777/oauth/token grant_type=authorization_code code={code}
|
||||
|
||||
Get user info:
|
||||
|
||||
http http://localhost:7777/oauth/user_info 'Authorization:Bearer {token}'
|
||||
|
||||
|
||||
## Template structure
|
||||
|
||||
base
|
||||
single: for login, register page
|
||||
default: for all pages when user log ins
|
||||
# Run the code locally
|
||||
|
||||
## How to create new migration
|
||||
|
||||
Whenever the model changes, a new migration needs to be created
|
||||
|
||||
Set the database connection to use staging environment:
|
||||
|
||||
> ln -sf ~/config/simplelogin/staging.env .env
|
||||
|
||||
Generate the migration script and make sure to review it:
|
||||
|
||||
> flask db migrate
|
||||
|
||||
## Code structure
|
||||
|
||||
local_data/: contain files used only locally. In deployment, these files should be replaced.
|
||||
- jwtRS256.key: generated using
|
||||
|
||||
```bash
|
||||
ssh-keygen -t rsa -b 4096 -m PEM -f jwtRS256.key
|
||||
# Don't add passphrase
|
||||
openssl rsa -in jwtRS256.key -pubout -outform PEM -out jwtRS256.key.pub
|
||||
```
|
||||
|
||||
## 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 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
|
||||
|
||||
|
||||
## API endpoints for extension
|
||||
To run the code locally, please create a local setting file based on `.env.example`:
|
||||
|
||||
```
|
||||
GET /alias/options hostname?="www.groupon.com"
|
||||
recommendation?:
|
||||
alias: www_groupon_com@simplelogin.co
|
||||
hostname: www.groupon.com
|
||||
|
||||
custom?:
|
||||
suggestion: www_groupon_com
|
||||
suffix: [@my_domain.com, .abcde@simplelogin.co]
|
||||
|
||||
can_create_custom: true
|
||||
can_create_random: true
|
||||
|
||||
existing:
|
||||
[email1, email2, ...]
|
||||
|
||||
POST /alias/custom/new
|
||||
prefix: www_groupon_com
|
||||
suffix: @my_domain.com
|
||||
|
||||
201 -> OK {alias: "www_groupon_com@my_domain.com"}
|
||||
409 -> duplicated
|
||||
|
||||
POST /alias/random/new
|
||||
201 -> OK {alias: "random_word@simplelogin.co"}
|
||||
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
Feel free to custom your `.env` file, it would be your default setting when developing locally. This file is ignored by git.
|
||||
|
||||
You don't need all the parameters, for ex if you don't update images to s3, then
|
||||
`BUCKET`, `AWS_ACCESS_KEY_ID` can be empty or if you don't use login with Github locally, `GITHUB_CLIENT_ID` doesn't have to be filled. The `.env.example` file contains minimal requirement so that if you run:
|
||||
|
||||
```
|
||||
python3 server.py
|
||||
```
|
||||
|
||||
then open http://localhost:7777, you should be able to login with the following account
|
||||
|
||||
```
|
||||
john@wick.com / password
|
||||
```
|
||||
|
||||
# Other topics
|
||||
|
||||
Please go to the following pages for different topics:
|
||||
|
||||
- [api](docs/api.md)
|
||||
- [database migration](docs/db-migration.md)
|
||||
- [oauth](docs/oauth.md)
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
46
docs/api.md
Normal file
46
docs/api.md
Normal file
|
|
@ -0,0 +1,46 @@
|
|||
# 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
|
||||
can_create_random: true # obsolete now
|
||||
|
||||
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
|
||||
|
||||
```
|
||||
|
||||
10
docs/code-structure.md
Normal file
10
docs/code-structure.md
Normal file
|
|
@ -0,0 +1,10 @@
|
|||
# TODO
|
||||
|
||||
`local_data/`: contain files used only locally. In deployment, these files should be replaced.
|
||||
- jwtRS256.key: generated using
|
||||
|
||||
```bash
|
||||
ssh-keygen -t rsa -b 4096 -m PEM -f jwtRS256.key
|
||||
# Don't add passphrase
|
||||
openssl rsa -in jwtRS256.key -pubout -outform PEM -out jwtRS256.key.pub
|
||||
```
|
||||
13
docs/db-migration.md
Normal file
13
docs/db-migration.md
Normal file
|
|
@ -0,0 +1,13 @@
|
|||
## 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
|
||||
62
docs/oauth.md
Normal file
62
docs/oauth.md
Normal file
|
|
@ -0,0 +1,62 @@
|
|||
# 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 a new issue