One document matched: draft-jones-simple-web-discovery-01.xml
<?xml version="1.0" encoding="us-ascii"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
<!ENTITY rfc2119 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">
<!ENTITY rfc2616 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2616.xml">
<!ENTITY rfc3339 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3339.xml">
<!ENTITY rfc3986 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3986.xml">
<!ENTITY rfc4627 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4627.xml">
<!ENTITY rfc5246 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5246.xml">
<!ENTITY rfc5785 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5785.xml">
<!ENTITY W3C.REC-html401-19991224 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml4/reference.W3C.REC-html401-19991224.xml">
]>
<?rfc toc="yes"?>
<?rfc tocompact="yes"?>
<?rfc tocdepth="3"?>
<?rfc tocindent="yes"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes"?>
<?rfc comments="yes"?>
<?rfc inline="yes"?>
<?rfc compact="yes"?>
<?rfc subcompact="no"?>
<rfc category="std" docName="draft-jones-simple-web-discovery-01"
ipr="trust200902">
<front>
<title>Simple Web Discovery (SWD)</title>
<author fullname="Michael B. Jones" initials="M.B." surname="Jones"> <!-- role="editor" -->
<organization>Microsoft</organization>
<address>
<email>mbj@microsoft.com</email>
<uri>http://self-issued.info/</uri>
</address>
</author>
<author fullname="Yaron Y. Goland" initials="Y.Y." surname="Goland">
<organization>Microsoft</organization>
<address>
<email>yarong@microsoft.com</email>
</address>
</author>
<date day="11" month="July" year="2011" />
<area>Applications</area>
<keyword>RFC</keyword>
<keyword>Request for Comments</keyword>
<keyword>I-D</keyword>
<keyword>Internet-Draft</keyword>
<keyword>Discovery</keyword>
<keyword>Finger</keyword>
<abstract>
<t>
Simple Web Discovery (SWD) defines a HTTPS GET based mechanism to discover the location of a given type of service for a given principal
starting only with a domain name.
</t>
</abstract>
<note title="Requirements Language">
<t>
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in <xref
target="RFC2119">RFC 2119</xref>.
</t>
</note>
</front>
<middle>
<section title="Introduction">
<t>
Simple Web Discovery (SWD) defines a HTTPS GET based mechanism to discover the location of a given type of service for a given principal
starting only with a domain name. SWD requests use the x-www-form-urlencoded format to specify a URI for the principal and another URI
for the type of service being sought. If the request is successful then the response, by default, is a JSON object containing an array of URIs that point to where the
principal has instances of services of the requested type.
</t>
<t>For example, let us say that a requester wants to discover where Joe keeps his calendar. The requester could take Joe's e-mail address,
joe@example.com and take from it its domain to create a HTTPS GET request of the following form:</t>
<figure>
<artwork>
<![CDATA[GET /.well-known/simple-web-discovery?principal=mailto:joe@example.com&service=urn:adatum.com:calendar HTTP/1.1
Host: example.com
HTTP/1.1 200 O.K.
Content-Type: application/json
{
"locations": ["http://calendars.proseware.com/calendars/joseph"]
}]]>
</artwork>
</figure>
<t>Note: The request-URI is left un-encoded in the above example
for the sake of readability in the above example.</t>
</section>
<section title="Simple Web Discovery Request">
<t>Domains that support SWD requests MUST make available a SWD server for their domain at the path .well-known/simple-web-discovery.
The syntax and semantics of ".well-known" are defined in <xref target="RFC5785">RFC 5785</xref>.
"simple-web-discovery" MUST point to a SWD server compliant with this specification.</t>
<t>
SWD servers MUST support receiving SWD requests via TLS 1.2 as defined in <xref target="RFC5246">RFC 5246</xref> and MAY support
other transport layer security mechanisms of equivalent security. SWD servers MUST reject SWD requests sent over plain HTTP or any other
transport that does not provide both privacy and validation of the server's identity.
</t>
<t>
A SWD server is queried using a HTTPS GET request with the
previously specified path along with a query segment
containing a x-www-form-urlencoded form as defined in <xref
target="W3C.REC-html401-19991224">HTML 4.01</xref>. The form
MUST contain two name/value pairs that MUST appear exactly
once, <spanx style="verb">principal</spanx> and <spanx
style="verb">service</spanx>. Both name/value pairs MUST have
values that are set to URIs (as defined in <xref
target="RFC3986">RFC 3986</xref>). If any of the previous
requirements are not met in a SWD request, then the request
MUST be rejected with a 400 Bad Request.
</t>
<t>
The SWD request form MAY contain additional name/value pairs but if those name/value pairs are not recognized by the SWD server then the SWD
server MUST ignore them for processing purposes.
</t>
<t>
The <spanx style="verb">principal</spanx> query component is a
URI that identifies an entity. The <spanx
style="verb">service</spanx> query component is a URI that
identifies a service type. The semantics of the SWD query is
"Please return the location(s) of instances of the specified
service type associated with the specified principal". The
definition of URIs used to identify principals and services
are outside the scope of this specification.
</t>
</section>
<section title="Simple Web Discovery Responses">
<section title="Response Containing One or More Locations">
<t>Unless another content-type is negotiated, a 200
O.K. response to a SWD request that contains the information
requested MUST return content of type application/json as
defined in <xref target="RFC4627">RFC 4627</xref>. The JSON
response MUST contain a JSON object that contains a member
pair whose name is the string <spanx
style="verb">locations</spanx> and whose value is an array of
strings that are each a URI pointing to a location where the
desired service type belonging to the specified principal can
be found. There are no semantics associated with the order in
which the URIs are listed in the array.</t>
<t>The JSON object MAY contain other members but a receiver of the object MAY ignore any member pairs whose name it does not recognize.</t>
</section>
<section title="Redirecting All Simple Web Discovery Requests">
<t>
SWD requests by definition start off by being issued to the
.well-known/simple-web-discovery location. But locating a
SWD server at a root location can prove inconvenient. To
enable service level redirection a SWD server MAY return a
200 O.k. to an HTTPS request with a content type of
application/json (or whatever other content type has been
negotiated) that contains a JSON object that contains a
member pair whose name is the string <spanx
style="verb">SWD_service_redirect</spanx> whose value is a
JSON object with a member pair whose name is <spanx
style="verb">location</spanx> and whose value is a string
that encodes a URI. Optionally the JSON object value of
<spanx style="verb">SWD_service_redirect</spanx> MAY also
contain a member whose name is <spanx
style="verb">expires</spanx> and whose value is a JSON
number that encodes an integer.
</t>
<t>
A SWD compliant client MUST support the <spanx
style="verb">SWD_service_redirect</spanx> response.
</t>
<t>
The JSON objects MAY contain other members but a receiver of
the objects MAY ignore any pairs whose name it does not
recognize.
</t>
<t>
The <spanx style="verb">location</spanx> member identifies
the URI that the caller MUST redirect all SWD requests for
that domain to until the <spanx style="verb">expires</spanx>
time is met. SWD requests for the redirected domain MUST be
constructed by taking the URI returned in the <spanx
style="verb">location</spanx> and using it as the base URI
to which the SWD form arguments are then added as query
parameters. The location URI MUST NOT include a query
component.
</t>
<figure>
<artwork>
<![CDATA[GET /.well-known/simple-web-discovery?principal=mailto:joe@example.com&service=urn:adatum.com:calendar HTTP/1.1
Host: example.com
HTTP/1.1 200 O.K.
Content-Type: application/json
{
"SWD_service_redirect":
{
"location": "https://swd.proseware.com/swd_server",
"expires": 1300752001
}
}
GET /swd_server?principal=mailto:joe@example.com&service=urn:adatum.com:calendar HTTP/1.1
Host: swd.proseware.com
HTTP/1.1 200 O.K.
Content-Type: application/json
{
"locations": ["http://calendars.proseware.com/calendars/joseph"]
}]]>
</artwork>
</figure>
<t>Note: The request-URIs are left un-encoded in the above
example for the sake of readability in the above example.</t>
<t>
The <spanx style="verb">location</spanx> URI MUST be an HTTPS URL.
</t>
<t>
The optional <spanx style="verb">expires</spanx> member
identifies the point in time at which the caller MUST NOT
redirect its SWD requests for that domain to the previously
obtained <spanx style="verb">location</spanx> and MUST instead return to the
.well-known/simple-web-discovery location. The value of the
<spanx style="verb">expires</spanx> member MUST encode the
number of seconds from 1970-01-01T0:0:0Z as measured in UTC
until the desired date/time. See <xref target="RFC3339">RFC
3339</xref> for details regarding date/times in general and
UTC in particular. If the <spanx
style="verb">expires</spanx> value is in the past or if the
value is more than one hour in the future then the response
MUST be treated as if it didn't contain an <spanx
style="verb">expires</spanx> value.
</t>
<t>
If the <spanx style="verb">expires</spanx> value is omitted
or if its value is incorrect then the <spanx
style="verb">expires</spanx> value MUST be treated as having
a value of exactly one hour into the future.
</t>
<t>
If a JSON response is received that contains both a member
pair with the name <spanx
style="verb">SWD_service_redirect</spanx> and a member pair
with the name <spanx style="verb">locations</spanx> as
children of the object root then the <spanx
style="verb">SWD_service_redirect</spanx> member pair MUST
be ignored.
</t>
</section>
<section title="401 Unauthorized Response">
<t>
A SWD server MAY respond to a request with a 401
Unauthorized Response, as described in <xref
target="RFC2616">RFC 2616</xref>, Section 10. Per the RFC,
the request MAY be repeated with a suitable Authorization
header field. Authorization information may be communicated
in this manner, including a JSON Web Token <xref
target="JWT"></xref>.
</t>
</section>
<section title="Other HTTP 1.1 Responses">
<t>
A SWD server MAY return other HTTP 1.1 responses, including
404 Not Found, 400 Bad Request, and 403 Forbidden. SWD
implementations MUST correctly handle these responses.
</t>
</section>
</section>
<section anchor="IANA" title="IANA Considerations">
<t>
Per <xref target="RFC5785">RFC 5785</xref>, the following
registration template is offered:
<list style="hanging">
<t hangText="URI suffix">simple-web-discovery</t>
<t hangText="Change controller">IETF</t>
<t hangText="Specification document">This RFC</t>
</list>
</t>
</section>
<section anchor="Security" title="Security Considerations">
<t>
SWD responses can contain confidential information. Therefore
a, general approach is used to require TLS in all cases. But
TLS can only provide for privacy and server validation, it
cannot validate that the requester is authorized to see the
results of a query. The exact mechanism used to determine if
the requester is authorized to see the result of the query is
outside the scope of this specification.
</t>
<t>
Because SWD responses can contain confidential information,
the requestor may need authorization to receive them.
Standard HTTP authorization mechanisms MAY be employed to
request authorized access, including the use of an HTTP
Authorization header field in requests, which in turn, may
contain a JSON Web Token <xref target="JWT"></xref>, among
other authorization data formats.
</t>
<t>
The ability to redirect an entire SWD server as defined in
this document is an obvious attack point. This is another
reason why we have mandated TLS, so as to be sure that the
redirect can only be received over a secure connection. We
have also put in the upper limit of 60 minutes for a redirect
so as to provide a path for regaining control over queries
should a successful attack be launched to return false
redirects.
</t>
<t>
The <spanx style="verb">SWD_service_redirect</spanx>
capability may cause unanticipated failures in cases where a
requestor may have permissions to discover content at the
original SWD endpoint but not the one redirected to, or
vice-versa.
</t>
</section>
</middle>
<back>
<references title="Normative References">
&rfc2119;
&rfc2616;
&rfc3339;
&rfc3986;
&rfc4627;
&rfc5246;
&rfc5785;
&W3C.REC-html401-19991224;
</references>
<references title="Informative References">
<reference anchor="JWT">
<front>
<title>JSON Web Token (JWT)</title>
<author fullname="Michael B. Jones" initials="M.B." surname="Jones">
<organization>Microsoft</organization>
</author>
<author fullname="Dirk Balfanz" initials="D. " surname="Balfanz">
<organization>Google</organization>
</author>
<author fullname="John Bradley" initials="J." surname="Bradley">
<organization>independent</organization>
</author>
<author fullname="Yaron Y. Goland" initials="Y.Y." surname="Goland">
<organization>Microsoft</organization>
</author>
<author fullname="John Panzer" initials="J. " surname="Panzer">
<organization>Google</organization>
</author>
<author fullname="Nat Sakimura" initials="N. " surname="Sakimura">
<organization>Nomura Research Institute</organization>
</author>
<author fullname="Paul Tarjan" initials="P." surname="Tarjan">
<organization>Facebook</organization>
</author>
<date day="11" month="July" year="2011" />
</front>
<format target="http://self-issued.info/docs/draft-jones-json-web-token.html" type="HTML"/>
</reference>
</references>
<section title='Document History'>
<t>
-01
<list style='symbols'>
<t>
Refresh draft before expiration of -00.
No normative changes.
</t>
</list>
</t>
<t>
-00
<list style='symbols'>
<t>
Initial version.
</t>
</list>
</t>
</section>
</back>
</rfc>
| PAFTECH AB 2003-2026 | 2026-04-23 21:40:38 |