Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

add DCLOGIN uri scheme #48

Merged
merged 10 commits into from
Sep 28, 2022
Merged

add DCLOGIN uri scheme #48

Changes from 3 commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
c304e8f
add `DCLOGIN` uri scheme
Simon-Laux Jul 5, 2022
4c630be
document json and move the version to the end
Simon-Laux Jul 5, 2022
97b3416
uri based scheme instead of json
Simon-Laux Jul 10, 2022
b5309b7
dclogin-scheme: discourage usage of full names
Simon-Laux Jul 14, 2022
a095a0e
only use short names
Simon-Laux Jul 14, 2022
7f23e56
move password to `p` $GET-field
Simon-Laux Jul 19, 2022
77301ab
2 more syntax examples for `dclogin:`
Simon-Laux Aug 4, 2022
52a7a5e
apply link2xt's suggestions
Simon-Laux Aug 9, 2022
2600109
address flub's comment
Simon-Laux Sep 12, 2022
42e6f10
clarify that `dclogin://` is prefered
Simon-Laux Sep 12, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
84 changes: 84 additions & 0 deletions uri-schemes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -96,6 +96,8 @@ see the [mailadm](https://github.com/deltachat/mailadm) project for more details
DCACCOUNT:https://example.org/new_email?t=1w_7wDjgjelxeX884x96v3
```

You may want to use [`DCLOGIN`](#DCLOGIN) instead, if you want a qr code containing login information for a single account.

#### The http endpoint needs the following api:

##### On Success
Expand Down Expand Up @@ -124,6 +126,88 @@ HTTP Status code: NOT 2XX, idealy the 4XX if it's user error and 5XX if it's the

json object can have other properties too, but currently they are ignored by core.

## **DCLOGIN** <a name="DCLOGIN"></a>

| | |
| ------------------------ | --------------------- |
| Scheme | `DCLOGIN:` |
| Used for | Account setup |
| Related Terms\* | Account Login QR code |
| Available on | draft |
| Decoded by the core \*\* | draft |
| Other apps using it | none, only DeltaChat |

### Syntax

```
dclogin://user:password@host/?options
dclogin://user:password@host?options
dclogin:user:password@host/?options
# example: (email: me@example.com, password: securePassword)
dclogin://me:securePassword@example.com?v=1
Copy link
Member

@adbenitez adbenitez Jul 10, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

not sure if it is a thing but IIRC some servers use only the local part of the email address as the username to log in, how would that be specified here? or this is only for servers that the login is with the email address and that the server address ends with @host and host is the right imap/smtp host? I guess it will have then to do the DC autoconfig to detect right host and ports

personally would have preferred something like dclogin://addr:password?mail_server=...&send_server=...&(other dc config options here)

Copy link
Member

@adbenitez adbenitez Jul 10, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

and then calling it dcsetup: would makes more sense since you could setup several config options for the user, would be more useful for admins setting up servers for easy onboarding, example if creating the DC account is triggered from inside another service /account and then you could preconfigure the same username that the user has in that other service

# example: (email: myself@example.com, password: 123456, insecure smtp at different server)
dclogin://myself:123456@example.com?v=1&sh=mail.example.com&sc=3&ss=plain
```

#### Options `?options`

Format: URL Query parameters also known as GET variables (`varname=value` behind the question mark, chained/delimited by `&`)

The query parameters contain advanced options and a version parameter.
All advanced options are optional except for `v`, which is the only required option at this point.

| short name | full name | description | example |
| ---------- | ------------------------- | --------------------------------------------------- | --------------------- |
| `v` | `version` | defines the format version, more explanation below | `v=1` |
| ---------- | ------------------------- | --------------------------------------------------- | ---------------- |
| `ih` | `imap_host` | IMAP host | `ih=imap.example.com` |
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

mmh ok so actually the host can be specified in options, then splitting the email address in local part and host kinda feels unnecessary 🤔

Copy link
Member Author

@Simon-Laux Simon-Laux Jul 11, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

it's because url spec has username:password@host as format, so to be consistent with other schemes/standards

Copy link
Member

@r10s r10s Jul 11, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

following this "auth spec" seems not to be needed and does not really match anyway as we have to deal with potentially two different usernames and passwords. and if we follow: the part before the colon is the username, so that would be the full email address in many, but of course not all cases.

so, trying to reconstruct the email address and username from different parts is doable, but would results in quite some "if" and unneeded complexity.

it seems much easier to have a dedicated field for the email address: DCLOGIN:?a=foo%40bar.de&ipw= password just map everything 1:1 to the existing config fields. having that as a parameter also eliminates doubts how and if to urlencode, it is just all the same.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure we need to "simplify" everything that much,

maybe DCLOGIN:email@example.com?pw=1234&v=1, but I don't see the big benefit in specifying everything in the query part, though we could do it, minimum version (no advanced options) would then look like:

DCLOGIN:?a=email@example.com&p=1234&v=1

and when reusing the existing imap password field (though that might be more annoying to explain than an extra property):

DCLOGIN:?a=email@example.com&ipw=1234&v=1

BTW: the v=1 is there for future proofing, that we can increase this number to force specific advanced options like oauth2 or similar in the future, if it's a number not supported by dc it will tell the user to update the app.

Copy link
Contributor

@missytake missytake Sep 27, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We also can have separate passwords for IMAP & SMTP, right? So what about recommending DCLOGIN://user:password@example.com/?v=1 as default, not having a p= option at all, but instead smtp_password= and imap_password= options, which override the password in the "authority" field?

That would feel most intuitive for me, and kind of maps the login field with the advanced login settings.

edit: I just saw that there are smtp_password and imap_password parameters already 🙃 I like to have the password in the front, as it makes it clearer what overrides which imho.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not really willing to change everything at this stage again, r10s is right that it might be more complicated to do it in the userinfo part (because URI encoding and stuff like that, passwords tend to contain special characters)

| `ip` | `imap_port` | IMAP port | `ip=993` |
| `iu` | `imap_username` | IMAP username | |
| `ipw` | `imap_password` | IMAP password | |
| `is` | `imap_security` | IMAP security: "`ssl`" or "`default`" | `is=ssl` |
| `ic` | `imap_certificate_checks` | IMAP certificate checks, see below for options | `ic=1` |
| ---------- | ------------------------- | --------------------------------------------------- | ---------------- |
| `sh` | `smtp_host` | SMTP host | `sh=mail.example.com` |
| `sp` | `smtp_port` | SMTP port | `sp=465` |
| `su` | `smtp_username` | SMTP username | |
| `spw` | `smtp_password` | SMTP password | |
| `ss` | `smtp_security` | SMTP security: "`ssl`", "`starttls`" or "`plain`" | `ss=plain` |
| `sc` | `smtp_certificate_checks` | SMTP certificate checks, see below for options | `sc=3` |

#### `minVersion`
Simon-Laux marked this conversation as resolved.
Show resolved Hide resolved

Format version:
Used for breaking new versions that add new **required** properties, basically deltachat checks for this and if it's newer than the version deltachat supports it prompts the user to update the app.

The version number only increases on incompatible changes (changes to required properties).

#### `CertificateChecks`

| code | name & description |
| ---- | ---------------------------------------------------------------------------------------------------------------- |
| 0 | `Automatic`, same as `AcceptInvalidCertificates` unless overridden by `strict_tls` setting in provider database. |
| 1 | `Strict` |
| 3 | `AcceptInvalidCertificates` |

#### Important information for using the `DCLOGIN:` scheme

- There is a maximum length of how much data fits in side of a qr code (depending on the error correction level 1273 chars to 2953 chars)
- make sure to use the short names for advanced properties
Simon-Laux marked this conversation as resolved.
Show resolved Hide resolved
- If working with long domains/password/usernames in advanced options, **consider creating a configuration file at the server instead** using either [Autoconfigure](https://web.archive.org/web/20210402044801/https://developer.mozilla.org/en-US/docs/Mozilla/Thunderbird/Autoconfiguration) or [Autodiscover](<https://technet.microsoft.com/library/bb124251(v=exchg.150).aspx>)
Simon-Laux marked this conversation as resolved.
Show resolved Hide resolved
- **Every value** (username & password too) **needs to be URI encoded**:
- [`encodeURIComponent()` in JS](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent)
- note that email username and password are in different order, than email: `username:password@host` vs. `username@host`
Simon-Laux marked this conversation as resolved.
Show resolved Hide resolved

#### Implementation hints

implementations should be somewhat tolerant:

- both `dclogin:` and `dclogin://` should work
Simon-Laux marked this conversation as resolved.
Show resolved Hide resolved
- both short names and full names should be parsed for properties (though short names are preferred)
- have a test for usename+extention@host cases
Simon-Laux marked this conversation as resolved.
Show resolved Hide resolved
- if version is bigger than whats implemented tell the user to update
Simon-Laux marked this conversation as resolved.
Show resolved Hide resolved


## **DCWEBRTC**

| | |
Expand Down