This document defines a protocol that enables verification of an HTTP request via XMPP.
NOTICE: This JEP is currently within Last Call or under consideration by the Jabber Council for advancement to the next stage in the JSF standards process. For further details, visit <http://www.jabber.org/council/queue.shtml>.
Status: Proposed
Type: Standards Track
Number: 0070
Version: 0.8
Last Updated: 2005-10-19
JIG: Standards JIG
Approving Body: Jabber Council
Dependencies: XMPP Core, RFC 2616, RFC 2617, JEP-0030
Supersedes: None
Superseded By: None
Short Name: http-auth
Wiki Page: <http://wiki.jabber.org/index.php/Authenticating HTTP Requests via XMPP (JEP-0070)>
Email: linuxwolf@outer-planes.net
JID: linuxwolf@outer-planes.net
Email: jhildebrand@jabber.com
JID: hildjj@jabber.org
Email: dizzyd@jabber.org
JID: dizzyd@jabber.org
Email: stpeter@jabber.org
JID: stpeter@jabber.org
This Jabber Enhancement Proposal is copyright 1999 - 2005 by the Jabber Software Foundation (JSF) and is in full conformance with the JSF's Intellectual Property Rights Policy <http://www.jabber.org/jsf/ipr-policy.shtml>. This material may be distributed only subject to the terms and conditions set forth in the Creative Commons Attribution License (<http://creativecommons.org/licenses/by/2.5/>).
The preferred venue for discussion of this document is the Standards-JIG discussion list: <http://mail.jabber.org/mailman/listinfo/standards-jig>.
Given that this JEP normatively references IETF technologies, discussion on the JSF-IETF list may also be appropriate (see <http://mail.jabber.org/mailman/listinfo/jsf-ietf> for details).
The Extensible Messaging and Presence Protocol (XMPP) is defined in the XMPP Core (RFC 3920) and XMPP IM (RFC 3921) specifications contributed by the Jabber Software Foundation to the Internet Standards Process, which is managed by the Internet Engineering Task Force in accordance with RFC 2026. Any protocol defined in this JEP has been developed outside the Internet Standards Process and is to be understood as an extension to XMPP rather than as an evolution, development, or modification of XMPP itself.
The keywords "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 RFC 2119.
HTTP (see RFC 2616 [1]) is a nearly-ubiquitous mechanism for the publication of information. Sometimes it is appropriate for an HTTP Server to allow access to that information only if the HTTP Client first provides authentication credentials. While there exist several standardized HTTP authentication schemes (see RFC 2617 [2]), it may be useful in some applications to authenticate an HTTP request by requiring an XMPP entity (normally an IM user) to affirm that it made the request -- for example, to take advantage of the strong user authentication provided in XMPP (see RFC 3920 [3]).
Additionally, web-based, XMPP-aware applications may wish to utilize known information about a JID when making HTTP requests, without prompting the user for yet another username/password combination (the first being provided through their XMPP Client), thus resulting in automated login or "single-sign-on" functionality.
Therefore, this document specifies the processes and structure for an authentication scheme that enables authentication of HTTP requests via XMPP.
This document inherits terminology about the HyperText Transfer Protocol from RFC 2616 and RFC 2617.
Table 1: Terms for Entities Described Herein
| Term | Definition |
|---|---|
| HTTP Client | A client that implements the HyperText Transfer Protocol (HTTP) |
| HTTP Server | A server that implements the HyperText Transfer Protocol (HTTP) |
| XMPP Client | A client that implements the Extensible Messaging and Presence Protocol (XMPP) or its antecedents |
| XMPP Server | A server that implements the Extensible Messaging and Presence Protocol (XMPP) or its antecedents |
Note well that a XMPP Client can simultaneously be an HTTP Client (or vice-versa), and that a XMPP Server can simultaneously be an HTTP Server (or vice-versa). However, for the purposes of this discussion, we assume that these entities are logically if not physically separate and distinct.
The motivations for this document are:
The process flow for this protocol is as follows:
Error cases:
This process flow is described in more detail in the following sections.
Let us stipulate that a user (say, <juliet@capulet.com>) learns of a URL (e.g., <http://files.shakespeare.lit:9345/missive.html>). The user then attempts to retrieve the URL using her HTTP Client, which opens a TCP connection to the appropriate port of the host and sends an HTTP request as defined in RFC 2616. The request method MAY be any valid HTTP request method, including user-defined methods. In addition, the initial request MAY contain authorization credentials (as described below) in order to avoid a round trip. An example is provided below:
Example 1. HTTP Client Makes Request (No Credentials)
GET missive.html HTTP/1.1
If the user did not provide authorization credentials in the initial request, the HTTP Server then responds with a (401) Authenticate response as defined in RFC 2616. The response MUST contain an HTTP 401 error and one WWW-Authenticate header for each authentication scheme recognized by the HTTP Server (these headers SHOULD include a header for the "x-xmpp-auth" scheme). Authentication schemes that do not include usernames SHOULD NOT be offered by the HTTP Server if the "x-xmpp-auth" scheme is offered. The Authenticate response SHOULD also include a realm of "xmpp" (case-sensitive).
Example 2. HTTP Server Allows Access to Object
401 Unauthorized HTTP/1.1
WWW-Authenticate: Basic realm="xmpp"
WWW-Authenticate: Digest realm="xmpp", domain="shakespeare.lit", stale=false, \
nonce="ec2cc00f21f71acd35ab9be057970609", qop="auth", algorithm="MD5"
WWW-Authenticate: x-xmpp-auth realm="xmpp"
The HTTP Client responds with an Authorization Request as defined in RFC 2616. The request MUST include the Jabber Identifier (JID) of the user making the request, preferably a full JID (<user@host/resource>), although a bare JID (<user@host>) may also be provided. The Authentication Request process is described in the following subsections.
The Basic Access Authentication scheme is defined in RFC 2617. This scheme specifies that the authorization information shall consist of a userid and password, separated by a ':' character and then encoded using Base64. The profile defined herein further specifies that the userid MUST be a valid JID as described above, that the password entity SHOULD be a unique identifier for the transation (generated by the HTTP Client or end user), that Base64 encoding MUST adhere to Section 3 of RFC 3548 [4], and that any character that is outside the range of the US-ASCII coded character set MUST be transformed into a percent-encoded octet as specified in Section 2.1 of RFC 3986 [5].
(Refer to RFC 2617 regarding the syntax of the Basic Access Authentication scheme; that information is not duplicated here.)
The Digest Access Authentication scheme is defined in RFC 2617. This scheme specifies that the authorization information shall consist of the MD5 checksum of the username, the password, a nonce value provided in the challenge, the HTTP method, and the requested URI. The profile defined herein further specifies that prior to creating the MD5 checksum the username MUST be a valid JID as described above, that the password SHOULD be a unique identifier for the transation (generated by the HTTP Client or end user), and that any character that is outside the range of the US-ASCII coded character set MUST be transformed into a percent-encoded octet as specified in Section 2.1 of RFC 3986.
(Refer to RFC 2617 regarding the syntax of the Digest Access Authentication scheme; that information is not duplicated here.)
This section defines the "x-xmpp-auth" HTTP authentication scheme. This scheme is included mainly to provide a "trap door" for web-based XMPP clients (e.g., XMPP clients that communicate via the HTTP Binding [6] rather than the TCP binding specified in RFC 3920), so that they can intercept a page load, see that the "x-xmpp-auth" authentication scheme is offered, and pass the user's JID directly back to the connection manager or proxy.
The "x-xmpp-auth" scheme challenge provides the realm (as required by RFC 2617), which MUST be "xmpp" (case-sensitive).
The "x-xmpp-auth" scheme credentials MUST provide the full or bare JID of the entity that can confirm the request. The JID MUST be provided as a quoted-string.
The enhanced BNF for the "x-xmpp-auth" Access Authentication scheme is as follows:
x-xmpp-auth-challenge := "x-xmpp-auth" 1*SP "realm" "=" "xmpp"
x-xmpp-auth-credentials := "x-xmpp-auth" 1*SP "jid" "=" \
<quoted-string>
jid := XMPP address as specified in RFC 3920
(Refer to RFC 2616 regarding header syntax and the meaning of error codes, and to Section 1 of RFC 2617 regarding the framework of an authentication scheme; that information is not duplicated here.)
Example 3. HTTP Client Sends x-xmpp-auth Authorization Request
GET missive.html HTTP/1.1
Authorization: x-xmpp-auth jid="juliet@capulet.com/balcony"
The HTTP Server MAY offer any other valid authentication scheme, instead of or in addition to the Basic and Digest schemes mentioned above.
Once the HTTP Client has communicated the full JID or bare JID to the HTTP Server, the XMPP Server sends a confirmation request (via XMPP) to the XMPP Client.
If the JID provided was a full JID, the confirmation request SHOULD be sent in an <iq/> stanza of type "get" whose 'to' attribute is set to the full JID, but MAY be sent in a <message/> stanza.
If the JID provided was a bare JID, the confirmation request MUST be sent in a <message/> stanza whose 'to' attribute is set to the bare JID; this enables delivery to the "most available" resource for the user (however "most available" is determined by the XMPP Server). The <message/> stanza MAY include a <body/> element that provides human-readable information or instructions.
If the HTTP Client included a unique transaction identifier as the password entity via the Basic Access Authentication or Digest Access Authentication scheme, that ID MUST be provided as the value of the <confirm/> element's 'id' attribute.
Example 4. Confirmation Request Sent via IQ
<iq type='get'
from='files.shakespeare.lit'
to='juliet@capulet.com/balcony'
id='ha000'>
<confirm xmlns='http://jabber.org/protocol/http-auth'
method='GET'
id='transaction-identifier'
url='http://files.shakespeare.lit:9345/missive.html'/>
</iq>
Example 5. Confirmation Request Sent via Message
<message type='normal'
from='files.shakespeare.lit'
to='juliet@capulet.com'>
<thread>e0ffe42b28561960c6b12b944a092794b9683a38</thread>
<body>
Someone (maybe you) has requested the file
http://files.shakespeare.lit:9345/missive.html.
If you wish to confirm the request, please reply
to this message by typing "OK". If not, please
reply with "No".
</body>
<confirm xmlns='http://jabber.org/protocol/http-auth'
method='GET'
id='transaction-identifier'
url='http://files.shakespeare.lit:9345/missive.html'/>
</message>
The <confirm/> element MUST possess both a 'url' attribute and a 'method' attribute; the value of the 'url' attribute MUST be the full path of the HTTP object requested and the value of the 'method' attribute MUST be a valid HTTP method.
In addition, the <confirm/> element MAY possess an 'id' attribute; see the Implementation Notes for details.
If provided, the <thread/> element and its XML character data value MUST be mirrored in any message reply.
If the confirmation request was provided via an <iq/> stanza, the XMPP Client MUST respond to the request by sending an <iq/> stanza back to the XMPP Server. If the user wishes to confirm the request, the <iq/> response stanza MUST be of type "result" and MAY contain the original <confirm/> child element (although this is not required):
Example 6. XMPP Client Confirms Request via IQ
<iq type='result'
from='juliet@capulet.com/balcony'
to='files.shakespeare.lit'
id='ha000'/>
If the user wishes to deny the request, the <iq/> response stanza MUST be of type "error", MAY contain the original <confirm/> child element (although this is not required), and MUST specify an error, which SHOULD be <not-authorized/>:
Example 7. XMPP Client Denies Request via IQ
<iq type='error'
from='juliet@capulet.com/balcony'
to='files.shakespeare.lit'
id='ha000'>
<confirm xmlns='http://jabber.org/protocol/http-auth'
method='GET'
id='transaction-identifier'
url='http://files.shakespeare.lit:9345/missive.html'/>
<error code='401' type='auth'>
<not-authorized xmlns='urn:ietf:params:xml:xmpp-stanzas'/>
</error>
</iq>
If the confirmation request was provided via a <message/> stanza, the XMPP Client SHOULD respond to the request by sending a <message/> stanza back to the XMPP Server. If the user wishes to confirm the request, the <message/> response stanza SHOULD be of type "normal", MUST mirror the <thread/> ID (if provided), and MAY contain the original <confirm/> child element (although this is not required):
Example 8. XMPP Client Confirms Request via Message
<message from='juliet@capulet.com/balcony'
to='files.shakespeare.lit'>
<thread>e0ffe42b28561960c6b12b944a092794b9683a38</thread>
<confirm xmlns='http://jabber.org/protocol/http-auth'
method='GET'
id='transaction-identifier'
url='http://files.shakespeare.lit:9345/missive.html'/>
</message>
If the user wishes to deny the request, the <message/> response stanza MUST be of type "error", SHOULD mirror the <thread/> ID (if provided), MAY (but is not required to) contain the original <confirm/> child element, and MUST specify an error, which SHOULD be <not-authorized/>:
Example 9. XMPP Client Denies Request via Message
<message type='error'
from='juliet@capulet.com/balcony'
to='files.shakespeare.lit'>
<thread>e0ffe42b28561960c6b12b944a092794b9683a38</thread>
<confirm xmlns='http://jabber.org/protocol/http-auth'
method='GET'
url='http://files.shakespeare.lit:9345/missive.html'/>
<error code='401' type='auth'>
<not-authorized xmlns='urn:ietf:params:xml:xmpp-stanzas'/>
</error>
</message>
Once the XMPP Client has successfully confirmed the request, the HTTP Server allows access:
Example 10. HTTP Server Allows Access to Object
200 OK HTTP/1.1
Content-Type: text/html
Content-Length: 3032
...
If the XMPP Client denied the request, the HTTP Server MUST return a Forbidden error:
Example 11. HTTP Server Denies Access to Object
403 Forbidden HTTP/1.1
For the HEAD and OPTIONS methods, the credentials SHOULD be usable for a subsequent request from the same entity. This enables an entity to both determine support for the mechanism defined herein and start the authentication process.
For the POST and PUT methods (or any method containing a message body), clients MUST send all data with each request; the HTTP server is under no obligation to assume that the client will fail. This is especially true since the client can obtain credentials with a previous HEAD or OPTIONS method.
Confirmation of HTTP requests via XMPP is still vulnerable to man-in-the-middle attacks. However, it may be less vulnerable than pure HTTP authentication, since it utilizes an outside connection for a significant amount of the negotiation. This outside channel may be more trusted than a pure HTTP connection can be, given the existence of strong authentication (via SASL) in XMPP.
In order to provide a stronger connection between the HTTP request and the XMPP confirmation, a transaction identifier SHOULD be provided if the HTTP Basic Access Authentication or Digest Access Authentication scheme is used, then passed unchanged to the XMPP Client as the value of the <confirm/> element's 'id' attribute.
Section 4.6 of RFC 2617 specifies that if an HTTP server returns multiple challenges with a 401 (Authenticate) response, an HTTP client must use the strongest authentication scheme it understands. For the purposes of this document, an HTTP client MUST consider the "x-xmpp-auth" scheme to be stronger than the HTTP Basic scheme and SHOULD consider the HTTP Digest scheme to be stronger than the "x-xmpp-auth" scheme.
To reduce the likelihood of man-in-the-middle attacks, channel encryption SHOULD be used for both the XMPP channel and the HTTP channel. In particular:
For added security, the XMPP Server and XMPP Client may wish to communicate using end-to-end encryption. Methods for doing so are outside the scope of this proposal.
If the Internet Assigned Numbers Authority (IANA) [8] establishes a registry for HTTP authentication schemes, the "x-xmpp-auth" scheme may be registered there.
The Jabber Registrar [9] shall include "http://jabber.org/protocol/http-auth" in its registry of protocol namespaces.
<?xml version='1.0' encoding='UTF-8'?>
<xs:schema
xmlns:xs='http://www.w3.org/2001/XMLSchema'
targetNamespace='http://jabber.org/protocol/http-auth'
xmlns='http://jabber.org/protocol/http-auth'
elementFormDefault='qualified'>
<xs:element name='confirm'>
<xs:complexType>
<xs:simpleContent>
<xs:extension base='empty'>
<xs:attribute name='id' use='optional' type='xs:string'/>
<xs:attribute name='method' use='required' type='xs:NCName'/>
<xs:attribute name='url' use='required' type='xs:anyURI'/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
<xs:simpleType name='empty'>
<xs:restriction base='xs:string'>
<xs:enumeration value=''/>
</xs:restriction>
</xs:simpleType>
</xs:schema>
1. RFC 2616: Hypertext Transport Protocol -- HTTP/1.1 <http://www.ietf.org/rfc/rfc2616.txt>.
2. RFC 2617: HTTP Authentication: Basic and Digest Access Authentication <http://www.ietf.org/rfc/rfc2617.txt>.
3. RFC 3920: Extensible Messaging and Presence Protocol (XMPP): Core <http://www.ietf.org/rfc/rfc3920.txt>.
4. RFC 3548: The Base16, Base32, and Base64 Data Encodings <http://www.ietf.org/rfc/rfc3548.txt>.
5. RFC 3986: Uniform Resource Identifiers (URI): Generic Syntax <http://www.ietf.org/rfc/rfc3986.txt>.
6. JEP-0124: HTTP Binding <http://www.jabber.org/jeps/jep-0124.html>.
7. RFC 2817: Upgrading to TLS Within HTTP/1.1 <http://www.ietf.org/rfc/rfc2817.txt>.
8. The Internet Assigned Numbers Authority (IANA) is the central coordinator for the assignment of unique parameter values for Internet protocols, such as port numbers and URI schemes. For further information, see <http://www.iana.org/>.
9. The Jabber Registrar maintains a list of reserved Jabber protocol namespaces as well as registries of parameters used in the context of protocols approved by the Jabber Software Foundation. For further information, see <http://www.jabber.org/registrar/>.
END