Changeset 2242 for draft-ietf-httpbis/latest
- Timestamp:
- 07/05/13 14:04:14 (10 years ago)
- Location:
- draft-ietf-httpbis/latest
- Files:
-
- 2 edited
Legend:
- Unmodified
- Added
- Removed
-
draft-ietf-httpbis/latest/p7-auth.html
r2232 r2242 449 449 } 450 450 @bottom-center { 451 content: "Expires November 2, 2013";451 content: "Expires November 8, 2013"; 452 452 } 453 453 @bottom-right { … … 489 489 <meta name="dct.creator" content="Reschke, J. F."> 490 490 <meta name="dct.identifier" content="urn:ietf:id:draft-ietf-httpbis-p7-auth-latest"> 491 <meta name="dct.issued" scheme="ISO8601" content="2013-05-0 1">491 <meta name="dct.issued" scheme="ISO8601" content="2013-05-07"> 492 492 <meta name="dct.replaces" content="urn:ietf:rfc:2616"> 493 493 <meta name="dct.abstract" content="The Hypertext Transfer Protocol (HTTP) is an application-level protocol for distributed, collaborative, hypermedia information systems. This document defines the HTTP Authentication framework."> … … 517 517 <tr> 518 518 <td class="left">Intended status: Standards Track</td> 519 <td class="right">May 1, 2013</td>519 <td class="right">May 7, 2013</td> 520 520 </tr> 521 521 <tr> 522 <td class="left">Expires: November 2, 2013</td>522 <td class="left">Expires: November 8, 2013</td> 523 523 <td class="right"></td> 524 524 </tr> … … 546 546 in progress”. 547 547 </p> 548 <p>This Internet-Draft will expire on November 2, 2013.</p>548 <p>This Internet-Draft will expire on November 8, 2013.</p> 549 549 <h1><a id="rfc.copyrightnotice" href="#rfc.copyrightnotice">Copyright Notice</a></h1> 550 550 <p>Copyright © 2013 IETF Trust and the persons identified as the document authors. All rights reserved.</p> … … 572 572 <li><a href="#rfc.section.2.1">2.1</a> <a href="#challenge.and.response">Challenge and Response</a></li> 573 573 <li><a href="#rfc.section.2.2">2.2</a> <a href="#protection.space">Protection Space (Realm)</a></li> 574 <li><a href="#rfc.section.2.3">2.3</a> <a href="#authentication.scheme.registry">Authentication Scheme Registry</a><ul>575 <li><a href="#rfc.section.2.3.1">2.3.1</a> <a href="#considerations.for.new.authentication.schemes">Considerations for New Authentication Schemes</a></li>576 </ul>577 </li>578 574 </ul> 579 575 </li> … … 591 587 </li> 592 588 <li><a href="#rfc.section.5">5.</a> <a href="#IANA.considerations">IANA Considerations</a><ul> 593 <li><a href="#rfc.section.5.1">5.1</a> <a href="#authentication.scheme.registration">Authentication Scheme Registry</a></li> 589 <li><a href="#rfc.section.5.1">5.1</a> <a href="#authentication.scheme.registry">Authentication Scheme Registry</a><ul> 590 <li><a href="#rfc.section.5.1.1">5.1.1</a> <a href="#authentication.scheme.registry.procedure">Procedure</a></li> 591 <li><a href="#rfc.section.5.1.2">5.1.2</a> <a href="#considerations.for.new.authentication.schemes">Considerations for New Authentication Schemes</a></li> 592 </ul> 593 </li> 594 594 <li><a href="#rfc.section.5.2">5.2</a> <a href="#status.code.registration">Status Code Registration</a></li> 595 595 <li><a href="#rfc.section.5.3">5.3</a> <a href="#header.field.registration">Header Field Registration</a></li> … … 711 711 with existing clients that have been accepting both notations for a long time. 712 712 </p> 713 <h2 id="rfc.section.2.3"><a href="#rfc.section.2.3">2.3</a> <a id="authentication.scheme.registry" href="#authentication.scheme.registry">Authentication Scheme Registry</a></h2> 714 <p id="rfc.section.2.3.p.1">The HTTP Authentication Scheme Registry defines the name space for the authentication schemes in challenges and credentials.</p> 715 <p id="rfc.section.2.3.p.2">Registrations <em class="bcp14">MUST</em> include the following fields: 713 <h1 id="rfc.section.3"><a href="#rfc.section.3">3.</a> <a id="status.code.definitions" href="#status.code.definitions">Status Code Definitions</a></h1> 714 <div id="rfc.iref.8"></div> 715 <h2 id="rfc.section.3.1"><a href="#rfc.section.3.1">3.1</a> <a id="status.401" href="#status.401">401 Unauthorized</a></h2> 716 <p id="rfc.section.3.1.p.1">The <dfn>401 (Unauthorized)</dfn> status code indicates that the request has not been applied because it lacks valid authentication credentials for the target 717 resource. The origin server <em class="bcp14">MUST</em> send 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 4.4</a>) containing at least one challenge applicable to the target resource. If the request included authentication credentials, 718 then the 401 response indicates that authorization has been refused for those credentials. The user agent <em class="bcp14">MAY</em> repeat the request with a new or replaced <a href="#header.authorization" class="smpl">Authorization</a> header field (<a href="#header.authorization" id="rfc.xref.header.authorization.2" title="Authorization">Section 4.1</a>). If the 401 response contains the same challenge as the prior response, and the user agent has already attempted authentication 719 at least once, then the user agent <em class="bcp14">SHOULD</em> present the enclosed representation to the user, since it usually contains relevant diagnostic information. 720 </p> 721 <div id="rfc.iref.8"></div> 722 <h2 id="rfc.section.3.2"><a href="#rfc.section.3.2">3.2</a> <a id="status.407" href="#status.407">407 Proxy Authentication Required</a></h2> 723 <p id="rfc.section.3.2.p.1">The <dfn>407 (Proxy Authentication Required)</dfn> status code is similar to <a href="#status.401" class="smpl">401 (Unauthorized)</a>, but indicates that the client needs to authenticate itself in order to use a proxy. The proxy <em class="bcp14">MUST</em> send 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 4.2</a>) containing a challenge applicable to that proxy for the target resource. The client <em class="bcp14">MAY</em> repeat the request with a new or replaced <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 4.3</a>). 724 </p> 725 <h1 id="rfc.section.4"><a href="#rfc.section.4">4.</a> <a id="header.field.definitions" href="#header.field.definitions">Header Field Definitions</a></h1> 726 <p id="rfc.section.4.p.1">This section defines the syntax and semantics of HTTP/1.1 header fields related to authentication.</p> 727 <div id="rfc.iref.a.1"></div> 728 <h2 id="rfc.section.4.1"><a href="#rfc.section.4.1">4.1</a> <a id="header.authorization" href="#header.authorization">Authorization</a></h2> 729 <p id="rfc.section.4.1.p.1">The "Authorization" header field allows a user agent to authenticate itself with an origin server — usually, but not necessarily, 730 after receiving a <a href="#status.401" class="smpl">401 731 (Unauthorized)</a> response. Its value consists of credentials containing information of the user agent for the realm of the resource being requested. 732 </p> 733 <div id="rfc.figure.u.4"></div><pre class="inline"><span id="rfc.iref.g.6"></span> <a href="#header.authorization" class="smpl">Authorization</a> = <a href="#challenge.and.response" class="smpl">credentials</a> 734 </pre><p id="rfc.section.4.1.p.3">If a request is authenticated and a realm specified, the same credentials <em class="bcp14">SHOULD</em> be valid for all other requests within this realm (assuming that the authentication scheme itself does not require otherwise, 735 such as credentials that vary according to a challenge value or using synchronized clocks). 736 </p> 737 <p id="rfc.section.4.1.p.4">See <a href="p6-cache.html#caching.authenticated.responses" title="Storing Responses to Authenticated Requests">Section 3.2</a> of <a href="#Part6" id="rfc.xref.Part6.1"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Caching">[Part6]</cite></a> for details of and requirements pertaining to handling of the Authorization field by HTTP caches. 738 </p> 739 <div id="rfc.iref.p.2"></div> 740 <h2 id="rfc.section.4.2"><a href="#rfc.section.4.2">4.2</a> <a id="header.proxy-authenticate" href="#header.proxy-authenticate">Proxy-Authenticate</a></h2> 741 <p id="rfc.section.4.2.p.1">The "Proxy-Authenticate" header field consists of at least one challenge that indicates the authentication scheme(s) and parameters 742 applicable to the proxy for this effective request URI (<a href="p1-messaging.html#effective.request.uri" title="Effective Request URI">Section 5.5</a> of <a href="#Part1" id="rfc.xref.Part1.4"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing">[Part1]</cite></a>). It <em class="bcp14">MUST</em> be included as part of a <a href="#status.407" class="smpl">407 (Proxy Authentication Required)</a> response. 743 </p> 744 <div id="rfc.figure.u.5"></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> 745 </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 746 from the downstream client, which in some circumstances will appear as if the proxy is forwarding the Proxy-Authenticate header 747 field. 748 </p> 749 <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 4.4</a> for details. 750 </p> 751 <div id="rfc.iref.p.3"></div> 752 <h2 id="rfc.section.4.3"><a href="#rfc.section.4.3">4.3</a> <a id="header.proxy-authorization" href="#header.proxy-authorization">Proxy-Authorization</a></h2> 753 <p id="rfc.section.4.3.p.1">The "Proxy-Authorization" header field allows the client to identify itself (or its user) to a proxy that requires authentication. 754 Its value consists of credentials containing the authentication information of the client for the proxy and/or realm of the 755 resource being requested. 756 </p> 757 <div id="rfc.figure.u.6"></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> 758 </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 759 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 760 authenticate a given request. 761 </p> 762 <div id="rfc.iref.w.1"></div> 763 <h2 id="rfc.section.4.4"><a href="#rfc.section.4.4">4.4</a> <a id="header.www-authenticate" href="#header.www-authenticate">WWW-Authenticate</a></h2> 764 <p id="rfc.section.4.4.p.1">The "WWW-Authenticate" header field consists of at least one challenge that indicates the authentication scheme(s) and parameters 765 applicable to the effective request URI (<a href="p1-messaging.html#effective.request.uri" title="Effective Request URI">Section 5.5</a> of <a href="#Part1" id="rfc.xref.Part1.5"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing">[Part1]</cite></a>). 766 </p> 767 <p id="rfc.section.4.4.p.2">It <em class="bcp14">MUST</em> be included in <a href="#status.401" class="smpl">401 (Unauthorized)</a> response messages and <em class="bcp14">MAY</em> be included in other response messages to indicate that supplying credentials (or different credentials) might affect the 768 response. 769 </p> 770 <div id="rfc.figure.u.7"></div><pre class="inline"><span id="rfc.iref.g.9"></span> <a href="#header.www-authenticate" class="smpl">WWW-Authenticate</a> = 1#<a href="#challenge.and.response" class="smpl">challenge</a> 771 </pre><p id="rfc.section.4.4.p.4">User agents are advised to take special care in parsing the WWW-Authenticate field value as it might contain more than one 772 challenge, or if more than one WWW-Authenticate header field is provided, the contents of a challenge itself can contain a 773 comma-separated list of authentication parameters. 774 </p> 775 <div id="rfc.figure.u.8"></div> 776 <p>For instance:</p><pre class="text"> WWW-Authenticate: Newauth realm="apps", type=1, 777 title="Login to \"apps\"", Basic realm="simple" 778 </pre><p>This header field contains two challenges; one for the "Newauth" scheme with a realm value of "apps", and two additional parameters 779 "type" and "title", and another one for the "Basic" scheme with a realm value of "simple". 780 </p> 781 <div class="note" id="rfc.section.4.4.p.6"> 782 <p> <b>Note:</b> The challenge grammar production uses the list syntax as well. Therefore, a sequence of comma, whitespace, and comma can be 783 considered both as applying to the preceding challenge, or to be an empty entry in the list of challenges. In practice, this 784 ambiguity does not affect the semantics of the header field value and thus is harmless. 785 </p> 786 </div> 787 <h1 id="rfc.section.5"><a href="#rfc.section.5">5.</a> <a id="IANA.considerations" href="#IANA.considerations">IANA Considerations</a></h1> 788 <h2 id="rfc.section.5.1"><a href="#rfc.section.5.1">5.1</a> <a id="authentication.scheme.registry" href="#authentication.scheme.registry">Authentication Scheme Registry</a></h2> 789 <p id="rfc.section.5.1.p.1">The HTTP Authentication Scheme Registry defines the name space for the authentication schemes in challenges and credentials. 790 It is maintained at <<a href="http://www.iana.org/assignments/http-authschemes">http://www.iana.org/assignments/http-authschemes</a>>. 791 </p> 792 <h3 id="rfc.section.5.1.1"><a href="#rfc.section.5.1.1">5.1.1</a> <a id="authentication.scheme.registry.procedure" href="#authentication.scheme.registry.procedure">Procedure</a></h3> 793 <p id="rfc.section.5.1.1.p.1">Registrations <em class="bcp14">MUST</em> include the following fields: 716 794 </p> 717 795 <ul> … … 720 798 <li>Notes (optional)</li> 721 799 </ul> 722 <p id="rfc.section.2.3.p.3">Values to be added to this name space require IETF Review (see <a href="#RFC5226" id="rfc.xref.RFC5226.1"><cite title="Guidelines for Writing an IANA Considerations Section in RFCs">[RFC5226]</cite></a>, <a href="http://tools.ietf.org/html/rfc5226#section-4.1">Section 4.1</a>). 723 </p> 724 <p id="rfc.section.2.3.p.4">The registry itself is maintained at <<a href="http://www.iana.org/assignments/http-authschemes">http://www.iana.org/assignments/http-authschemes</a>>. 725 </p> 726 <h3 id="rfc.section.2.3.1"><a href="#rfc.section.2.3.1">2.3.1</a> <a id="considerations.for.new.authentication.schemes" href="#considerations.for.new.authentication.schemes">Considerations for New Authentication Schemes</a></h3> 727 <p id="rfc.section.2.3.1.p.1">There are certain aspects of the HTTP Authentication Framework that put constraints on how new authentication schemes can 800 <p id="rfc.section.5.1.1.p.2">Values to be added to this name space require IETF Review (see <a href="#RFC5226" id="rfc.xref.RFC5226.1"><cite title="Guidelines for Writing an IANA Considerations Section in RFCs">[RFC5226]</cite></a>, <a href="http://tools.ietf.org/html/rfc5226#section-4.1">Section 4.1</a>). 801 </p> 802 <h3 id="rfc.section.5.1.2"><a href="#rfc.section.5.1.2">5.1.2</a> <a id="considerations.for.new.authentication.schemes" href="#considerations.for.new.authentication.schemes">Considerations for New Authentication Schemes</a></h3> 803 <p id="rfc.section.5.1.2.p.1">There are certain aspects of the HTTP Authentication Framework that put constraints on how new authentication schemes can 728 804 work: 729 805 </p> 730 <p id="rfc.section. 2.3.1.p.2"> </p>806 <p id="rfc.section.5.1.2.p.2"> </p> 731 807 <ul> 732 808 <li> 733 809 <p>HTTP authentication is presumed to be stateless: all of the information necessary to authenticate a request <em class="bcp14">MUST</em> be provided in the request, rather than be dependent on the server remembering prior requests. Authentication based on, or 734 810 bound to, the underlying connection is outside the scope of this specification and inherently flawed unless steps are taken 735 to ensure that the connection cannot be used by any party other than the authenticated user (see <a href="p1-messaging.html#intermediaries" title="Intermediaries">Section 2.3</a> of <a href="#Part1" id="rfc.xref.Part1. 4"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing">[Part1]</cite></a>).811 to ensure that the connection cannot be used by any party other than the authenticated user (see <a href="p1-messaging.html#intermediaries" title="Intermediaries">Section 2.3</a> of <a href="#Part1" id="rfc.xref.Part1.6"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing">[Part1]</cite></a>). 736 812 </p> 737 813 </li> … … 769 845 <li> 770 846 <p>The credentials carried in an <a href="#header.authorization" class="smpl">Authorization</a> header field are specific to the User Agent, and therefore have the same effect on HTTP caches as the "private" Cache-Control 771 response directive (<a href="p6-cache.html#cache-response-directive.private" title="private">Section 7.2.2. 2</a> of <a href="#Part6" id="rfc.xref.Part6.1"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Caching">[Part6]</cite></a>), within the scope of the request they appear in.847 response directive (<a href="p6-cache.html#cache-response-directive.private" title="private">Section 7.2.2.6</a> of <a href="#Part6" id="rfc.xref.Part6.2"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Caching">[Part6]</cite></a>), within the scope of the request they appear in. 772 848 </p> 773 849 <p>Therefore, new authentication schemes that choose not to carry credentials in the <a href="#header.authorization" class="smpl">Authorization</a> header field (e.g., using a newly defined header field) will need to explicitly disallow caching, by mandating the use of 774 either Cache-Control request directives (e.g., "no-store", <a href="p6-cache.html#cache-request-directive.no-store" title="no-store">Section 7.2.1. 2</a> of <a href="#Part6" id="rfc.xref.Part6.2"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Caching">[Part6]</cite></a>) or response directives (e.g., "private").850 either Cache-Control request directives (e.g., "no-store", <a href="p6-cache.html#cache-request-directive.no-store" title="no-store">Section 7.2.1.5</a> of <a href="#Part6" id="rfc.xref.Part6.3"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Caching">[Part6]</cite></a>) or response directives (e.g., "private"). 775 851 </p> 776 852 </li> 777 853 </ul> 778 <h1 id="rfc.section.3"><a href="#rfc.section.3">3.</a> <a id="status.code.definitions" href="#status.code.definitions">Status Code Definitions</a></h1>779 <div id="rfc.iref.8"></div>780 <h2 id="rfc.section.3.1"><a href="#rfc.section.3.1">3.1</a> <a id="status.401" href="#status.401">401 Unauthorized</a></h2>781 <p id="rfc.section.3.1.p.1">The <dfn>401 (Unauthorized)</dfn> status code indicates that the request has not been applied because it lacks valid authentication credentials for the target782 resource. The origin server <em class="bcp14">MUST</em> send 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 4.4</a>) containing at least one challenge applicable to the target resource. If the request included authentication credentials,783 then the 401 response indicates that authorization has been refused for those credentials. The user agent <em class="bcp14">MAY</em> repeat the request with a new or replaced <a href="#header.authorization" class="smpl">Authorization</a> header field (<a href="#header.authorization" id="rfc.xref.header.authorization.2" title="Authorization">Section 4.1</a>). If the 401 response contains the same challenge as the prior response, and the user agent has already attempted authentication784 at least once, then the user agent <em class="bcp14">SHOULD</em> present the enclosed representation to the user, since it usually contains relevant diagnostic information.785 </p>786 <div id="rfc.iref.8"></div>787 <h2 id="rfc.section.3.2"><a href="#rfc.section.3.2">3.2</a> <a id="status.407" href="#status.407">407 Proxy Authentication Required</a></h2>788 <p id="rfc.section.3.2.p.1">The <dfn>407 (Proxy Authentication Required)</dfn> status code is similar to <a href="#status.401" class="smpl">401 (Unauthorized)</a>, but indicates that the client needs to authenticate itself in order to use a proxy. The proxy <em class="bcp14">MUST</em> send 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 4.2</a>) containing a challenge applicable to that proxy for the target resource. The client <em class="bcp14">MAY</em> repeat the request with a new or replaced <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 4.3</a>).789 </p>790 <h1 id="rfc.section.4"><a href="#rfc.section.4">4.</a> <a id="header.field.definitions" href="#header.field.definitions">Header Field Definitions</a></h1>791 <p id="rfc.section.4.p.1">This section defines the syntax and semantics of HTTP/1.1 header fields related to authentication.</p>792 <div id="rfc.iref.a.1"></div>793 <h2 id="rfc.section.4.1"><a href="#rfc.section.4.1">4.1</a> <a id="header.authorization" href="#header.authorization">Authorization</a></h2>794 <p id="rfc.section.4.1.p.1">The "Authorization" header field allows a user agent to authenticate itself with an origin server — usually, but not necessarily,795 after receiving a <a href="#status.401" class="smpl">401796 (Unauthorized)</a> response. Its value consists of credentials containing information of the user agent for the realm of the resource being requested.797 </p>798 <div id="rfc.figure.u.4"></div><pre class="inline"><span id="rfc.iref.g.6"></span> <a href="#header.authorization" class="smpl">Authorization</a> = <a href="#challenge.and.response" class="smpl">credentials</a>799 </pre><p id="rfc.section.4.1.p.3">If a request is authenticated and a realm specified, the same credentials <em class="bcp14">SHOULD</em> be valid for all other requests within this realm (assuming that the authentication scheme itself does not require otherwise,800 such as credentials that vary according to a challenge value or using synchronized clocks).801 </p>802 <p id="rfc.section.4.1.p.4">See <a href="p6-cache.html#caching.authenticated.responses" title="Storing Responses to Authenticated Requests">Section 3.2</a> of <a href="#Part6" id="rfc.xref.Part6.3"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Caching">[Part6]</cite></a> for details of and requirements pertaining to handling of the Authorization field by HTTP caches.803 </p>804 <div id="rfc.iref.p.2"></div>805 <h2 id="rfc.section.4.2"><a href="#rfc.section.4.2">4.2</a> <a id="header.proxy-authenticate" href="#header.proxy-authenticate">Proxy-Authenticate</a></h2>806 <p id="rfc.section.4.2.p.1">The "Proxy-Authenticate" header field consists of at least one challenge that indicates the authentication scheme(s) and parameters807 applicable to the proxy for this effective request URI (<a href="p1-messaging.html#effective.request.uri" title="Effective Request URI">Section 5.5</a> of <a href="#Part1" id="rfc.xref.Part1.5"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing">[Part1]</cite></a>). It <em class="bcp14">MUST</em> be included as part of a <a href="#status.407" class="smpl">407 (Proxy Authentication Required)</a> response.808 </p>809 <div id="rfc.figure.u.5"></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>810 </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 them811 from the downstream client, which in some circumstances will appear as if the proxy is forwarding the Proxy-Authenticate header812 field.813 </p>814 <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 4.4</a> for details.815 </p>816 <div id="rfc.iref.p.3"></div>817 <h2 id="rfc.section.4.3"><a href="#rfc.section.4.3">4.3</a> <a id="header.proxy-authorization" href="#header.proxy-authorization">Proxy-Authorization</a></h2>818 <p id="rfc.section.4.3.p.1">The "Proxy-Authorization" header field allows the client to identify itself (or its user) to a proxy that requires authentication.819 Its value consists of credentials containing the authentication information of the client for the proxy and/or realm of the820 resource being requested.821 </p>822 <div id="rfc.figure.u.6"></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>823 </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 proxy824 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 cooperatively825 authenticate a given request.826 </p>827 <div id="rfc.iref.w.1"></div>828 <h2 id="rfc.section.4.4"><a href="#rfc.section.4.4">4.4</a> <a id="header.www-authenticate" href="#header.www-authenticate">WWW-Authenticate</a></h2>829 <p id="rfc.section.4.4.p.1">The "WWW-Authenticate" header field consists of at least one challenge that indicates the authentication scheme(s) and parameters830 applicable to the effective request URI (<a href="p1-messaging.html#effective.request.uri" title="Effective Request URI">Section 5.5</a> of <a href="#Part1" id="rfc.xref.Part1.6"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing">[Part1]</cite></a>).831 </p>832 <p id="rfc.section.4.4.p.2">It <em class="bcp14">MUST</em> be included in <a href="#status.401" class="smpl">401 (Unauthorized)</a> response messages and <em class="bcp14">MAY</em> be included in other response messages to indicate that supplying credentials (or different credentials) might affect the833 response.834 </p>835 <div id="rfc.figure.u.7"></div><pre class="inline"><span id="rfc.iref.g.9"></span> <a href="#header.www-authenticate" class="smpl">WWW-Authenticate</a> = 1#<a href="#challenge.and.response" class="smpl">challenge</a>836 </pre><p id="rfc.section.4.4.p.4">User agents are advised to take special care in parsing the WWW-Authenticate field value as it might contain more than one837 challenge, or if more than one WWW-Authenticate header field is provided, the contents of a challenge itself can contain a838 comma-separated list of authentication parameters.839 </p>840 <div id="rfc.figure.u.8"></div>841 <p>For instance:</p><pre class="text"> WWW-Authenticate: Newauth realm="apps", type=1,842 title="Login to \"apps\"", Basic realm="simple"843 </pre><p>This header field contains two challenges; one for the "Newauth" scheme with a realm value of "apps", and two additional parameters844 "type" and "title", and another one for the "Basic" scheme with a realm value of "simple".845 </p>846 <div class="note" id="rfc.section.4.4.p.6">847 <p> <b>Note:</b> The challenge grammar production uses the list syntax as well. Therefore, a sequence of comma, whitespace, and comma can be848 considered both as applying to the preceding challenge, or to be an empty entry in the list of challenges. In practice, this849 ambiguity does not affect the semantics of the header field value and thus is harmless.850 </p>851 </div>852 <h1 id="rfc.section.5"><a href="#rfc.section.5">5.</a> <a id="IANA.considerations" href="#IANA.considerations">IANA Considerations</a></h1>853 <h2 id="rfc.section.5.1"><a href="#rfc.section.5.1">5.1</a> <a id="authentication.scheme.registration" href="#authentication.scheme.registration">Authentication Scheme Registry</a></h2>854 <p id="rfc.section.5.1.p.1">The registration procedure for HTTP Authentication Schemes is defined by <a href="#authentication.scheme.registry" title="Authentication Scheme Registry">Section 2.3</a> of this document.855 </p>856 <p id="rfc.section.5.1.p.2">The HTTP Method Authentication Scheme shall be created at <<a href="http://www.iana.org/assignments/http-authschemes">http://www.iana.org/assignments/http-authschemes</a>>.857 </p>858 854 <h2 id="rfc.section.5.2"><a href="#rfc.section.5.2">5.2</a> <a id="status.code.registration" href="#status.code.registration">Status Code Registration</a></h2> 859 855 <p id="rfc.section.5.2.p.1">The HTTP Status Code Registry located at <<a href="http://www.iana.org/assignments/http-status-codes">http://www.iana.org/assignments/http-status-codes</a>> shall be updated with the registrations below: … … 1055 1051 </p> 1056 1052 <p id="rfc.section.A.p.4">This specification introduces the Authentication Scheme Registry, along with considerations for new authentication schemes. 1057 (<a href="#authentication.scheme.registry" title="Authentication Scheme Registry">Section 2.3</a>)1053 (<a href="#authentication.scheme.registry" title="Authentication Scheme Registry">Section 5.1</a>) 1058 1054 </p> 1059 1055 <h1 id="rfc.section.B"><a href="#rfc.section.B">B.</a> <a id="imported.abnf" href="#imported.abnf">Imported ABNF</a></h1> … … 1138 1134 </li> 1139 1135 <li> <<a href="http://tools.ietf.org/wg/httpbis/trac/ticket/463">http://tools.ietf.org/wg/httpbis/trac/ticket/463</a>>: "Editorial suggestions" 1136 </li> 1137 <li> <<a href="http://tools.ietf.org/wg/httpbis/trac/ticket/464">http://tools.ietf.org/wg/httpbis/trac/ticket/464</a>>: "placement of extension point considerations" 1140 1138 </li> 1141 1139 </ul> … … 1179 1177 </li> 1180 1178 <li><a id="rfc.index.P" href="#rfc.index.P"><b>P</b></a><ul> 1181 <li><em>Part1</em> <a href="#rfc.xref.Part1.1">1.1</a>, <a href="#rfc.xref.Part1.2">1.2</a>, <a href="#rfc.xref.Part1.3">2.2</a>, <a href="#rfc.xref.Part1.4"> 2.3.1</a>, <a href="#rfc.xref.Part1.5">4.2</a>, <a href="#rfc.xref.Part1.6">4.4</a>, <a href="#rfc.xref.Part1.7">6</a>, <a href="#rfc.xref.Part1.8">7</a>, <a href="#Part1"><b>8.1</b></a>, <a href="#rfc.xref.Part1.9">B</a>, <a href="#rfc.xref.Part1.10">B</a>, <a href="#rfc.xref.Part1.11">B</a>, <a href="#rfc.xref.Part1.12">B</a>, <a href="#rfc.xref.Part1.13">B</a>, <a href="#rfc.xref.Part1.14">C</a><ul>1179 <li><em>Part1</em> <a href="#rfc.xref.Part1.1">1.1</a>, <a href="#rfc.xref.Part1.2">1.2</a>, <a href="#rfc.xref.Part1.3">2.2</a>, <a href="#rfc.xref.Part1.4">4.2</a>, <a href="#rfc.xref.Part1.5">4.4</a>, <a href="#rfc.xref.Part1.6">5.1.2</a>, <a href="#rfc.xref.Part1.7">6</a>, <a href="#rfc.xref.Part1.8">7</a>, <a href="#Part1"><b>8.1</b></a>, <a href="#rfc.xref.Part1.9">B</a>, <a href="#rfc.xref.Part1.10">B</a>, <a href="#rfc.xref.Part1.11">B</a>, <a href="#rfc.xref.Part1.12">B</a>, <a href="#rfc.xref.Part1.13">B</a>, <a href="#rfc.xref.Part1.14">C</a><ul> 1182 1180 <li><em>Section 1.2</em> <a href="#rfc.xref.Part1.2">1.2</a>, <a href="#rfc.xref.Part1.14">C</a></li> 1183 <li><em>Section 2.3</em> <a href="#rfc.xref.Part1. 4">2.3.1</a></li>1181 <li><em>Section 2.3</em> <a href="#rfc.xref.Part1.6">5.1.2</a></li> 1184 1182 <li><em>Section 2.5</em> <a href="#rfc.xref.Part1.1">1.1</a></li> 1185 1183 <li><em>Section 3.2.3</em> <a href="#rfc.xref.Part1.10">B</a>, <a href="#rfc.xref.Part1.11">B</a></li> 1186 1184 <li><em>Section 3.2.6</em> <a href="#rfc.xref.Part1.12">B</a>, <a href="#rfc.xref.Part1.13">B</a></li> 1187 <li><em>Section 5.5</em> <a href="#rfc.xref.Part1.3">2.2</a>, <a href="#rfc.xref.Part1. 5">4.2</a>, <a href="#rfc.xref.Part1.6">4.4</a></li>1185 <li><em>Section 5.5</em> <a href="#rfc.xref.Part1.3">2.2</a>, <a href="#rfc.xref.Part1.4">4.2</a>, <a href="#rfc.xref.Part1.5">4.4</a></li> 1188 1186 <li><em>Section 9</em> <a href="#rfc.xref.Part1.8">7</a></li> 1189 1187 </ul> … … 1193 1191 </ul> 1194 1192 </li> 1195 <li><em>Part6</em> <a href="#rfc.xref.Part6.1"> 2.3.1</a>, <a href="#rfc.xref.Part6.2">2.3.1</a>, <a href="#rfc.xref.Part6.3">4.1</a>, <a href="#Part6"><b>8.1</b></a><ul>1196 <li><em>Section 3.2</em> <a href="#rfc.xref.Part6. 3">4.1</a></li>1197 <li><em>Section 7.2.1. 2</em> <a href="#rfc.xref.Part6.2">2.3.1</a></li>1198 <li><em>Section 7.2.2. 2</em> <a href="#rfc.xref.Part6.1">2.3.1</a></li>1193 <li><em>Part6</em> <a href="#rfc.xref.Part6.1">4.1</a>, <a href="#rfc.xref.Part6.2">5.1.2</a>, <a href="#rfc.xref.Part6.3">5.1.2</a>, <a href="#Part6"><b>8.1</b></a><ul> 1194 <li><em>Section 3.2</em> <a href="#rfc.xref.Part6.1">4.1</a></li> 1195 <li><em>Section 7.2.1.5</em> <a href="#rfc.xref.Part6.3">5.1.2</a></li> 1196 <li><em>Section 7.2.2.6</em> <a href="#rfc.xref.Part6.2">5.1.2</a></li> 1199 1197 </ul> 1200 1198 </li> … … 1214 1212 <li><em>RFC3986</em> <a href="#rfc.xref.RFC3986.1">2.1</a>, <a href="#RFC3986"><b>8.2</b></a></li> 1215 1213 <li><em>RFC4648</em> <a href="#rfc.xref.RFC4648.1">2.1</a>, <a href="#RFC4648"><b>8.2</b></a></li> 1216 <li><em>RFC5226</em> <a href="#rfc.xref.RFC5226.1"> 2.3</a>, <a href="#RFC5226"><b>8.2</b></a><ul>1217 <li><em>Section 4.1</em> <a href="#rfc.xref.RFC5226.1"> 2.3</a></li>1214 <li><em>RFC5226</em> <a href="#rfc.xref.RFC5226.1">5.1.1</a>, <a href="#RFC5226"><b>8.2</b></a><ul> 1215 <li><em>Section 4.1</em> <a href="#rfc.xref.RFC5226.1">5.1.1</a></li> 1218 1216 </ul> 1219 1217 </li> -
draft-ietf-httpbis/latest/p7-auth.xml
r2232 r2242 314 314 </section> 315 315 316 <section title="Authentication Scheme Registry" anchor="authentication.scheme.registry">317 <t>318 The HTTP Authentication Scheme Registry defines the name space for the319 authentication schemes in challenges and credentials.320 </t>321 <t>322 Registrations &MUST; include the following fields:323 <list style="symbols">324 <t>Authentication Scheme Name</t>325 <t>Pointer to specification text</t>326 <t>Notes (optional)</t>327 </list>328 </t>329 <t>330 Values to be added to this name space require IETF Review331 (see <xref target="RFC5226" x:fmt="," x:sec="4.1"/>).332 </t>333 <t>334 The registry itself is maintained at <eref target="http://www.iana.org/assignments/http-authschemes"/>.335 </t>336 337 <section title="Considerations for New Authentication Schemes" anchor="considerations.for.new.authentication.schemes">338 <t>339 There are certain aspects of the HTTP Authentication Framework that put340 constraints on how new authentication schemes can work:341 </t>342 <t>343 <list style="symbols">344 <x:lt>345 <t>346 HTTP authentication is presumed to be stateless: all of the information347 necessary to authenticate a request &MUST; be provided in the request,348 rather than be dependent on the server remembering prior requests.349 Authentication based on, or bound to, the underlying connection is350 outside the scope of this specification and inherently flawed unless351 steps are taken to ensure that the connection cannot be used by any352 party other than the authenticated user353 (see &msg-orient-and-buffering;).354 </t>355 </x:lt>356 <x:lt>357 <t>358 The authentication parameter "realm" is reserved for defining Protection359 Spaces as defined in <xref target="protection.space"/>. New schemes360 &MUST-NOT; use it in a way incompatible with that definition.361 </t>362 </x:lt>363 <x:lt>364 <t>365 The "token68" notation was introduced for compatibility with existing366 authentication schemes and can only be used once per challenge or credential.367 New schemes thus ought to use the "auth-param" syntax instead, because368 otherwise future extensions will be impossible.369 </t>370 </x:lt>371 <x:lt>372 <t>373 The parsing of challenges and credentials is defined by this specification,374 and cannot be modified by new authentication schemes. When the auth-param375 syntax is used, all parameters ought to support both token and376 quoted-string syntax, and syntactical constraints ought to be defined on377 the field value after parsing (i.e., quoted-string processing). This is378 necessary so that recipients can use a generic parser that applies to379 all authentication schemes.380 </t>381 <t>382 &Note; The fact that the value syntax for the "realm" parameter383 is restricted to quoted-string was a bad design choice not to be repeated384 for new parameters.385 </t>386 </x:lt>387 <x:lt>388 <t>389 Definitions of new schemes ought to define the treatment of unknown390 extension parameters. In general, a "must-ignore" rule is preferable391 over "must-understand", because otherwise it will be hard to introduce392 new parameters in the presence of legacy recipients. Furthermore,393 it's good to describe the policy for defining new parameters (such394 as "update the specification", or "use this registry").395 </t>396 </x:lt>397 <x:lt>398 <t>399 Authentication schemes need to document whether they are usable in400 origin-server authentication (i.e., using <x:ref>WWW-Authenticate</x:ref>),401 and/or proxy authentication (i.e., using <x:ref>Proxy-Authenticate</x:ref>).402 </t>403 </x:lt>404 <x:lt>405 <t>406 The credentials carried in an <x:ref>Authorization</x:ref> header field are specific to407 the User Agent, and therefore have the same effect on HTTP caches as the408 "private" Cache-Control response directive (&caching-rsd-private;),409 within the scope of the request they appear in.410 </t>411 <t>412 Therefore, new authentication schemes that choose not to carry413 credentials in the <x:ref>Authorization</x:ref> header field (e.g., using a newly defined414 header field) will need to explicitly disallow caching, by mandating the use of415 either Cache-Control request directives (e.g., "no-store",416 &caching-rqd-no-store;) or response directives (e.g., "private").417 </t>418 </x:lt>419 </list>420 </t>421 </section>422 423 </section>424 425 316 </section> 426 317 … … 597 488 <section title="IANA Considerations" anchor="IANA.considerations"> 598 489 599 <section title="Authentication Scheme Registry" anchor="authentication.scheme.registration"> 600 <t> 601 The registration procedure for HTTP Authentication Schemes is defined by 602 <xref target="authentication.scheme.registry"/> of this document. 603 </t> 604 <t> 605 The HTTP Method Authentication Scheme shall be created at <eref target="http://www.iana.org/assignments/http-authschemes"/>. 606 </t> 490 <section title="Authentication Scheme Registry" anchor="authentication.scheme.registry"> 491 <t> 492 The HTTP Authentication Scheme Registry defines the name space for the 493 authentication schemes in challenges and credentials. It is maintained at 494 <eref target="http://www.iana.org/assignments/http-authschemes"/>. 495 </t> 496 497 <section title="Procedure" anchor="authentication.scheme.registry.procedure"> 498 <t> 499 Registrations &MUST; include the following fields: 500 <list style="symbols"> 501 <t>Authentication Scheme Name</t> 502 <t>Pointer to specification text</t> 503 <t>Notes (optional)</t> 504 </list> 505 </t> 506 <t> 507 Values to be added to this name space require IETF Review 508 (see <xref target="RFC5226" x:fmt="," x:sec="4.1"/>). 509 </t> 510 </section> 511 512 <section title="Considerations for New Authentication Schemes" anchor="considerations.for.new.authentication.schemes"> 513 <t> 514 There are certain aspects of the HTTP Authentication Framework that put 515 constraints on how new authentication schemes can work: 516 </t> 517 <t> 518 <list style="symbols"> 519 <x:lt> 520 <t> 521 HTTP authentication is presumed to be stateless: all of the information 522 necessary to authenticate a request &MUST; be provided in the request, 523 rather than be dependent on the server remembering prior requests. 524 Authentication based on, or bound to, the underlying connection is 525 outside the scope of this specification and inherently flawed unless 526 steps are taken to ensure that the connection cannot be used by any 527 party other than the authenticated user 528 (see &msg-orient-and-buffering;). 529 </t> 530 </x:lt> 531 <x:lt> 532 <t> 533 The authentication parameter "realm" is reserved for defining Protection 534 Spaces as defined in <xref target="protection.space"/>. New schemes 535 &MUST-NOT; use it in a way incompatible with that definition. 536 </t> 537 </x:lt> 538 <x:lt> 539 <t> 540 The "token68" notation was introduced for compatibility with existing 541 authentication schemes and can only be used once per challenge or credential. 542 New schemes thus ought to use the "auth-param" syntax instead, because 543 otherwise future extensions will be impossible. 544 </t> 545 </x:lt> 546 <x:lt> 547 <t> 548 The parsing of challenges and credentials is defined by this specification, 549 and cannot be modified by new authentication schemes. When the auth-param 550 syntax is used, all parameters ought to support both token and 551 quoted-string syntax, and syntactical constraints ought to be defined on 552 the field value after parsing (i.e., quoted-string processing). This is 553 necessary so that recipients can use a generic parser that applies to 554 all authentication schemes. 555 </t> 556 <t> 557 &Note; The fact that the value syntax for the "realm" parameter 558 is restricted to quoted-string was a bad design choice not to be repeated 559 for new parameters. 560 </t> 561 </x:lt> 562 <x:lt> 563 <t> 564 Definitions of new schemes ought to define the treatment of unknown 565 extension parameters. In general, a "must-ignore" rule is preferable 566 over "must-understand", because otherwise it will be hard to introduce 567 new parameters in the presence of legacy recipients. Furthermore, 568 it's good to describe the policy for defining new parameters (such 569 as "update the specification", or "use this registry"). 570 </t> 571 </x:lt> 572 <x:lt> 573 <t> 574 Authentication schemes need to document whether they are usable in 575 origin-server authentication (i.e., using <x:ref>WWW-Authenticate</x:ref>), 576 and/or proxy authentication (i.e., using <x:ref>Proxy-Authenticate</x:ref>). 577 </t> 578 </x:lt> 579 <x:lt> 580 <t> 581 The credentials carried in an <x:ref>Authorization</x:ref> header field are specific to 582 the User Agent, and therefore have the same effect on HTTP caches as the 583 "private" Cache-Control response directive (&caching-rsd-private;), 584 within the scope of the request they appear in. 585 </t> 586 <t> 587 Therefore, new authentication schemes that choose not to carry 588 credentials in the <x:ref>Authorization</x:ref> header field (e.g., using a newly defined 589 header field) will need to explicitly disallow caching, by mandating the use of 590 either Cache-Control request directives (e.g., "no-store", 591 &caching-rqd-no-store;) or response directives (e.g., "private"). 592 </t> 593 </x:lt> 594 </list> 595 </t> 596 </section> 607 597 </section> 608 598 … … 1176 1166 "Editorial suggestions" 1177 1167 </t> 1168 <t> 1169 <eref target="http://tools.ietf.org/wg/httpbis/trac/ticket/464"/>: 1170 "placement of extension point considerations" 1171 </t> 1178 1172 </list> 1179 1173 </t>
Note: See TracChangeset
for help on using the changeset viewer.