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.
To achieve this, we define how OAuth can be implemented and used to grant this access.
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.
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.
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.
There is an existing published XEP related to use of OAuth in XMPP, OAuth Over XMPP (XEP-0235)
Other use cases that are not described by this document, but may also be achieved using OAuth include:
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.
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.
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:
Imagine that a developer has made an XMPP web application that allows people to create and browse XMPP social content (such as Microblogging Over XMPP (XEP-0277)
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.
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.
The following entities play a part in these sections:
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).
The application takes the hostname from the JID, and initiates a client connection
to the user’s account on that server. Per XMPP Core
The server will present a list of SASL mechanisms, either using the core SASL profile defined
in XMPP Core
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.
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
RFC 7628
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
RFC 8414
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
RFC 7591
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.
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 (
RFC 6749
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.
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.
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).
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
RFC 6749
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.
For this reason, we define some basic scopes in this specification, without excluding the possibility that additional scopes will be defined in the future.
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.
This specification defines the following scopes:
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.
These scopes do not permit communication access to the XMPP network. They SHOULD be supported by servers.
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. Message Carbons (XEP-0280)
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.
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.
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.
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).
Following the few paragraphs above will lead to implementations which are simpler, safer and forwards-compatible with OAuth 2.1.
At a minimum, servers are required to implement the OAUTHBEARER SASL mechanism defined in
RFC 6749
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.
This specification builds upon the existing OAuth standards, this allows reuse of existing implementation experience and security practices.
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:
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 XEP-xxxx: Client Management.
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.
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.
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.
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.
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.
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.
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.
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.
As noted in the Security Considerations, implementations MUST support viewing and revoking authorizations after they have been granted.
None.
This specification introduces a registry of scope names. The format of an entry should be in the following format:
Upon advancement of this XEP, the registrar will create the registry with the following initial contents:
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.