xep-0493.xml

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
  <!ENTITY % ents SYSTEM 'xep.ent'>
<!ENTITY rfc6749 "
<span class='ref'><link url='http://tools.ietf.org/html/rfc6749'>RFC 6749</link></span>

<note>

RFC 6749: The OAuth 2.0 Authorization Framework &lt;<link url='http://tools.ietf.org/html/rfc6749'>http://tools.ietf.org/html/rfc6749</link>&gt;.

</note>
" >

<!ENTITY rfc7591 "
<span class='ref'><link url='http://tools.ietf.org/html/rfc7591'>RFC 7591</link></span>

<note>

RFC 7591: OAuth 2.0 Dynamic Client Registration Protocol &lt;<link url='http://tools.ietf.org/html/rfc7591'>http://tools.ietf.org/html/rfc7591</link>&gt;.

</note>
" >

<!ENTITY rfc7636 "
<span class='ref'><link url='http://tools.ietf.org/html/rfc7636'>RFC 7636</link></span>

<note>

RFC 7636: Proof Key for Code Exchange by OAuth Public Clients &lt;<link url='http://tools.ietf.org/html/rfc7636'>http://tools.ietf.org/html/rfc7636</link>&gt;.

</note>
" >

<!ENTITY rfc7628 "
<span class='ref'><link url='http://tools.ietf.org/html/rfc7628'>RFC 7628</link></span>

<note>

RFC 7628: A Set of Simple Authentication and Security Layer (SASL) Mechanisms for OAuth &lt;<link url='http://tools.ietf.org/html/rfc7628'>http://tools.ietf.org/html/rfc7628</link>&gt;.

</note>
" >

<!ENTITY rfc8414 "
<span class='ref'><link url='http://tools.ietf.org/html/rfc8414'>RFC 8414</link></span>

<note>

RFC 8414: OAuth 2.0 Authorization Server Metadata &lt;<link url='http://tools.ietf.org/html/rfc8414'>http://tools.ietf.org/html/rfc8414</link>&gt;.

</note>
" >

<!ENTITY ietfOAuthSecurity "
<span class='ref'><link url='https://datatracker.ietf.org/doc/html/draft-ietf-oauth-security-topics'>draft-ietf-oauth-security-topics</link></span>

<note>

OAuth 2.0 Security Best Current Practice &lt;<link url='https://datatracker.ietf.org/doc/html/draft-ietf-oauth-security-topics'>https://datatracker.ietf.org/doc/html/draft-ietf-oauth-security-topics</link>&gt;.

</note>
" >
%ents;
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep><header>
<title>OAuth Client Login</title>
<abstract>This specification details how a third-party can be securely granted access to an XMPP account without exposing the account credentials, using OAuth.</abstract>
&LEGALNOTICE;
<number>0493</number>
<status>Experimental</status>
<type>Informational</type>
<sig>Standards</sig>
<approver>Council</approver>
<dependencies/>
<supersedes/>
<supersededby/>
<shortname>tsa</shortname>
<author>
<firstname>Matthew</firstname>
<surname>Wild</surname>
<email>mwild1@gmail.com</email>
</author>
<revision>
    <version>0.1.0</version>
    <date>2024-09-17</date>
    <initials>XEP Editor: dg</initials>
    <remark>
      <ul>
        <li>Promoted to Experimental</li>
      </ul>
    </remark>
  </revision>
<revision>
<version>0.0.1</version>
<date>2024-08-20</date>
<initials>mjw</initials>
<remark>
</remark>
</revision>
</header>
<section1 topic="Introduction" anchor="introduction">

<p>This specification defines a way to allow an XMPP account owner to safely and securely log in to their account
through a client or other application without sharing their password or other primary credentials with that
application. This is particularly important if the application is hosted by a third party (e.g. as a web app),
as some XMPP applications are.</p>

<p>To achieve this, we define how OAuth can be implemented and used to grant this access.</p>

<section2 topic="Use of OAuth" anchor="use-of-oauth">

<p>OAuth is a widely used authentication and authorization framework. It allows a resource owner (such as an XMPP user)
to safely and securely grant address to a resource (such as their XMPP account) to software and services that they choose.
In the past, granting access to an account was only possible by sharing the account password with the software or service
that wants to access it. Once shared, such access is unlimited and impossible to selectively revoke.</p>

<p>However, OAuth is also a very broad framework with many features and capabilities, spread across multiple specifications.
This can make it difficult for developers to know which parts are necessary for different usage scenarios, and this leads
to non-interoperable implementations, or avoiding implementation at all.</p>

</section2><section2 topic="Defining the scope of this document" anchor="defining-the-scope-of-this-document">

<p>This specification focuses on one primary use case - securely granting third-party access to an account. It does not
introduce any new protocols, but describes how existing protocols can be combined together to enable this use case.</p>

<p>There is an existing published XEP related to use of OAuth in XMPP, &xep0235;. However this describes a different use
case - specifically, how an arbitrary XMPP entity can use OAuth to manage access to its own services by other XMPP entities.
Furthermore, that specification is based on the outdated OAuth 1.0, while this specification builds upon OAuth 2.0+ only.</p>

<p>Other use cases that are <strong>not</strong> described by this document, but may also be achieved using OAuth include:</p>

<ul>
<li>Allowing users to identify themselves to a third-party service by proving ownership of an XMPP account (e.g. this would allow a web service to display
a "Log in with XMPP" button).
Such a feature could be implemented by adding support for OpenID Connect protocols in addition to the simpler protocols described here.
Alternatively, &xep0070; defines a pre-OAuth method of achieving similar functionality.</li>
<li>Allowing users to identify themselves to their XMPP server using a third-party service (e.g. this would allow an XMPP client to display
a "Log in with TrendyService" button). This can be achieved through use of OpenID Connect, which has significant overlap with the parts
of OAuth used in this specification, but ultimately requires different protocol flows.</li>
</ul>

<p>By limiting the scope of this document to secure account access delegation, we aim to make it easier for developers to safely
and securely implement this important feature, without the distractions of the complex and sprawling wider OAuth ecosystem.</p>

<p>However, this XEP’s protocols do unlock additional use cases. For example, the flows described here would enable server admins to deploy and
utilize OAuth-compatible identity providers to manage access to XMPP user accounts, which in turn can be used for features such as Single Sign-On.</p>

</section2></section1><section1 topic="Requirements" anchor="requirements">

<ul>
<li>It should be possible for an XMPP account owner to provide an application or service access to their account without sharing their password (or any similar unconstrained credentials).</li>
</ul>

<p>Although the protocol details will not be covered in this particular document, following this specification must enable the following
important features to be implemented by the service:</p>

<ul>
<li>It should be possible to control the level of the access granted (e.g. providing read-only access, or allowing access to only certain aspects of the account).</li>
<li>It should be possible to revoke the granted access at any time.</li>
</ul>

<section2 topic="Use cases" anchor="use-cases">

<p>Imagine that a developer has made an XMPP web application that allows people to create and browse XMPP social content (such as &xep0277;) on the XMPP network. To work, it needs to connect to a user’s XMPP account. However the developer does not want the liability of requesting (and potentially storing) user passwords to allow the application to log in to user accounts. Additionally, users do not want to type their passwords into a third-party service.</p>

<p>Using OAuth, the user is able to enter only their JID in the application, and then through OAuth negotiation the application will be able to obtain unique credentials that can be used to connect to the user’s XMPP account.</p>

</section2><section2 topic="Client login flow" anchor="client-login-flow">

<p>The initial login process can be broken down into a series of steps, which are each given a section here, in the order they will typically occur.</p>

<p>The following entities play a part in these sections:</p>

<ul>
<li>The "user" - this is the, typically human, individual that wants to use the application with their XMPP account.</li>
<li>The "application" (or in the context of XMPP, also referred to as the "client") - this is the application or service that wants to access the user’s account on behalf of the user.</li>
<li>The "server" - this is the user’s XMPP service, identified by the domain part of their JID.</li>
<li>The "OAuth provider" - this is the service with which the application performs OAuth. It may be part of the user’s XMPP server, but may also be located elsewhere. The OAuth provider is responsible for issuing credentials that can be used to access the user’s account.</li>
</ul>

</section2><section2 topic="Obtaining authorization" anchor="obtaining-authorization">

<p>To begin the process, the application must first obtain the user’s JID. For example, it
may present a login form with a field for the JID (but no field for the password).</p>

<section3 topic="Discovering OAuth support" anchor="discovering-oauth-support">

<p>The application takes the hostname from the JID, and initiates a client connection
to the user’s account on that server. Per &xmppcore;, the client SHOULD include the user’s
JID in the 'from' attribute on opening stream headers, but MUST only do so after the
connection is secured with TLS.</p>

<p>The server will present a list of SASL mechanisms, either using the core SASL profile defined
in &xmppcore;, or using &xep0388;.</p>

<p>If the server does not offer the OAUTHBEARER mechanism in this list, then it does not support the
flow defined in this XEP. The application SHOULD indicate to the user that their server does not
support secure third-party application access and abort the login process. However, the application
MAY offer password login as a fallback, if such fallback has been enabled by the administrator of the application deployment.</p>

<p>During initial authentication, the client does not have any credentials, so it SHOULD proceed
with the OAUTHBEARER mechanism, but provide an empty access token. Per the rules in &rfc7628;,
the server will respond with a JSON object that includes the discovery URL for the requested user.</p>

<p>The application makes a request to the discovery URL to fetch metadata about the OAuth provider,
which is needed to complete the authorization process. The response from the discovery URL SHOULD be parsed according to &rfc8414;.</p>

</section3><section3 topic="Registering with the OAuth provider" anchor="registering-with-the-oauth-provider">

<p>If the application has not previously interacted with this OAuth provider (identified by the "issuer" URL in the metadata), then it must first register itself. This registration is necessary to protect against certain attacks on the OAuth process, and it also provides an opportunity for the application to provide details such as a name and logo that will be presented to the user. Details of this registration process are specified in &rfc7591;.</p>

</section3><section3 topic="Authorization request" anchor="authorization-request">

<p>Authorization begins by preparing an authorization request. In the case of server-side "hosted" applications, this request is not made directly by the application. Rather, the application must craft the URL (known as the "Authorization Endpoint") for the request and then redirect the user to that URL.</p>

<p>The base of the Authorization Endpoint is obtained from the earlier discovery process. The client then adds parameters specific to the current authorization request. XMPP implementations SHOULD implement at least the Authorization Code grant type (&rfc6749; section 4.1), and details of the expected parameters for this grant type can be found in &rfc6749; section 4.1.1. In addition, servers and clients MUST support the PKCE extension to this flow, which is defined in &rfc7636;.</p>

<p>The application SHOULD request specific scopes, according to the access that it requires. These scopes MUST be limited to the minimum level of access required for the application to function. OAuth itself does not define any standard scopes, however some standard scopes are included in this specification that are expected to be offered, in addition to any custom scopes that a specific service or implementation may offer.</p>

<p>At this point, the OAuth provider will display to the user whatever steps are necessary to grant the authorization, such as requiring the user to authenticate themselves.</p>

</section3><section3 topic="Successful authorization" anchor="successful-authorization">

<p>If the user successfully approves the application’s access, the OAuth provider will redirect them back to the application (specifically, the application’s "Redirection URI" which it provided to the server previously in the Authorization Request or Client Registration).</p>

<p>In the case of the Authorization Code grant type, the application will be able to exchange the authorization code received in the URL for the final credentials - an access token that can be used with the SASL OAUTHBEARER mechanism. This exchange is described in &rfc6749; sections 4.1.3 and 4.1.4.</p>

</section3></section2></section1><section1 topic="OAuth Scopes" anchor="oauth-scopes">

<p>OAuth allows each authorization grant to have different permissions, it calls these "scopes". However, because
OAuth is a generic framework, it does not specify any scopes itself. This can become an interoperability issue,
if applications don’t understand what scopes they need to request for the functionality they implement.</p>

<p>For this reason, we define some basic scopes in this specification, without excluding the possibility that
additional scopes will be defined in the future.</p>

<p>Scope names SHOULD be registered with the XSF before being used, however this
is not a requirement. Custom scopes that are not intended for standardization
SHOULD avoid the 'xmpp:' prefix to prevent conflicts. Note that scope names
are arbitrary opaque strings as far as OAuth is concerned, and are not defined
to be URIs, or any specific format.</p>

<p>This specification defines the following scopes:</p>

<ul>
<li><tt>xmpp:client:normal</tt> - The application gains access to most features of the account, but may be restricted from certain sensitive operations, such as changing the account password or managing connected devices. This ensures that such a client cannot escalate its privileges or take over an account. This scope MUST be supported by the server.</li>
</ul>

<section2 topic="Special scopes" anchor="special-scopes">

<p>For certain specialized non-IM applications, it may be preferable to request limited access to a user’s account. For example, an
application which allows a user to view or export or backup their data.</p>

<p>These scopes do not permit communication access to the XMPP network. They SHOULD be supported by servers.</p>

<section3 topic="Account-only access" anchor="account-only-access">

<p>These scopes control access to account data (including user profile information, public and private PEP nodes, and roster). In general they allow
communication with the account’s server to facilitate this access, but not with other XMPP entities. Notably they do not grant access to a user’s
current or past communications (e.g. &xep0280; or &xep0313;).</p>

<ul>
<li><tt>xmpp:account:read</tt> - Read-only access to the account and associated data.</li>
<li><tt>xmpp:account:write</tt> - Write access to the account and associated data.</li>
</ul>

</section3></section2></section1><section1 topic="Implementation notes" anchor="implementation-notes">

<section2 topic="OAuth versions" anchor="oauth-versions">

<p>At the time of writing, OAuth 2.0 is published as RFCs and widely supported by
implementations and libraries generally. OAuth 2.1 is under development, and
while broadly compatible it has many improvements that improve robustness,
increase interoperability and reduce the potential for security issues.</p>

<p>The subset of OAuth required by this specification is not likely to change
substantially, and it is probable that a future version of this XEP may advise
support for OAuth 2.1 when it is finalized. Implementers are encouraged to
cross-reference the OAuth 2.1 drafts, as they can be simpler than the original
OAuth 2.0 specifications while the protocol remains largely identical.</p>

<p>In particular, OAuth 2.1 requires the PKCE extension to the Authorization Grant
flow, which this XEP already requires. Many of the other OAuth 2.0 grant types
are removed from OAuth 2.1, and this XEP does not recommend that
implementations support these grant types.</p>

<p>Finally, OAuth 2.1 formally forbids the practice of allowing wildcards in the
client’s redirect_uri fields. Allowing fuzzy matching can lead to unintented
security issues, and a simple string comparison should be used instead, aside
from special handling of certain localhost URLs (see the OAuth 2.1
specification for details).</p>

<p>Following the few paragraphs above will lead to implementations which are
simpler, safer and forwards-compatible with OAuth 2.1.</p>

</section2><section2 topic="Servers" anchor="servers">

<p>At a minimum, servers are required to implement the OAUTHBEARER SASL mechanism defined in &rfc6749;. To ensure
clients can adequately discover support and the information they need to successfully obtain authorization,
servers MUST provide a URL to a valid OAuth Discovery document (&rfc8414;) in the openid-configuration field
described in that RFC.</p>

<p>The discovery document, as well as the rest of the OAuth exchange, may be implemented and served by the XMPP
server itself, or by an external OAuth-compatible identity provider that the server admin configures. This
choice is left to individual implementations and deployments.</p>

</section2></section1><section1 topic="Security considerations" anchor="security-considerations">

<section2 topic="OAuth security" anchor="oauth-security">

<p>This specification builds upon the existing OAuth standards, this allows reuse
of existing implementation experience and security practices.</p>

<p>Nevertheless, while OAuth has the potential to greatly improve security (compared to a world where users freely hand out their passwords
to third-party services), there has been a long history of security issues related to OAuth implementations. Some general advice for
developers:</p>

<ul>
<li>Read &ietfOAuthSecurity; for an excellent review of known security pitfalls that can be encountered while implementing OAuth applications and services.</li>
<li>Reuse existing libraries and APIs where possible, and read their documentation carefully.</li>
<li>Do not implement or support OAuth 1.x, or any of the deprecated grant types.</li>
<li>Read the security considerations in the RFCs this specification builds upon.</li>
</ul>

<p>Server implementations MUST NOT support this specification without giving account owners a method to manage and revoke access. While
this could be a proprietary interface, implementations SHOULD provide support for this using standard XMPP protocols, such as &xep0494;.</p>

<p>Be sure to review the 'OAuth versions' section of the Implementation Notes
above and implement the requirements listed there for improved security and
for compatibility with OAuth 2.1 when it arrives.</p>

</section2><section2 topic="Authentication vs Authorization" anchor="authentication-vs-authorization">

<p>Note well that this specification is about an XMPP account owner granting
(i.e. authorizing) an application access to their account. It is not about
the account owner asserting any particular identity to the application, nor is
is it designed to assert the identity of the application towards the XMPP
service.</p>

<p>One simple example of how this confusion could manifest, is if a user
initially provides one JID (which they may not own) to an application, but
authenticates to the server using a different JID during the OAuth process,
potentially confusing the application about the user’s identity.</p>

<p>OAuth is an authorization (permission) protocol, not an authentication
(identity) protocol. Applications can safely use the credentials returned from
OAuth negotiation to connect and authenticate to the XMPP service as the
authenticated user, but should be careful not to make the assumption that this
somehow authenticates the user to the application itself. Such authentication
is not the intention of OAuth.</p>

<p>In the case of an XMPP client that establishes a session, note that the full
JID of the authenticated session is returned by the server during resource
binding, which allows the application to know which JID was ultimately
authenticated.</p>

<p>Alternatively, the OpenID Connect protocols build upon OAuth to allow an
application to securely learn the identity of an authenticated user. However,
as described in the Requirements section earlier, these use cases are beyond
the scope of this specification.</p>

<p>In all cases, a shared application that maintains local state (i.e. outside of
the user’s XMPP server) MUST be extremely careful to avoid leaking such data
between user accounts, although such care must be taken with or without OAuth.</p>

</section2></section1><section1 topic="Accessibility Considerations" anchor="accessibility-considerations">

<p>This specification potentially adds new human interaction points, such as
during the authentication and authorization process. These steps will be
provided by the XMPP server or an identity provider configured by the server
administrator. These interfaces should be implemented and chosen according to
accessibility best practices. Deployments should consider the accessibility
impact of features such as CAPTCHAs which may be presented during an
authentication flow, and ensure there are accessible variants if they must be
used.</p>

</section1><section1 topic="Privacy Considerations" anchor="privacy-considerations">

<p>As noted in the Security Considerations, implementations MUST support viewing
and revoking authorizations after they have been granted.</p>

</section1><section1 topic="IANA Considerations" anchor="iana-considerations">

<p>None.</p>

</section1><section1 topic="XMPP Registrar Considerations" anchor="xmpp-registrar-considerations">

<section2 topic="Scope name registry" anchor="scope-name-registry">

<p>This specification introduces a registry of scope names. The format of an
entry should be in the following format:</p>

<example ><![CDATA[<scope>
  <name>Name of the OAuth scope to be used in the protocol, typically begins with 'xmpp:' prefix</name>
  <doc>Associated specification</doc>
  <desc>Natural-language description of the scope and its purpose</desc>
</scope>]]></example>

<section3 topic="Initial contents" anchor="initial-contents">

<p>Upon advancement of this XEP, the registrar will create the registry with the
following initial contents:</p>

<example ><![CDATA[<scope>
  <name>xmpp:client:normal</name>
  <doc>XEP-xxxx</doc>
  <desc>Permit general access to an XMPP account, excluding security-relevant features</desc>
</scope>

<scope>
  <name>xmpp:account:read</name>
  <doc>XEP-xxxx</doc>
  <desc>Permit access to read account data</desc>
</scope>

<scope>
  <name>xmpp:account:write</name>
  <doc>XEP-xxxx</doc>
  <desc>Permit access to modify account data</desc>
</scope>]]></example>

</section3></section2></section1><section1 topic="Acknowledgements" anchor="acknowledgements">

<p>Thanks to Jonas Schäfer for assisting in the review of this document, and to
Kim Alvefur for the (almost) tireless assistance with developing the prototype
implemention and making sense of the of various OAuth specifications with me.
Thanks to NLnet for providing the funding that made it possible for me to do
this work on XMPP authentication improvements.</p>
</section1>
</xep>