One document matched: draft-jones-simple-web-discovery-04.xml
<?xml version="1.0" encoding="us-ascii"?>
<?xml-stylesheet type='text/xsl' href='http://xml.resource.org/authoring/rfc2629.xslt' ?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd">
<?rfc toc="yes"?>
<?rfc tocompact="yes"?>
<?rfc tocdepth="4"?>
<?rfc tocindent="yes"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes"?>
<?rfc comments="yes"?>
<?rfc inline="yes"?>
<?rfc compact="yes"?>
<?rfc subcompact="no"?>
<rfc category="std" ipr="trust200902" docName="draft-jones-simple-web-discovery-04">
<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="5" month="November" year="2012" />
<area>Security</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 an 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>
</front>
<middle>
<section title="Introduction">
<t>
Simple Web Discovery (SWD) defines an 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
query parameters
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
JavaScript Object Notation (JSON) <xref target="RFC4627"/>
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,
<spanx style="verb">joe@example.com</spanx>, and use its domain to create an HTTPS GET request of the following form
(with long lines broken for display purposes only):</t>
<figure>
<artwork><![CDATA[
GET /.well-known/simple-web-discovery
?principal=joe@example.com
&service=urn:example:service:calendar HTTP/1.1
Host: example.com
HTTP/1.1 200 OK
Content-Type: application/json
{
"locations": ["https://calendars.example.net/calendars/joseph"]
}
]]></artwork>
</figure>
<t>Note: The request-URI is left unencoded in the above example
for the sake of readability. The query parameters above would
actually be encoded as
<spanx style="verb">?principal=joe%40example.com&service=urn%3Aexample%3Aservice%3Acalendar</spanx>.</t>
<section title='Notational Conventions'>
<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
Key words for use in RFCs to Indicate Requirement Levels <xref target='RFC2119' />.
</t>
</section>
</section>
<section title="Simple Web Discovery Request">
<t>Domains that support SWD requests SHOULD make an SWD server available for their
domain at the path <spanx style="verb">/.well-known/simple-web-discovery</spanx>.
The syntax and semantics of <spanx style="verb">/.well-known</spanx> are defined in <xref target="RFC5785">RFC 5785</xref>.
<spanx style="verb">/.well-known/simple-web-discovery</spanx>
MUST point to an SWD server compliant with this specification.</t>
<t>
SWD servers MUST support receiving SWD requests via TLS 1.2 <xref target="RFC5246"/> 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>
An SWD server is queried using an HTTPS GET request with the
previously specified path along with a query segment
containing a form encoded using the
application/x-www-form-urlencoded encoding algorithm
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 <xref target="RFC3986"/>.
If any of the previous
requirements are not met in an 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>
<t>
SWD servers MAY also be located on ports other than 443
(the default HTTPS port), provided they use TLS on those ports.
The means by which an SWD client would know to use any alternative
ports are out of scope for this specification.
</t>
<section title='"simple-web-discovery" Subdomain'>
<t>
It may be difficult or impossible for some domains wanting to support
SWD requests to make an SWD server available for their domain at the path
<spanx style="verb">/.well-known/simple-web-discovery</spanx>.
For instance, in the case of hosted domains, no web server may be
running on the domain host at all.
</t>
<t>
For that reason, SWD servers for a domain MAY be located on a specific
subdomain of that domain: <spanx style="verb">simple-web-discovery</spanx>.
For example, the SWD server for the domain
<spanx style="verb">example.com</spanx> MAY be located at the URI
<spanx style="verb">https://simple-web-discovery.example.com/.well-known/simple-web-discovery</spanx>.
</t>
<t>
SWD clients MUST first attempt to make an SWD request to the domain's
<spanx style="verb">/.well-known/simple-web-discovery</spanx> endpoint,
and then if that fails, they MUST then attempt to make the request to
the SWD endpoint at the <spanx style="verb">simple-web-discovery</spanx>
subdomain for the domain.
</t>
</section>
</section>
<section title="Simple Web Discovery Responses">
<section title="Response Containing One or More Locations">
<t>A 200
OK response to an SWD request that contains the information
requested MUST return content of type application/json
<xref target="RFC4627"/>. 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="401 Unauthorized Response">
<t>
An 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>
An 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>
This specification registers a well-known URI suffix value
relative to "/.well-known/" in the IANA Well-Known URI registry
defined in <xref target="RFC5785">RFC 5785</xref>:
<list style="hanging">
<t hangText="URI suffix:">simple-web-discovery</t>
<t hangText="Change controller:">IETF</t>
<t hangText="Specification document:">[[ this document ]]</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>
When the SWD server for a domain is located at the
<spanx style="verb">simple-web-discovery</spanx> subdomain,
a TLS certificate will need to be present for that subdomain.
</t>
</section>
</middle>
<back>
<references title="Normative References">
<?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml' ?>
<?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.2616.xml' ?>
<?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.3986.xml' ?>
<?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.4627.xml' ?>
<?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.5246.xml' ?>
<?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.5785.xml' ?>
<?rfc include='http://xml.resource.org/public/rfc/bibxml4/reference.W3C.REC-html401-19991224.xml' ?>
</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>
<address>
<email>mbj@microsoft.com</email>
<uri>http://self-issued.info/</uri>
</address>
</author>
<author fullname="John Bradley" initials="J." surname="Bradley">
<organization abbrev="Ping Identity">Ping Identity</organization>
<address>
<email>ve7jtb@ve7jtb.com</email>
</address>
</author>
<author fullname="Nat Sakimura" initials="N." surname="Sakimura">
<organization abbrev="NRI">Nomura Research Institute</organization>
<address>
<email>n-sakimura@nri.co.jp</email>
</address>
</author>
<date day="15" month="October" year="2012" />
</front>
<format target="http://tools.ietf.org/html/draft-ietf-oauth-json-web-token" type="HTML" />
</reference>
</references>
<section title='Document History'>
<t>
[[ to be removed by the RFC editor before publication as an RFC ]]
</t>
<t>
-04
<list style='symbols'>
<t>
Specified that the SWD server for a domain may be located at the
<spanx style="verb">simple-web-discovery</spanx> subdomain of the
domain and that SWD clients must first try the endpoint at the
domain and then the endpoint at the subdomain.
</t>
<t>
Removed the <spanx style="verb">SWD_service_redirect</spanx> response,
since redirection can be accomplished by pointing the
<spanx style="verb">simple-web-discovery</spanx> subdomain to a
different location than the domain's host.
</t>
<t>
Removed <spanx style="verb">mailto:</spanx> from examples
in favor of bare e-mail address syntax.
</t>
<t>
Specified that SWD servers may also be run on ports other than 443,
provided they use TLS on those ports.
</t>
</list>
</t>
<t>
-03
<list style='symbols'>
<t>
Changed "requests use the x-www-form-urlencoded format"
to "requests use query parameters" and changed
"an x-www-form-urlencoded form" to "a form encoded using the
application/x-www-form-urlencoded encoding algorithm",
both at the suggestion of Julian Reschke.
</t>
<t>
Updated examples to use "urn:example:" URNs rather than
"urn:example.org:" URNs, also at Julian's suggestion.
</t>
<t>
Applied applicable editorial improvements from JOSE specs to SWD.
</t>
<t>
Updated references to related specifications.
</t>
</list>
</t>
<t>
-02
<list style='symbols'>
<t>
Update examples to use example.{com,net,org} domain names.
</t>
<t>
Provide encoded representation of the request-URI query
parameters for the first example request.
</t>
<t>
Changed "200 O.K." to "200 OK".
</t>
<t>
Respect line length restrictions in examples.
</t>
<t>
No normative changes.
</t>
</list>
</t>
<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-24 07:12:00 |