Ignore:
Timestamp:
Jul 8, 2012, 11:15:03 AM (8 years ago)
Author:
julian.reschke@…
Message:

Work-in-progress: hyperlink header field definitions, plus minor editorial improvements (P2)

File:
1 edited

Legend:

Unmodified
Added
Removed
  • draft-ietf-httpbis/latest/p7-auth.html

    r1736 r1740  
    648648         mechanisms, except in cases where it has direct impact on security. This is because different uses of the protocol require
    649649         different error handling strategies; for example, a Web browser might wish to transparently recover from a response where
    650          the Location header field doesn't parse according to the ABNF, whereby in a systems control protocol using HTTP, this type
    651          of error recovery could lead to dangerous consequences.
     650         the <a href="p2-semantics.html#header.location" class="smpl">Location</a> header field doesn't parse according to the ABNF, whereby in a systems control protocol using HTTP, this type of error recovery
     651         could lead to dangerous consequences.
    652652      </p>
    653653      <h2 id="rfc.section.1.2"><a href="#rfc.section.1.2">1.2</a>&nbsp;<a id="notation" href="#notation">Syntax Notation</a></h2>
     
    683683         with or without padding, but excluding whitespace (<a href="#RFC4648" id="rfc.xref.RFC4648.1"><cite title="The Base16, Base32, and Base64 Data Encodings">[RFC4648]</cite></a>).
    684684      </p>
    685       <p id="rfc.section.2.1.p.5">The <a href="#status.401" class="smpl">401 (Unauthorized)</a> response message is used by an origin server to challenge the authorization of a user agent. This response <em class="bcp14">MUST</em> include a WWW-Authenticate header field containing at least one challenge applicable to the requested resource.
    686       </p>
    687       <p id="rfc.section.2.1.p.6">The <a href="#status.407" class="smpl">407 (Proxy Authentication Required)</a> response message is used by a proxy to challenge the authorization of a client and <em class="bcp14">MUST</em> include a Proxy-Authenticate header field containing at least one challenge applicable to the proxy for the requested resource.
     685      <p id="rfc.section.2.1.p.5">The <a href="#status.401" class="smpl">401 (Unauthorized)</a> response message is used by an origin server to challenge the authorization of a user agent. This response <em class="bcp14">MUST</em> include a <a href="#header.www-authenticate" class="smpl">WWW-Authenticate</a> header field containing at least one challenge applicable to the requested resource.
     686      </p>
     687      <p id="rfc.section.2.1.p.6">The <a href="#status.407" class="smpl">407 (Proxy Authentication Required)</a> response message is used by a proxy to challenge the authorization of a client and <em class="bcp14">MUST</em> include a <a href="#header.proxy-authenticate" class="smpl">Proxy-Authenticate</a> header field containing at least one challenge applicable to the proxy for the requested resource.
    688688      </p>
    689689      <div id="rfc.figure.u.3"></div><pre class="inline"><span id="rfc.iref.c.1"></span><span id="rfc.iref.g.4"></span>  <a href="#challenge.and.response" class="smpl">challenge</a>   = <a href="#challenge.and.response" class="smpl">auth-scheme</a> [ 1*<a href="#notation" class="smpl">SP</a> ( <a href="#challenge.and.response" class="smpl">b64token</a> / #<a href="#challenge.and.response" class="smpl">auth-param</a> ) ]
    690690</pre><div class="note" id="rfc.section.2.1.p.8">
    691          <p> <b>Note:</b> User agents will need to take special care in parsing the WWW-Authenticate and Proxy-Authenticate header field values because
    692             they can contain more than one challenge, or if more than one of each is provided, since the contents of a challenge can itself
    693             contain a comma-separated list of authentication parameters.
     691         <p> <b>Note:</b> User agents will need to take special care in parsing the <a href="#header.www-authenticate" class="smpl">WWW-Authenticate</a> and <a href="#header.proxy-authenticate" class="smpl">Proxy-Authenticate</a> header field values because they can contain more than one challenge, or if more than one of each is provided, since the contents
     692            of a challenge can itself contain a comma-separated list of authentication parameters.
    694693         </p>
    695694      </div>
     
    701700      <p id="rfc.section.2.1.p.10">A user agent that wishes to authenticate itself with an origin server — usually, but not necessarily, after receiving a <a href="#status.401" class="smpl">401 (Unauthorized)</a> — can do so by including an <a href="#header.authorization" class="smpl">Authorization</a> header field with the request.
    702701      </p>
    703       <p id="rfc.section.2.1.p.11">A client that wishes to authenticate itself with a proxy — usually, but not necessarily, after receiving a <a href="#status.407" class="smpl">407 (Proxy Authentication Required)</a> — can do so by including a Proxy-Authorization header field with the request.
    704       </p>
    705       <p id="rfc.section.2.1.p.12">Both the <a href="#header.authorization" class="smpl">Authorization</a> field value and the Proxy-Authorization field value contain the client's credentials for the realm of the resource being requested,
    706          based upon a challenge received from the server (possibly at some point in the past). When creating their values, the user
    707          agent ought to do so by selecting the challenge with what it considers to be the most secure auth-scheme that it understands,
    708          obtaining credentials from the user as appropriate.
     702      <p id="rfc.section.2.1.p.11">A client that wishes to authenticate itself with a proxy — usually, but not necessarily, after receiving a <a href="#status.407" class="smpl">407 (Proxy Authentication Required)</a> — can do so by including a <a href="#header.proxy-authorization" class="smpl">Proxy-Authorization</a> header field with the request.
     703      </p>
     704      <p id="rfc.section.2.1.p.12">Both the <a href="#header.authorization" class="smpl">Authorization</a> field value and the <a href="#header.proxy-authorization" class="smpl">Proxy-Authorization</a> field value contain the client's credentials for the realm of the resource being requested, based upon a challenge received
     705         from the server (possibly at some point in the past). When creating their values, the user agent ought to do so by selecting
     706         the challenge with what it considers to be the most secure auth-scheme that it understands, obtaining credentials from the
     707         user as appropriate.
    709708      </p>
    710709      <div id="rfc.figure.u.4"></div><pre class="inline"><span id="rfc.iref.c.2"></span><span id="rfc.iref.g.5"></span>  <a href="#challenge.and.response" class="smpl">credentials</a> = <a href="#challenge.and.response" class="smpl">auth-scheme</a> [ 1*<a href="#notation" class="smpl">SP</a> ( <a href="#challenge.and.response" class="smpl">b64token</a> / #<a href="#challenge.and.response" class="smpl">auth-param</a> ) ]
    711710</pre><p id="rfc.section.2.1.p.14">Upon a request for a protected resource that omits credentials, contains invalid credentials (e.g., a bad password) or partial
    712          credentials (e.g., when the authentication scheme requires more than one round trip), an origin server <em class="bcp14">SHOULD</em> return a <a href="#status.401" class="smpl">401 (Unauthorized)</a> response. Such responses <em class="bcp14">MUST</em> include a WWW-Authenticate header field containing at least one (possibly new) challenge applicable to the requested resource.
     711         credentials (e.g., when the authentication scheme requires more than one round trip), an origin server <em class="bcp14">SHOULD</em> return a <a href="#status.401" class="smpl">401 (Unauthorized)</a> response. Such responses <em class="bcp14">MUST</em> include a <a href="#header.www-authenticate" class="smpl">WWW-Authenticate</a> header field containing at least one (possibly new) challenge applicable to the requested resource.
    713712      </p>
    714713      <p id="rfc.section.2.1.p.15">Likewise, upon a request that requires authentication by proxies that omit credentials or contain invalid or partial credentials,
    715          a proxy <em class="bcp14">SHOULD</em> return a <a href="#status.407" class="smpl">407 (Proxy Authentication Required)</a> response. Such responses <em class="bcp14">MUST</em> include a Proxy-Authenticate header field containing a (possibly new) challenge applicable to the proxy.
     714         a proxy <em class="bcp14">SHOULD</em> return a <a href="#status.407" class="smpl">407 (Proxy Authentication Required)</a> response. Such responses <em class="bcp14">MUST</em> include a <a href="#header.proxy-authenticate" class="smpl">Proxy-Authenticate</a> header field containing a (possibly new) challenge applicable to the proxy.
    716715      </p>
    717716      <p id="rfc.section.2.1.p.16">A server receiving credentials that are valid, but not adequate to gain access, ought to respond with the <a href="p2-semantics.html#status.403" class="smpl">403 (Forbidden)</a> status code (<a href="p2-semantics.html#status.403" title="403 Forbidden">Section 4.6.3</a> of <a href="#Part2" id="rfc.xref.Part2.1"><cite title="HTTP/1.1, part 2: Message Semantics, Payload and Content Negotiation">[Part2]</cite></a>).
     
    721720         authentication information. However, such additional mechanisms are not defined by this specification.
    722721      </p>
    723       <p id="rfc.section.2.1.p.18">Proxies <em class="bcp14">MUST</em> forward the WWW-Authenticate and <a href="#header.authorization" class="smpl">Authorization</a> header fields unmodified and follow the rules found in <a href="#header.authorization" id="rfc.xref.header.authorization.1" title="Authorization">Section&nbsp;4.1</a>.
     722      <p id="rfc.section.2.1.p.18">Proxies <em class="bcp14">MUST</em> forward the <a href="#header.www-authenticate" class="smpl">WWW-Authenticate</a> and <a href="#header.authorization" class="smpl">Authorization</a> header fields unmodified and follow the rules found in <a href="#header.authorization" id="rfc.xref.header.authorization.1" title="Authorization">Section&nbsp;4.1</a>.
    724723      </p>
    725724      <div id="rfc.iref.p.1"></div>
     
    794793         </li>
    795794         <li>
    796             <p>Authentication schemes need to document whether they are usable in origin-server authentication (i.e., using WWW-Authenticate),
    797                and/or proxy authentication (i.e., using Proxy-Authenticate).
     795            <p>Authentication schemes need to document whether they are usable in origin-server authentication (i.e., using <a href="#header.www-authenticate" class="smpl">WWW-Authenticate</a>), and/or proxy authentication (i.e., using <a href="#header.proxy-authenticate" class="smpl">Proxy-Authenticate</a>).
    798796            </p>
    799797         </li>
     
    811809      <div id="rfc.iref.s.1"></div>
    812810      <h2 id="rfc.section.3.1"><a href="#rfc.section.3.1">3.1</a>&nbsp;<a id="status.401" href="#status.401">401 Unauthorized</a></h2>
    813       <p id="rfc.section.3.1.p.1">The request requires user authentication. The response <em class="bcp14">MUST</em> include a WWW-Authenticate header field (<a href="#header.www-authenticate" id="rfc.xref.header.www-authenticate.1" title="WWW-Authenticate">Section&nbsp;4.4</a>) containing a challenge applicable to the target resource. The client <em class="bcp14">MAY</em> repeat the request with a suitable <a href="#header.authorization" class="smpl">Authorization</a> header field (<a href="#header.authorization" id="rfc.xref.header.authorization.2" title="Authorization">Section&nbsp;4.1</a>). If the request already included Authorization credentials, then the 401 response indicates that authorization has been
     811      <p id="rfc.section.3.1.p.1">The request requires user authentication. The response <em class="bcp14">MUST</em> include a <a href="#header.www-authenticate" class="smpl">WWW-Authenticate</a> header field (<a href="#header.www-authenticate" id="rfc.xref.header.www-authenticate.1" title="WWW-Authenticate">Section&nbsp;4.4</a>) containing a challenge applicable to the target resource. The client <em class="bcp14">MAY</em> repeat the request with a suitable <a href="#header.authorization" class="smpl">Authorization</a> header field (<a href="#header.authorization" id="rfc.xref.header.authorization.2" title="Authorization">Section&nbsp;4.1</a>). If the request already included Authorization credentials, then the 401 response indicates that authorization has been
    814812         refused for those credentials. If the 401 response contains the same challenge as the prior response, and the user agent has
    815813         already attempted authentication at least once, then the user <em class="bcp14">SHOULD</em> be presented the representation that was given in the response, since that representation might include relevant diagnostic
     
    819817      <div id="rfc.iref.s.2"></div>
    820818      <h2 id="rfc.section.3.2"><a href="#rfc.section.3.2">3.2</a>&nbsp;<a id="status.407" href="#status.407">407 Proxy Authentication Required</a></h2>
    821       <p id="rfc.section.3.2.p.1">This code is similar to <a href="#status.401" class="smpl">401 (Unauthorized)</a>, but indicates that the client ought to first authenticate itself with the proxy. The proxy <em class="bcp14">MUST</em> return a Proxy-Authenticate header field (<a href="#header.proxy-authenticate" id="rfc.xref.header.proxy-authenticate.1" title="Proxy-Authenticate">Section&nbsp;4.2</a>) containing a challenge applicable to the proxy for the target resource. The client <em class="bcp14">MAY</em> repeat the request with a suitable Proxy-Authorization header field (<a href="#header.proxy-authorization" id="rfc.xref.header.proxy-authorization.1" title="Proxy-Authorization">Section&nbsp;4.3</a>).
     819      <p id="rfc.section.3.2.p.1">This code is similar to <a href="#status.401" class="smpl">401 (Unauthorized)</a>, but indicates that the client ought to first authenticate itself with the proxy. The proxy <em class="bcp14">MUST</em> return a <a href="#header.proxy-authenticate" class="smpl">Proxy-Authenticate</a> header field (<a href="#header.proxy-authenticate" id="rfc.xref.header.proxy-authenticate.1" title="Proxy-Authenticate">Section&nbsp;4.2</a>) containing a challenge applicable to the proxy for the target resource. The client <em class="bcp14">MAY</em> repeat the request with a suitable <a href="#header.proxy-authorization" class="smpl">Proxy-Authorization</a> header field (<a href="#header.proxy-authorization" id="rfc.xref.header.proxy-authorization.1" title="Proxy-Authorization">Section&nbsp;4.3</a>).
    822820      </p>
    823821      <h1 id="rfc.section.4"><a href="#rfc.section.4">4.</a>&nbsp;<a id="header.field.definitions" href="#header.field.definitions">Header Field Definitions</a></h1>
     
    854852      </p>
    855853      <div id="rfc.figure.u.6"></div><pre class="inline"><span id="rfc.iref.g.7"></span>  <a href="#header.proxy-authenticate" class="smpl">Proxy-Authenticate</a> = 1#<a href="#challenge.and.response" class="smpl">challenge</a>
    856 </pre><p id="rfc.section.4.2.p.3">Unlike WWW-Authenticate, the Proxy-Authenticate header field applies only to the current connection, and intermediaries <em class="bcp14">SHOULD NOT</em> forward it to downstream clients. However, an intermediate proxy might need to obtain its own credentials by requesting them
     854</pre><p id="rfc.section.4.2.p.3">Unlike <a href="#header.www-authenticate" class="smpl">WWW-Authenticate</a>, the Proxy-Authenticate header field applies only to the current connection, and intermediaries <em class="bcp14">SHOULD NOT</em> forward it to downstream clients. However, an intermediate proxy might need to obtain its own credentials by requesting them
    857855         from the downstream client, which in some circumstances will appear as if the proxy is forwarding the Proxy-Authenticate header
    858856         field.
    859857      </p>
    860       <p id="rfc.section.4.2.p.4">Note that the parsing considerations for WWW-Authenticate apply to this header field as well; see <a href="#header.www-authenticate" id="rfc.xref.header.www-authenticate.2" title="WWW-Authenticate">Section&nbsp;4.4</a> for details.
     858      <p id="rfc.section.4.2.p.4">Note that the parsing considerations for <a href="#header.www-authenticate" class="smpl">WWW-Authenticate</a> apply to this header field as well; see <a href="#header.www-authenticate" id="rfc.xref.header.www-authenticate.2" title="WWW-Authenticate">Section&nbsp;4.4</a> for details.
    861859      </p>
    862860      <div id="rfc.iref.p.3"></div>
     
    868866      </p>
    869867      <div id="rfc.figure.u.7"></div><pre class="inline"><span id="rfc.iref.g.8"></span>  <a href="#header.proxy-authorization" class="smpl">Proxy-Authorization</a> = <a href="#challenge.and.response" class="smpl">credentials</a>
    870 </pre><p id="rfc.section.4.3.p.3">Unlike <a href="#header.authorization" class="smpl">Authorization</a>, the Proxy-Authorization header field applies only to the next outbound proxy that demanded authentication using the Proxy-Authenticate
    871          field. When multiple proxies are used in a chain, the Proxy-Authorization header field is consumed by the first outbound proxy
     868</pre><p id="rfc.section.4.3.p.3">Unlike <a href="#header.authorization" class="smpl">Authorization</a>, the Proxy-Authorization header field applies only to the next outbound proxy that demanded authentication using the <a href="#header.proxy-authenticate" class="smpl">Proxy-Authenticate</a> field. When multiple proxies are used in a chain, the Proxy-Authorization header field is consumed by the first outbound proxy
    872869         that was expecting to receive credentials. A proxy <em class="bcp14">MAY</em> relay the credentials from the client request to the next proxy if that is the mechanism by which the proxies cooperatively
    873870         authenticate a given request.
Note: See TracChangeset for help on using the changeset viewer.