<?xml version='1.0' encoding='utf-8'?>
<rfc xmlns:xi="http://www.w3.org/2001/XInclude" version="3" category="exp" docName="draft-thornburgh-fwk-dc-token-iss-01" indexInclude="true" ipr="trust200902" prepTime="2020-08-26T17:41:44" scripts="Common,Latin" sortRefs="false" submissionType="independent" symRefs="true" tocDepth="3" tocInclude="true">
  <front>
    <title abbrev="Decentralized Token Issuance">A Framework For Decentralized Bearer Token Issuance in HTTP</title>
    <seriesInfo name="Internet-Draft" status="experimental" stream="independent" value="draft-thornburgh-fwk-dc-token-iss-01"/>
    <author initials="M" surname="Thornburgh" fullname="Michael C. Thornburgh">
      <address>
        <postal>
          <city>Santa Cruz</city>
          <region>CA</region>
          <code>95060-1950</code>
          <country>US</country>
        </postal>
        <email>zenomt@zenomt.com</email>
        <uri>https://zenomt.zenomt.com/card.ttl#me</uri>
      </address>
    </author>
    <date day="26" month="08" year="2020"/>
    <workgroup>Independent Submission</workgroup>
    <abstract pn="section-abstract">
      <t pn="section-abstract-1">

		This memo describes a protocol framework for HTTP clients to
		obtain bearer tokens for accessing restricted resources, where
		in some applications the client may not have prior knowledge
		of, or a direct relationship with, the resource server's
		authorization infrastructure (such as in decentralized identity
		systems).  Semi-concrete applications of the framework using
		proof-of-possession and TLS client certificate mechanisms are
		also described.

      </t>
    </abstract>
    <boilerplate>
      <section anchor="status-of-memo" numbered="false" removeInRFC="false" toc="exclude" pn="section-boilerplate.1">
        <name slugifiedName="name-status-of-this-memo">Status of This Memo</name>
        <t pn="section-boilerplate.1-1">
        This Internet-Draft is submitted in full conformance with the
        provisions of BCP 78 and BCP 79.
        </t>
        <t pn="section-boilerplate.1-2">
        Internet-Drafts are working documents of the Internet Engineering Task
        Force (IETF). Note that other groups may also distribute working
        documents as Internet-Drafts. The list of current Internet-Drafts is
        at <eref target="https://datatracker.ietf.org/drafts/current/" brackets="none"/>.
        </t>
        <t pn="section-boilerplate.1-3">
        Internet-Drafts are draft documents valid for a maximum of six months
        and may be updated, replaced, or obsoleted by other documents at any
        time. It is inappropriate to use Internet-Drafts as reference
        material or to cite them other than as "work in progress."
        </t>
        <t pn="section-boilerplate.1-4">
        This Internet-Draft will expire on 27 February 2021.
        </t>
      </section>
      <section anchor="copyright" numbered="false" removeInRFC="false" toc="exclude" pn="section-boilerplate.2">
        <name slugifiedName="name-copyright-notice">Copyright Notice</name>
        <t pn="section-boilerplate.2-1">
            Copyright (c) 2020 IETF Trust and the persons identified as the
            document authors. All rights reserved.
        </t>
        <t pn="section-boilerplate.2-2">
            This document is subject to BCP 78 and the IETF Trust's Legal
            Provisions Relating to IETF Documents
            (<eref target="https://trustee.ietf.org/license-info" brackets="none"/>) in effect on the date of
            publication of this document. Please review these documents
            carefully, as they describe your rights and restrictions with
            respect to this document.
        </t>
      </section>
    </boilerplate>
    <toc>
      <section anchor="toc" numbered="false" removeInRFC="false" toc="exclude" pn="section-toc.1">
        <name slugifiedName="name-table-of-contents">Table of Contents</name>
        <ul bare="true" empty="true" indent="2" spacing="compact" pn="section-toc.1-1">
          <li pn="section-toc.1-1.1">
            <t pn="section-toc.1-1.1.1"><xref derivedContent="1" format="counter" sectionFormat="of" target="section-1"/>.  <xref derivedContent="" format="title" sectionFormat="of" target="name-introduction">Introduction</xref></t>
            <ul bare="true" empty="true" indent="2" spacing="compact" pn="section-toc.1-1.1.2">
              <li pn="section-toc.1-1.1.2.1">
                <t keepWithNext="true" pn="section-toc.1-1.1.2.1.1"><xref derivedContent="1.1" format="counter" sectionFormat="of" target="section-1.1"/>.  <xref derivedContent="" format="title" sectionFormat="of" target="name-motivation">Motivation</xref></t>
                <ul bare="true" empty="true" indent="2" spacing="compact" pn="section-toc.1-1.1.2.1.2">
                  <li pn="section-toc.1-1.1.2.1.2.1">
                    <t keepWithNext="true" pn="section-toc.1-1.1.2.1.2.1.1"><xref derivedContent="1.1.1" format="counter" sectionFormat="of" target="section-1.1.1"/>.  <xref derivedContent="" format="title" sectionFormat="of" target="name-use-cases">Use Cases</xref></t>
                  </li>
                </ul>
              </li>
              <li pn="section-toc.1-1.1.2.2">
                <t keepWithNext="true" pn="section-toc.1-1.1.2.2.1"><xref derivedContent="1.2" format="counter" sectionFormat="of" target="section-1.2"/>.  <xref derivedContent="" format="title" sectionFormat="of" target="name-terminology">Terminology</xref></t>
              </li>
            </ul>
          </li>
          <li pn="section-toc.1-1.2">
            <t pn="section-toc.1-1.2.1"><xref derivedContent="2" format="counter" sectionFormat="of" target="section-2"/>.  <xref derivedContent="" format="title" sectionFormat="of" target="name-general-framework">General Framework</xref></t>
            <ul bare="true" empty="true" indent="2" spacing="compact" pn="section-toc.1-1.2.2">
              <li pn="section-toc.1-1.2.2.1">
                <t pn="section-toc.1-1.2.2.1.1"><xref derivedContent="2.1" format="counter" sectionFormat="of" target="section-2.1"/>.  <xref derivedContent="" format="title" sectionFormat="of" target="name-nonce-considerations">Nonce Considerations</xref></t>
              </li>
              <li pn="section-toc.1-1.2.2.2">
                <t pn="section-toc.1-1.2.2.2.1"><xref derivedContent="2.2" format="counter" sectionFormat="of" target="section-2.2"/>.  <xref derivedContent="" format="title" sectionFormat="of" target="name-common-token-response">Common Token Response</xref></t>
              </li>
              <li pn="section-toc.1-1.2.2.3">
                <t pn="section-toc.1-1.2.2.3.1"><xref derivedContent="2.3" format="counter" sectionFormat="of" target="section-2.3"/>.  <xref derivedContent="" format="title" sectionFormat="of" target="name-common-mechanism-flow">Common Mechanism Flow</xref></t>
              </li>
            </ul>
          </li>
          <li pn="section-toc.1-1.3">
            <t pn="section-toc.1-1.3.1"><xref derivedContent="3" format="counter" sectionFormat="of" target="section-3"/>.  <xref derivedContent="" format="title" sectionFormat="of" target="name-proof-of-possession-mechani">Proof-of-Possession Mechanism</xref></t>
            <ul bare="true" empty="true" indent="2" spacing="compact" pn="section-toc.1-1.3.2">
              <li pn="section-toc.1-1.3.2.1">
                <t pn="section-toc.1-1.3.2.1.1"><xref derivedContent="3.1" format="counter" sectionFormat="of" target="section-3.1"/>.  <xref derivedContent="" format="title" sectionFormat="of" target="name-proof-token">Proof Token</xref></t>
              </li>
              <li pn="section-toc.1-1.3.2.2">
                <t pn="section-toc.1-1.3.2.2.1"><xref derivedContent="3.2" format="counter" sectionFormat="of" target="section-3.2"/>.  <xref derivedContent="" format="title" sectionFormat="of" target="name-proof-of-possession-api">Proof-of-Possession API</xref></t>
              </li>
              <li pn="section-toc.1-1.3.2.3">
                <t pn="section-toc.1-1.3.2.3.1"><xref derivedContent="3.3" format="counter" sectionFormat="of" target="section-3.3"/>.  <xref derivedContent="" format="title" sectionFormat="of" target="name-proof-of-possession-example">Proof-of-Possession Example</xref></t>
              </li>
            </ul>
          </li>
          <li pn="section-toc.1-1.4">
            <t pn="section-toc.1-1.4.1"><xref derivedContent="4" format="counter" sectionFormat="of" target="section-4"/>.  <xref derivedContent="" format="title" sectionFormat="of" target="name-tls-client-certificate-mech">TLS Client Certificate Mechanism</xref></t>
            <ul bare="true" empty="true" indent="2" spacing="compact" pn="section-toc.1-1.4.2">
              <li pn="section-toc.1-1.4.2.1">
                <t pn="section-toc.1-1.4.2.1.1"><xref derivedContent="4.1" format="counter" sectionFormat="of" target="section-4.1"/>.  <xref derivedContent="" format="title" sectionFormat="of" target="name-client-certificate-api">Client Certificate API</xref></t>
              </li>
              <li pn="section-toc.1-1.4.2.2">
                <t pn="section-toc.1-1.4.2.2.1"><xref derivedContent="4.2" format="counter" sectionFormat="of" target="section-4.2"/>.  <xref derivedContent="" format="title" sectionFormat="of" target="name-client-certificate-example">Client Certificate Example</xref></t>
              </li>
            </ul>
          </li>
          <li pn="section-toc.1-1.5">
            <t pn="section-toc.1-1.5.1"><xref derivedContent="5" format="counter" sectionFormat="of" target="section-5"/>.  <xref derivedContent="" format="title" sectionFormat="of" target="name-iana-considerations">IANA Considerations</xref></t>
          </li>
          <li pn="section-toc.1-1.6">
            <t pn="section-toc.1-1.6.1"><xref derivedContent="6" format="counter" sectionFormat="of" target="section-6"/>.  <xref derivedContent="" format="title" sectionFormat="of" target="name-security-considerations">Security Considerations</xref></t>
          </li>
          <li pn="section-toc.1-1.7">
            <t pn="section-toc.1-1.7.1"><xref derivedContent="7" format="counter" sectionFormat="of" target="section-7"/>.  <xref derivedContent="" format="title" sectionFormat="of" target="name-references">References</xref></t>
            <ul bare="true" empty="true" indent="2" spacing="compact" pn="section-toc.1-1.7.2">
              <li pn="section-toc.1-1.7.2.1">
                <t pn="section-toc.1-1.7.2.1.1"><xref derivedContent="7.1" format="counter" sectionFormat="of" target="section-7.1"/>.  <xref derivedContent="" format="title" sectionFormat="of" target="name-normative-references">Normative References</xref></t>
              </li>
              <li pn="section-toc.1-1.7.2.2">
                <t pn="section-toc.1-1.7.2.2.1"><xref derivedContent="7.2" format="counter" sectionFormat="of" target="section-7.2"/>.  <xref derivedContent="" format="title" sectionFormat="of" target="name-informative-references">Informative References</xref></t>
              </li>
            </ul>
          </li>
          <li pn="section-toc.1-1.8">
            <t pn="section-toc.1-1.8.1"><xref derivedContent="" format="none" sectionFormat="of" target="section-appendix.a"/><xref derivedContent="" format="title" sectionFormat="of" target="name-authors-address">Author's Address</xref></t>
          </li>
        </ul>
      </section>
    </toc>
  </front>
  <middle>
    <section numbered="true" removeInRFC="false" toc="include" pn="section-1">
      <name slugifiedName="name-introduction">Introduction</name>
      <t pn="section-1-1">This memo describes a general protocol framework for HTTP clients to obtain
bearer tokens (<xref section="1.2" target="RFC6750" sectionFormat="of" format="default" derivedLink="https://rfc-editor.org/rfc/rfc6750#section-1.2" derivedContent="RFC6750"/>)
from a resource server's authorization service in order to access protected
resources on the server. This framework is especially intended for systems
(such as decentralized identity systems like <xref target="WebID" format="default" sectionFormat="of" derivedContent="WebID"/>, and
decentralized social or mashup data systems like the
<eref target="https://solidproject.org" brackets="none">Solid project</eref>) where
the client might not have prior knowledge of, or a preexisting direct
relationship with, the authorization service for the resource server; however,
it can be applied in other use cases as well.</t>
      <t pn="section-1-2">The protocol includes a method for the client to discover the nature(s)
of principals (such as identities, capabilities, sender-constrained access
tokens, or verifiable credentials) that the server expects to interact with,
and methods for the client to discover the API endpoint URIs for multiple potential
mechanisms for obtaining bearer tokens. The framework is constructed to mitigate
man-in-the-middle token-stealing attacks.</t>
      <t pn="section-1-3">This memo defines two mechanisms within the framework for a client to
obtain a bearer token: one using a cryptographic proof-of-possession, and one
using <xref target="RFC8446" format="default" sectionFormat="of" derivedContent="RFC8446">TLS</xref> client certificates. These mechanisms
retain generality, and must be further refined in other specifications according
to the application and the nature of the principals expected by the servers.
Other mechanisms within the framework are also possible.</t>
      <section numbered="true" removeInRFC="false" toc="include" pn="section-1.1">
        <name slugifiedName="name-motivation">Motivation</name>
        <t pn="section-1.1-1">This work was originally motivated by a desire to address security, semantic,
and operational shortcomings in an experimental, decentralized, application-layer
authentication scheme for the

<eref target="https://solidproject.org" brackets="none">Solid project</eref> that was based on
<xref target="WebID" format="default" sectionFormat="of" derivedContent="WebID"/>,
<xref target="OpenID.Core" format="default" sectionFormat="of" derivedContent="OpenID.Core">OpenID Connect</xref>, and
<xref target="RFC7800" format="default" sectionFormat="of" derivedContent="RFC7800">proof-of-possession key semantics</xref>.</t>
        <t pn="section-1.1-2">An explicit goal of the solution is to leverage the benefits of bearer
tokens for accessing restricted resources:</t>
        <ul bare="false" empty="false" spacing="normal" pn="section-1.1-3">
          <li pn="section-1.1-3.1">The token can encapsulate (by direct encoding or by reference)
		exactly and only the implementation-specific and deployment-specific
		properties needed to make access control decisions in the
		resource server;</li>
          <li pn="section-1.1-3.2">
            <t pn="section-1.1-3.2.1">The effort (including computational, cryptographic, and network)
		required to establish a client's identity and authorizations
		can be done once by the client and the authorization service,
		compiled to a token, and this effort amortized over many
		requests to the same resource server, with simple revalidation
		and lifetime semantics that can be influenced by both parties;
		specifically:</t>
            <ul bare="false" empty="false" spacing="normal" pn="section-1.1-3.2.2">
              <li pn="section-1.1-3.2.2.1">The server's authorization system chooses an expiration
				period for the token, and can also revoke it at any time,
				to cause a reauthentication and revalidation;</li>
              <li pn="section-1.1-3.2.2.2">The client can forget the token at any time and acquire a new
				one to cause a reauthentication and revalidation;
				this can be particularly advantageous if the
				client acquires new privileges, authorizations,
				or endorsements that might otherwise be subject
				to unknown caching policies in an access
				controller;</li>
            </ul>
          </li>
          <li pn="section-1.1-3.3">The representation of the token can be optimized for network
		transmission and for decoding, verification, and processing
		according to the server's implementation;</li>
          <li pn="section-1.1-3.4">HTTP header compression schemes such as
		<xref target="RFC7541" format="default" sectionFormat="of" derivedContent="RFC7541">HPACK</xref> can reduce network resource
		consumption when a token is reused for multiple requests in
		the same origin.</li>
        </ul>
        <t pn="section-1.1-4">As work progressed, a general form emerged that could address multiple use
cases beyond the original motivator.</t>
        <section numbered="true" removeInRFC="false" toc="include" pn="section-1.1.1">
          <name slugifiedName="name-use-cases">Use Cases</name>
          <t pn="section-1.1.1-1">It is envisioned that the framework described in this memo can be used in
at least the following cases, with appropriate further specification, to
realize the benefits listed above:</t>
          <ul bare="false" empty="false" spacing="normal" pn="section-1.1.1-2">
            <li pn="section-1.1.1-2.1">Decentralized identity systems such as WebID and
		<xref target="DID" format="default" sectionFormat="of" derivedContent="DID">Decentralized Identifiers</xref>;</li>
            <li pn="section-1.1.1-2.2">Centralized or decentralized authorization systems based on
		<xref target="VC" format="default" sectionFormat="of" derivedContent="VC">Verifiable Credentials</xref>;</li>
            <li pn="section-1.1.1-2.3">Authenticated access to a multitude of decentralized, uncoordinated
		resource servers, such as for social or mashup data
		applications;</li>
            <li pn="section-1.1.1-2.4">Identity systems based on aspects of a TLS client certificate,
		without requiring use of that certificate for all accesses
		to a resource server (particularly in browser-based applications,
		to allow selective unauthenticated access to non-protected
		resources within the limitations of negotiating client
		certificates in TLS);</li>
            <li pn="section-1.1.1-2.5">Obtaining an audience-constrained bearer token given a
		sender-constrained access credential or capability issued by
		a central authority;</li>
            <li pn="section-1.1.1-2.6">Obtaining an audience-constrained bearer token in a centralized,
		federated, or confederated identity system given an identity
		bound with a pre-shared public key.</li>
          </ul>
          <t pn="section-1.1.1-3">This list of use cases should not be construed as exhaustive or limiting.
Other effective applications of this framework are possible.</t>
        </section>
        <!-- Use Cases -->
</section>
      <!-- Motivation -->

<section numbered="true" removeInRFC="false" toc="include" pn="section-1.2">
        <name slugifiedName="name-terminology">Terminology</name>
        <t pn="section-1.2-1">The key words "<bcp14>MUST</bcp14>", "<bcp14>MUST NOT</bcp14>",
"<bcp14>REQUIRED</bcp14>", "<bcp14>SHALL</bcp14>", "<bcp14>SHALL NOT</bcp14>",
"<bcp14>SHOULD</bcp14>", "<bcp14>SHOULD NOT</bcp14>", "<bcp14>RECOMMENDED</bcp14>",
"<bcp14>NOT RECOMMENDED</bcp14>", "<bcp14>MAY</bcp14>", and "<bcp14>OPTIONAL</bcp14>"
in this document are to be interpreted as described in BCP 14
<xref target="RFC2119" format="default" sectionFormat="of" derivedContent="RFC2119"/> <xref target="RFC8174" format="default" sectionFormat="of" derivedContent="RFC8174"/> when, and only when, they
appear in all capitals, as shown here.</t>
        <t pn="section-1.2-2">The term "bearer token" in this document has the meaning described in
<xref target="RFC6750" format="default" sectionFormat="of" derivedContent="RFC6750"/>.</t>
        <t pn="section-1.2-3">The term "protection space" in this document has the meaning described in
<xref section="2.2" target="RFC7235" sectionFormat="of" format="default" derivedLink="https://rfc-editor.org/rfc/rfc7235#section-2.2" derivedContent="RFC7235"/>.</t>
      </section>
      <!-- Terminology -->
</section>
    <!-- Introduction -->

<section numbered="true" removeInRFC="false" toc="include" pn="section-2">
      <name slugifiedName="name-general-framework">General Framework</name>
      <t pn="section-2-1">The server challenges an unauthenticated client
(<xref section="2.1" target="RFC7235" sectionFormat="of" format="default" derivedLink="https://rfc-editor.org/rfc/rfc7235#section-2.1" derivedContent="RFC7235"/>) with an HTTP
<tt>401</tt> response, including a <tt>WWW-Authenticate</tt> response header
with the <tt>Bearer</tt> <em>auth-scheme</em>
(<xref section="3" target="RFC6750" sectionFormat="of" format="default" derivedLink="https://rfc-editor.org/rfc/rfc6750#section-3" derivedContent="RFC6750"/>),
and comprising parameters including how to use one or more token acquisition
mechanisms.

The client examines the challenge and determines which mechanisms, if any,
it is able to use to acquire a bearer token. If possible, the client uses a
compatible mechanism, including attributes of the original request and the
challenge, to request a bearer token. The token will have a stated lifetime
and will be valid for accesses within the same protection space as the original
request, until the token expires or is revoked.
</t>
      <t pn="section-2-2">A <tt>WWW-Authenticate</tt> challenge for any mechanism includes at least
these <em>auth-params</em>:</t>
      <dl newline="false" spacing="normal" pn="section-2-3">
        <dt pn="section-2-3.1"><tt>scope</tt></dt>
        <dd pn="section-2-3.2">
          <bcp14>REQUIRED</bcp14>: A space-delimited
		list of case-sensitive strings, each a well-known or
		server-defined value indicating the nature(s) of the principal
		expected to be used when requesting a bearer token.  To avoid
		ambiguity, server-defined scopes <bcp14>SHOULD</bcp14> be
		URIs.</dd>
        <dt pn="section-2-3.3"><tt>nonce</tt></dt>
        <dd pn="section-2-3.4">
          <bcp14>REQUIRED</bcp14>: An opaque (to the
		client) string to be included unmodified when requesting a
		bearer token. See <xref target="nonce_considerations" format="default" sectionFormat="of" derivedContent="Section 2.1"/> for
		considerations on constructing the challenge nonce.</dd>
        <dt pn="section-2-3.5"><tt>error</tt></dt>
        <dd pn="section-2-3.6">
          <t pn="section-2-3.6.1">If present, a reason code indicating that
		the request had a problem other than not presenting an access
		token. The following reason codes are initially defined:</t>
          <dl newline="false" spacing="normal" pn="section-2-3.6.2">
            <dt pn="section-2-3.6.2.1"><tt>invalid_token</tt></dt>
            <dd pn="section-2-3.6.2.2">A bearer token
				was presented, but it was expired, revoked,
				or otherwise not recognized as valid.</dd>
            <dt pn="section-2-3.6.2.3"><tt>proof_required</tt></dt>
            <dd pn="section-2-3.6.2.4">An access token
				requiring proof-of-possession of a key (but
				potentially otherwise valid) was presented.</dd>
          </dl>
        </dd>
      </dl>
      <t pn="section-2-4">Additionally, one or more mechanism-specific <em>auth-params</em> are
included in the challenge to indicate the availability of that mechanism and
its unique parameters (usually the URI at which to use the mechanism). This
memo defines two mechanism-specific <em>auth-params</em>:</t>
      <dl newline="false" spacing="normal" pn="section-2-5">
        <dt pn="section-2-5.1"><tt>token_pop_endpoint</tt></dt>
        <dd pn="section-2-5.2">If present, the
		<xref target="token_pop_mechanism" format="default" sectionFormat="of" derivedContent="Section 3">Proof-of-Possession
		mechanism</xref> is available. The parameter value is the URI
		at which to exchange a proof-of-possession for a bearer
		token.</dd>
        <dt pn="section-2-5.3"><tt>client_cert_endpoint</tt></dt>
        <dd pn="section-2-5.4">If present, the
		<xref target="client_cert_mechanism" format="default" sectionFormat="of" derivedContent="Section 4">TLS Client Certificate
		mechanism</xref> is available. The parameter value is the URI
		at which to request a bearer token.</dd>
      </dl>
      <t pn="section-2-6">The challenge can include other <em>auth-params</em> (such as <tt>realm</tt>),
including ones for other mechanisms. Unrecognized <em>auth-params</em>
        <bcp14>SHOULD</bcp14> be ignored.</t>
      <t pn="section-2-7">If a request is made for a resource within a protection space and that
request includes an <tt>Authorization</tt> header with an invalid <tt>Bearer</tt>
token, the resource server <bcp14>SHOULD</bcp14> reply with an HTTP <tt>401</tt>
response and <tt>WWW-Authenticate</tt> header as above, even if processing
the request doesn't otherwise require authorization.  This is to allow a
client to obtain a fresh bearer token proactively (for example, before the
current token expires, to avoid delaying a real request by the user).</t>
      <section anchor="nonce_considerations" numbered="true" removeInRFC="false" toc="include" pn="section-2.1">
        <name slugifiedName="name-nonce-considerations">Nonce Considerations</name>
        <t pn="section-2.1-1">The nonce in the <tt>WWW-Authenticate</tt> challenge <bcp14>SHOULD</bcp14>
have the following properties:</t>
        <ul bare="false" empty="false" spacing="normal" pn="section-2.1-2">
          <li pn="section-2.1-2.1">Be cryptographically strong and unguessable;</li>
          <li pn="section-2.1-2.2">Be recognizable when returned in a token request as having been
		issued for this protection space (for example, by recording
		the nonce in a database, or including a cryptographic
		signature);</li>
          <li pn="section-2.1-2.3">Be valid for a limited (short) time;</li>
          <li pn="section-2.1-2.4">Be redeemable at most once;</li>
          <li pn="section-2.1-2.5">Be coupled to the original request URI in a recognizable way.</li>
        </ul>
      </section>
      <!-- Nonce Considerations -->

<section anchor="common_response" numbered="true" removeInRFC="false" toc="include" pn="section-2.2">
        <name slugifiedName="name-common-token-response">Common Token Response</name>
        <t pn="section-2.2-1">It is anticipated that most mechanisms (especially ones that use an HTTP
API) will respond to a token request using a common response format. Both of
the mechanisms described in this memo use the common format described in this
section, which is substantially the same as the format described in
<xref section="5" target="RFC6749" sectionFormat="of" format="default" derivedLink="https://rfc-editor.org/rfc/rfc6749#section-5" derivedContent="RFC6749"/>.</t>
        <t pn="section-2.2-2">A successful common response is an HTTP <tt>200</tt> response with
Content-Type <tt>application/json</tt>, and having a response body in
<xref target="RFC8259" format="default" sectionFormat="of" derivedContent="RFC8259">JSON</xref> format encoding a JSON object with at least
the following members:</t>
        <dl newline="false" spacing="normal" pn="section-2.2-3">
          <dt pn="section-2.2-3.1"><tt>access_token</tt></dt>
          <dd pn="section-2.2-3.2">An opaque (to the client) string;
		a bearer access token
		(<xref section="1.1" target="RFC6750" sectionFormat="of" format="default" derivedLink="https://rfc-editor.org/rfc/rfc6750#section-1.1" derivedContent="RFC6750"/>)
		which can be used for requests in the same protection space
		as the original request;</dd>
          <dt pn="section-2.2-3.3"><tt>expires_in</tt></dt>
          <dd pn="section-2.2-3.4">The number of seconds from the
		<tt>Date</tt> of this response after which the <tt>access_token</tt>
		will no longer be valid;</dd>
          <dt pn="section-2.2-3.5"><tt>token_type</tt></dt>
          <dd pn="section-2.2-3.6">A case-insensitive string identifying
		the kind of token returned in this response. This value
		<bcp14>MUST</bcp14> be <tt>Bearer</tt>.</dd>
        </dl>
        <t pn="section-2.2-4">If there is a problem with the request, the response <bcp14>SHALL</bcp14>
be an HTTP <tt>400</tt> response with Content-Type <tt>application/json</tt>,
and having a response body in JSON format encoding a JSON object with at least
an <tt>error</tt> member, and others as appropriate, whose keys and values
are defined in <xref section="5.2" target="RFC6749" sectionFormat="of" format="default" derivedLink="https://rfc-editor.org/rfc/rfc6749#section-5.2" derivedContent="RFC6749"/>.</t>
        <t pn="section-2.2-5">Additional members <bcp14>MAY</bcp14> be included in a successful or
unsuccessful response object depending on the scope(s) from the
challenge, the mechanism used, and the implementation. Unrecognized response
object members <bcp14>SHOULD</bcp14> be ignored.</t>
      </section>
      <!-- Common Response -->

<section numbered="true" removeInRFC="false" toc="include" pn="section-2.3">
        <name slugifiedName="name-common-mechanism-flow">Common Mechanism Flow</name>
        <t pn="section-2.3-1">It is anticipated that most mechanisms will comprise a simple mechanism-specific
API endpoint and respond with a <xref target="common_response" format="default" sectionFormat="of" derivedContent="Section 2.2">Common
Response</xref>.  The abstract flow for a client to acquire a bearer token
in the common way is illustrated in <xref target="common_sequence" format="default" sectionFormat="of" derivedContent="Figure 1"/>.</t>
        <figure anchor="common_sequence" align="left" suppress-title="false" pn="figure-1">
          <name slugifiedName="name-common-protocol-flow-sequen">Common Protocol Flow Sequence Diagram</name>
          <artwork align="center" type="call-flow" pn="section-2.3-2.1">
Client                Mechanism Endpoint      Resource Server
|                             |                             | 
|-- request URI -------------------------------------------&gt;| 
|&lt;------------------------------ 401 Bearer nonce, scope, --| 
|                             |      endpoints              | 
|determine compatibility,     |                             | 
|prepare token request        |                             | 
|-- POST token request-------&gt;|                             | 
|                             |validate request,            | 
|                             |issue token                  | 
|&lt;--------- Common Response --|                             | 
|                             |                             | 
|                                                           | 
|-- request URI with access_token -------------------------&gt;| 
|                                validate &amp; translate token,|
|                                      apply access controls|
|                                                           | 
|&lt;--------------------------------------- answer resource --|

</artwork>
        </figure>
        <t pn="section-2.3-3">Note that the "validate request" step can involve complex operations and
include fetching supplemental information from external sources, depending
on the semantics of the mechanism, scopes, and principal.</t>
      </section>
      <!-- Common Flow -->
</section>
    <!-- General Framework -->

<section anchor="token_pop_mechanism" numbered="true" removeInRFC="false" toc="include" pn="section-3">
      <name slugifiedName="name-proof-of-possession-mechani">Proof-of-Possession Mechanism</name>
      <t pn="section-3-1">The client recognizes the availability of, and its compatibility with,
this mechanism, by recognizing combinations of challenge scopes with
which it is compatible, the presence of the <tt>token_pop_endpoint</tt>, and
control of an appropriate principal having proof-of-possession semantics (for
example, an access token bound to a proof-of-possession key, or a
<xref target="RFC7519" format="default" sectionFormat="of" derivedContent="RFC7519">JSON Web Token (JWT)</xref> with a <tt>cnf</tt> claim
<xref target="RFC7800" format="default" sectionFormat="of" derivedContent="RFC7800"/>) and compatibility with the same combination of
challenge scopes.</t>
      <t pn="section-3-2">The client constructs and signs a
<xref target="proof_token" format="default" sectionFormat="of" derivedContent="Section 3.1"> <em>proof-token</em> </xref>.</t>
      <t pn="section-3-3">The client sends the <em>proof-token</em> to the
<xref target="pop_api" format="default" sectionFormat="of" derivedContent="Section 3.2"> <tt>token_pop_endpoint</tt> API URI with HTTP
<tt>POST</tt> </xref>.  The API endpoint validates the request including the
<em>proof-token</em>, and if appropriate, it responds with a bearer token.</t>
      <section anchor="proof_token" numbered="true" removeInRFC="false" toc="include" pn="section-3.1">
        <name slugifiedName="name-proof-token">Proof Token</name>
        <t pn="section-3.1-1">The <em>proof-token</em> is a <xref target="RFC7519" format="default" sectionFormat="of" derivedContent="RFC7519">JWT</xref>, with a
signature proving possesion of the key bound to the client's principal, and having
the following claims:</t>
        <dl newline="false" spacing="normal" pn="section-3.1-2">
          <dt pn="section-3.1-2.1"><tt>sub</tt></dt>
          <dd pn="section-3.1-2.2">
            <bcp14>REQUIRED</bcp14>: The
		client's principal (having proof-of-possession semantics and
		compatible with a combination of the challenge scopes);</dd>
          <dt pn="section-3.1-2.3"><tt>aud</tt></dt>
          <dd pn="section-3.1-2.4">
            <bcp14>REQUIRED</bcp14>: The absolute URI
		(<xref section="4.3" target="RFC3986" sectionFormat="of" format="default" derivedLink="https://rfc-editor.org/rfc/rfc3986#section-4.3" derivedContent="RFC3986"/>),
		including scheme, authority (host and optional port), path,
		and query, but not including fragment identifier, corresponding
		to the original request that resulted in the HTTP <tt>401</tt>
		challenge; if this claim is an array, it <bcp14>MUST</bcp14>
		have exactly one element;</dd>
          <dt pn="section-3.1-2.5"><tt>nonce</tt></dt>
          <dd pn="section-3.1-2.6">
            <bcp14>REQUIRED</bcp14>: The nonce from
		the <tt>WWW-Authenticate</tt> challenge;</dd>
          <dt pn="section-3.1-2.7"><tt>jti</tt></dt>
          <dd pn="section-3.1-2.8">
            <bcp14>RECOMMENDED</bcp14>: Use of this
		claim is recommended so that the client can salt the
		<em>proof-token</em>'s signature; the verifier can ignore
		this claim, if present;</dd>
          <dt pn="section-3.1-2.9"><tt>exp</tt></dt>
          <dd pn="section-3.1-2.10">
            <bcp14>OPTIONAL</bcp14>: If present, this
		claim <bcp14>MUST NOT</bcp14> be after the expiration time
		of the <tt>sub</tt> (if it has one), and <bcp14>MUST NOT</bcp14> be before the current time on the verifier;
		ordinarily the validity of the nonce is sufficient to establish
		not-before and not-after constraints on the proof, so this
		claim isn't usually necessary (and clocks on end-user devices,
		where <em>proof-tokens</em> are likely to be generated, are
		notoriously inaccurate). The issuer <bcp14>MAY</bcp14> take the
		expiration periods of the <em>proof-token</em> and the
		<tt>sub</tt> into account when determining the expiration
		period of the bearer token it issues, but it is not required
		to do so and is free to issue bearer tokens with any expiration
		period.</dd>
        </dl>
        <t pn="section-3.1-3">Additional claims can appear in the <em>proof-token</em> according to, and
conditioned on, the semantics of the scope(s). Unrecognized or
incompatible claims <bcp14>SHOULD</bcp14> be ignored.</t>
      </section>
      <!-- Proof Token -->

<section anchor="pop_api" numbered="true" removeInRFC="false" toc="include" pn="section-3.2">
        <name slugifiedName="name-proof-of-possession-api">Proof-of-Possession API</name>
        <t pn="section-3.2-1">This API endpoint is implemented by the authorization server
(<xref section="1.1" target="RFC6749" sectionFormat="of" format="default" derivedLink="https://rfc-editor.org/rfc/rfc6749#section-1.1" derivedContent="RFC6749"/>)
for the protection space of the original request.</t>
        <t pn="section-3.2-2">The client uses this API by making an HTTP <tt>POST</tt> request to the
<tt>token_pop_endpoint</tt> URI. The request body has Content-Type
<tt>application/x-www-form-urlencoded</tt> and includes at least the following
parameter:</t>
        <dl newline="false" spacing="normal" pn="section-3.2-3">
          <dt pn="section-3.2-3.1"><tt>proof_token</tt></dt>
          <dd pn="section-3.2-3.2">
            <bcp14>REQUIRED</bcp14>: A
		<xref target="proof_token" format="default" sectionFormat="of" derivedContent="Section 3.1"> <em>proof-token</em> </xref>
		as described above.</dd>
        </dl>
        <t pn="section-3.2-4">Additional parameters can be sent according to, and conditioned on, the
semantics of the scope(s). Unrecognized or incompatible parameters
<bcp14>SHOULD</bcp14> be ignored.</t>
        <t pn="section-3.2-5">The authorization server verifies the request:</t>
        <ol spacing="normal" start="1" type="1" pn="section-3.2-6">
          <li pn="section-3.2-6.1" derivedCounter="1.">Parse the <tt>proof_token</tt> parameter and find its claims;</li>
          <li pn="section-3.2-6.2" derivedCounter="2.">Verify that the <tt>proof_token</tt>'s signature matches the
		proof-of-possession key associated with the <tt>sub</tt>
		claim, and that it hasn't expired;</li>
          <li pn="section-3.2-6.3" derivedCounter="3.">Verify that the <tt>aud</tt> claim is an absolute URI for a
		resource in a protection space for which this endpoint is
		responsible;</li>
          <li pn="section-3.2-6.4" derivedCounter="4.">Verify the <tt>nonce</tt> claim (for example, by confirming that
		it was really issued by this system and not too far in the
		past, that it hasn't been redeemed yet, and that it was issued
		for a request for the <tt>aud</tt> claim);</li>
          <li pn="section-3.2-6.5" derivedCounter="5.">Verify the validity and authenticity of the <tt>sub</tt> claim
		according to its kind and the semantics of the relevant
		scope(s);</li>
          <li pn="section-3.2-6.6" derivedCounter="6.">Perform any other processing, verification, and validation
		appropriate to the relevant scope(s), additional claims, or
		additional parameters.</li>
        </ol>
        <t pn="section-3.2-7">If the request is verified, the authorization server issues a bearer
<tt>access_token</tt> valid for the protection space of the original request
and for a limited time.  The authorization server responds using the common
response format
(<xref target="common_response" format="default" sectionFormat="of" derivedContent="Section 2.2"/>).</t>
      </section>
      <!-- POP API -->

<section anchor="token_pop_example" numbered="true" removeInRFC="false" toc="include" pn="section-3.3">
        <name slugifiedName="name-proof-of-possession-example">Proof-of-Possession Example</name>
        <t pn="section-3.3-1">Note: This section is not normative.</t>
        <t pn="section-3.3-2">A client (for example, an in-browser application working on behalf of a
user) attempts an HTTP request to a resource server for an access-restricted
URI initially without presenting any special credentials:</t>
        <sourcecode markers="false" pn="section-3.3-3">
GET /some/restricted/resource HTTP/1.1
Host: www.example
Origin: https://app.example

</sourcecode>
        <t pn="section-3.3-4">The resource server does not allow this request without authorization. It
generates an unguessable, opaque nonce that the server will be able to later
recognize as having generated. The server responds with an HTTP <tt>401</tt>
Unauthorized message, and includes the protection space identifier (realm),
the nonce, the appropriate scopes, and at least the <tt>token_pop_endpoint</tt>
in the <tt>WWW-Authenticate</tt> response header with the <tt>Bearer</tt>
method.  The server also includes an HTML response body to allow the user to
perform a first-party login using another method, for cases where the resource
was navigated to directly in the browser:</t>
        <sourcecode markers="false" pn="section-3.3-5">
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="/auth/",
  scope="webid openid",
  nonce="j16C4SOLQWFor3VYUtZWnrUr5AG5uwDF7q9RFsDk",
  token_pop_endpoint="/auth/webid-pop",
  client_cert_endpoint="https://webid-tls.example/auth/webid-tls"
Access-Control-Allow-Origin: https://app.example
Access-Control-Expose-Headers: WWW-Authenticate
Date: Mon,  6 May 2019 01:48:48 GMT
Content-type: text/html

&lt;html&gt;Human first-party login page...&lt;/html&gt;
</sourcecode>
        <t pn="section-3.3-6">The client recognizes the response as compatible with this mechanism by
recognizing the scheme as <tt>Bearer</tt>, compatible scopes (in this example,
<tt>openid</tt> and <tt>webid</tt>), and the presence of the <tt>nonce</tt>
and the <tt>token_pop_endpoint</tt>.</t>
        <t pn="section-3.3-7">The client controls a principal appropriate to the scopes (in this example,
a JWT substantially similar to an
<xref target="OpenID.Core" format="default" sectionFormat="of" derivedContent="OpenID.Core">OpenID Connect ID Token</xref>
and containing a <xref target="RFC7800" format="default" sectionFormat="of" derivedContent="RFC7800">confirmation key</xref>) and determines
to use the proof-of-possession mechanism.</t>
        <t pn="section-3.3-8">The client creates a new <em>proof-token</em> JWT as described above
(<xref target="proof_token" format="default" sectionFormat="of" derivedContent="Section 3.1"/>), setting its <tt>aud</tt> claim to the absolute
URI of the original request, the <tt>nonce</tt> claim to the <tt>nonce</tt>
parameter from the <tt>WWW-Authenticate</tt> response header, the <tt>sub</tt>
claim to its ID Token, includes other claims as appropriate to the scopes
(<tt>iss</tt> in this example), and signs this <em>proof-token</em> with the
proof-of-possession key bound to its principal and with a signing algorithm
compatible with the signing key and the scopes:</t>
        <sourcecode type="json" markers="false" pn="section-3.3-9">
{
  "typ": "JWT",
  "alg": "RS256"
}
.
{
  "sub": "eyJhbGciOiJ...",
  "aud": "https://www.example/some/restricted/resource",
  "nonce": "j16C4SOLQWFor3VYUtZWnrUr5AG5uwDF7q9RFsDk",
  "jti": "1C49A92C-C260-4F76-9D7B-E81AE13037B8",
  "iss": "https://app.example/oauth/code"
}
.
RS256-signature-here
</sourcecode>
        <t pn="section-3.3-10">The client sends a request to the <tt>token_pop_endpoint</tt> URI and
includes the <em>proof-token</em>:</t>
        <sourcecode markers="false" pn="section-3.3-11">
POST /auth/webid-pop
Host: www.example
Origin: https://app.example
Content-type: application/x-www-form-urlencoded

proof_token=eyJ0eXAiOiJKV1QiCg...
</sourcecode>
        <t pn="section-3.3-12">The <tt>token_pop_endpoint</tt> verifies the request as described in
<xref target="pop_api" format="default" sectionFormat="of" derivedContent="Section 3.2"/>, determines that the request is good, and issues a
bearer token:</t>
        <sourcecode markers="false" pn="section-3.3-13">
HTTP/1.1 200
Content-type: application/json; charset=utf-8
Cache-control: no-cache, no-store
Pragma: no-cache
Access-Control-Allow-Origin: https://app.example
Date: Mon,  6 May 2019 01:48:50 GMT

{
  "access_token": "RPAOmgrWb5wD7DzloDjZ7Ain",
  "expires_in": 1800,
  "token_type": "Bearer"
}
</sourcecode>
        <t pn="section-3.3-14">The client can now use the <tt>access_token</tt> in an <tt>Authorization</tt>
header for requests to resources in the same protection space as the original
request until the access token expires or is revoked:</t>
        <sourcecode markers="false" pn="section-3.3-15">
GET /some/restricted/resource HTTP/1.1
Host: www.example
Origin: https://app.example
Authorization: Bearer RPAOmgrWb5wD7DzloDjZ7Ain

</sourcecode>
        <t pn="section-3.3-16">The server validates and translates the bearer token in its
implementation-specific way, and makes a determination whether to grant the
requested access.</t>
      </section>
      <!-- POP Example -->
</section>
    <!-- Proof-of-Possession -->

<section anchor="client_cert_mechanism" numbered="true" removeInRFC="false" toc="include" pn="section-4">
      <name slugifiedName="name-tls-client-certificate-mech">TLS Client Certificate Mechanism</name>
      <t pn="section-4-1">The client recognizes the availability of, and its compatibility with,
this mechanism, by recognizing combinations of challenge scopes with which
it is compatible, the presence of the <tt>client_cert_endpoint</tt> and the
<tt>nonce</tt>, and either direct control of an appropriate
<xref target="RFC8446" format="default" sectionFormat="of" derivedContent="RFC8446">TLS</xref> client certificate and its signing key, or
in the case of browser-based Javascript applications, an assumption that such
a certificate is configured into the browser and that it will be selected by
the user.</t>
      <t pn="section-4-2">The client constructs and sends a token request to the
<xref target="client_cert_api" format="default" sectionFormat="of" derivedContent="Section 4.1"> <tt>client_cert_endpoint</tt> API URI with
HTTP <tt>POST</tt></xref>, using its TLS client certificate.</t>
      <t pn="section-4-3">The API endpoint validates the request, including aspects of the client
certificate, and if appropriate, it responds with a bearer token.</t>
      <section anchor="client_cert_api" numbered="true" removeInRFC="false" toc="include" pn="section-4.1">
        <name slugifiedName="name-client-certificate-api">Client Certificate API</name>
        <t pn="section-4.1-1">This API endpoint is implemented by the authorization server for the
protection space of the original request.</t>
        <t pn="section-4.1-2">The client uses this API by making an HTTP <tt>POST</tt> request to the
<tt>client_cert_endpoint</tt> URI.  The request body has Content-Type
<tt>application/x-www-form-urlencoded</tt> and includes at least the following
parameters:</t>
        <dl newline="false" spacing="normal" pn="section-4.1-3">
          <dt pn="section-4.1-3.1"><tt>uri</tt></dt>
          <dd pn="section-4.1-3.2">
            <bcp14>REQUIRED</bcp14>: The absolute URI,
		including scheme, authority (host and optional port), path,
		and query, but not including fragment identifier, corresponding
		to the original request that resulted in the HTTP <tt>401</tt>
		response;</dd>
          <dt pn="section-4.1-3.3"><tt>nonce</tt></dt>
          <dd pn="section-4.1-3.4">
            <bcp14>REQUIRED</bcp14>: The nonce from
		the <tt>WWW-Authenticate</tt> challenge.</dd>
        </dl>
        <t pn="section-4.1-4">Additional parameters can be sent according to, and conditioned on, the
semantics of the scope(s). Unrecognized or incompatible parameters
<bcp14>SHOULD</bcp14> be ignored.</t>
        <t pn="section-4.1-5">A TLS client certificate is <bcp14>REQUIRED</bcp14> when communicating
with this API endpoint.  That means the origin of this API endpoint will
probably be different from that of the original request URI so that the server
can request a client certificate in a distinct TLS connection handshake
(<xref section="4.3.2" target="RFC8446" sectionFormat="of" format="default" derivedLink="https://rfc-editor.org/rfc/rfc8446#section-4.3.2" derivedContent="RFC8446"/>).</t>
        <t pn="section-4.1-6">The authorization server verifies the request:</t>
        <ol spacing="normal" start="1" type="1" pn="section-4.1-7">
          <li pn="section-4.1-7.1" derivedCounter="1.">Verify that <tt>uri</tt> is an absolute URI and is in a protection
		space for which this endpoint is responsible;</li>
          <li pn="section-4.1-7.2" derivedCounter="2.">Verify the <tt>nonce</tt> (for example, confirming that it was
		really generated by this system, not too far in the past,
		that it hasn't been redeemed yet, and if possible that it
		corresponds to a request for <tt>uri</tt>);</li>
          <li pn="section-4.1-7.3" derivedCounter="3.">Verify the validity and authenticity of the client certificate
		(beyond those validations required for the TLS connection)
		according to the semantics of the relevant scope(s);</li>
          <li pn="section-4.1-7.4" derivedCounter="4.">Perform any other processing, verification, and validation
		appropriate to the relevant scope(s) or additional parameters.</li>
        </ol>
        <t pn="section-4.1-8">If the request is acceptable, the authorization server issues a bearer
<tt>access_token</tt> valid for the protection space of the original request
and for a limited time. The authorization server responds using the
<xref target="common_response" format="default" sectionFormat="of" derivedContent="Section 2.2">common response format</xref>.</t>
      </section>
      <!-- cert API -->

<section numbered="true" removeInRFC="false" toc="include" pn="section-4.2">
        <name slugifiedName="name-client-certificate-example">Client Certificate Example</name>
        <t pn="section-4.2-1">Note: This section is not normative.</t>
        <t pn="section-4.2-2">A client (for example, an in-browser application working on behalf of a
user) attempts an HTTP request to a resource server for an access-restricted
URI initially without presenting any special credentials:</t>
        <sourcecode markers="false" pn="section-4.2-3">
GET /some/restricted/resource HTTP/1.1
Host: www.example
Origin: https://app.example

</sourcecode>
        <t pn="section-4.2-4">The resource server does not allow this request without authorization. It
generates an unguessable, opaque nonce that the authorization server will be
able to later recognize as having generated. The server responds with an HTTP
<tt>401</tt> Unauthorized message, and includes the protection space identifier
(realm), the nonce, the appropriate scopes, and at least the
<tt>client_cert_endpoint</tt> in the <tt>WWW-Authenticate</tt> response header
with the <tt>Bearer</tt> method.  The server also includes an HTML response
body to allow the user to perform a first-party login using another method,
for cases where the resource was navigated to directly in the browser:</t>
        <sourcecode markers="false" pn="section-4.2-5">
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="/auth/",
  scope="webid openid",
  nonce="j16C4SOLQWFor3VYUtZWnrUr5AG5uwDF7q9RFsDk",
  token_pop_endpoint="/auth/webid-pop",
  client_cert_endpoint="https://webid-tls.example/auth/webid-tls"
Access-Control-Allow-Origin: https://app.example
Access-Control-Expose-Headers: WWW-Authenticate
Date: Mon,  6 May 2019 01:48:48 GMT
Content-type: text/html

&lt;html&gt;Human first-party login page...&lt;/html&gt;
</sourcecode>
        <t pn="section-4.2-6">The client recognizes the response as compatible with this mechanism by
recognizing the scheme as <tt>Bearer</tt>, compatible scopes (in this example,
<tt>webid</tt>), and the presence of the <tt>nonce</tt> and the
<tt>client_cert_endpoint</tt>.</t>
        <t pn="section-4.2-7">The client determines to use the client certificate mechanism (for example,
by being configured by the user to do so when available, with the assumption
the user will choose an appropriate certificate when prompted by the browser).</t>
        <t pn="section-4.2-8">The client sends, using its TLS client certificate, a token request to the
<tt>client_cert_endpoint</tt> URI and includes the required parameters:</t>
        <sourcecode markers="false" pn="section-4.2-9">
POST /auth/webid-tls HTTP/1.1
Host: webid-tls.example
Origin: https://app.example
Content-type: application/x-www-form-urlencoded

uri=https://www.example/some/restricted/resource
&amp;nonce=j16C4SOLQWFor3VYUtZWnrUr5AG5uwDF7q9RFsDk
</sourcecode>
        <t pn="section-4.2-10">The <tt>client_cert_endpoint</tt> verifies the request as described in
<xref target="client_cert_api" format="default" sectionFormat="of" derivedContent="Section 4.1"/> (in this example, with scope <tt>webid</tt>,
the validation and processing steps further comprise establishing and validating
the user's WebID according to <xref target="WebID-TLS" format="default" sectionFormat="of" derivedContent="WebID-TLS"/>).  The endpoint
determines that the request is good, and issues a bearer token:</t>
        <sourcecode markers="false" pn="section-4.2-11">
HTTP/1.1 200
Content-type: application/json; charset=utf-8
Cache-control: no-cache, no-store
Pragma: no-cache
Access-Control-Allow-Origin: https://app.example
Date: Mon,  6 May 2019 01:48:50 GMT

{
  "access_token": "RPAOmgrWb5wD7DzloDjZ7Ain",
  "expires_in": 1800,
  "token_type": "Bearer"
}
</sourcecode>
        <t pn="section-4.2-12">The client can now use the <tt>access_token</tt> in an <tt>Authorization</tt>
header for requests to resources in the same protection space as the original
request until the bearer token expires or is revoked:</t>
        <sourcecode markers="false" pn="section-4.2-13">
GET /some/restricted/resource HTTP/1.1
Host: www.example
Origin: https://app.example
Authorization: Bearer RPAOmgrWb5wD7DzloDjZ7Ain

</sourcecode>
        <t pn="section-4.2-14">The server validates and translates the bearer token in its
implementation-specific way, and makes a determination whether to grant the
requested access.</t>
      </section>
      <!-- client cert example -->
</section>
    <!-- TLS Client Certificate -->

<section numbered="true" removeInRFC="false" toc="include" pn="section-5">
      <name slugifiedName="name-iana-considerations">IANA Considerations</name>
      <t pn="section-5-1">TBD. Mechanism parameters "token_pop_endpoint" and "client_cert_endpoint" for auth-scheme "Bearer".</t>
    </section>
    <!-- IANA -->

<section numbered="true" removeInRFC="false" toc="include" pn="section-6">
      <name slugifiedName="name-security-considerations">Security Considerations</name>
      <t pn="section-6-1">When using the
<xref target="token_pop_mechanism" format="default" sectionFormat="of" derivedContent="Section 3">Proof-of-Possession mechanism</xref>, the
scope designer should carefully consider whether additional information should
go in the <em>proof-token</em> (which would therefore be signed) or can be
<tt>POST</tt> parameters (which would not be signed). The safe choice (which
therefore <bcp14>SHOULD</bcp14> be the default) is to include any additional
information in the <em>proof-token</em>.</t>
      <t pn="section-6-2">Bearer tokens can be shared freely with other parties by an application.
Therefore, a bearer token obtained with the
<xref target="client_cert_mechanism" format="default" sectionFormat="of" derivedContent="Section 4">TLS Client Certificate mechanism</xref>
        <bcp14>MUST NOT</bcp14> be construed to carry the same weight when authenticating
an HTTP request as if the client used the corresponding client certificate
for the request's connection. However, particularly for browser-based
applications where the application and the resource server(s) are not associated
with each other, the user typically doesn't audit the data being sent in HTTP
requests (even when a client certificate is used), so the portion of the
application running in the browser could be receiving data from anywhere else
and sending it over HTTP using the user's client certificate anyway.</t>
      <t pn="section-6-3">Security considerations specific to challenge scopes are beyond the purview
of this memo.</t>
    </section>
    <!-- Security Considerations -->

</middle>
  <back>
    <references pn="section-7">
      <name slugifiedName="name-references">References</name>
      <references pn="section-7.1">
        <name slugifiedName="name-normative-references">Normative References</name>
        <reference anchor="RFC2119" target="https://www.rfc-editor.org/info/rfc2119" xml:base="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.2119.xml" quoteTitle="true" derivedAnchor="RFC2119">
          <front>
            <title>Key words for use in RFCs to Indicate Requirement Levels</title>
            <author initials="S." surname="Bradner" fullname="S. Bradner">
              <organization showOnFrontPage="true"/>
            </author>
            <date year="1997" month="March"/>
            <abstract>
              <t>In many standards track documents several words are used to signify the requirements in the specification.  These words are often capitalized. This document defines these words as they should be interpreted in IETF documents.  This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements.</t>
            </abstract>
          </front>
          <seriesInfo name="BCP" value="14"/>
          <seriesInfo name="RFC" value="2119"/>
          <seriesInfo name="DOI" value="10.17487/RFC2119"/>
        </reference>
        <!-- BCP14 -->
		<reference anchor="RFC3986" target="https://www.rfc-editor.org/info/rfc3986" xml:base="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.3986.xml" quoteTitle="true" derivedAnchor="RFC3986">
          <front>
            <title>Uniform Resource Identifier (URI): Generic Syntax</title>
            <author initials="T." surname="Berners-Lee" fullname="T. Berners-Lee">
              <organization showOnFrontPage="true"/>
            </author>
            <author initials="R." surname="Fielding" fullname="R. Fielding">
              <organization showOnFrontPage="true"/>
            </author>
            <author initials="L." surname="Masinter" fullname="L. Masinter">
              <organization showOnFrontPage="true"/>
            </author>
            <date year="2005" month="January"/>
            <abstract>
              <t>A Uniform Resource Identifier (URI) is a compact sequence of characters that identifies an abstract or physical resource.  This specification defines the generic URI syntax and a process for resolving URI references that might be in relative form, along with guidelines and security considerations for the use of URIs on the Internet.  The URI syntax defines a grammar that is a superset of all valid URIs, allowing an implementation to parse the common components of a URI reference without knowing the scheme-specific requirements of every possible identifier.  This specification does not define a generative grammar for URIs; that task is performed by the individual specifications of each URI scheme.  [STANDARDS-TRACK]</t>
            </abstract>
          </front>
          <seriesInfo name="STD" value="66"/>
          <seriesInfo name="RFC" value="3986"/>
          <seriesInfo name="DOI" value="10.17487/RFC3986"/>
        </reference>
        <!-- URI syntax -->
		<reference anchor="RFC6749" target="https://www.rfc-editor.org/info/rfc6749" xml:base="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.6749.xml" quoteTitle="true" derivedAnchor="RFC6749">
          <front>
            <title>The OAuth 2.0 Authorization Framework</title>
            <author initials="D." surname="Hardt" fullname="D. Hardt" role="editor">
              <organization showOnFrontPage="true"/>
            </author>
            <date year="2012" month="October"/>
            <abstract>
              <t>The OAuth 2.0 authorization framework enables a third-party application to obtain limited access to an HTTP service, either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and the HTTP service, or by allowing the third-party application to obtain access on its own behalf.  This specification replaces and obsoletes the OAuth 1.0 protocol described in RFC 5849.  [STANDARDS-TRACK]</t>
            </abstract>
          </front>
          <seriesInfo name="RFC" value="6749"/>
          <seriesInfo name="DOI" value="10.17487/RFC6749"/>
        </reference>
        <!-- OAuth framework -->
		<reference anchor="RFC6750" target="https://www.rfc-editor.org/info/rfc6750" xml:base="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.6750.xml" quoteTitle="true" derivedAnchor="RFC6750">
          <front>
            <title>The OAuth 2.0 Authorization Framework: Bearer Token Usage</title>
            <author initials="M." surname="Jones" fullname="M. Jones">
              <organization showOnFrontPage="true"/>
            </author>
            <author initials="D." surname="Hardt" fullname="D. Hardt">
              <organization showOnFrontPage="true"/>
            </author>
            <date year="2012" month="October"/>
            <abstract>
              <t>This specification describes how to use bearer tokens in HTTP requests to access OAuth 2.0 protected resources.  Any party in possession of a bearer token (a "bearer") can use it to get access to the associated resources (without demonstrating possession of a cryptographic key).  To prevent misuse, bearer tokens need to be protected from disclosure in storage and in transport.   [STANDARDS-TRACK]</t>
            </abstract>
          </front>
          <seriesInfo name="RFC" value="6750"/>
          <seriesInfo name="DOI" value="10.17487/RFC6750"/>
        </reference>
        <!-- Bearer tokens -->
		<reference anchor="RFC7235" target="https://www.rfc-editor.org/info/rfc7235" xml:base="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.7235.xml" quoteTitle="true" derivedAnchor="RFC7235">
          <front>
            <title>Hypertext Transfer Protocol (HTTP/1.1): Authentication</title>
            <author initials="R." surname="Fielding" fullname="R. Fielding" role="editor">
              <organization showOnFrontPage="true"/>
            </author>
            <author initials="J." surname="Reschke" fullname="J. Reschke" role="editor">
              <organization showOnFrontPage="true"/>
            </author>
            <date year="2014" month="June"/>
            <abstract>
              <t>The Hypertext Transfer Protocol (HTTP) is a stateless application- level protocol for distributed, collaborative, hypermedia information systems.  This document defines the HTTP Authentication framework.</t>
            </abstract>
          </front>
          <seriesInfo name="RFC" value="7235"/>
          <seriesInfo name="DOI" value="10.17487/RFC7235"/>
        </reference>
        <!-- HTTP Auth -->
		<reference anchor="RFC7519" target="https://www.rfc-editor.org/info/rfc7519" xml:base="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.7519.xml" quoteTitle="true" derivedAnchor="RFC7519">
          <front>
            <title>JSON Web Token (JWT)</title>
            <author initials="M." surname="Jones" fullname="M. Jones">
              <organization showOnFrontPage="true"/>
            </author>
            <author initials="J." surname="Bradley" fullname="J. Bradley">
              <organization showOnFrontPage="true"/>
            </author>
            <author initials="N." surname="Sakimura" fullname="N. Sakimura">
              <organization showOnFrontPage="true"/>
            </author>
            <date year="2015" month="May"/>
            <abstract>
              <t>JSON Web Token (JWT) is a compact, URL-safe means of representing claims to be transferred between two parties.  The claims in a JWT are encoded as a JSON object that is used as the payload of a JSON Web Signature (JWS) structure or as the plaintext of a JSON Web Encryption (JWE) structure, enabling the claims to be digitally signed or integrity protected with a Message Authentication Code (MAC) and/or encrypted.</t>
            </abstract>
          </front>
          <seriesInfo name="RFC" value="7519"/>
          <seriesInfo name="DOI" value="10.17487/RFC7519"/>
        </reference>
        <!-- JWT -->
		<reference anchor="RFC8174" target="https://www.rfc-editor.org/info/rfc8174" xml:base="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.8174.xml" quoteTitle="true" derivedAnchor="RFC8174">
          <front>
            <title>Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words</title>
            <author initials="B." surname="Leiba" fullname="B. Leiba">
              <organization showOnFrontPage="true"/>
            </author>
            <date year="2017" month="May"/>
            <abstract>
              <t>RFC 2119 specifies common key words that may be used in protocol  specifications.  This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the  defined special meanings.</t>
            </abstract>
          </front>
          <seriesInfo name="BCP" value="14"/>
          <seriesInfo name="RFC" value="8174"/>
          <seriesInfo name="DOI" value="10.17487/RFC8174"/>
        </reference>
        <!-- BCP14 -->
		<reference anchor="RFC8259" target="https://www.rfc-editor.org/info/rfc8259" xml:base="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.8259.xml" quoteTitle="true" derivedAnchor="RFC8259">
          <front>
            <title>The JavaScript Object Notation (JSON) Data Interchange Format</title>
            <author initials="T." surname="Bray" fullname="T. Bray" role="editor">
              <organization showOnFrontPage="true"/>
            </author>
            <date year="2017" month="December"/>
            <abstract>
              <t>JavaScript Object Notation (JSON) is a lightweight, text-based, language-independent data interchange format.  It was derived from the ECMAScript Programming Language Standard.  JSON defines a small set of formatting rules for the portable representation of structured data.</t>
              <t>This document removes inconsistencies with other specifications of JSON, repairs specification errors, and offers experience-based interoperability guidance.</t>
            </abstract>
          </front>
          <seriesInfo name="STD" value="90"/>
          <seriesInfo name="RFC" value="8259"/>
          <seriesInfo name="DOI" value="10.17487/RFC8259"/>
        </reference>
        <!-- JSON -->

	</references>
      <references pn="section-7.2">
        <name slugifiedName="name-informative-references">Informative References</name>
        <reference anchor="DID" target="https://www.w3.org/TR/did-core/" quoteTitle="true" derivedAnchor="DID">
          <front>
            <title>Decentralized Identifiers (DIDs) v1.0</title>
            <author initials="D." surname="Reed"/>
            <author initials="M." surname="Sporny"/>
            <author initials="D." surname="Longley"/>
            <author initials="C." surname="Allen"/>
            <author initials="R." surname="Grant"/>
            <author initials="M." surname="Sabadello"/>
            <date month="April" year="2020"/>
          </front>
        </reference>
        <reference anchor="RFC7541" target="https://www.rfc-editor.org/info/rfc7541" xml:base="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.7541.xml" quoteTitle="true" derivedAnchor="RFC7541">
          <front>
            <title>HPACK: Header Compression for HTTP/2</title>
            <author initials="R." surname="Peon" fullname="R. Peon">
              <organization showOnFrontPage="true"/>
            </author>
            <author initials="H." surname="Ruellan" fullname="H. Ruellan">
              <organization showOnFrontPage="true"/>
            </author>
            <date year="2015" month="May"/>
            <abstract>
              <t>This specification defines HPACK, a compression format for efficiently representing HTTP header fields, to be used in HTTP/2.</t>
            </abstract>
          </front>
          <seriesInfo name="RFC" value="7541"/>
          <seriesInfo name="DOI" value="10.17487/RFC7541"/>
        </reference>
        <!-- HPACK -->
		<reference anchor="RFC7800" target="https://www.rfc-editor.org/info/rfc7800" xml:base="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.7800.xml" quoteTitle="true" derivedAnchor="RFC7800">
          <front>
            <title>Proof-of-Possession Key Semantics for JSON Web Tokens (JWTs)</title>
            <author initials="M." surname="Jones" fullname="M. Jones">
              <organization showOnFrontPage="true"/>
            </author>
            <author initials="J." surname="Bradley" fullname="J. Bradley">
              <organization showOnFrontPage="true"/>
            </author>
            <author initials="H." surname="Tschofenig" fullname="H. Tschofenig">
              <organization showOnFrontPage="true"/>
            </author>
            <date year="2016" month="April"/>
            <abstract>
              <t>This specification describes how to declare in a JSON Web Token (JWT) that the presenter of the JWT possesses a particular proof-of- possession key and how the recipient can cryptographically confirm proof of possession of the key by the presenter.  Being able to prove possession of a key is also sometimes described as the presenter being a holder-of-key.</t>
            </abstract>
          </front>
          <seriesInfo name="RFC" value="7800"/>
          <seriesInfo name="DOI" value="10.17487/RFC7800"/>
        </reference>
        <!-- POP Token -->
		<reference anchor="RFC8446" target="https://www.rfc-editor.org/info/rfc8446" xml:base="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.8446.xml" quoteTitle="true" derivedAnchor="RFC8446">
          <front>
            <title>The Transport Layer Security (TLS) Protocol Version 1.3</title>
            <author initials="E." surname="Rescorla" fullname="E. Rescorla">
              <organization showOnFrontPage="true"/>
            </author>
            <date year="2018" month="August"/>
            <abstract>
              <t>This document specifies version 1.3 of the Transport Layer Security (TLS) protocol.  TLS allows client/server applications to communicate over the Internet in a way that is designed to prevent eavesdropping, tampering, and message forgery.</t>
              <t>This document updates RFCs 5705 and 6066, and obsoletes RFCs 5077, 5246, and 6961.  This document also specifies new requirements for TLS 1.2 implementations.</t>
            </abstract>
          </front>
          <seriesInfo name="RFC" value="8446"/>
          <seriesInfo name="DOI" value="10.17487/RFC8446"/>
        </reference>
        <!-- TLS -->

		<reference anchor="OpenID.Core" target="https://openid.net/specs/openid-connect-core-1_0.html" quoteTitle="true" derivedAnchor="OpenID.Core">
          <front>
            <title>OpenID Connect Core 1.0</title>
            <author initials="N." surname="Sakimura"/>
            <author initials="J." surname="Bradley"/>
            <author initials="M." surname="Jones"/>
            <author initials="B." surname="de Medeiros"/>
            <author initials="C." surname="Mortimore"/>
            <date month="November" year="2014"/>
          </front>
        </reference>
        <reference anchor="VC" target="https://www.w3.org/TR/vc-data-model/" quoteTitle="true" derivedAnchor="VC">
          <front>
            <title>Verifiable Credentials Data Model 1.0</title>
            <author initials="M." surname="Sporny"/>
            <author initials="D." surname="Longley"/>
            <author initials="D." surname="Chadwick"/>
            <author initials="G." surname="Noble" role="editor"/>
            <author initials="D." surname="Burnett" role="editor"/>
            <author initials="B." surname="Zundel" role="editor"/>
            <date month="November" year="2019"/>
          </front>
        </reference>
        <reference anchor="WebID" target="https://www.w3.org/2005/Incubator/webid/spec/identity/" quoteTitle="true" derivedAnchor="WebID">
          <front>
            <title>WebID 1.0: Web Identity and Discovery</title>
            <author initials="A." surname="Sambra"/>
            <author initials="H." surname="Story"/>
            <author initials="T." surname="Berners-Lee"/>
            <author initials="S." surname="Corlosquet" role="editor"/>
            <date month="March" year="2014"/>
          </front>
        </reference>
        <reference anchor="WebID-TLS" target="https://www.w3.org/2005/Incubator/webid/spec/tls/" quoteTitle="true" derivedAnchor="WebID-TLS">
          <front>
            <title>WebID Authentication over TLS</title>
            <author initials="T." surname="Inkster"/>
            <author initials="H." surname="Story"/>
            <author initials="B." surname="Harbulot"/>
            <author initials="S." surname="Corlosquet" role="editor"/>
            <author initials="A." surname="Sambra" role="editor"/>
            <date month="March" year="2014"/>
          </front>
        </reference>
      </references>
    </references>
    <section anchor="authors-addresses" numbered="false" removeInRFC="false" toc="include" pn="section-appendix.a">
      <name slugifiedName="name-authors-address">Author's Address</name>
      <author initials="M" surname="Thornburgh" fullname="Michael C. Thornburgh">
        <address>
          <postal>
            <city>Santa Cruz</city>
            <region>CA</region>
            <code>95060-1950</code>
            <country>US</country>
          </postal>
          <email>zenomt@zenomt.com</email>
          <uri>https://zenomt.zenomt.com/card.ttl#me</uri>
        </address>
      </author>
    </section>
  </back>
</rfc>
