2020-01-02 00:50:19 +08:00
< p align = "center" >
2020-01-02 01:55:59 +08:00
< a href = "https://simplelogin.io" >
< img src = "./docs/diagram.png" height = "300px" >
< / a >
2020-01-02 00:50:19 +08:00
< / p >
2020-01-02 01:55:59 +08:00
[SimpleLogin ](https://simplelogin.io ) | Privacy-First Email Forwarding and Identity Provider Service
2019-12-19 00:10:10 +08:00
---
2020-01-28 01:12:53 +08:00
< p >
2020-01-02 01:31:06 +08:00
< a href = "https://chrome.google.com/webstore/detail/simplelogin-protect-your/dphilobhebphkdjbpfohgikllaljmgbn" >
< img src = "https://img.shields.io/chrome-web-store/rating/dphilobhebphkdjbpfohgikllaljmgbn?label=Chrome%20Extension" >
< / a >
2020-01-28 01:12:53 +08:00
< a href = "https://addons.mozilla.org/en-GB/firefox/addon/simplelogin/" >
2020-01-02 01:31:06 +08:00
< img src = "https://img.shields.io/amo/rating/simplelogin?label=Firefox%20Add-On&logo=SimpleLogin" >
< / a >
2020-01-28 01:12:53 +08:00
< a href = "https://stats.uptimerobot.com/APkzziNWoM" >
2020-01-02 01:31:06 +08:00
< img src = "https://img.shields.io/uptimerobot/ratio/7/m782965045-15d8e413b20b5376f58db050" >
< / a >
< a href = "./LICENSE" >
< img src = "https://img.shields.io/github/license/simple-login/app" >
< / a >
< a href = "https://twitter.com/simple_login" >
< img src = "https://img.shields.io/twitter/follow/simple_login?style=social" >
< / a >
2020-01-02 01:37:03 +08:00
2020-01-02 01:31:06 +08:00
< / p >
2019-12-19 00:10:10 +08:00
2020-01-02 00:50:19 +08:00
> Yet another email forwarding service?
In some way yes... However, SimpleLogin is a bit different because:
- Fully open source: both the server and client code (browser extension, JS library) are open source so anyone can freely inspect and (hopefully) improve the code.
2020-01-28 01:12:53 +08:00
- The only email forwarding solution that is **self-hostable** : with our detailed self-hosting instructions and most of components running as Docker container, anyone who knows `ssh` is able to deploy SimpleLogin on their server.
2020-01-02 00:50:19 +08:00
- Not just email alias: SimpleLogin is a privacy-first and developer-friendly identity provider that:
- offers privacy for users
- is simple to use for developers. SimpleLogin is a privacy-focused alternative to the "Login with Facebook/Google/Twitter" buttons.
2020-01-28 01:12:53 +08:00
2020-01-02 00:50:19 +08:00
- Plenty of features: browser extension, custom domain, catch-all alias, OAuth libraries, etc.
2020-01-28 01:12:53 +08:00
2020-01-02 00:50:19 +08:00
- Open roadmap at https://trello.com/b/4d6A69I4/open-roadmap: you know the exciting features we are working on.
2020-01-02 01:55:59 +08:00
At the heart of SimpleLogin is `email alias` : an alias is a normal email address but all emails sent to an alias are **forwarded** to your email inbox. SimpleLogin alias can also **send** emails: for your contact, the alias is therefore your email address. Use alias whenever you need to give out your email address to protect your online identity. More info on our website at https://simplelogin.io
2020-01-02 00:50:19 +08:00
< p align = "center" >
< img src = "./docs/custom-alias.png" height = "150px" >
< / p >
2020-01-01 17:38:19 +08:00
# Quick start
2020-01-02 00:50:19 +08:00
If you have Docker installed, run the following command to start SimpleLogin local server:
2020-01-01 17:38:19 +08:00
```bash
2020-01-28 01:12:53 +08:00
docker run --name sl -it --rm \
2020-01-01 17:38:19 +08:00
-e RESET_DB=true \
2020-01-23 16:23:53 +08:00
-e CONFIG=/code/example.env \
2020-01-01 17:38:19 +08:00
-p 7777:7777 \
2020-04-15 04:54:57 +08:00
simplelogin/app:3.0.1 python server.py
2020-01-01 17:38:19 +08:00
```
Then open http://localhost:7777, you should be able to login with `john@wick.com/password` account!
2020-01-02 00:50:19 +08:00
To use SimpleLogin aliases, you need to deploy it on your server with some DNS setup though,
2020-03-11 19:13:38 +08:00
the following section will show a step-by-step guide on how to get your own email forwarder service!
2020-01-01 17:43:44 +08:00
2019-12-20 04:19:16 +08:00
# Table of Contents
[1. General Architecture ](#general-architecture )
[2. Self Hosting ](#self-hosting )
[3. Contributing Guide ](#contributing )
2019-12-19 00:10:10 +08:00
## General Architecture
2020-01-02 00:50:19 +08:00
< p align = "center" >
2020-01-02 01:55:59 +08:00
< img src = "./docs/archi.png" height = "450px" >
2020-01-02 00:50:19 +08:00
< / p >
SimpleLogin backend consists of 2 main components:
2019-12-19 00:10:10 +08:00
- the `webapp` used by several clients: web UI (the dashboard), browser extension (Chrome & Firefox for now), OAuth clients (apps that integrate "Login with SimpleLogin" button) and mobile app (work in progress).
2020-01-02 00:50:19 +08:00
- the `email handler` : implements the email forwarding (i.e. alias receiving email) and email sending (i.e. alias sending email).
2019-12-19 00:10:10 +08:00
## Self hosting
### Prerequisites
2019-12-21 19:58:33 +08:00
- a Linux server (either a VM or dedicated server). This doc shows the setup for Ubuntu 18.04 LTS but the steps could be adapted for other popular Linux distributions. As most of components run as Docker container and Docker can be a bit heavy, having at least 2 GB of RAM is recommended. The server needs to have the port 25 (email), 80, 443 (for the webapp), 22 (so you can ssh into it) open.
2019-12-19 00:10:10 +08:00
2020-01-28 01:12:53 +08:00
- a domain that you can config the DNS. It could be a sub-domain. In the rest of the doc, let's say it's `mydomain.com` for the email and `app.mydomain.com` for SimpleLogin webapp. Please make sure to replace these values by your domain name whenever they appear in the doc. A trick we use is to download this README file on your computer and replace all `mydomain.com` occurrences by your domain.
2019-12-19 00:10:10 +08:00
2019-12-21 19:58:33 +08:00
- [Optional] AWS S3, Sentry, Google/Facebook/Github developer accounts. These are necessary only if you want to activate these options.
2019-12-19 00:10:10 +08:00
2020-01-02 00:50:19 +08:00
Except for the DNS setup that is usually done on your domain registrar interface, all the below steps are to be done on your server. The commands are to run with `bash` (or any bash-compatible shell like `zsh` ) being the shell. If you use other shells like `fish` , please make sure to adapt the commands.
2019-12-19 00:10:10 +08:00
2020-01-28 01:12:53 +08:00
### Some utility packages
These packages are used to verify the setup. Install them by:
```bash
sudo apt install -y dnsutils
```
2020-03-25 19:03:34 +08:00
Create a directory to store SimpleLogin data:
```bash
mkdir sl
mkdir sl/pgp # to store PGP key
mkdir sl/db # to store database
```
2020-01-28 01:12:53 +08:00
2019-12-19 00:10:10 +08:00
### DKIM
From Wikipedia https://en.wikipedia.org/wiki/DomainKeys_Identified_Mail
> DomainKeys Identified Mail (DKIM) is an email authentication method designed to detect forged sender addresses in emails (email spoofing), a technique often used in phishing and email spam.
2019-12-21 19:58:33 +08:00
Setting up DKIM is highly recommended to reduce the chance your emails ending up in the recipient's Spam folder.
2019-12-19 00:10:10 +08:00
First you need to generate a private and public key for DKIM:
```bash
openssl genrsa -out dkim.key 1024
openssl rsa -in dkim.key -pubout -out dkim.pub.key
```
You will need the files `dkim.key` and `dkim.pub.key` for the next steps.
2019-12-21 19:58:33 +08:00
For email gurus, we have chosen 1024 key length instead of 2048 for DNS simplicity as some registrars don't play well with long TXT record.
2019-12-19 00:10:10 +08:00
### DNS
2020-01-28 01:12:53 +08:00
Please note that DNS changes could take up to 24 hours to propagate. In practice, it's a lot faster though (~1 minute or so in our test). In DNS setup, we usually use domain with a trailing dot (`.`) at the end to to force using absolute domain.
2019-12-19 00:10:10 +08:00
#### MX record
2020-01-28 01:12:53 +08:00
Create a **MX record** that points `mydomain.com.` to `app.mydomain.com.` with priority 10.
To verify if the DNS works, the following command
```bash
dig @1 .1.1.1 mydomain.com mx
```
2019-12-19 00:10:10 +08:00
2020-01-28 01:12:53 +08:00
should return:
2019-12-19 00:10:10 +08:00
```
mydomain.com. 3600 IN MX 10 app.mydomain.com.
```
#### A record
2020-01-28 01:12:53 +08:00
An **A record** that points `app.mydomain.com.` to your server IP. To verify, the following command
```bash
dig @1 .1.1.1 app.mydomain.com a
2020-03-11 19:13:38 +08:00
```
2020-01-28 01:12:53 +08:00
should return your server IP.
2019-12-19 00:10:10 +08:00
#### DKIM
2020-01-28 01:12:53 +08:00
Set up DKIM by adding a TXT record for `dkim._domainkey.mydomain.com.` with the following value:
2019-12-19 00:10:10 +08:00
```
2019-12-21 19:58:33 +08:00
v=DKIM1; k=rsa; p=PUBLIC_KEY
2019-12-19 00:10:10 +08:00
```
2019-12-21 19:58:33 +08:00
with `PUBLIC_KEY` being your `dkim.pub.key` but
2019-12-19 00:10:10 +08:00
- remove the `-----BEGIN PUBLIC KEY-----` and `-----END PUBLIC KEY-----`
- join all the lines on a single line.
2020-01-02 00:50:19 +08:00
For example, if your `dkim.pub.key` is
2019-12-19 00:10:10 +08:00
```
-----BEGIN PUBLIC KEY-----
ab
cd
ef
gh
-----END PUBLIC KEY-----
```
2019-12-21 19:58:33 +08:00
then the `PUBLIC_KEY` would be `abcdefgh` .
2019-12-19 00:10:10 +08:00
2020-01-28 15:39:09 +08:00
You can get the `PUBLIC_KEY` by running this command:
```bash
sed "s/-----BEGIN PUBLIC KEY-----/v=DKIM1; k=rsa; p=/g" dkim.pub.key | sed 's/-----END PUBLIC KEY-----//g' |tr -d '\n'
```
2020-01-28 01:12:53 +08:00
To verify, the following command
```bash
dig @1 .1.1.1 dkim._domainkey.mydomain.com txt
2020-03-11 19:13:38 +08:00
```
2020-01-28 01:12:53 +08:00
should return the above value.
2019-12-19 00:10:10 +08:00
#### SPF
From Wikipedia https://en.wikipedia.org/wiki/Sender_Policy_Framework
> Sender Policy Framework (SPF) is an email authentication method designed to detect forging sender addresses during the delivery of the email
2020-01-02 00:50:19 +08:00
Similar to DKIM, setting up SPF is highly recommended.
2020-01-28 15:40:36 +08:00
Add a TXT record for `mydomain.com.` with the value:
2020-01-28 01:12:53 +08:00
```
v=spf1 mx -all
2020-03-11 19:13:38 +08:00
```
2020-01-28 01:12:53 +08:00
2020-03-11 19:13:38 +08:00
What it means is only your server can send email with `@mydomain.com` domain.
To verify, the following command
2020-01-28 01:12:53 +08:00
```bash
dig @1 .1.1.1 mydomain.com txt
```
should return the above value.
2020-01-28 15:40:36 +08:00
#### DMARC
From Wikipedia https://en.wikipedia.org/wiki/DMARC
> It (DMARC) is designed to give email domain owners the ability to protect their domain from unauthorized use, commonly known as email spoofing
Setting up DMARC is also recommended.
Add a TXT record for `_dmarc.mydomain.com.` with the following value
```
v=DMARC1; p=quarantine; adkim=r; aspf=r
```
This is a `relaxed` DMARC policy. You can also use a more strict policy with `v=DMARC1; p=reject; adkim=s; aspf=s` value.
To verify, the following command
```bash
dig @1 .1.1.1 _dmarc.mydomain.com txt
```
2020-03-11 19:13:38 +08:00
should return the set value.
2020-01-28 15:40:36 +08:00
For more information on DMARC, please consult https://tools.ietf.org/html/rfc7489
2019-12-19 00:10:10 +08:00
### Docker
Now the boring DNS stuffs are done, let's do something more fun!
2020-01-02 00:50:19 +08:00
If you don't already have Docker installed on your server, please follow the steps on [Docker CE for Ubuntu ](https://docs.docker.com/v17.12/install/linux/docker-ce/ubuntu/ ) to install Docker.
2019-12-19 00:10:10 +08:00
2020-01-28 15:43:30 +08:00
Tips: if you are not using `root` user and you want to run Docker without the `sudo` prefix, add your account to `docker` group with the following command.
You might need to exit and ssh again to your server for this to be taken into account.
2019-12-19 00:10:10 +08:00
```bash
sudo usermod -a -G docker $USER
```
### Prepare the Docker network
This Docker network will be used by the other Docker containers run in the next steps.
Later, we will setup Postfix to authorize this network.
```bash
2020-01-28 15:43:30 +08:00
sudo docker network create -d bridge \
2020-01-19 06:13:20 +08:00
--subnet=240.0.0.0/24 \
--gateway=240.0.0.1 \
2019-12-19 00:10:10 +08:00
sl-network
```
### Postgres
2020-03-11 19:13:38 +08:00
This section creates a Postgres database using Docker.
2019-12-19 00:10:10 +08:00
2020-01-29 11:43:20 +08:00
If you already have a Postgres database in use, you can skip this section and just copy the database configuration (i.e. host, port, username, password, database name) to use in the next sections.
2019-12-19 00:10:10 +08:00
2020-01-29 11:43:20 +08:00
Run a Postgres Docker container as your Postgres database server. Make sure to replace `myuser` and `mypassword` with something more secret.
2019-12-19 00:10:10 +08:00
```bash
2020-01-28 15:43:30 +08:00
sudo docker run -d \
2019-12-19 00:10:10 +08:00
--name sl-db \
-e POSTGRES_PASSWORD=mypassword \
-e POSTGRES_USER=myuser \
-e POSTGRES_DB=simplelogin \
2020-01-28 01:12:53 +08:00
-p 5432:5432 \
2020-03-25 19:03:34 +08:00
-v $(pwd)/sl/db:/var/lib/postgresql/data \
2020-01-31 22:45:21 +08:00
--restart always \
2019-12-19 00:10:10 +08:00
--network="sl-network" \
2020-01-28 15:43:30 +08:00
postgres:12.1
2019-12-19 00:10:10 +08:00
```
2019-12-24 06:09:38 +08:00
To test whether the database operates correctly or not, run the following command:
2019-12-21 19:59:46 +08:00
```bash
2020-01-28 15:43:30 +08:00
sudo docker exec -it sl-db psql -U myuser simplelogin
2019-12-21 19:59:46 +08:00
```
2020-01-28 01:12:53 +08:00
you should be logged in the postgres console. Type `exit` to exit postgres console.
2019-12-19 00:10:10 +08:00
### Postfix
2019-12-24 06:09:38 +08:00
Install `postfix` and `postfix-pgsql` . The latter is used to connect Postfix and the Postgres database in the next steps.
2019-12-19 00:10:10 +08:00
```bash
2020-01-28 01:12:53 +08:00
sudo apt-get install -y postfix postfix-pgsql -y
2019-12-19 00:10:10 +08:00
```
2020-01-02 00:50:19 +08:00
Choose "Internet Site" in Postfix installation window then keep using the proposed value as *System mail name* in the next window.
2019-12-19 00:10:10 +08:00
2020-01-28 01:12:53 +08:00
Replace `/etc/postfix/main.cf` with the following content. Make sure to replace `mydomain.com` by your domain.
2019-12-19 00:10:10 +08:00
2020-01-28 01:12:53 +08:00
```
2020-01-28 15:44:35 +08:00
# POSTFIX config file, adapted for SimpleLogin
2020-01-28 01:12:53 +08:00
smtpd_banner = $myhostname ESMTP $mail_name (Ubuntu)
biff = no
# appending .domain is the MUA's job.
append_dot_mydomain = no
2019-12-19 00:10:10 +08:00
2020-01-28 01:12:53 +08:00
# Uncomment the next line to generate "delayed mail" warnings
#delay_warning_time = 4h
2019-12-19 00:10:10 +08:00
2020-01-28 01:12:53 +08:00
readme_directory = no
2020-01-20 20:58:05 +08:00
2020-01-28 01:12:53 +08:00
# See http://www.postfix.org/COMPATIBILITY_README.html -- default to 2 on
# fresh installs.
compatibility_level = 2
2020-01-20 20:58:05 +08:00
2020-01-28 01:12:53 +08:00
# TLS parameters
smtpd_tls_cert_file=/etc/ssl/certs/ssl-cert-snakeoil.pem
smtpd_tls_key_file=/etc/ssl/private/ssl-cert-snakeoil.key
smtpd_use_tls=yes
smtpd_tls_session_cache_database = btree:${data_directory}/smtpd_scache
smtp_tls_session_cache_database = btree:${data_directory}/smtp_scache
2020-01-20 20:58:05 +08:00
2020-01-28 01:12:53 +08:00
# See /usr/share/doc/postfix/TLS_README.gz in the postfix-doc package for
# information on enabling SSL in the smtp client.
2020-01-20 20:58:05 +08:00
2020-01-28 01:12:53 +08:00
alias_maps = hash:/etc/aliases
mynetworks = 127.0.0.0/8 [::ffff:127.0.0.0]/104 [::1]/128 240.0.0.0/24
2020-01-28 15:44:35 +08:00
# Set your domain here
2020-03-24 03:39:51 +08:00
mydestination =
2020-01-28 15:44:35 +08:00
myhostname = app.mydomain.com
2020-01-28 01:12:53 +08:00
mydomain = mydomain.com
myorigin = mydomain.com
2020-01-28 15:44:35 +08:00
2020-01-28 01:12:53 +08:00
relay_domains = pgsql:/etc/postfix/pgsql-relay-domains.cf
transport_maps = pgsql:/etc/postfix/pgsql-transport-maps.cf
2020-01-28 15:44:35 +08:00
# HELO restrictions
2020-01-28 01:12:53 +08:00
smtpd_delay_reject = yes
smtpd_helo_required = yes
2020-01-28 15:44:35 +08:00
smtpd_helo_restrictions =
permit_mynetworks,
reject_non_fqdn_helo_hostname,
reject_invalid_helo_hostname,
permit
# Sender restrictions:
smtpd_sender_restrictions =
permit_mynetworks,
reject_non_fqdn_sender,
reject_unknown_sender_domain,
permit
# Recipient restrictions:
smtpd_recipient_restrictions =
reject_unauth_pipelining,
reject_non_fqdn_recipient,
reject_unknown_recipient_domain,
permit_mynetworks,
reject_unauth_destination,
reject_rbl_client zen.spamhaus.org,
reject_rbl_client bl.spamcop.net,
permit
2019-12-19 00:10:10 +08:00
```
2020-03-11 19:13:38 +08:00
Create the `/etc/postfix/pgsql-relay-domains.cf` file with the following content.
2020-01-28 15:44:35 +08:00
Make sure that the database config is correctly set and replace `mydomain.com` with your domain.
2019-12-19 00:10:10 +08:00
```
# postgres config
hosts = localhost
user = myuser
password = mypassword
dbname = simplelogin
2020-03-11 19:13:38 +08:00
query = SELECT domain FROM custom_domain WHERE domain='%s' AND verified=true
2020-01-28 15:44:35 +08:00
UNION SELECT '%s' WHERE '%s' = 'mydomain.com' LIMIT 1;
2019-12-19 00:10:10 +08:00
```
2020-03-11 19:13:38 +08:00
Create the `/etc/postfix/pgsql-transport-maps.cf` file with the following content.
2020-01-28 15:44:35 +08:00
Again, make sure that the database config is correctly set and replace `mydomain.com` with your domain.
2019-12-19 00:10:10 +08:00
```
# postgres config
hosts = localhost
user = myuser
password = mypassword
dbname = simplelogin
# forward to smtp:127.0.0.1:20381 for custom domain AND email domain
2020-03-11 19:13:38 +08:00
query = SELECT 'smtp:127.0.0.1:20381' FROM custom_domain WHERE domain = '%s' AND verified=true
2020-01-28 15:44:35 +08:00
UNION SELECT 'smtp:127.0.0.1:20381' WHERE '%s' = 'mydomain.com' LIMIT 1;
2019-12-19 00:10:10 +08:00
```
2019-12-24 06:09:38 +08:00
Finally, restart Postfix
2019-12-19 00:10:10 +08:00
2020-01-28 15:43:30 +08:00
```bash
sudo systemctl restart postfix
```
2019-12-19 00:10:10 +08:00
### Run SimpleLogin Docker containers
2020-01-23 16:23:53 +08:00
To run the server, you need a config file. Please have a look at [config example ](example.env ) for an example to create one. Some parameters are optional and are commented out by default. Some have "dummy" values, fill them up if you want to enable these features (Paddle, AWS, etc).
2019-12-19 00:10:10 +08:00
2020-01-28 01:12:53 +08:00
Let's put your config file at `~/simplelogin.env` . Below is an example that you can use right away, make sure to replace `mydomain.com` by your domain and set `FLASK_SECRET` to a secret string.
2019-12-19 00:10:10 +08:00
2019-12-27 18:49:33 +08:00
Make sure to update the following variables and replace these values by yours.
2019-12-19 00:10:10 +08:00
```.env
2020-01-28 01:12:53 +08:00
# WebApp URL
2019-12-19 00:10:10 +08:00
URL=http://app.mydomain.com
2020-01-28 01:12:53 +08:00
# domain used to create alias
2019-12-19 00:10:10 +08:00
EMAIL_DOMAIN=mydomain.com
2020-01-28 01:12:53 +08:00
# transactional email is sent from this email address
2019-12-19 00:10:10 +08:00
SUPPORT_EMAIL=support@mydomain.com
2020-01-28 01:12:53 +08:00
# custom domain needs to point to these MX servers
2019-12-19 00:10:10 +08:00
EMAIL_SERVERS_WITH_PRIORITY=[(10, "app.mydomain.com.")]
2020-01-28 01:12:53 +08:00
# By default, new aliases must end with ".{random_word}". This is to avoid a person taking all "nice" aliases.
# this option doesn't make sense in self-hosted. Set this variable to disable this option.
DISABLE_ALIAS_SUFFIX=1
# If you want to use another MTA to send email, you could set the address of your MTA here
# By default, emails are sent using the the same Postfix server that receives emails
# POSTFIX_SERVER=my-postfix.com
# the DKIM private key used to compute DKIM-Signature
2019-12-19 00:10:10 +08:00
DKIM_PRIVATE_KEY_PATH=/dkim.key
2020-01-28 01:12:53 +08:00
# the DKIM public key used to setup custom domain DKIM
2019-12-28 06:35:28 +08:00
DKIM_PUBLIC_KEY_PATH=/dkim.pub.key
2020-01-28 01:12:53 +08:00
# DB Connection
2019-12-27 18:49:33 +08:00
DB_URI=postgresql://myuser:mypassword@sl-db:5432/simplelogin
2020-01-28 01:12:53 +08:00
FLASK_SECRET=put_something_secret_here
2020-03-25 19:03:34 +08:00
GNUPGHOME=/sl/pgp
2019-12-19 00:10:10 +08:00
```
2020-01-28 15:43:30 +08:00
Before running the webapp, you need to prepare the database by running the migration:
2019-12-19 00:10:10 +08:00
```bash
2020-01-28 15:43:30 +08:00
sudo docker run --rm \
2019-12-19 00:10:10 +08:00
--name sl-migration \
2020-03-25 19:03:34 +08:00
-v $(pwd)/sl:/sl \
2019-12-19 00:10:10 +08:00
-v $(pwd)/dkim.key:/dkim.key \
2019-12-28 06:35:28 +08:00
-v $(pwd)/dkim.pub.key:/dkim.pub.key \
2019-12-21 19:59:46 +08:00
-v $(pwd)/simplelogin.env:/code/.env \
2019-12-19 00:10:10 +08:00
--network="sl-network" \
2020-04-15 04:54:57 +08:00
simplelogin/app:3.0.1 flask db upgrade
2019-12-19 00:10:10 +08:00
```
This command could take a while to download the `simplelogin/app` docker image.
2019-12-24 06:09:38 +08:00
Now, it's time to run the `webapp` container!
2019-12-19 00:10:10 +08:00
```bash
2020-01-28 15:43:30 +08:00
sudo docker run -d \
2019-12-19 00:10:10 +08:00
--name sl-app \
2020-03-25 19:03:34 +08:00
-v $(pwd)/sl:/sl \
2019-12-21 19:59:46 +08:00
-v $(pwd)/simplelogin.env:/code/.env \
2019-12-19 00:10:10 +08:00
-v $(pwd)/dkim.key:/dkim.key \
2019-12-28 06:35:28 +08:00
-v $(pwd)/dkim.pub.key:/dkim.pub.key \
2019-12-19 00:10:10 +08:00
-p 7777:7777 \
2020-01-31 22:45:21 +08:00
--restart always \
2019-12-19 00:10:10 +08:00
--network="sl-network" \
2020-04-15 04:54:57 +08:00
simplelogin/app:3.0.1
2019-12-19 00:10:10 +08:00
```
2019-12-21 19:59:46 +08:00
Next run the `email handler`
2019-12-19 00:10:10 +08:00
```bash
2020-01-28 15:43:30 +08:00
sudo docker run -d \
2019-12-19 00:10:10 +08:00
--name sl-email \
2020-03-25 19:03:34 +08:00
-v $(pwd)/sl:/sl \
2019-12-21 19:59:46 +08:00
-v $(pwd)/simplelogin.env:/code/.env \
2019-12-19 00:10:10 +08:00
-v $(pwd)/dkim.key:/dkim.key \
2019-12-28 06:35:28 +08:00
-v $(pwd)/dkim.pub.key:/dkim.pub.key \
2019-12-19 00:10:10 +08:00
-p 20381:20381 \
2020-01-31 22:45:21 +08:00
--restart always \
2019-12-19 00:10:10 +08:00
--network="sl-network" \
2020-04-15 04:54:57 +08:00
simplelogin/app:3.0.1 python email_handler.py
2019-12-19 00:10:10 +08:00
```
### Nginx
Install Nginx
```bash
sudo apt-get install -y nginx
```
2019-12-24 06:09:38 +08:00
Then, create `/etc/nginx/sites-enabled/simplelogin` with the following lines:
2019-12-19 00:10:10 +08:00
```
server {
server_name app.mydomain.com;
location / {
proxy_pass http://localhost:7777;
}
}
```
2019-12-24 06:09:38 +08:00
Reload Nginx with the command below
2019-12-19 00:10:10 +08:00
```bash
sudo systemctl reload nginx
```
At this step, you should also setup the SSL for Nginx. [Certbot ](https://certbot.eff.org/lets-encrypt/ubuntuxenial-nginx ) can be a good option if you want a free SSL certificate.
### Enjoy!
2020-01-02 00:50:19 +08:00
If all of the above steps are successful, open http://app.mydomain.com/ and create your first account!
2019-12-19 00:10:10 +08:00
2020-01-28 01:12:53 +08:00
By default, new accounts are not premium so don't have unlimited alias. To make your account premium,
2020-01-23 16:21:16 +08:00
please go to the database, table "users" and set "lifetime" column to "1" or "TRUE".
2020-01-28 01:12:53 +08:00
You don't have to pay anything to SimpleLogin to use all its features.
You could make a donation to SimpleLogin on our Patreon page at https://www.patreon.com/simplelogin if you wish though.
2020-01-20 16:23:31 +08:00
2020-02-01 00:45:08 +08:00
### Misc
The above self-hosting instructions correspond to a freshly Ubuntu server and doesn't cover all possible server configuration.
Below are pointers to different topics:
2020-03-25 18:57:06 +08:00
- [Enable SSL ](docs/ssl.md )
2020-03-11 19:13:38 +08:00
- [UFW - uncomplicated firewall ](docs/ufw.md )
2020-02-01 00:56:33 +08:00
- [SES - Amazon Simple Email Service ](docs/ses.md )
2020-03-13 07:16:22 +08:00
- [Upgrade existing SimpleLogin installation ](docs/upgrade.md )
2020-02-01 00:45:08 +08:00
2019-12-19 00:10:10 +08:00
## Contributing
2020-01-02 00:50:19 +08:00
All work on SimpleLogin happens directly on GitHub.
2019-12-20 04:19:16 +08:00
### Run code locally
2020-02-04 18:56:47 +08:00
The project uses Python 3.7+ and Node v10. First, install all dependencies by running the following command. Feel free to use `virtualenv` or similar tools to isolate development environment.
2019-12-20 04:19:16 +08:00
```bash
pip3 install -r requirements.txt
```
2020-03-13 07:04:48 +08:00
You also need to install `gpg` , on Mac it can be done with:
```bash
brew install gnupg
```
2019-12-20 04:19:16 +08:00
Then make sure all tests pass
```bash
pytest
```
2020-03-11 19:13:38 +08:00
Install npm packages
2020-02-04 18:56:47 +08:00
```bash
cd static & & npm install
```
2020-01-23 16:23:53 +08:00
To run the code locally, please create a local setting file based on `example.env` :
create BaseForm to enable CSRF
register page
redirect user to dashboard if they are logged in
enable csrf for login page
Set models more strict
bootstrap developer page
add helper method to ModelMixin, remove CRUDMixin
display list of clients on developer index, add copy client-secret to clipboard using clipboardjs
add toastr and use jquery non slim
display a toast when user copies the client-secret
create new client, generate client-id using unidecode
client detail page: can edit client
add delete client
implement /oauth/authorize and /oauth/allow-deny
implement /oauth/token
add /oauth/user_info endpoint
handle scopes: wip
take into account scope: display scope, return user data according to scope
create virtual-domain, gen email, client_user model WIP
create authorize_nonlogin_user page
user can choose to generate a new email
no need to interfere with root logger
log for before and after request
if user has already allowed a client: generate a auth-code and redirect user to client
get_user_info takes into account gen email
display list of clients that have user has authorised
use yk-client domain instead of localhost as cookie depends on the domain name
use wtforms instead of flask_wtf
Dockerfile
delete virtual domain
EMAIL_DOMAIN can come from env var
bind to host 0.0.0.0
fix signup error: use session as default csrf_context
rename yourkey to simplelogin
add python-dotenv, ipython, sqlalchemy_utils
create DB_URI, FLASK_SECRET. Load config from CONFIG file if exist
add shortcuts to logging
create shell
add psycopg2
do not add local data in Dockerfile
add drop_db into shell
add shell.prepare_db()
fix prepare_db
setup sentry
copy assets from tabler/dist
add icon downloaded from https://commons.wikimedia.org/wiki/File:Simpleicons_Interface_key-tool-1.svg
integrate tabler - login and register page
add favicon
template: default, header. Use gravatar for user avatar url
use default template for dashboard, developer page
use another icon
add clipboard and notie
prettify dashboard
add notie css
add fake gen email and client-user
prettify list client page, use notie for toast
add email, name scope to new client
display client scope in client list
prettify new-client, client-detail
add sentry-sdk and blinker
add arrow, add dt jinja filter, prettify logout, dashboard
comment "last used" in dashboard for now
prettify date display
add copy email to clipboard to dashboard
use "users" as table name for User as "user" is reserved key in postgres
call prepare_db() when creating new db
error page 400, 401, 403, 404
prettify authorize_login_user
create already_authorize.html for user who has already authorized a client
user can generate new email
display all other generated emails
add ENV variable, only reset DB when ENV=local
fix: not return other users gen emails
display nb users for each client
refactor shell: remove prepare_db()
add sendgrid
add /favicon.ico route
add new config: URL, SUPPORT_EMAIL, SENDGRID_API_KEY
user needs to activate their account before login
create copy button on dashboard
client can have multiple redirect uris, in client detail can add/remove redirect-uri,
use redirect_uri passed in /authorize
refactor: move get_user_info into ClientUser model
dashboard: display all apps, all generated emails
add "id" into user_info
add trigger email button
invalidate the session at each new version by changing the secret
centralize Client creation into Client.create_new
user can enable/disable email forwarding
setup auto dismiss alert: just add .alert-auto-dismiss
move name down in register form
add shell.add_real_data
move blueprint template to its own package
prettify authorize page for non-authenticated user
update readme, return error if not redirect_uri
add flask-wtf, use psycopg2-binary
use flask-wtf FlaskForm instead of Form
rename email -> email_utils
add AWS_REGION, BUCKET, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY to config
add s3 module
add File model, add Client.icon_id
handle client icon update
can create client with icon
display client icon in client list page
add Client.home_url
take into account Client.home_url
add boto3
register: ask name first
only show "trigger test email" if email forwarding is enabled
display gen email in alphabetical order, client in client.name alphabetical order
better error page
the modal does not get close when user clicks outside of modal
add Client.published column
discover page that displays all published Client
add missing bootstrap.bundle.min.js.map
developer can publish/unpublish their app in discover
use notie for display flash message
create hotmail account
fix missing jquery
add footer, add global jinja2 variable
strengthen model: use nullable=False whenever possible,
rename client_id to oauth_client_id, client_secret to oauth_client_secret
add flask-migrate
init migrate
1st migrate version
fix rename client_id -> oauth_client_id
prettify UI
use flask_migrate.upgrade() instead of db.create_all()
make sure requirejs.config is called for all page
enable sentry for js, use uppercase for global jinja2 variables
add flask-admin
add User.is_admin column
setup flask admin, only accessible to admin user
fix migration: add server_default
replace session[redirect_after_login] by "next" request args
add pyproject.toml: ignore migrations/ in black
add register waiting_activation_email page
better email wording
add pytest
add get_host_name_and_scheme and tests
example fail test
fix test
fix client-id display
add flask-cors
/user_info supports cors, add /me as /user_info synonym
return client in /me
support implicit flow
no need to use with "app.app_context()"
add watchtower to requirement
add param ENABLE_CLOUDWATCH, CLOUDWATCH_LOG_GROUP, CLOUDWATCH_LOG_STREAM
add cloudwatch logger if cloudwatch is enabled
add 500 error page
add help text for list of used client
display list of app/website that an email has been used
click on client name brings to client detail page
create style.css to add additional style, append its url with the current sha1 to avoid cache
POC on how to send email using postfix
add sqlalchemy-utils
use arrow instead of datetime
add new params STRIPE_API, STRIPE_YEARLY_SKU, STRIPE_MONTHLY_PLAN
show full error in local
add plan, plan_expiration to User, need to create enum directly in migration script, cf https://github.com/sqlalchemy/alembic/issues/67
reformat all html files: use space instead of tab
new user will have trial plan for 15 days
add new param MAX_NB_EMAIL_FREE_PLAN
only user with enough quota can create new email
if user cannot create new gen email, pick randomly one from existing gen emails. Use flush instead of commit
rename STRIPE_YEARLY_SKU -> STRIPE_YEARLY_PLAN
open client page in discover in a new tab
add stripe
not logging /static call: disable flask logging, replace by after_request
add param STRIPE_SECRET_KEY
add 3 columns stripe_customer_id, stripe_card_token, stripe_subscription_id
user can upgrade their pricing
add setting page as coming-soon
add GenEmail, ClientUser to admin
ignore /admin/static logging
add more fake data
add ondelete="cascade" whenever possible
rename plan_expiration -> trial_expiration
reset migration: delete old migrations, create new one
rename test_send_email -> poc_send_email to avoid the file being called by pytest
add new param LYRA_ANALYTICS_ID, add lyra analytics
add how to create new migration into readme
add drift to base.html
notify admin when new user signs up or pays subscription
log exception in case of 500
use sendgrid to notify admin
add alias /userinfo to user_info endpoint
add change_password to shell
add info on how payment is handled
invite user to retry if card not working
remove drift and add "contact us" link
move poc_send_email into poc/
support getting client-id, client-secret from form-data in addition to basic auth
client-id, client-secret is passed in form-data by passport-oauth2 for ex
add jwtRS256 private and public key
add jwk-jws-jwt poc
add new param OPENID_PRIVATE_KEY_PATH, OPENID_PRIVATE_KEY_PATH
add scope, redirect_url to AuthorizationCode and OauthToken
take into scope when creating oauth-token, authorization-code
add jwcrypto
add jose_utils: make_id_token and verify_id_token
add &scope to redirect uri
add "email_verified": True into user_info
fix user not activated
add /oauth2 as alias for /oauth
handle case where scope and state are empty
remove threaded=False
Use Email Alias as wording
remove help text
user can re-send activation email
add "expired" into ActivationCode
Handle the case activation code is expired
reformat: use form.validate_on_submit instead of request.method == post && form.validate
use error text instead of flash()
display client oauth-id and oauth-secret on client detail page
not display oauth-secret on client listing
fix expiration check
improve page title, footer
add /jwks and /.well-known/openid-configuration
init properly tests, fix blueprint conflict bug in flask-admin
create oauth_models module
rename Scope -> ScopeE to distinguish with Scope DB model
set app.url_map.strict_slashes = False
use ScopeE instead of SCOPE_NAME, ...
support access_token passed as args in /userinfo
merge /allow-deny into /authorize
improve wording
take into account the case response_type=code and openid is in scope
take into account response_type=id_token, id_token token, id_token code
make sure to use in-memory db in test
fix scope can be null
allow cross_origin for /.well-known/openid-configuration and /jwks
fix footer link
center authorize form
rename trial_expiration to plan_expiration
move stripe init to create_app()
use real email to be able to receive email notification
add user.profile_picture_id column
use user profile picture and fallback to gravatar
use nguyenkims+local@gm to distinguish with staging
handle plan cancel, reactivation, user profile update
fix can_create_new_email
create cron.py that set plan to free when expired
add crontab.yml
add yacron
use notify_admin instead of LOG.error
add ResetPasswordCode model
user can change password in setting
increase display time for notie
add forgot_password page
If login error: redirect to this page upon success login.
hide discover tab
add column user.is_developer
only show developer menu to developer
comment out the publish button
set local user to developer
make sure only developer can access /developer blueprint
User is invited to upgrade if they are in free plan or their trial ends soon
not sending email when in local mode
create Partner model
create become partner page
use normal error handling on local
fix migration
add "import sqlalchemy_utils" into migration template
small refactoring on setting page
handle promo code. TODO: add migration file
add migration for user.promo_codes
move email alias on top of apps in dashboard
add introjs
move encode_url to utils
create GenEmail.create_new_gen_email
create a first alias mail to show user how to use when they login
show intro when user visits the website the first time
fix register
2019-07-02 15:20:12 +08:00
2019-12-10 05:26:58 +08:00
```
2020-01-23 16:23:53 +08:00
cp example.env .env
create BaseForm to enable CSRF
register page
redirect user to dashboard if they are logged in
enable csrf for login page
Set models more strict
bootstrap developer page
add helper method to ModelMixin, remove CRUDMixin
display list of clients on developer index, add copy client-secret to clipboard using clipboardjs
add toastr and use jquery non slim
display a toast when user copies the client-secret
create new client, generate client-id using unidecode
client detail page: can edit client
add delete client
implement /oauth/authorize and /oauth/allow-deny
implement /oauth/token
add /oauth/user_info endpoint
handle scopes: wip
take into account scope: display scope, return user data according to scope
create virtual-domain, gen email, client_user model WIP
create authorize_nonlogin_user page
user can choose to generate a new email
no need to interfere with root logger
log for before and after request
if user has already allowed a client: generate a auth-code and redirect user to client
get_user_info takes into account gen email
display list of clients that have user has authorised
use yk-client domain instead of localhost as cookie depends on the domain name
use wtforms instead of flask_wtf
Dockerfile
delete virtual domain
EMAIL_DOMAIN can come from env var
bind to host 0.0.0.0
fix signup error: use session as default csrf_context
rename yourkey to simplelogin
add python-dotenv, ipython, sqlalchemy_utils
create DB_URI, FLASK_SECRET. Load config from CONFIG file if exist
add shortcuts to logging
create shell
add psycopg2
do not add local data in Dockerfile
add drop_db into shell
add shell.prepare_db()
fix prepare_db
setup sentry
copy assets from tabler/dist
add icon downloaded from https://commons.wikimedia.org/wiki/File:Simpleicons_Interface_key-tool-1.svg
integrate tabler - login and register page
add favicon
template: default, header. Use gravatar for user avatar url
use default template for dashboard, developer page
use another icon
add clipboard and notie
prettify dashboard
add notie css
add fake gen email and client-user
prettify list client page, use notie for toast
add email, name scope to new client
display client scope in client list
prettify new-client, client-detail
add sentry-sdk and blinker
add arrow, add dt jinja filter, prettify logout, dashboard
comment "last used" in dashboard for now
prettify date display
add copy email to clipboard to dashboard
use "users" as table name for User as "user" is reserved key in postgres
call prepare_db() when creating new db
error page 400, 401, 403, 404
prettify authorize_login_user
create already_authorize.html for user who has already authorized a client
user can generate new email
display all other generated emails
add ENV variable, only reset DB when ENV=local
fix: not return other users gen emails
display nb users for each client
refactor shell: remove prepare_db()
add sendgrid
add /favicon.ico route
add new config: URL, SUPPORT_EMAIL, SENDGRID_API_KEY
user needs to activate their account before login
create copy button on dashboard
client can have multiple redirect uris, in client detail can add/remove redirect-uri,
use redirect_uri passed in /authorize
refactor: move get_user_info into ClientUser model
dashboard: display all apps, all generated emails
add "id" into user_info
add trigger email button
invalidate the session at each new version by changing the secret
centralize Client creation into Client.create_new
user can enable/disable email forwarding
setup auto dismiss alert: just add .alert-auto-dismiss
move name down in register form
add shell.add_real_data
move blueprint template to its own package
prettify authorize page for non-authenticated user
update readme, return error if not redirect_uri
add flask-wtf, use psycopg2-binary
use flask-wtf FlaskForm instead of Form
rename email -> email_utils
add AWS_REGION, BUCKET, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY to config
add s3 module
add File model, add Client.icon_id
handle client icon update
can create client with icon
display client icon in client list page
add Client.home_url
take into account Client.home_url
add boto3
register: ask name first
only show "trigger test email" if email forwarding is enabled
display gen email in alphabetical order, client in client.name alphabetical order
better error page
the modal does not get close when user clicks outside of modal
add Client.published column
discover page that displays all published Client
add missing bootstrap.bundle.min.js.map
developer can publish/unpublish their app in discover
use notie for display flash message
create hotmail account
fix missing jquery
add footer, add global jinja2 variable
strengthen model: use nullable=False whenever possible,
rename client_id to oauth_client_id, client_secret to oauth_client_secret
add flask-migrate
init migrate
1st migrate version
fix rename client_id -> oauth_client_id
prettify UI
use flask_migrate.upgrade() instead of db.create_all()
make sure requirejs.config is called for all page
enable sentry for js, use uppercase for global jinja2 variables
add flask-admin
add User.is_admin column
setup flask admin, only accessible to admin user
fix migration: add server_default
replace session[redirect_after_login] by "next" request args
add pyproject.toml: ignore migrations/ in black
add register waiting_activation_email page
better email wording
add pytest
add get_host_name_and_scheme and tests
example fail test
fix test
fix client-id display
add flask-cors
/user_info supports cors, add /me as /user_info synonym
return client in /me
support implicit flow
no need to use with "app.app_context()"
add watchtower to requirement
add param ENABLE_CLOUDWATCH, CLOUDWATCH_LOG_GROUP, CLOUDWATCH_LOG_STREAM
add cloudwatch logger if cloudwatch is enabled
add 500 error page
add help text for list of used client
display list of app/website that an email has been used
click on client name brings to client detail page
create style.css to add additional style, append its url with the current sha1 to avoid cache
POC on how to send email using postfix
add sqlalchemy-utils
use arrow instead of datetime
add new params STRIPE_API, STRIPE_YEARLY_SKU, STRIPE_MONTHLY_PLAN
show full error in local
add plan, plan_expiration to User, need to create enum directly in migration script, cf https://github.com/sqlalchemy/alembic/issues/67
reformat all html files: use space instead of tab
new user will have trial plan for 15 days
add new param MAX_NB_EMAIL_FREE_PLAN
only user with enough quota can create new email
if user cannot create new gen email, pick randomly one from existing gen emails. Use flush instead of commit
rename STRIPE_YEARLY_SKU -> STRIPE_YEARLY_PLAN
open client page in discover in a new tab
add stripe
not logging /static call: disable flask logging, replace by after_request
add param STRIPE_SECRET_KEY
add 3 columns stripe_customer_id, stripe_card_token, stripe_subscription_id
user can upgrade their pricing
add setting page as coming-soon
add GenEmail, ClientUser to admin
ignore /admin/static logging
add more fake data
add ondelete="cascade" whenever possible
rename plan_expiration -> trial_expiration
reset migration: delete old migrations, create new one
rename test_send_email -> poc_send_email to avoid the file being called by pytest
add new param LYRA_ANALYTICS_ID, add lyra analytics
add how to create new migration into readme
add drift to base.html
notify admin when new user signs up or pays subscription
log exception in case of 500
use sendgrid to notify admin
add alias /userinfo to user_info endpoint
add change_password to shell
add info on how payment is handled
invite user to retry if card not working
remove drift and add "contact us" link
move poc_send_email into poc/
support getting client-id, client-secret from form-data in addition to basic auth
client-id, client-secret is passed in form-data by passport-oauth2 for ex
add jwtRS256 private and public key
add jwk-jws-jwt poc
add new param OPENID_PRIVATE_KEY_PATH, OPENID_PRIVATE_KEY_PATH
add scope, redirect_url to AuthorizationCode and OauthToken
take into scope when creating oauth-token, authorization-code
add jwcrypto
add jose_utils: make_id_token and verify_id_token
add &scope to redirect uri
add "email_verified": True into user_info
fix user not activated
add /oauth2 as alias for /oauth
handle case where scope and state are empty
remove threaded=False
Use Email Alias as wording
remove help text
user can re-send activation email
add "expired" into ActivationCode
Handle the case activation code is expired
reformat: use form.validate_on_submit instead of request.method == post && form.validate
use error text instead of flash()
display client oauth-id and oauth-secret on client detail page
not display oauth-secret on client listing
fix expiration check
improve page title, footer
add /jwks and /.well-known/openid-configuration
init properly tests, fix blueprint conflict bug in flask-admin
create oauth_models module
rename Scope -> ScopeE to distinguish with Scope DB model
set app.url_map.strict_slashes = False
use ScopeE instead of SCOPE_NAME, ...
support access_token passed as args in /userinfo
merge /allow-deny into /authorize
improve wording
take into account the case response_type=code and openid is in scope
take into account response_type=id_token, id_token token, id_token code
make sure to use in-memory db in test
fix scope can be null
allow cross_origin for /.well-known/openid-configuration and /jwks
fix footer link
center authorize form
rename trial_expiration to plan_expiration
move stripe init to create_app()
use real email to be able to receive email notification
add user.profile_picture_id column
use user profile picture and fallback to gravatar
use nguyenkims+local@gm to distinguish with staging
handle plan cancel, reactivation, user profile update
fix can_create_new_email
create cron.py that set plan to free when expired
add crontab.yml
add yacron
use notify_admin instead of LOG.error
add ResetPasswordCode model
user can change password in setting
increase display time for notie
add forgot_password page
If login error: redirect to this page upon success login.
hide discover tab
add column user.is_developer
only show developer menu to developer
comment out the publish button
set local user to developer
make sure only developer can access /developer blueprint
User is invited to upgrade if they are in free plan or their trial ends soon
not sending email when in local mode
create Partner model
create become partner page
use normal error handling on local
fix migration
add "import sqlalchemy_utils" into migration template
small refactoring on setting page
handle promo code. TODO: add migration file
add migration for user.promo_codes
move email alias on top of apps in dashboard
add introjs
move encode_url to utils
create GenEmail.create_new_gen_email
create a first alias mail to show user how to use when they login
show intro when user visits the website the first time
fix register
2019-07-02 15:20:12 +08:00
```
2019-12-21 20:00:07 +08:00
Make sure to uncomment the `RESET_DB=true` to create the database locally.
2019-12-10 05:26:58 +08:00
Feel free to custom your `.env` file, it would be your default setting when developing locally. This file is ignored by git.
create BaseForm to enable CSRF
register page
redirect user to dashboard if they are logged in
enable csrf for login page
Set models more strict
bootstrap developer page
add helper method to ModelMixin, remove CRUDMixin
display list of clients on developer index, add copy client-secret to clipboard using clipboardjs
add toastr and use jquery non slim
display a toast when user copies the client-secret
create new client, generate client-id using unidecode
client detail page: can edit client
add delete client
implement /oauth/authorize and /oauth/allow-deny
implement /oauth/token
add /oauth/user_info endpoint
handle scopes: wip
take into account scope: display scope, return user data according to scope
create virtual-domain, gen email, client_user model WIP
create authorize_nonlogin_user page
user can choose to generate a new email
no need to interfere with root logger
log for before and after request
if user has already allowed a client: generate a auth-code and redirect user to client
get_user_info takes into account gen email
display list of clients that have user has authorised
use yk-client domain instead of localhost as cookie depends on the domain name
use wtforms instead of flask_wtf
Dockerfile
delete virtual domain
EMAIL_DOMAIN can come from env var
bind to host 0.0.0.0
fix signup error: use session as default csrf_context
rename yourkey to simplelogin
add python-dotenv, ipython, sqlalchemy_utils
create DB_URI, FLASK_SECRET. Load config from CONFIG file if exist
add shortcuts to logging
create shell
add psycopg2
do not add local data in Dockerfile
add drop_db into shell
add shell.prepare_db()
fix prepare_db
setup sentry
copy assets from tabler/dist
add icon downloaded from https://commons.wikimedia.org/wiki/File:Simpleicons_Interface_key-tool-1.svg
integrate tabler - login and register page
add favicon
template: default, header. Use gravatar for user avatar url
use default template for dashboard, developer page
use another icon
add clipboard and notie
prettify dashboard
add notie css
add fake gen email and client-user
prettify list client page, use notie for toast
add email, name scope to new client
display client scope in client list
prettify new-client, client-detail
add sentry-sdk and blinker
add arrow, add dt jinja filter, prettify logout, dashboard
comment "last used" in dashboard for now
prettify date display
add copy email to clipboard to dashboard
use "users" as table name for User as "user" is reserved key in postgres
call prepare_db() when creating new db
error page 400, 401, 403, 404
prettify authorize_login_user
create already_authorize.html for user who has already authorized a client
user can generate new email
display all other generated emails
add ENV variable, only reset DB when ENV=local
fix: not return other users gen emails
display nb users for each client
refactor shell: remove prepare_db()
add sendgrid
add /favicon.ico route
add new config: URL, SUPPORT_EMAIL, SENDGRID_API_KEY
user needs to activate their account before login
create copy button on dashboard
client can have multiple redirect uris, in client detail can add/remove redirect-uri,
use redirect_uri passed in /authorize
refactor: move get_user_info into ClientUser model
dashboard: display all apps, all generated emails
add "id" into user_info
add trigger email button
invalidate the session at each new version by changing the secret
centralize Client creation into Client.create_new
user can enable/disable email forwarding
setup auto dismiss alert: just add .alert-auto-dismiss
move name down in register form
add shell.add_real_data
move blueprint template to its own package
prettify authorize page for non-authenticated user
update readme, return error if not redirect_uri
add flask-wtf, use psycopg2-binary
use flask-wtf FlaskForm instead of Form
rename email -> email_utils
add AWS_REGION, BUCKET, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY to config
add s3 module
add File model, add Client.icon_id
handle client icon update
can create client with icon
display client icon in client list page
add Client.home_url
take into account Client.home_url
add boto3
register: ask name first
only show "trigger test email" if email forwarding is enabled
display gen email in alphabetical order, client in client.name alphabetical order
better error page
the modal does not get close when user clicks outside of modal
add Client.published column
discover page that displays all published Client
add missing bootstrap.bundle.min.js.map
developer can publish/unpublish their app in discover
use notie for display flash message
create hotmail account
fix missing jquery
add footer, add global jinja2 variable
strengthen model: use nullable=False whenever possible,
rename client_id to oauth_client_id, client_secret to oauth_client_secret
add flask-migrate
init migrate
1st migrate version
fix rename client_id -> oauth_client_id
prettify UI
use flask_migrate.upgrade() instead of db.create_all()
make sure requirejs.config is called for all page
enable sentry for js, use uppercase for global jinja2 variables
add flask-admin
add User.is_admin column
setup flask admin, only accessible to admin user
fix migration: add server_default
replace session[redirect_after_login] by "next" request args
add pyproject.toml: ignore migrations/ in black
add register waiting_activation_email page
better email wording
add pytest
add get_host_name_and_scheme and tests
example fail test
fix test
fix client-id display
add flask-cors
/user_info supports cors, add /me as /user_info synonym
return client in /me
support implicit flow
no need to use with "app.app_context()"
add watchtower to requirement
add param ENABLE_CLOUDWATCH, CLOUDWATCH_LOG_GROUP, CLOUDWATCH_LOG_STREAM
add cloudwatch logger if cloudwatch is enabled
add 500 error page
add help text for list of used client
display list of app/website that an email has been used
click on client name brings to client detail page
create style.css to add additional style, append its url with the current sha1 to avoid cache
POC on how to send email using postfix
add sqlalchemy-utils
use arrow instead of datetime
add new params STRIPE_API, STRIPE_YEARLY_SKU, STRIPE_MONTHLY_PLAN
show full error in local
add plan, plan_expiration to User, need to create enum directly in migration script, cf https://github.com/sqlalchemy/alembic/issues/67
reformat all html files: use space instead of tab
new user will have trial plan for 15 days
add new param MAX_NB_EMAIL_FREE_PLAN
only user with enough quota can create new email
if user cannot create new gen email, pick randomly one from existing gen emails. Use flush instead of commit
rename STRIPE_YEARLY_SKU -> STRIPE_YEARLY_PLAN
open client page in discover in a new tab
add stripe
not logging /static call: disable flask logging, replace by after_request
add param STRIPE_SECRET_KEY
add 3 columns stripe_customer_id, stripe_card_token, stripe_subscription_id
user can upgrade their pricing
add setting page as coming-soon
add GenEmail, ClientUser to admin
ignore /admin/static logging
add more fake data
add ondelete="cascade" whenever possible
rename plan_expiration -> trial_expiration
reset migration: delete old migrations, create new one
rename test_send_email -> poc_send_email to avoid the file being called by pytest
add new param LYRA_ANALYTICS_ID, add lyra analytics
add how to create new migration into readme
add drift to base.html
notify admin when new user signs up or pays subscription
log exception in case of 500
use sendgrid to notify admin
add alias /userinfo to user_info endpoint
add change_password to shell
add info on how payment is handled
invite user to retry if card not working
remove drift and add "contact us" link
move poc_send_email into poc/
support getting client-id, client-secret from form-data in addition to basic auth
client-id, client-secret is passed in form-data by passport-oauth2 for ex
add jwtRS256 private and public key
add jwk-jws-jwt poc
add new param OPENID_PRIVATE_KEY_PATH, OPENID_PRIVATE_KEY_PATH
add scope, redirect_url to AuthorizationCode and OauthToken
take into scope when creating oauth-token, authorization-code
add jwcrypto
add jose_utils: make_id_token and verify_id_token
add &scope to redirect uri
add "email_verified": True into user_info
fix user not activated
add /oauth2 as alias for /oauth
handle case where scope and state are empty
remove threaded=False
Use Email Alias as wording
remove help text
user can re-send activation email
add "expired" into ActivationCode
Handle the case activation code is expired
reformat: use form.validate_on_submit instead of request.method == post && form.validate
use error text instead of flash()
display client oauth-id and oauth-secret on client detail page
not display oauth-secret on client listing
fix expiration check
improve page title, footer
add /jwks and /.well-known/openid-configuration
init properly tests, fix blueprint conflict bug in flask-admin
create oauth_models module
rename Scope -> ScopeE to distinguish with Scope DB model
set app.url_map.strict_slashes = False
use ScopeE instead of SCOPE_NAME, ...
support access_token passed as args in /userinfo
merge /allow-deny into /authorize
improve wording
take into account the case response_type=code and openid is in scope
take into account response_type=id_token, id_token token, id_token code
make sure to use in-memory db in test
fix scope can be null
allow cross_origin for /.well-known/openid-configuration and /jwks
fix footer link
center authorize form
rename trial_expiration to plan_expiration
move stripe init to create_app()
use real email to be able to receive email notification
add user.profile_picture_id column
use user profile picture and fallback to gravatar
use nguyenkims+local@gm to distinguish with staging
handle plan cancel, reactivation, user profile update
fix can_create_new_email
create cron.py that set plan to free when expired
add crontab.yml
add yacron
use notify_admin instead of LOG.error
add ResetPasswordCode model
user can change password in setting
increase display time for notie
add forgot_password page
If login error: redirect to this page upon success login.
hide discover tab
add column user.is_developer
only show developer menu to developer
comment out the publish button
set local user to developer
make sure only developer can access /developer blueprint
User is invited to upgrade if they are in free plan or their trial ends soon
not sending email when in local mode
create Partner model
create become partner page
use normal error handling on local
fix migration
add "import sqlalchemy_utils" into migration template
small refactoring on setting page
handle promo code. TODO: add migration file
add migration for user.promo_codes
move email alias on top of apps in dashboard
add introjs
move encode_url to utils
create GenEmail.create_new_gen_email
create a first alias mail to show user how to use when they login
show intro when user visits the website the first time
fix register
2019-07-02 15:20:12 +08:00
2019-12-24 06:09:38 +08:00
You don't need all the parameters, for example, if you don't update images to s3, then
2020-01-23 16:23:53 +08:00
`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 `example.env` file contains minimal requirement so that if you run:
2019-12-04 07:48:30 +08:00
```
2019-12-10 05:26:58 +08:00
python3 server.py
```
2019-12-04 07:48:30 +08:00
2019-12-10 05:26:58 +08:00
then open http://localhost:7777, you should be able to login with the following account
2019-12-04 07:48:30 +08:00
2019-12-10 05:26:58 +08:00
```
john@wick.com / password
```
2019-12-04 07:48:30 +08:00
2019-12-20 04:19:16 +08:00
### API
2020-01-28 01:12:53 +08:00
SimpleLogin current API clients are Chrome/Firefox/Safari extension and mobile (iOS/Android) app.
2020-01-20 21:36:39 +08:00
These clients rely on `API Code` for authentication.
2019-12-20 04:19:16 +08:00
2020-01-20 21:36:39 +08:00
Once the `Api Code` is obtained, either via user entering it (in Browser extension case) or by logging in (in Mobile case),
2020-01-28 01:12:53 +08:00
the client includes the `api code` in `Authentication` header in almost all requests.
2019-12-20 04:19:16 +08:00
2020-01-28 01:12:53 +08:00
For some endpoints, the `hostname` should be passed in query string. `hostname` is the the URL hostname (cf https://en.wikipedia.org/wiki/URL), for ex if URL is http://www.example.com/index.html then the hostname is `www.example.com` . This information is important to know where an alias is used in order to suggest user the same alias if they want to create on alias on the same website in the future.
2020-01-06 03:47:56 +08:00
If error, the API returns 4** with body containing the error message, for example:
```json
2020-01-06 04:09:54 +08:00
{
"error": "request body cannot be empty"
}
2020-01-06 03:47:56 +08:00
```
2020-01-28 01:12:53 +08:00
The error message could be displayed to user as-is, for example for when user exceeds their alias quota.
Some errors should be fixed during development however: for example error like `request body cannot be empty` is there to catch development error and should never be shown to user.
2020-01-06 04:09:54 +08:00
All following endpoint return `401` status code if the API Key is incorrect.
2020-01-06 03:47:56 +08:00
2020-01-06 05:48:38 +08:00
#### GET /api/user_info
2020-01-28 01:12:53 +08:00
Given the API Key, return user name and whether user is premium.
2020-01-06 05:48:38 +08:00
This endpoint could be used to validate the api key.
Input:
- `Authentication` header that contains the api key
Output: if api key is correct, return a json with user name and whether user is premium, for example:
```json
{
2020-03-19 01:34:37 +08:00
"name": "John Wick",
"is_premium": false,
2020-03-19 02:08:16 +08:00
"email": "john@wick.com",
"in_trial": true
2020-01-06 05:48:38 +08:00
}
```
If api key is incorrect, return 401.
2020-05-02 22:21:18 +08:00
#### GET /api/v4/alias/options
2020-01-06 03:47:56 +08:00
User alias info and suggestion. Used by the first extension screen when user opens the extension.
Input:
- `Authentication` header that contains the api key
2020-01-28 01:12:53 +08:00
- (Optional but recommended) `hostname` passed in query string.
2020-01-06 03:47:56 +08:00
Output: a json with the following field:
- can_create: boolean. Whether user can create new alias
2020-05-02 22:21:18 +08:00
- suffixes: list of `[suffix, signed-suffix]` . List of alias `suffix` that user can use. The `signed-suffix` is necessary to avoid request tampering.
2020-01-06 03:47:56 +08:00
- prefix_suggestion: string. Suggestion for the `alias prefix` . Usually this is the website name extracted from `hostname` . If no `hostname` , then the `prefix_suggestion` is empty.
- recommendation: optional field, dictionary. If an alias is already used for this website, the recommendation will be returned. There are 2 subfields in `recommendation` : `alias` which is the recommended alias and `hostname` is the website on which this alias is used before.
For ex:
```json
{
"can_create": true,
2020-05-02 22:21:18 +08:00
"prefix_suggestion": "",
2020-01-06 03:47:56 +08:00
"suffixes": [
2020-05-02 22:21:18 +08:00
[
"@ab.cd",
"@ab.cd.Xq2BOA.zBebBB-QYikFkbPZ9CPKGpJ2-PU"
],
[
".yeah@local1.localhost",
".yeah@local1.localhost.Xq2BOA.dM9gyHyHcSXuJ8ps4i3wpJZ_Frw"
]
2020-01-06 03:47:56 +08:00
]
}
2019-12-20 04:19:16 +08:00
```
2020-05-02 22:22:17 +08:00
#### POST /api/v2/alias/custom/new
2019-12-20 04:19:16 +08:00
2020-01-06 03:47:56 +08:00
Create a new custom alias.
2019-12-30 20:33:32 +08:00
2020-01-28 01:12:53 +08:00
Input:
2020-01-06 03:47:56 +08:00
- `Authentication` header that contains the api key
- (Optional but recommended) `hostname` passed in query string
- Request Message Body in json (`Content-Type` is `application/json` )
- alias_prefix: string. The first part of the alias that user can choose.
2020-05-02 22:22:17 +08:00
- signed_suffix: should be one of the suffixes returned in the `GET /api/v4/alias/options` endpoint.
2020-03-11 19:18:27 +08:00
- (Optional) note: alias note
2019-12-29 22:43:59 +08:00
2020-01-06 03:47:56 +08:00
Output:
2020-01-28 01:12:53 +08:00
If success, 201 with the new alias, for example
2019-12-20 04:19:16 +08:00
2020-01-06 03:47:56 +08:00
```json
2020-01-06 04:09:54 +08:00
{
2020-03-27 02:48:36 +08:00
"alias": "www_groupon_com@my_domain.com",
"creation_date": "2020-02-04 16:23:02+00:00",
"creation_timestamp": 1580833382,
"email": "www_groupon_com@my_domain.com",
"id": 4,
"nb_block": 0,
"nb_forward": 0,
"nb_reply": 0,
"enabled": true,
"note": "This is a note"
2020-01-06 04:09:54 +08:00
}
2019-12-20 04:19:16 +08:00
```
2020-01-06 04:15:16 +08:00
#### POST /api/alias/random/new
Create a new random alias.
2020-01-28 01:12:53 +08:00
Input:
2020-01-06 04:15:16 +08:00
- `Authentication` header that contains the api key
- (Optional but recommended) `hostname` passed in query string
2020-02-07 22:30:46 +08:00
- (Optional) mode: either `uuid` or `word` . By default, use the user setting when creating new random alias.
2020-03-11 19:24:30 +08:00
- Request Message Body in json (`Content-Type` is `application/json` )
- (Optional) note: alias note
2020-01-06 04:15:16 +08:00
Output:
2020-01-28 01:12:53 +08:00
If success, 201 with the new alias, for example
2020-01-06 04:15:16 +08:00
```json
{
2020-03-27 02:50:22 +08:00
"alias": "prefix.suffix@my_domain.com",
"creation_date": "2020-02-04 16:23:02+00:00",
"creation_timestamp": 1580833382,
"email": "www_groupon_com@my_domain.com",
"id": 4,
"nb_block": 0,
"nb_forward": 0,
"nb_reply": 0,
"enabled": true,
"note": "This is a note"
2020-01-06 04:15:16 +08:00
}
```
2019-12-20 04:19:16 +08:00
2020-01-20 21:36:39 +08:00
#### POST /api/auth/login
Input:
- email
- password
- device: device name. Used to create the API Key. Should be humanly readable so user can manage later on the "API Key" page.
Output:
- name: user name, could be an empty string
- mfa_enabled: boolean
- mfa_key: only useful when user enables MFA. In this case, user needs to enter their OTP token in order to login.
- api_key: if MFA is not enabled, the `api key` is returned right away.
2020-01-20 22:00:56 +08:00
The `api_key` is used in all subsequent requests. It's empty if MFA is enabled.
If user hasn't enabled MFA, `mfa_key` is empty.
2020-05-08 03:54:36 +08:00
Return 403 if user has enabled FIDO. The client can display a message to suggest user to use the `API Key` instead.
2020-01-20 22:00:56 +08:00
#### POST /api/auth/mfa
Input:
- mfa_token: OTP token that user enters
- mfa_key: MFA key obtained in previous auth request, e.g. /api/auth/login
- device: the device name, used to create an ApiKey associated with this device
Output:
- name: user name, could be an empty string
- api_key: if MFA is not enabled, the `api key` is returned right away.
2020-01-20 21:36:39 +08:00
The `api_key` is used in all subsequent requests. It's empty if MFA is enabled.
2020-01-28 01:12:53 +08:00
If user hasn't enabled MFA, `mfa_key` is empty.
2020-01-20 21:36:39 +08:00
2020-02-27 23:57:24 +08:00
#### POST /api/auth/facebook
Input:
- facebook_token: Facebook access token
- device: device name. Used to create the API Key. Should be humanly readable so user can manage later on the "API Key" page.
Output: Same output as for `/api/auth/login` endpoint
2020-02-28 18:29:33 +08:00
#### POST /api/auth/google
Input:
2020-03-05 04:35:31 +08:00
- google_token: Google access token
2020-02-28 18:29:33 +08:00
- device: device name. Used to create the API Key. Should be humanly readable so user can manage later on the "API Key" page.
Output: Same output as for `/api/auth/login` endpoint
2020-02-27 23:57:24 +08:00
2020-02-28 20:01:54 +08:00
#### POST /api/auth/register
Input:
- email
2020-03-11 19:13:38 +08:00
- password
2020-02-28 20:01:54 +08:00
Output: 200 means user is going to receive an email that contains an *activation code* . User needs to enter this code to confirm their account -> next endpoint.
#### POST /api/auth/activate
Input:
- email
2020-03-11 19:13:38 +08:00
- code: the activation code
2020-02-28 20:01:54 +08:00
Output:
- 200: account is activated. User can login now
- 400: wrong email, code
- 410: wrong code too many times. User needs to ask for an reactivation -> next endpoint
#### POST /api/auth/reactivate
Input:
- email
Output:
2020-03-11 19:13:38 +08:00
- 200: user is going to receive an email that contains the activation code.
2020-02-28 20:01:54 +08:00
2020-03-19 01:43:04 +08:00
#### POST /api/auth/forgot_password
Input:
- email
2020-03-19 04:55:50 +08:00
Output: always return 200, even if email doesn't exist. User need to enter correctly their email.
2020-03-19 01:43:04 +08:00
2020-04-26 05:40:40 +08:00
#### GET /api/mailboxes
Get user verified mailboxes.
Input:
- `Authentication` header that contains the api key
Output:
List of mailboxes. Each mailbox has id, email field.
```json
{
"mailboxes": [
{
"email": "a@b.c",
"id": 1
},
{
"email": "m1@example.com",
"id": 2
}
]
}
```
2020-04-07 04:26:35 +08:00
#### GET /api/v2/aliases
2020-02-05 00:26:59 +08:00
Get user aliases.
Input:
- `Authentication` header that contains the api key
2020-03-30 02:25:28 +08:00
- `page_id` in query. Used for the pagination. The endpoint returns maximum 20 aliases for each page. `page_id` starts at 0.
2020-03-18 02:32:45 +08:00
- (Optional) query: included in request body. Some frameworks might prevent GET request having a non-empty body, in this case this endpoint also supports POST.
2020-02-05 00:26:59 +08:00
Output:
2020-04-07 04:26:35 +08:00
If success, 200 with the list of aliases. Each alias has the following fields:
- id
- email
2020-04-26 16:38:58 +08:00
- name
2020-04-07 04:26:35 +08:00
- enabled
- creation_timestamp
- note
- nb_block
- nb_forward
- nb_reply
2020-04-26 05:13:05 +08:00
- mailbox
- id
- email
2020-04-07 04:26:35 +08:00
- (optional) latest_activity:
- action: forward|reply|block|bounced
- timestamp
- contact:
- email
- name
- reverse_alias
Here's an example:
2020-02-05 00:26:59 +08:00
```json
{
2020-04-07 04:26:35 +08:00
"aliases": [
{
"creation_date": "2020-04-06 17:57:14+00:00",
"creation_timestamp": 1586195834,
"email": "prefix1.cat@sl.local",
2020-04-26 16:38:58 +08:00
"name": "A Name",
2020-04-07 04:26:35 +08:00
"enabled": true,
"id": 3,
2020-04-26 05:13:05 +08:00
"mailbox": {
"email": "a@b.c",
"id": 1
},
2020-04-07 04:26:35 +08:00
"latest_activity": {
"action": "forward",
"contact": {
"email": "c1@example.com",
"name": null,
"reverse_alias": "\"c1 at example.com\" < re1 @ SL > "
2020-02-05 00:26:59 +08:00
},
2020-04-07 04:26:35 +08:00
"timestamp": 1586195834
},
"nb_block": 0,
"nb_forward": 1,
"nb_reply": 0,
"note": null
},
{
"creation_date": "2020-04-06 17:57:14+00:00",
"creation_timestamp": 1586195834,
"email": "prefix0.hey@sl.local",
2020-04-26 16:38:58 +08:00
"name": null,
2020-04-07 04:26:35 +08:00
"enabled": true,
"id": 2,
2020-04-26 05:13:05 +08:00
"mailbox": {
"email": "a@b.c",
"id": 1
},
2020-04-07 04:26:35 +08:00
"latest_activity": {
"action": "forward",
"contact": {
"email": "c0@example.com",
"name": null,
"reverse_alias": "\"c0 at example.com\" < re0 @ SL > "
},
"timestamp": 1586195834
},
"nb_block": 0,
"nb_forward": 1,
"nb_reply": 0,
"note": null
}
]
2020-02-05 00:26:59 +08:00
}
```
2020-03-27 02:44:00 +08:00
#### GET /api/aliases/:alias_id
Get alias info
Input:
- `Authentication` header that contains the api key
- `alias_id` in url
Output:
Alias info
```json
{
"creation_date": "2020-02-04 16:23:02+00:00",
"creation_timestamp": 1580833382,
"email": "e3@.alo@sl.local",
"id": 4,
"nb_block": 0,
"nb_forward": 0,
"nb_reply": 0,
"enabled": true,
"note": "This is a note"
}
```
2020-02-05 19:21:17 +08:00
#### DELETE /api/aliases/:alias_id
Delete an alias
Input:
- `Authentication` header that contains the api key
2020-03-11 19:13:38 +08:00
- `alias_id` in url.
2020-02-05 19:21:17 +08:00
Output:
If success, 200.
```json
{
"deleted": true
}
```
2020-02-05 19:28:54 +08:00
#### POST /api/aliases/:alias_id/toggle
Enable/disable alias
Input:
- `Authentication` header that contains the api key
2020-03-11 19:13:38 +08:00
- `alias_id` in url.
2020-02-05 19:28:54 +08:00
Output:
If success, 200 along with the new alias status:
```json
{
"enabled": false
}
```
2020-02-05 19:57:11 +08:00
#### GET /api/aliases/:alias_id/activities
Get activities for a given alias.
Input:
- `Authentication` header that contains the api key
- `alias_id` : the alias id, passed in url.
- `page_id` used in request query (`?page_id=0`). The endpoint returns maximum 20 aliases for each page. `page_id` starts at 0.
Output:
If success, 200 with the list of activities, for example:
```json
{
"activities": [
{
"action": "reply",
"from": "yes_meo_chat@sl.local",
"timestamp": 1580903760,
2020-04-05 01:18:07 +08:00
"to": "marketing@example.com",
2020-04-15 04:54:57 +08:00
"reverse_alias": "\"marketing at example.com\" < reply @ a . b > "
2020-02-05 19:57:11 +08:00
},
{
"action": "reply",
"from": "yes_meo_chat@sl.local",
"timestamp": 1580903760,
2020-04-05 01:18:07 +08:00
"to": "marketing@example.com",
2020-04-15 04:54:57 +08:00
"reverse_alias": "\"marketing at example.com\" < reply @ a . b > "
2020-02-05 19:57:11 +08:00
}
]
}
```
2020-03-14 18:38:39 +08:00
#### PUT /api/aliases/:alias_id
Update alias note. In the future, the endpoint will support other updates (e.g. mailbox update) as well.
Input:
- `Authentication` header that contains the api key
- `alias_id` in url.
2020-04-25 19:10:00 +08:00
- (optional) `note` in request body
- (optional) `mailbox_id` in request body
2020-04-26 16:38:16 +08:00
- (optional) `name` in request body
2020-03-14 18:38:39 +08:00
Output:
If success, return 200
2020-03-14 19:22:43 +08:00
#### GET /api/aliases/:alias_id/contacts
Get contacts for a given alias.
Input:
- `Authentication` header that contains the api key
- `alias_id` : the alias id, passed in url.
- `page_id` used in request query (`?page_id=0`). The endpoint returns maximum 20 contacts for each page. `page_id` starts at 0.
Output:
If success, 200 with the list of contacts, for example:
```json
{
"contacts": [
{
2020-03-17 19:38:50 +08:00
"id": 1,
2020-03-14 19:22:43 +08:00
"contact": "marketing@example.com",
"creation_date": "2020-02-21 11:35:00+00:00",
"creation_timestamp": 1582284900,
"last_email_sent_date": null,
"last_email_sent_timestamp": null,
"reverse_alias": "marketing at example.com < reply + bzvpazcdedcgcpztehxzgjgzmxskqa @ sl . co > "
},
{
2020-03-17 19:38:50 +08:00
"id": 2,
2020-03-14 19:22:43 +08:00
"contact": "newsletter@example.com",
"creation_date": "2020-02-21 11:35:00+00:00",
"creation_timestamp": 1582284900,
2020-04-15 04:54:57 +08:00
"last_email_sent_date": "2020-02-21 11:35:00+00:00",
2020-03-14 19:22:43 +08:00
"last_email_sent_timestamp": 1582284900,
"reverse_alias": "newsletter at example.com < reply + bzvpazcdedcgcpztehxzgjgzmxskqa @ sl . co > "
}
]
}
```
Please note that last_email_sent_timestamp and last_email_sent_date can be null.
2020-02-05 00:26:59 +08:00
2020-03-14 19:55:38 +08:00
#### POST /api/aliases/:alias_id/contacts
Create a new contact for an alias.
Input:
- `Authentication` header that contains the api key
- `alias_id` in url.
- `contact` in request body
Output:
If success, return 201
Return 409 if contact is already added.
```
{
2020-03-17 19:38:50 +08:00
"id": 1,
2020-03-14 19:55:38 +08:00
"contact": "First Last < first @ example . com > ",
"creation_date": "2020-03-14 11:52:41+00:00",
"creation_timestamp": 1584186761,
"last_email_sent_date": null,
"last_email_sent_timestamp": null,
"reverse_alias": "First Last first@example.com < ra + qytyzjhrumrreuszrbjxqjlkh @ sl . local > "
}
```
2020-03-18 02:18:26 +08:00
#### DELETE /api/contacts/:contact_id
Delete a contact
Input:
- `Authentication` header that contains the api key
- `contact_id` in url.
Output:
If success, 200.
```json
{
"deleted": true
}
```
2020-04-20 04:54:21 +08:00
#### POST /api/apple/process_payment
2020-04-19 17:13:38 +08:00
Process payment receipt
Input:
2020-04-19 17:20:44 +08:00
- `Authentication` in header: the api key
- `receipt_data` in body: the receipt_data base64Encoded returned by StoreKit, i.e. `rawReceiptData.base64EncodedString`
2020-04-29 21:50:06 +08:00
- (optional) `is_macapp` in body: if this field is present, the request is sent from the MacApp (Safari Extension) and not iOS app.
2020-04-19 17:13:38 +08:00
2020-04-19 17:22:05 +08:00
Output:
200 if user is upgraded successfully
4** if any error.
2019-12-20 04:19:16 +08:00
### Database migration
2019-12-04 07:48:30 +08:00
2019-12-20 04:19:16 +08:00
The database migration is handled by `alembic`
2019-12-04 07:48:30 +08:00
2020-05-05 18:39:31 +08:00
Whenever the model changes, a new migration has to be created.
2019-12-20 04:19:16 +08:00
2020-05-05 18:39:31 +08:00
If you have Docker installed, you can create the migration by the following script:
2019-12-20 04:19:16 +08:00
2019-12-27 18:49:33 +08:00
```bash
2020-05-07 23:59:21 +08:00
sh new_migration.sh
2019-12-27 18:49:33 +08:00
```
2020-05-05 18:39:31 +08:00
Make sure to review the migration script before committing it.
Sometimes (very rarely though), the automatically generated script can be incorrect.
We cannot use the local database to generate migration script as the local database doesn't use migration.
It is created via `db.create_all()` (cf `fake_data()` method). This is convenient for development and
unit tests as we don't have to wait for the migration.
2019-12-20 04:19:16 +08:00
2019-12-20 05:36:37 +08:00
### Code structure
2019-12-24 06:09:38 +08:00
The repo consists of the three following entry points:
2019-12-20 05:36:37 +08:00
2020-01-02 00:50:19 +08:00
- wsgi.py and server.py: the webapp.
- email_handler.py: the email handler.
- cron.py: the cronjob.
2019-12-20 05:36:37 +08:00
2019-12-24 06:09:38 +08:00
Here are the small sum-ups of the directory structures and their roles:
2019-12-20 05:36:37 +08:00
2019-12-24 06:09:38 +08:00
- app/: main Flask app. It is structured into different packages representing different features like oauth, api, dashboard, etc.
- local_data/: contains files to facilitate the local development. They are replaced during the deployment.
- migrations/: generated by flask-migrate. Edit these files will be only edited when you spot (very rare) errors on the database migration files.
2020-01-02 00:50:19 +08:00
- static/: files available at `/static` url.
2019-12-24 06:09:38 +08:00
- templates/: contains both html and email templates.
2019-12-20 05:36:37 +08:00
- tests/: tests. We don't really distinguish unit, functional or integration test. A test is simply here to make sure a feature works correctly.
2019-12-20 04:19:16 +08:00
2019-12-22 19:57:16 +08:00
The code is formatted using https://github.com/psf/black, to format the code, simply run
```
2020-01-29 11:43:20 +08:00
black .
2019-12-22 19:57:16 +08:00
```
2019-12-20 04:19:16 +08:00
### OAuth flow
SL currently supports code and implicit flow.
#### Code flow
2020-01-02 00:50:19 +08:00
To trigger the code flow locally, you can go to the following url after running `python server.py` :
2019-12-20 04:19:16 +08:00
```
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}
```
2019-12-24 06:09:38 +08:00
This should return an `access token` that allows to get user info via the following command. Again, `http` tool is used.
2019-12-20 04:19:16 +08:00
```
http http://localhost:7777/oauth/user_info 'Authorization:Bearer {token}'
```
#### Implicit flow
2020-01-02 00:50:19 +08:00
Similar to code flow, except for the the `access token` which we we get back with the redirection.
For implicit flow, the url is
2019-12-20 04:19:16 +08:00
```
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
```
2019-12-24 06:09:38 +08:00
#### OpenID and OAuth2 response_type & scope
2019-12-20 04:19:16 +08:00
2019-12-24 06:09:38 +08:00
According to the sharing web blog titled [Diagrams of All The OpenID Connect Flows ](https://medium.com/@darutk/diagrams-of-all-the-openid-connect-flows-6968e3990660 ), we should pay attention to:
2019-12-20 04:19:16 +08:00
2019-12-24 06:09:38 +08:00
- `response_type` can be either `code, token, id_token` or any combination of those attributes.
- `scope` might contain `openid`
2019-12-20 04:19:16 +08:00
2019-12-24 06:09:38 +08:00
Below are the potential combinations that are taken into account in SL until now:
2019-12-20 04:19:16 +08:00
```
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
2020-01-28 01:12:53 +08:00
2019-12-20 04:19:16 +08:00
response_type=id_token token
return `id_token` in addition to `access_token` in /authorization endpoint
2020-01-28 01:12:53 +08:00
2019-12-20 04:19:16 +08:00
response_type=id_token code
return `id_token` in addition to `authorization_code` in /authorization endpoint
```
2020-01-02 01:55:59 +08:00
## ❤️ Contributors
Thanks go to these wonderful people:
< table >
< tr >
< td align = "center" > < a href = "https://www.linkedin.com/in/vandungnguyen/" > < img src = "https://simplelogin.io/about/dung.jpg" width = "100px;" alt = "Dung Nguyen Van" / > < br / > < sub > < b > Dung Nguyen Van< / b > < / sub > < / a > < br / > < / td >
< td align = "center" > < a href = "https://www.linkedin.com/in/giuseppe-f-83449ba4/" > < img src = "https://simplelogin.io/about/giuseppe.jpeg" width = "100px;" alt = "Giuseppe Federico" / > < br / > < sub > < b > Giuseppe Federico< / b > < / sub > < / a > < br / > < / td >
< td align = "center" > < a href = "https://github.com/NinhDinh" > < img src = "https://avatars2.githubusercontent.com/u/1419742?s=460&v=4" width = "100px;" alt = "Ninh Dinh" / > < br / > < sub > < b > Ninh Dinh< / b > < / sub > < / a > < br / > < / td >
2020-01-28 01:12:53 +08:00
< td align = "center" > < a href = "https://github.com/ntung" > < img src = "https://avatars1.githubusercontent.com/u/663341?s=460&v=4" width = "100px;" alt = "Tung Nguyen V. N." / > < br / > < sub > < b > Tung Nguyen V. N.< / b > < / sub > < / a > < br / > < / td >
< td align = "center" > < a href = "https://www.linkedin.com/in/nguyenkims/" > < img src = "https://simplelogin.io/about/me.jpeg" width = "100px;" alt = "Son Nguyen Kim" / > < br / > < sub > < b > Son Nguyen Kim< / b > < / sub > < / a > < br / > < / td >
2020-01-02 01:55:59 +08:00
< / tr >
< / table >
