mAuth - OAuth2 profile for mail apps and other public clients
draft-bucksch-mauth-00
This document is an Internet-Draft (I-D).
Anyone may submit an I-D to the IETF.
This I-D is not endorsed by the IETF and has no formal standing in the
IETF standards process.
| Document | Type | Active Internet-Draft (individual) | |
|---|---|---|---|
| Author | Ben Bucksch | ||
| Last updated | 2024-07-23 | ||
| RFC stream | (None) | ||
| Intended RFC status | (None) | ||
| Formats | |||
| Stream | Stream state | (No stream defined) | |
| Consensus boilerplate | Unknown | ||
| RFC Editor Note | (None) | ||
| IESG | IESG state | I-D Exists | |
| Telechat date | (None) | ||
| Responsible AD | (None) | ||
| Send notices to | (None) |
draft-bucksch-mauth-00
Network Working Group B. Bucksch
Internet-Draft Beonex
Intended status: Informational 23 July 2024
Expires: 24 January 2025
mAuth - OAuth2 profile for mail apps and other public clients
draft-bucksch-mauth-00
Abstract
This document creates a specific OAuth2 profile that is suitable for
mail, chat, calendar and similar clients.
It defines specific parameters of OAuth2, to allow email clients to
reliably authenticate using OAuth2 on any mail provider.
About This Document
This note is to be removed before publishing as an RFC.
The latest revision of this draft can be found at
https://benbucksch.github.io/mauth-spec/draft-mauth.html. Status
information for this document may be found at
https://datatracker.ietf.org/doc/draft-bucksch-mauth/.
Source for this draft and an issue tracker can be found at
https://github.com/benbucksch/mauth-spec.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on 24 January 2025.
Bucksch Expires 24 January 2025 [Page 1]
Internet-Draft mAuth July 2024
Copyright Notice
Copyright (c) 2024 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents (https://trustee.ietf.org/
license-info) in effect on the date of publication of this document.
Please review these documents carefully, as they describe your rights
and restrictions with respect to this document. Code Components
extracted from this document must include Revised BSD License text as
described in Section 4.e of the Trust Legal Provisions and are
provided without warranty as described in the Revised BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
3. Client ID . . . . . . . . . . . . . . . . . . . . . . . . . . 4
3.1. Rationale . . . . . . . . . . . . . . . . . . . . . . . . 4
3.2. Definition Client ID . . . . . . . . . . . . . . . . . . 4
4. Client software name and version . . . . . . . . . . . . . . 4
5. Username in authentication request . . . . . . . . . . . . . 5
6. Error codes . . . . . . . . . . . . . . . . . . . . . . . . . 6
7. Refresh token . . . . . . . . . . . . . . . . . . . . . . . . 6
7.1. Revokation . . . . . . . . . . . . . . . . . . . . . . . 7
7.2. Rationale . . . . . . . . . . . . . . . . . . . . . . . . 7
8. Conventions and Definitions . . . . . . . . . . . . . . . . . 7
9. Security Considerations . . . . . . . . . . . . . . . . . . . 7
9.1. Data protection and privacy . . . . . . . . . . . . . . . 7
9.2. Abuse . . . . . . . . . . . . . . . . . . . . . . . . . . 7
10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8
11. Normative References . . . . . . . . . . . . . . . . . . . . 8
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 8
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 8
1. Introduction
Mail clients today use mostly username and password to log in to
IMAP. OAuth2 can only be used at the biggest providers, but causes
major problems for mail clients in its current application.
This document creates a specific OAuth2 profile that is suitable for
mail, chat, calendar and similar clients.
It defines specific parameters of OAuth2, with the purpose of making
OAuth2 as reliable for client and for end users as password login is
today.
Bucksch Expires 24 January 2025 [Page 2]
Internet-Draft mAuth July 2024
It also avoids provider-specific configuration and adjustments. This
in turn would allow email clients to authenticate using OAuth2 on any
mail provider, without having to specifically register with or test
each and every mail provider in the world.
2. Scope
To avoid that the client needs to know the provider-specific version
of scope names, the server MUST accept the following literal scope
names (RFC 6749 3.3), for the following purposes:
+==========================+=================================+
| Scope | Resource protocol or standard |
+==========================+=================================+
| IMAP | RFC 9051 |
+--------------------------+---------------------------------+
| SMTP | RFC 5321 |
+--------------------------+---------------------------------+
| POP3 | RFC 1939 |
+--------------------------+---------------------------------+
| CalDAV | RFC 4791 |
+--------------------------+---------------------------------+
| CardDAV | RFC 6352 |
+--------------------------+---------------------------------+
| WebDAV | RFC 4918 |
+--------------------------+---------------------------------+
| XMPP | RFC 6120 |
+--------------------------+---------------------------------+
| matrix.org/Matrix | Matrix chat client/server API |
+--------------------------+---------------------------------+
| microsoft.com/EWS | Microsoft Exchange Web Services |
+--------------------------+---------------------------------+
| microsoft.com/ActiveSync | Microsoft ActiveSync |
+--------------------------+---------------------------------+
Table 1
For all RFC references, previous versions and updates of these
standards are also included.
If a client requests one or multiple of these scopes, the token
issued by the server MUST be valid for this user on the resource
servers of the provider which implement the corresponding protocols.
Bucksch Expires 24 January 2025 [Page 3]
Internet-Draft mAuth July 2024
If the provider does not have an resource server which implements
this protocol, the server MUST ignore the unsupported scope and issue
the token for the supported scopes. The authorization server
response MUST include only the supported scopes. It MAY reject the
token request with error invalid_scope, if _all_ requested scopes are
unsupported. (See RFC 6749 3.3 Paragraph 3)
3. Client ID
3.1. Rationale
OAuth2 was created with server-to-server relations in mind, where a
contractual relationship between both parties exist. RFC 6749
states: 'Client ID ... may require a contractual relationship...'
(TODO find quote)
This concept is not compatible with the concept of mail clients. A
mail client cannot realistically register with all mail providers in
the world.
Last but not least, the client ID currently allows a mail provider to
force a contract on a mail client. This is directly contrary to a
free Internet and IETF values.
Furthermore, given that mail providers typically also offer mail
clients and mail clients are therefore almost always competitors to
the mail provider, a mail provider blocking clients or allowing the
clients only under conditions, is inherently anti-competitive.
3.2. Definition Client ID
The server MUST accept the following Client ID (RFC 6749 2.2): open
The client SHALL use this Client ID.
The server MUST NOT require other authentication or authorization for
the client software.
4. Client software name and version
The client MUST use the following mechanisms to identify itself, as
appropriate for the protocol used:
Bucksch Expires 24 January 2025 [Page 4]
Internet-Draft mAuth July 2024
+==========+========================+================+
| Protocol | Identification method | Standard |
+==========+========================+================+
| OAuth2 | User-Agent HTTP header | RFC 2616 14.43 |
+----------+------------------------+----------------+
| HTTPS | User-Agent HTTP header | RFC 2616 14.43 |
+----------+------------------------+----------------+
| IMAP | ID command | RFC 2971 |
+----------+------------------------+----------------+
Table 2
All all cases, the client MUST use as primary name component a string
reflecting the commonly known name of the end user application, and
at least the major version. The client MAY include as secondary name
component the software library that implements the protocol.
In the case of HTTP user agent strings, the order is reversed, so a
typical user agent string should be, for mail app "ACME Mail" using
"Best Effort IMAP" library:
User-Agent: Best-Effort-IMAP/2.3 ACME-Mail/4.5
The OAuth2 authorization server MUST NOT reject or disadvantage
clients that send non-browser User-Agent strings. The client SHALL
NOT send generic browser user agent strings, unless the authorization
server is known to disadvantage a client without such user agent
string.
5. Username in authentication request
In most cases, the client would like to authenticate to a specific
account or email address which is known before the authentication is
started. However, RFC 6749 does not specify how the client informs
the authorization server which username is intended to log in.
Various proprietary provider-specific mechanisms exist, e.g.
login_hint at Office365, but there is no interoperable standard.
In the Authorization Request, an additional URL query parameter
username MAY be passed by the client, with the email address or
account ID of the account that the client expects to log in. If
given, the server MUST skip the interactive username input, SHALL
show the username on the login page, and SHALL NOT allow the user to
log in with another account.
Bucksch Expires 24 January 2025 [Page 5]
Internet-Draft mAuth July 2024
6. Error codes
In the Authorization Response Error Response (RFC 6749 4.1.2.1.), the
following more specific error codes MUST be used, if their case
applies:
+===============+================================================+
| error code | Problem |
+===============+================================================+
| auth_failed | The user made a login attempt, but the |
| | password or username or second factor was |
| | wrong. |
+---------------+------------------------------------------------+
| blocked | The login credentials were valid, but the user |
| | account was blocked. The error_description |
| | MUST give a detailed cause for the block, and |
| | SHALL explain a way for the user to remedy the |
| | problem and unblock the account. |
+---------------+------------------------------------------------+
| unknown_user | The user doesn't exist, as far as this server |
| | is aware. |
+---------------+------------------------------------------------+
| user_not_here | The user account is known to exist, but must |
| | use another OAuth2 server. |
+---------------+------------------------------------------------+
| no_oauth | The user account exists, but is not allowed to |
| | use OAuth2. |
+---------------+------------------------------------------------+
Table 3
7. Refresh token
The authorization server access token response MUST contain a working
refresh token together with the access token (RFC 6749 5.1. and 6.).
When the client requests a new access token using a valid refresh
token, the authorization server MUST return a new refresh token with
a renewed expiry time.
The expiry time of the refresh token MUST be long enough for typical
uses of an email client that checks email in the background, i.e. at
least 24 hours, but preferably 1 year.
The expires_in field MUST be returned in the response (in RFC 6749
5.1., it is RECOMMENDED).
Bucksch Expires 24 January 2025 [Page 6]
Internet-Draft mAuth July 2024
7.1. Revokation
The tokens MAY be revoked or invalidated by the authorization server
at any time, if there is a concrete reason to believe that this
specific account has been compromised.
7.2. Rationale
This avoids that users get logged out of their email silenty and do
not get new mail notifications anymore.
It also avoids that users have to re-log in constantly, which is
known to be detrimental to security, due to passwords being written
down or re-using the same password on multiple services to remember
them.
8. Conventions and Definitions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in
BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here.
9. Security Considerations
9.1. Data protection and privacy
The client MUST act directly on behalf of the user who is
authenticating using OAuth2.
The client MUST keep the data obtained via the obtained access token
from the protected resources on the user's computers and MUST not
route the data through servers not under control of the resource
server owner (including avoiding servers of the application vendor),
unless specifically and explicitly requested by the user. (TODO
rephrase with better English)
9.2. Abuse
The server MAY reject access, if the specific connection or IP
address acted on many different users' behalf or has issued an
excessive amount of requests that don't reflect an interactive client
usage.
Bucksch Expires 24 January 2025 [Page 7]
Internet-Draft mAuth July 2024
10. IANA Considerations
This document has no IANA actions.
11. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/rfc/rfc2119>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/rfc/rfc8174>.
Acknowledgments
Author's Address
Ben Bucksch
Beonex
Email: ben.bucksch@beonex.com
Bucksch Expires 24 January 2025 [Page 8]