From 7e1603c9add91857b72ef8d2b65c3fc0e3182338 Mon Sep 17 00:00:00 2001 From: Jesper Jensen Date: Fri, 19 Dec 2025 16:46:33 +0100 Subject: Add the authentication stuff --- docs/rfc2617.txt | 1907 ++++++++++++++++++++++++ docs/rfc6749.txt | 4259 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/rfc6750.txt | 1011 +++++++++++++ docs/rfc7235.txt | 1067 ++++++++++++++ 4 files changed, 8244 insertions(+) create mode 100644 docs/rfc2617.txt create mode 100644 docs/rfc6749.txt create mode 100644 docs/rfc6750.txt create mode 100644 docs/rfc7235.txt (limited to 'docs') diff --git a/docs/rfc2617.txt b/docs/rfc2617.txt new file mode 100644 index 0000000..771aa92 --- /dev/null +++ b/docs/rfc2617.txt @@ -0,0 +1,1907 @@ + + + + + + +Network Working Group J. Franks +Request for Comments: 2617 Northwestern University +Obsoletes: 2069 P. Hallam-Baker +Category: Standards Track Verisign, Inc. + J. Hostetler + AbiSource, Inc. + S. Lawrence + Agranat Systems, Inc. + P. Leach + Microsoft Corporation + A. Luotonen + Netscape Communications Corporation + L. Stewart + Open Market, Inc. + June 1999 + + + HTTP Authentication: Basic and Digest Access Authentication + +Status of this Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (1999). All Rights Reserved. + +Abstract + + "HTTP/1.0", includes the specification for a Basic Access + Authentication scheme. This scheme is not considered to be a secure + method of user authentication (unless used in conjunction with some + external secure system such as SSL [5]), as the user name and + password are passed over the network as cleartext. + + This document also provides the specification for HTTP's + authentication framework, the original Basic authentication scheme + and a scheme based on cryptographic hashes, referred to as "Digest + Access Authentication". It is therefore also intended to serve as a + replacement for RFC 2069 [6]. Some optional elements specified by + RFC 2069 have been removed from this specification due to problems + found since its publication; other new elements have been added for + compatibility, those new elements have been made optional, but are + strongly recommended. + + + +Franks, et al. Standards Track [Page 1] + +RFC 2617 HTTP Authentication June 1999 + + + Like Basic, Digest access authentication verifies that both parties + to a communication know a shared secret (a password); unlike Basic, + this verification can be done without sending the password in the + clear, which is Basic's biggest weakness. As with most other + authentication protocols, the greatest sources of risks are usually + found not in the core protocol itself but in policies and procedures + surrounding its use. + +Table of Contents + + 1 Access Authentication................................ 3 + 1.1 Reliance on the HTTP/1.1 Specification............ 3 + 1.2 Access Authentication Framework................... 3 + 2 Basic Authentication Scheme.......................... 5 + 3 Digest Access Authentication Scheme.................. 6 + 3.1 Introduction...................................... 6 + 3.1.1 Purpose......................................... 6 + 3.1.2 Overall Operation............................... 6 + 3.1.3 Representation of digest values................. 7 + 3.1.4 Limitations..................................... 7 + 3.2 Specification of Digest Headers................... 7 + 3.2.1 The WWW-Authenticate Response Header............ 8 + 3.2.2 The Authorization Request Header................ 11 + 3.2.3 The Authentication-Info Header.................. 15 + 3.3 Digest Operation.................................. 17 + 3.4 Security Protocol Negotiation..................... 18 + 3.5 Example........................................... 18 + 3.6 Proxy-Authentication and Proxy-Authorization...... 19 + 4 Security Considerations.............................. 19 + 4.1 Authentication of Clients using Basic + Authentication.................................... 19 + 4.2 Authentication of Clients using Digest + Authentication.................................... 20 + 4.3 Limited Use Nonce Values.......................... 21 + 4.4 Comparison of Digest with Basic Authentication.... 22 + 4.5 Replay Attacks.................................... 22 + 4.6 Weakness Created by Multiple Authentication + Schemes........................................... 23 + 4.7 Online dictionary attacks......................... 23 + 4.8 Man in the Middle................................. 24 + 4.9 Chosen plaintext attacks.......................... 24 + 4.10 Precomputed dictionary attacks.................... 25 + 4.11 Batch brute force attacks......................... 25 + 4.12 Spoofing by Counterfeit Servers................... 25 + 4.13 Storing passwords................................. 26 + 4.14 Summary........................................... 26 + 5 Sample implementation................................ 27 + 6 Acknowledgments...................................... 31 + + + +Franks, et al. Standards Track [Page 2] + +RFC 2617 HTTP Authentication June 1999 + + + 7 References........................................... 31 + 8 Authors' Addresses................................... 32 + 9 Full Copyright Statement............................. 34 + +1 Access Authentication + +1.1 Reliance on the HTTP/1.1 Specification + + This specification is a companion to the HTTP/1.1 specification [2]. + It uses the augmented BNF section 2.1 of that document, and relies on + both the non-terminals defined in that document and other aspects of + the HTTP/1.1 specification. + +1.2 Access Authentication Framework + + HTTP provides a simple challenge-response authentication mechanism + that MAY be used by a server to challenge a client request and by a + client to provide authentication information. It uses an extensible, + case-insensitive token to identify the authentication scheme, + followed by a comma-separated list of attribute-value pairs which + carry the parameters necessary for achieving authentication via that + scheme. + + auth-scheme = token + auth-param = token "=" ( token | quoted-string ) + + The 401 (Unauthorized) response message is used by an origin server + to challenge the authorization of a user agent. This response MUST + include a WWW-Authenticate header field containing at least one + challenge applicable to the requested resource. The 407 (Proxy + Authentication Required) response message is used by a proxy to + challenge the authorization of a client and MUST include a Proxy- + Authenticate header field containing at least one challenge + applicable to the proxy for the requested resource. + + challenge = auth-scheme 1*SP 1#auth-param + + Note: User agents will need to take special care in parsing the WWW- + Authenticate or Proxy-Authenticate header field value if it contains + more than one challenge, or if more than one WWW-Authenticate header + field is provided, since the contents of a challenge may itself + contain a comma-separated list of authentication parameters. + + The authentication parameter realm is defined for all authentication + schemes: + + realm = "realm" "=" realm-value + realm-value = quoted-string + + + +Franks, et al. Standards Track [Page 3] + +RFC 2617 HTTP Authentication June 1999 + + + The realm directive (case-insensitive) is required for all + authentication schemes that issue a challenge. The realm value + (case-sensitive), in combination with the canonical root URL (the + absoluteURI for the server whose abs_path is empty; see section 5.1.2 + of [2]) of the server being accessed, defines the protection space. + These realms allow the protected resources on a server to be + partitioned into a set of protection spaces, each with its own + authentication scheme and/or authorization database. The realm value + is a string, generally assigned by the origin server, which may have + additional semantics specific to the authentication scheme. Note that + there may be multiple challenges with the same auth-scheme but + different realms. + + A user agent that wishes to authenticate itself with an origin + server--usually, but not necessarily, after receiving a 401 + (Unauthorized)--MAY do so by including an Authorization header field + with the request. A client that wishes to authenticate itself with a + proxy--usually, but not necessarily, after receiving a 407 (Proxy + Authentication Required)--MAY do so by including a Proxy- + Authorization header field with the request. Both the Authorization + field value and the Proxy-Authorization field value consist of + credentials containing the authentication information of the client + for the realm of the resource being requested. The user agent MUST + choose to use one of the challenges with the strongest auth-scheme it + understands and request credentials from the user based upon that + challenge. + + credentials = auth-scheme #auth-param + + Note that many browsers will only recognize Basic and will require + that it be the first auth-scheme presented. Servers should only + include Basic if it is minimally acceptable. + + The protection space determines the domain over which credentials can + be automatically applied. If a prior request has been authorized, the + same credentials MAY be reused for all other requests within that + protection space for a period of time determined by the + authentication scheme, parameters, and/or user preference. Unless + otherwise defined by the authentication scheme, a single protection + space cannot extend outside the scope of its server. + + If the origin server does not wish to accept the credentials sent + with a request, it SHOULD return a 401 (Unauthorized) response. The + response MUST include a WWW-Authenticate header field containing at + least one (possibly new) challenge applicable to the requested + resource. If a proxy does not accept the credentials sent with a + request, it SHOULD return a 407 (Proxy Authentication Required). The + response MUST include a Proxy-Authenticate header field containing a + + + +Franks, et al. Standards Track [Page 4] + +RFC 2617 HTTP Authentication June 1999 + + + (possibly new) challenge applicable to the proxy for the requested + resource. + + The HTTP protocol does not restrict applications to this simple + challenge-response mechanism for access authentication. Additional + mechanisms MAY be used, such as encryption at the transport level or + via message encapsulation, and with additional header fields + specifying authentication information. However, these additional + mechanisms are not defined by this specification. + + Proxies MUST be completely transparent regarding user agent + authentication by origin servers. That is, they must forward the + WWW-Authenticate and Authorization headers untouched, and follow the + rules found in section 14.8 of [2]. Both the Proxy-Authenticate and + the Proxy-Authorization header fields are hop-by-hop headers (see + section 13.5.1 of [2]). + +2 Basic Authentication Scheme + + The "basic" authentication scheme is based on the model that the + client must authenticate itself with a user-ID and a password for + each realm. The realm value should be considered an opaque string + which can only be compared for equality with other realms on that + server. The server will service the request only if it can validate + the user-ID and password for the protection space of the Request-URI. + There are no optional authentication parameters. + + For Basic, the framework above is utilized as follows: + + challenge = "Basic" realm + credentials = "Basic" basic-credentials + + Upon receipt of an unauthorized request for a URI within the + protection space, the origin server MAY respond with a challenge like + the following: + + WWW-Authenticate: Basic realm="WallyWorld" + + where "WallyWorld" is the string assigned by the server to identify + the protection space of the Request-URI. A proxy may respond with the + same challenge using the Proxy-Authenticate header field. + + To receive authorization, the client sends the userid and password, + separated by a single colon (":") character, within a base64 [7] + encoded string in the credentials. + + basic-credentials = base64-user-pass + base64-user-pass = + user-pass = userid ":" password + userid = * + password = *TEXT + + Userids might be case sensitive. + + If the user agent wishes to send the userid "Aladdin" and password + "open sesame", it would use the following header field: + + Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== + + A client SHOULD assume that all paths at or deeper than the depth of + the last symbolic element in the path field of the Request-URI also + are within the protection space specified by the Basic realm value of + the current challenge. A client MAY preemptively send the + corresponding Authorization header with requests for resources in + that space without receipt of another challenge from the server. + Similarly, when a client sends a request to a proxy, it may reuse a + userid and password in the Proxy-Authorization header field without + receiving another challenge from the proxy server. See section 4 for + security considerations associated with Basic authentication. + +3 Digest Access Authentication Scheme + +3.1 Introduction + +3.1.1 Purpose + + The protocol referred to as "HTTP/1.0" includes the specification for + a Basic Access Authentication scheme[1]. That scheme is not + considered to be a secure method of user authentication, as the user + name and password are passed over the network in an unencrypted form. + This section provides the specification for a scheme that does not + send the password in cleartext, referred to as "Digest Access + Authentication". + + The Digest Access Authentication scheme is not intended to be a + complete answer to the need for security in the World Wide Web. This + scheme provides no encryption of message content. The intent is + simply to create an access authentication method that avoids the most + serious flaws of Basic authentication. + +3.1.2 Overall Operation + + Like Basic Access Authentication, the Digest scheme is based on a + simple challenge-response paradigm. The Digest scheme challenges + using a nonce value. A valid response contains a checksum (by + + + +Franks, et al. Standards Track [Page 6] + +RFC 2617 HTTP Authentication June 1999 + + + default, the MD5 checksum) of the username, the password, the given + nonce value, the HTTP method, and the requested URI. In this way, the + password is never sent in the clear. Just as with the Basic scheme, + the username and password must be prearranged in some fashion not + addressed by this document. + +3.1.3 Representation of digest values + + An optional header allows the server to specify the algorithm used to + create the checksum or digest. By default the MD5 algorithm is used + and that is the only algorithm described in this document. + + For the purposes of this document, an MD5 digest of 128 bits is + represented as 32 ASCII printable characters. The bits in the 128 bit + digest are converted from most significant to least significant bit, + four bits at a time to their ASCII presentation as follows. Each four + bits is represented by its familiar hexadecimal notation from the + characters 0123456789abcdef. That is, binary 0000 gets represented by + the character '0', 0001, by '1', and so on up to the representation + of 1111 as 'f'. + +3.1.4 Limitations + + The Digest authentication scheme described in this document suffers + from many known limitations. It is intended as a replacement for + Basic authentication and nothing more. It is a password-based system + and (on the server side) suffers from all the same problems of any + password system. In particular, no provision is made in this protocol + for the initial secure arrangement between user and server to + establish the user's password. + + Users and implementors should be aware that this protocol is not as + secure as Kerberos, and not as secure as any client-side private-key + scheme. Nevertheless it is better than nothing, better than what is + commonly used with telnet and ftp, and better than Basic + authentication. + +3.2 Specification of Digest Headers + + The Digest Access Authentication scheme is conceptually similar to + the Basic scheme. The formats of the modified WWW-Authenticate header + line and the Authorization header line are specified below. In + addition, a new header, Authentication-Info, is specified. + + + + + + + + +Franks, et al. Standards Track [Page 7] + +RFC 2617 HTTP Authentication June 1999 + + +3.2.1 The WWW-Authenticate Response Header + + If a server receives a request for an access-protected object, and an + acceptable Authorization header is not sent, the server responds with + a "401 Unauthorized" status code, and a WWW-Authenticate header as + per the framework defined above, which for the digest scheme is + utilized as follows: + + challenge = "Digest" digest-challenge + + digest-challenge = 1#( realm | [ domain ] | nonce | + [ opaque ] |[ stale ] | [ algorithm ] | + [ qop-options ] | [auth-param] ) + + + domain = "domain" "=" <"> URI ( 1*SP URI ) <"> + URI = absoluteURI | abs_path + nonce = "nonce" "=" nonce-value + nonce-value = quoted-string + opaque = "opaque" "=" quoted-string + stale = "stale" "=" ( "true" | "false" ) + algorithm = "algorithm" "=" ( "MD5" | "MD5-sess" | + token ) + qop-options = "qop" "=" <"> 1#qop-value <"> + qop-value = "auth" | "auth-int" | token + + The meanings of the values of the directives used above are as + follows: + + realm + A string to be displayed to users so they know which username and + password to use. This string should contain at least the name of + the host performing the authentication and might additionally + indicate the collection of users who might have access. An example + might be "registered_users@gotham.news.com". + + domain + A quoted, space-separated list of URIs, as specified in RFC XURI + [7], that define the protection space. If a URI is an abs_path, it + is relative to the canonical root URL (see section 1.2 above) of + the server being accessed. An absoluteURI in this list may refer to + a different server than the one being accessed. The client can use + this list to determine the set of URIs for which the same + authentication information may be sent: any URI that has a URI in + this list as a prefix (after both have been made absolute) may be + assumed to be in the same protection space. If this directive is + omitted or its value is empty, the client should assume that the + protection space consists of all URIs on the responding server. + + + +Franks, et al. Standards Track [Page 8] + +RFC 2617 HTTP Authentication June 1999 + + + This directive is not meaningful in Proxy-Authenticate headers, for + which the protection space is always the entire proxy; if present + it should be ignored. + + nonce + A server-specified data string which should be uniquely generated + each time a 401 response is made. It is recommended that this + string be base64 or hexadecimal data. Specifically, since the + string is passed in the header lines as a quoted string, the + double-quote character is not allowed. + + The contents of the nonce are implementation dependent. The quality + of the implementation depends on a good choice. A nonce might, for + example, be constructed as the base 64 encoding of + + time-stamp H(time-stamp ":" ETag ":" private-key) + + where time-stamp is a server-generated time or other non-repeating + value, ETag is the value of the HTTP ETag header associated with + the requested entity, and private-key is data known only to the + server. With a nonce of this form a server would recalculate the + hash portion after receiving the client authentication header and + reject the request if it did not match the nonce from that header + or if the time-stamp value is not recent enough. In this way the + server can limit the time of the nonce's validity. The inclusion of + the ETag prevents a replay request for an updated version of the + resource. (Note: including the IP address of the client in the + nonce would appear to offer the server the ability to limit the + reuse of the nonce to the same client that originally got it. + However, that would break proxy farms, where requests from a single + user often go through different proxies in the farm. Also, IP + address spoofing is not that hard.) + + An implementation might choose not to accept a previously used + nonce or a previously used digest, in order to protect against a + replay attack. Or, an implementation might choose to use one-time + nonces or digests for POST or PUT requests and a time-stamp for GET + requests. For more details on the issues involved see section 4. + of this document. + + The nonce is opaque to the client. + + opaque + A string of data, specified by the server, which should be returned + by the client unchanged in the Authorization header of subsequent + requests with URIs in the same protection space. It is recommended + that this string be base64 or hexadecimal data. + + + + +Franks, et al. Standards Track [Page 9] + +RFC 2617 HTTP Authentication June 1999 + + + stale + A flag, indicating that the previous request from the client was + rejected because the nonce value was stale. If stale is TRUE + (case-insensitive), the client may wish to simply retry the request + with a new encrypted response, without reprompting the user for a + new username and password. The server should only set stale to TRUE + if it receives a request for which the nonce is invalid but with a + valid digest for that nonce (indicating that the client knows the + correct username/password). If stale is FALSE, or anything other + than TRUE, or the stale directive is not present, the username + and/or password are invalid, and new values must be obtained. + + algorithm + A string indicating a pair of algorithms used to produce the digest + and a checksum. If this is not present it is assumed to be "MD5". + If the algorithm is not understood, the challenge should be ignored + (and a different one used, if there is more than one). + + In this document the string obtained by applying the digest + algorithm to the data "data" with secret "secret" will be denoted + by KD(secret, data), and the string obtained by applying the + checksum algorithm to the data "data" will be denoted H(data). The + notation unq(X) means the value of the quoted-string X without the + surrounding quotes. + + For the "MD5" and "MD5-sess" algorithms + + H(data) = MD5(data) + + and + + KD(secret, data) = H(concat(secret, ":", data)) + + i.e., the digest is the MD5 of the secret concatenated with a colon + concatenated with the data. The "MD5-sess" algorithm is intended to + allow efficient 3rd party authentication servers; for the + difference in usage, see the description in section 3.2.2.2. + + qop-options + This directive is optional, but is made so only for backward + compatibility with RFC 2069 [6]; it SHOULD be used by all + implementations compliant with this version of the Digest scheme. + If present, it is a quoted string of one or more tokens indicating + the "quality of protection" values supported by the server. The + value "auth" indicates authentication; the value "auth-int" + indicates authentication with integrity protection; see the + + + + + +Franks, et al. Standards Track [Page 10] + +RFC 2617 HTTP Authentication June 1999 + + + descriptions below for calculating the response directive value for + the application of this choice. Unrecognized options MUST be + ignored. + + auth-param + This directive allows for future extensions. Any unrecognized + directive MUST be ignored. + +3.2.2 The Authorization Request Header + + The client is expected to retry the request, passing an Authorization + header line, which is defined according to the framework above, + utilized as follows. + + credentials = "Digest" digest-response + digest-response = 1#( username | realm | nonce | digest-uri + | response | [ algorithm ] | [cnonce] | + [opaque] | [message-qop] | + [nonce-count] | [auth-param] ) + + username = "username" "=" username-value + username-value = quoted-string + digest-uri = "uri" "=" digest-uri-value + digest-uri-value = request-uri ; As specified by HTTP/1.1 + message-qop = "qop" "=" qop-value + cnonce = "cnonce" "=" cnonce-value + cnonce-value = nonce-value + nonce-count = "nc" "=" nc-value + nc-value = 8LHEX + response = "response" "=" request-digest + request-digest = <"> 32LHEX <"> + LHEX = "0" | "1" | "2" | "3" | + "4" | "5" | "6" | "7" | + "8" | "9" | "a" | "b" | + "c" | "d" | "e" | "f" + + The values of the opaque and algorithm fields must be those supplied + in the WWW-Authenticate response header for the entity being + requested. + + response + A string of 32 hex digits computed as defined below, which proves + that the user knows a password + + username + The user's name in the specified realm. + + + + + +Franks, et al. Standards Track [Page 11] + +RFC 2617 HTTP Authentication June 1999 + + + digest-uri + The URI from Request-URI of the Request-Line; duplicated here + because proxies are allowed to change the Request-Line in transit. + + qop + Indicates what "quality of protection" the client has applied to + the message. If present, its value MUST be one of the alternatives + the server indicated it supports in the WWW-Authenticate header. + These values affect the computation of the request-digest. Note + that this is a single token, not a quoted list of alternatives as + in WWW- Authenticate. This directive is optional in order to + preserve backward compatibility with a minimal implementation of + RFC 2069 [6], but SHOULD be used if the server indicated that qop + is supported by providing a qop directive in the WWW-Authenticate + header field. + + cnonce + This MUST be specified if a qop directive is sent (see above), and + MUST NOT be specified if the server did not send a qop directive in + the WWW-Authenticate header field. The cnonce-value is an opaque + quoted string value provided by the client and used by both client + and server to avoid chosen plaintext attacks, to provide mutual + authentication, and to provide some message integrity protection. + See the descriptions below of the calculation of the response- + digest and request-digest values. + + nonce-count + This MUST be specified if a qop directive is sent (see above), and + MUST NOT be specified if the server did not send a qop directive in + the WWW-Authenticate header field. The nc-value is the hexadecimal + count of the number of requests (including the current request) + that the client has sent with the nonce value in this request. For + example, in the first request sent in response to a given nonce + value, the client sends "nc=00000001". The purpose of this + directive is to allow the server to detect request replays by + maintaining its own copy of this count - if the same nc-value is + seen twice, then the request is a replay. See the description + below of the construction of the request-digest value. + + auth-param + This directive allows for future extensions. Any unrecognized + directive MUST be ignored. + + If a directive or its value is improper, or required directives are + missing, the proper response is 400 Bad Request. If the request- + digest is invalid, then a login failure should be logged, since + repeated login failures from a single client may indicate an attacker + attempting to guess passwords. + + + +Franks, et al. Standards Track [Page 12] + +RFC 2617 HTTP Authentication June 1999 + + + The definition of request-digest above indicates the encoding for its + value. The following definitions show how the value is computed. + +3.2.2.1 Request-Digest + + If the "qop" value is "auth" or "auth-int": + + request-digest = <"> < KD ( H(A1), unq(nonce-value) + ":" nc-value + ":" unq(cnonce-value) + ":" unq(qop-value) + ":" H(A2) + ) <"> + + If the "qop" directive is not present (this construction is for + compatibility with RFC 2069): + + request-digest = + <"> < KD ( H(A1), unq(nonce-value) ":" H(A2) ) > + <"> + + See below for the definitions for A1 and A2. + +3.2.2.2 A1 + + If the "algorithm" directive's value is "MD5" or is unspecified, then + A1 is: + + A1 = unq(username-value) ":" unq(realm-value) ":" passwd + + where + + passwd = < user's password > + + If the "algorithm" directive's value is "MD5-sess", then A1 is + calculated only once - on the first request by the client following + receipt of a WWW-Authenticate challenge from the server. It uses the + server nonce from that challenge, and the first client nonce value to + construct A1 as follows: + + A1 = H( unq(username-value) ":" unq(realm-value) + ":" passwd ) + ":" unq(nonce-value) ":" unq(cnonce-value) + + This creates a 'session key' for the authentication of subsequent + requests and responses which is different for each "authentication + session", thus limiting the amount of material hashed with any one + key. (Note: see further discussion of the authentication session in + + + +Franks, et al. Standards Track [Page 13] + +RFC 2617 HTTP Authentication June 1999 + + + section 3.3.) Because the server need only use the hash of the user + credentials in order to create the A1 value, this construction could + be used in conjunction with a third party authentication service so + that the web server would not need the actual password value. The + specification of such a protocol is beyond the scope of this + specification. + +3.2.2.3 A2 + + If the "qop" directive's value is "auth" or is unspecified, then A2 + is: + + A2 = Method ":" digest-uri-value + + If the "qop" value is "auth-int", then A2 is: + + A2 = Method ":" digest-uri-value ":" H(entity-body) + +3.2.2.4 Directive values and quoted-string + + Note that the value of many of the directives, such as "username- + value", are defined as a "quoted-string". However, the "unq" notation + indicates that surrounding quotation marks are removed in forming the + string A1. Thus if the Authorization header includes the fields + + username="Mufasa", realm=myhost@testrealm.com + + and the user Mufasa has password "Circle Of Life" then H(A1) would be + H(Mufasa:myhost@testrealm.com:Circle Of Life) with no quotation marks + in the digested string. + + No white space is allowed in any of the strings to which the digest + function H() is applied unless that white space exists in the quoted + strings or entity body whose contents make up the string to be + digested. For example, the string A1 illustrated above must be + + Mufasa:myhost@testrealm.com:Circle Of Life + + with no white space on either side of the colons, but with the white + space between the words used in the password value. Likewise, the + other strings digested by H() must not have white space on either + side of the colons which delimit their fields unless that white space + was in the quoted strings or entity body being digested. + + Also note that if integrity protection is applied (qop=auth-int), the + H(entity-body) is the hash of the entity body, not the message body - + it is computed before any transfer encoding is applied by the sender + + + + +Franks, et al. Standards Track [Page 14] + +RFC 2617 HTTP Authentication June 1999 + + + and after it has been removed by the recipient. Note that this + includes multipart boundaries and embedded headers in each part of + any multipart content-type. + +3.2.2.5 Various considerations + + The "Method" value is the HTTP request method as specified in section + 5.1.1 of [2]. The "request-uri" value is the Request-URI from the + request line as specified in section 5.1.2 of [2]. This may be "*", + an "absoluteURL" or an "abs_path" as specified in section 5.1.2 of + [2], but it MUST agree with the Request-URI. In particular, it MUST + be an "absoluteURL" if the Request-URI is an "absoluteURL". The + "cnonce-value" is an optional client-chosen value whose purpose is + to foil chosen plaintext attacks. + + The authenticating server must assure that the resource designated by + the "uri" directive is the same as the resource specified in the + Request-Line; if they are not, the server SHOULD return a 400 Bad + Request error. (Since this may be a symptom of an attack, server + implementers may want to consider logging such errors.) The purpose + of duplicating information from the request URL in this field is to + deal with the possibility that an intermediate proxy may alter the + client's Request-Line. This altered (but presumably semantically + equivalent) request would not result in the same digest as that + calculated by the client. + + Implementers should be aware of how authenticated transactions + interact with shared caches. The HTTP/1.1 protocol specifies that + when a shared cache (see section 13.7 of [2]) has received a request + containing an Authorization header and a response from relaying that + request, it MUST NOT return that response as a reply to any other + request, unless one of two Cache-Control (see section 14.9 of [2]) + directives was present in the response. If the original response + included the "must-revalidate" Cache-Control directive, the cache MAY + use the entity of that response in replying to a subsequent request, + but MUST first revalidate it with the origin server, using the + request headers from the new request to allow the origin server to + authenticate the new request. Alternatively, if the original response + included the "public" Cache-Control directive, the response entity + MAY be returned in reply to any subsequent request. + +3.2.3 The Authentication-Info Header + + The Authentication-Info header is used by the server to communicate + some information regarding the successful authentication in the + response. + + + + + +Franks, et al. Standards Track [Page 15] + +RFC 2617 HTTP Authentication June 1999 + + + AuthenticationInfo = "Authentication-Info" ":" auth-info + auth-info = 1#(nextnonce | [ message-qop ] + | [ response-auth ] | [ cnonce ] + | [nonce-count] ) + nextnonce = "nextnonce" "=" nonce-value + response-auth = "rspauth" "=" response-digest + response-digest = <"> *LHEX <"> + + The value of the nextnonce directive is the nonce the server wishes + the client to use for a future authentication response. The server + may send the Authentication-Info header with a nextnonce field as a + means of implementing one-time or otherwise changing nonces. If the + nextnonce field is present the client SHOULD use it when constructing + the Authorization header for its next request. Failure of the client + to do so may result in a request to re-authenticate from the server + with the "stale=TRUE". + + Server implementations should carefully consider the performance + implications of the use of this mechanism; pipelined requests will + not be possible if every response includes a nextnonce directive + that must be used on the next request received by the server. + Consideration should be given to the performance vs. security + tradeoffs of allowing an old nonce value to be used for a limited + time to permit request pipelining. Use of the nonce-count can + retain most of the security advantages of a new server nonce + without the deleterious affects on pipelining. + + message-qop + Indicates the "quality of protection" options applied to the + response by the server. The value "auth" indicates authentication; + the value "auth-int" indicates authentication with integrity + protection. The server SHOULD use the same value for the message- + qop directive in the response as was sent by the client in the + corresponding request. + + The optional response digest in the "response-auth" directive + supports mutual authentication -- the server proves that it knows the + user's secret, and with qop=auth-int also provides limited integrity + protection of the response. The "response-digest" value is calculated + as for the "request-digest" in the Authorization header, except that + if "qop=auth" or is not specified in the Authorization header for the + request, A2 is + + A2 = ":" digest-uri-value + + and if "qop=auth-int", then A2 is + + A2 = ":" digest-uri-value ":" H(entity-body) + + + +Franks, et al. Standards Track [Page 16] + +RFC 2617 HTTP Authentication June 1999 + + + where "digest-uri-value" is the value of the "uri" directive on the + Authorization header in the request. The "cnonce-value" and "nc- + value" MUST be the ones for the client request to which this message + is the response. The "response-auth", "cnonce", and "nonce-count" + directives MUST BE present if "qop=auth" or "qop=auth-int" is + specified. + + The Authentication-Info header is allowed in the trailer of an HTTP + message transferred via chunked transfer-coding. + +3.3 Digest Operation + + Upon receiving the Authorization header, the server may check its + validity by looking up the password that corresponds to the submitted + username. Then, the server must perform the same digest operation + (e.g., MD5) performed by the client, and compare the result to the + given request-digest value. + + Note that the HTTP server does not actually need to know the user's + cleartext password. As long as H(A1) is available to the server, the + validity of an Authorization header may be verified. + + The client response to a WWW-Authenticate challenge for a protection + space starts an authentication session with that protection space. + The authentication session lasts until the client receives another + WWW-Authenticate challenge from any server in the protection space. A + client should remember the username, password, nonce, nonce count and + opaque values associated with an authentication session to use to + construct the Authorization header in future requests within that + protection space. The Authorization header may be included + preemptively; doing so improves server efficiency and avoids extra + round trips for authentication challenges. The server may choose to + accept the old Authorization header information, even though the + nonce value included might not be fresh. Alternatively, the server + may return a 401 response with a new nonce value, causing the client + to retry the request; by specifying stale=TRUE with this response, + the server tells the client to retry with the new nonce, but without + prompting for a new username and password. + + Because the client is required to return the value of the opaque + directive given to it by the server for the duration of a session, + the opaque data may be used to transport authentication session state + information. (Note that any such use can also be accomplished more + easily and safely by including the state in the nonce.) For example, + a server could be responsible for authenticating content that + actually sits on another server. It would achieve this by having the + first 401 response include a domain directive whose value includes a + URI on the second server, and an opaque directive whose value + + + +Franks, et al. Standards Track [Page 17] + +RFC 2617 HTTP Authentication June 1999 + + + contains the state information. The client will retry the request, at + which time the server might respond with a 301/302 redirection, + pointing to the URI on the second server. The client will follow the + redirection, and pass an Authorization header , including the + data. + + As with the basic scheme, proxies must be completely transparent in + the Digest access authentication scheme. That is, they must forward + the WWW-Authenticate, Authentication-Info and Authorization headers + untouched. If a proxy wants to authenticate a client before a request + is forwarded to the server, it can be done using the Proxy- + Authenticate and Proxy-Authorization headers described in section 3.6 + below. + +3.4 Security Protocol Negotiation + + It is useful for a server to be able to know which security schemes a + client is capable of handling. + + It is possible that a server may want to require Digest as its + authentication method, even if the server does not know that the + client supports it. A client is encouraged to fail gracefully if the + server specifies only authentication schemes it cannot handle. + +3.5 Example + + The following example assumes that an access-protected document is + being requested from the server via a GET request. The URI of the + document is "http://www.nowhere.org/dir/index.html". Both client and + server know that the username for this document is "Mufasa", and the + password is "Circle Of Life" (with one space between each of the + three words). + + The first time the client requests the document, no Authorization + header is sent, so the server responds with: + + HTTP/1.1 401 Unauthorized + WWW-Authenticate: Digest + realm="testrealm@host.com", + qop="auth,auth-int", + nonce="dcd98b7102dd2f0e8b11d0f600bfb0c093", + opaque="5ccc069c403ebaf9f0171e9517f40e41" + + The client may prompt the user for the username and password, after + which it will respond with a new request, including the following + Authorization header: + + + + + +Franks, et al. Standards Track [Page 18] + +RFC 2617 HTTP Authentication June 1999 + + + Authorization: Digest username="Mufasa", + realm="testrealm@host.com", + nonce="dcd98b7102dd2f0e8b11d0f600bfb0c093", + uri="/dir/index.html", + qop=auth, + nc=00000001, + cnonce="0a4f113b", + response="6629fae49393a05397450978507c4ef1", + opaque="5ccc069c403ebaf9f0171e9517f40e41" + +3.6 Proxy-Authentication and Proxy-Authorization + + The digest authentication scheme may also be used for authenticating + users to proxies, proxies to proxies, or proxies to origin servers by + use of the Proxy-Authenticate and Proxy-Authorization headers. These + headers are instances of the Proxy-Authenticate and Proxy- + Authorization headers specified in sections 10.33 and 10.34 of the + HTTP/1.1 specification [2] and their behavior is subject to + restrictions described there. The transactions for proxy + authentication are very similar to those already described. Upon + receiving a request which requires authentication, the proxy/server + must issue the "407 Proxy Authentication Required" response with a + "Proxy-Authenticate" header. The digest-challenge used in the + Proxy-Authenticate header is the same as that for the WWW- + Authenticate header as defined above in section 3.2.1. + + The client/proxy must then re-issue the request with a Proxy- + Authorization header, with directives as specified for the + Authorization header in section 3.2.2 above. + + On subsequent responses, the server sends Proxy-Authentication-Info + with directives the same as those for the Authentication-Info header + field. + + Note that in principle a client could be asked to authenticate itself + to both a proxy and an end-server, but never in the same response. + +4 Security Considerations + +4.1 Authentication of Clients using Basic Authentication + + The Basic authentication scheme is not a secure method of user + authentication, nor does it in any way protect the entity, which is + transmitted in cleartext across the physical network used as the + carrier. HTTP does not prevent additional authentication schemes and + encryption mechanisms from being employed to increase security or the + addition of enhancements (such as schemes to use one-time passwords) + to Basic authentication. + + + +Franks, et al. Standards Track [Page 19] + +RFC 2617 HTTP Authentication June 1999 + + + The most serious flaw in Basic authentication is that it results in + the essentially cleartext transmission of the user's password over + the physical network. It is this problem which Digest Authentication + attempts to address. + + Because Basic authentication involves the cleartext transmission of + passwords it SHOULD NOT be used (without enhancements) to protect + sensitive or valuable information. + + A common use of Basic authentication is for identification purposes + -- requiring the user to provide a user name and password as a means + of identification, for example, for purposes of gathering accurate + usage statistics on a server. When used in this way it is tempting to + think that there is no danger in its use if illicit access to the + protected documents is not a major concern. This is only correct if + the server issues both user name and password to the users and in + particular does not allow the user to choose his or her own password. + The danger arises because naive users frequently reuse a single + password to avoid the task of maintaining multiple passwords. + + If a server permits users to select their own passwords, then the + threat is not only unauthorized access to documents on the server but + also unauthorized access to any other resources on other systems that + the user protects with the same password. Furthermore, in the + server's password database, many of the passwords may also be users' + passwords for other sites. The owner or administrator of such a + system could therefore expose all users of the system to the risk of + unauthorized access to all those sites if this information is not + maintained in a secure fashion. + + Basic Authentication is also vulnerable to spoofing by counterfeit + servers. If a user can be led to believe that he is connecting to a + host containing information protected by Basic authentication when, + in fact, he is connecting to a hostile server or gateway, then the + attacker can request a password, store it for later use, and feign an + error. This type of attack is not possible with Digest + Authentication. Server implementers SHOULD guard against the + possibility of this sort of counterfeiting by gateways or CGI + scripts. In particular it is very dangerous for a server to simply + turn over a connection to a gateway. That gateway can then use the + persistent connection mechanism to engage in multiple transactions + with the client while impersonating the original server in a way that + is not detectable by the client. + +4.2 Authentication of Clients using Digest Authentication + + Digest Authentication does not provide a strong authentication + mechanism, when compared to public key based mechanisms, for example. + + + +Franks, et al. Standards Track [Page 20] + +RFC 2617 HTTP Authentication June 1999 + + + However, it is significantly stronger than (e.g.) CRAM-MD5, which has + been proposed for use with LDAP [10], POP and IMAP (see RFC 2195 + [9]). It is intended to replace the much weaker and even more + dangerous Basic mechanism. + + Digest Authentication offers no confidentiality protection beyond + protecting the actual password. All of the rest of the request and + response are available to an eavesdropper. + + Digest Authentication offers only limited integrity protection for + the messages in either direction. If qop=auth-int mechanism is used, + those parts of the message used in the calculation of the WWW- + Authenticate and Authorization header field response directive values + (see section 3.2 above) are protected. Most header fields and their + values could be modified as a part of a man-in-the-middle attack. + + Many needs for secure HTTP transactions cannot be met by Digest + Authentication. For those needs TLS or SHTTP are more appropriate + protocols. In particular Digest authentication cannot be used for any + transaction requiring confidentiality protection. Nevertheless many + functions remain for which Digest authentication is both useful and + appropriate. Any service in present use that uses Basic should be + switched to Digest as soon as practical. + +4.3 Limited Use Nonce Values + + The Digest scheme uses a server-specified nonce to seed the + generation of the request-digest value (as specified in section + 3.2.2.1 above). As shown in the example nonce in section 3.2.1, the + server is free to construct the nonce such that it may only be used + from a particular client, for a particular resource, for a limited + period of time or number of uses, or any other restrictions. Doing + so strengthens the protection provided against, for example, replay + attacks (see 4.5). However, it should be noted that the method + chosen for generating and checking the nonce also has performance and + resource implications. For example, a server may choose to allow + each nonce value to be used only once by maintaining a record of + whether or not each recently issued nonce has been returned and + sending a next-nonce directive in the Authentication-Info header + field of every response. This protects against even an immediate + replay attack, but has a high cost checking nonce values, and perhaps + more important will cause authentication failures for any pipelined + requests (presumably returning a stale nonce indication). Similarly, + incorporating a request-specific element such as the Etag value for a + resource limits the use of the nonce to that version of the resource + and also defeats pipelining. Thus it may be useful to do so for + methods with side effects but have unacceptable performance for those + that do not. + + + +Franks, et al. Standards Track [Page 21] + +RFC 2617 HTTP Authentication June 1999 + + +4.4 Comparison of Digest with Basic Authentication + + Both Digest and Basic Authentication are very much on the weak end of + the security strength spectrum. But a comparison between the two + points out the utility, even necessity, of replacing Basic by Digest. + + The greatest threat to the type of transactions for which these + protocols are used is network snooping. This kind of transaction + might involve, for example, online access to a database whose use is + restricted to paying subscribers. With Basic authentication an + eavesdropper can obtain the password of the user. This not only + permits him to access anything in the database, but, often worse, + will permit access to anything else the user protects with the same + password. + + By contrast, with Digest Authentication the eavesdropper only gets + access to the transaction in question and not to the user's password. + The information gained by the eavesdropper would permit a replay + attack, but only with a request for the same document, and even that + may be limited by the server's choice of nonce. + +4.5 Replay Attacks + + A replay attack against Digest authentication would usually be + pointless for a simple GET request since an eavesdropper would + already have seen the only document he could obtain with a replay. + This is because the URI of the requested document is digested in the + client request and the server will only deliver that document. By + contrast under Basic Authentication once the eavesdropper has the + user's password, any document protected by that password is open to + him. + + Thus, for some purposes, it is necessary to protect against replay + attacks. A good Digest implementation can do this in various ways. + The server created "nonce" value is implementation dependent, but if + it contains a digest of the client IP, a time-stamp, the resource + ETag, and a private server key (as recommended above) then a replay + attack is not simple. An attacker must convince the server that the + request is coming from a false IP address and must cause the server + to deliver the document to an IP address different from the address + to which it believes it is sending the document. An attack can only + succeed in the period before the time-stamp expires. Digesting the + client IP and time-stamp in the nonce permits an implementation which + does not maintain state between transactions. + + For applications where no possibility of replay attack can be + tolerated the server can use one-time nonce values which will not be + honored for a second use. This requires the overhead of the server + + + +Franks, et al. Standards Track [Page 22] + +RFC 2617 HTTP Authentication June 1999 + + + remembering which nonce values have been used until the nonce time- + stamp (and hence the digest built with it) has expired, but it + effectively protects against replay attacks. + + An implementation must give special attention to the possibility of + replay attacks with POST and PUT requests. Unless the server employs + one-time or otherwise limited-use nonces and/or insists on the use of + the integrity protection of qop=auth-int, an attacker could replay + valid credentials from a successful request with counterfeit form + data or other message body. Even with the use of integrity protection + most metadata in header fields is not protected. Proper nonce + generation and checking provides some protection against replay of + previously used valid credentials, but see 4.8. + +4.6 Weakness Created by Multiple Authentication Schemes + + An HTTP/1.1 server may return multiple challenges with a 401 + (Authenticate) response, and each challenge may use a different + auth-scheme. A user agent MUST choose to use the strongest auth- + scheme it understands and request credentials from the user based + upon that challenge. + + Note that many browsers will only recognize Basic and will require + that it be the first auth-scheme presented. Servers should only + include Basic if it is minimally acceptable. + + When the server offers choices of authentication schemes using the + WWW-Authenticate header, the strength of the resulting authentication + is only as good as that of the of the weakest of the authentication + schemes. See section 4.8 below for discussion of particular attack + scenarios that exploit multiple authentication schemes. + +4.7 Online dictionary attacks + + If the attacker can eavesdrop, then it can test any overheard + nonce/response pairs against a list of common words. Such a list is + usually much smaller than the total number of possible passwords. The + cost of computing the response for each password on the list is paid + once for each challenge. + + The server can mitigate this attack by not allowing users to select + passwords that are in a dictionary. + + + + + + + + + +Franks, et al. Standards Track [Page 23] + +RFC 2617 HTTP Authentication June 1999 + + +4.8 Man in the Middle + + Both Basic and Digest authentication are vulnerable to "man in the + middle" (MITM) attacks, for example, from a hostile or compromised + proxy. Clearly, this would present all the problems of eavesdropping. + But it also offers some additional opportunities to the attacker. + + A possible man-in-the-middle attack would be to add a weak + authentication scheme to the set of choices, hoping that the client + will use one that exposes the user's credentials (e.g. password). For + this reason, the client should always use the strongest scheme that + it understands from the choices offered. + + An even better MITM attack would be to remove all offered choices, + replacing them with a challenge that requests only Basic + authentication, then uses the cleartext credentials from the Basic + authentication to authenticate to the origin server using the + stronger scheme it requested. A particularly insidious way to mount + such a MITM attack would be to offer a "free" proxy caching service + to gullible users. + + User agents should consider measures such as presenting a visual + indication at the time of the credentials request of what + authentication scheme is to be used, or remembering the strongest + authentication scheme ever requested by a server and produce a + warning message before using a weaker one. It might also be a good + idea for the user agent to be configured to demand Digest + authentication in general, or from specific sites. + + Or, a hostile proxy might spoof the client into making a request the + attacker wanted rather than one the client wanted. Of course, this is + still much harder than a comparable attack against Basic + Authentication. + +4.9 Chosen plaintext attacks + + With Digest authentication, a MITM or a malicious server can + arbitrarily choose the nonce that the client will use to compute the + response. This is called a "chosen plaintext" attack. The ability to + choose the nonce is known to make cryptanalysis much easier [8]. + + However, no way to analyze the MD5 one-way function used by Digest + using chosen plaintext is currently known. + + The countermeasure against this attack is for clients to be + configured to require the use of the optional "cnonce" directive; + this allows the client to vary the input to the hash in a way not + chosen by the attacker. + + + +Franks, et al. Standards Track [Page 24] + +RFC 2617 HTTP Authentication June 1999 + + +4.10 Precomputed dictionary attacks + + With Digest authentication, if the attacker can execute a chosen + plaintext attack, the attacker can precompute the response for many + common words to a nonce of its choice, and store a dictionary of + (response, password) pairs. Such precomputation can often be done in + parallel on many machines. It can then use the chosen plaintext + attack to acquire a response corresponding to that challenge, and + just look up the password in the dictionary. Even if most passwords + are not in the dictionary, some might be. Since the attacker gets to + pick the challenge, the cost of computing the response for each + password on the list can be amortized over finding many passwords. A + dictionary with 100 million password/response pairs would take about + 3.2 gigabytes of disk storage. + + The countermeasure against this attack is to for clients to be + configured to require the use of the optional "cnonce" directive. + +4.11 Batch brute force attacks + + With Digest authentication, a MITM can execute a chosen plaintext + attack, and can gather responses from many users to the same nonce. + It can then find all the passwords within any subset of password + space that would generate one of the nonce/response pairs in a single + pass over that space. It also reduces the time to find the first + password by a factor equal to the number of nonce/response pairs + gathered. This search of the password space can often be done in + parallel on many machines, and even a single machine can search large + subsets of the password space very quickly -- reports exist of + searching all passwords with six or fewer letters in a few hours. + + The countermeasure against this attack is to for clients to be + configured to require the use of the optional "cnonce" directive. + +4.12 Spoofing by Counterfeit Servers + + Basic Authentication is vulnerable to spoofing by counterfeit + servers. If a user can be led to believe that she is connecting to a + host containing information protected by a password she knows, when + in fact she is connecting to a hostile server, then the hostile + server can request a password, store it away for later use, and feign + an error. This type of attack is more difficult with Digest + Authentication -- but the client must know to demand that Digest + authentication be used, perhaps using some of the techniques + described above to counter "man-in-the-middle" attacks. Again, the + user can be helped in detecting this attack by a visual indication of + the authentication mechanism in use with appropriate guidance in + interpreting the implications of each scheme. + + + +Franks, et al. Standards Track [Page 25] + +RFC 2617 HTTP Authentication June 1999 + + +4.13 Storing passwords + + Digest authentication requires that the authenticating agent (usually + the server) store some data derived from the user's name and password + in a "password file" associated with a given realm. Normally this + might contain pairs consisting of username and H(A1), where H(A1) is + the digested value of the username, realm, and password as described + above. + + The security implications of this are that if this password file is + compromised, then an attacker gains immediate access to documents on + the server using this realm. Unlike, say a standard UNIX password + file, this information need not be decrypted in order to access + documents in the server realm associated with this file. On the other + hand, decryption, or more likely a brute force attack, would be + necessary to obtain the user's password. This is the reason that the + realm is part of the digested data stored in the password file. It + means that if one Digest authentication password file is compromised, + it does not automatically compromise others with the same username + and password (though it does expose them to brute force attack). + + There are two important security consequences of this. First the + password file must be protected as if it contained unencrypted + passwords, because for the purpose of accessing documents in its + realm, it effectively does. + + A second consequence of this is that the realm string should be + unique among all realms which any single user is likely to use. In + particular a realm string should include the name of the host doing + the authentication. The inability of the client to authenticate the + server is a weakness of Digest Authentication. + +4.14 Summary + + By modern cryptographic standards Digest Authentication is weak. But + for a large range of purposes it is valuable as a replacement for + Basic Authentication. It remedies some, but not all, weaknesses of + Basic Authentication. Its strength may vary depending on the + implementation. In particular the structure of the nonce (which is + dependent on the server implementation) may affect the ease of + mounting a replay attack. A range of server options is appropriate + since, for example, some implementations may be willing to accept the + server overhead of one-time nonces or digests to eliminate the + possibility of replay. Others may satisfied with a nonce like the one + recommended above restricted to a single IP address and a single ETag + or with a limited lifetime. + + + + + +Franks, et al. Standards Track [Page 26] + +RFC 2617 HTTP Authentication June 1999 + + + The bottom line is that *any* compliant implementation will be + relatively weak by cryptographic standards, but *any* compliant + implementation will be far superior to Basic Authentication. + +5 Sample implementation + + The following code implements the calculations of H(A1), H(A2), + request-digest and response-digest, and a test program which computes + the values used in the example of section 3.5. It uses the MD5 + implementation from RFC 1321. + + File "digcalc.h": + +#define HASHLEN 16 +typedef char HASH[HASHLEN]; +#define HASHHEXLEN 32 +typedef char HASHHEX[HASHHEXLEN+1]; +#define IN +#define OUT + +/* calculate H(A1) as per HTTP Digest spec */ +void DigestCalcHA1( + IN char * pszAlg, + IN char * pszUserName, + IN char * pszRealm, + IN char * pszPassword, + IN char * pszNonce, + IN char * pszCNonce, + OUT HASHHEX SessionKey + ); + +/* calculate request-digest/response-digest as per HTTP Digest spec */ +void DigestCalcResponse( + IN HASHHEX HA1, /* H(A1) */ + IN char * pszNonce, /* nonce from server */ + IN char * pszNonceCount, /* 8 hex digits */ + IN char * pszCNonce, /* client nonce */ + IN char * pszQop, /* qop-value: "", "auth", "auth-int" */ + IN char * pszMethod, /* method from the request */ + IN char * pszDigestUri, /* requested URL */ + IN HASHHEX HEntity, /* H(entity body) if qop="auth-int" */ + OUT HASHHEX Response /* request-digest or response-digest */ + ); + +File "digcalc.c": + +#include +#include + + + +Franks, et al. Standards Track [Page 27] + +RFC 2617 HTTP Authentication June 1999 + + +#include +#include "digcalc.h" + +void CvtHex( + IN HASH Bin, + OUT HASHHEX Hex + ) +{ + unsigned short i; + unsigned char j; + + for (i = 0; i < HASHLEN; i++) { + j = (Bin[i] >> 4) & 0xf; + if (j <= 9) + Hex[i*2] = (j + '0'); + else + Hex[i*2] = (j + 'a' - 10); + j = Bin[i] & 0xf; + if (j <= 9) + Hex[i*2+1] = (j + '0'); + else + Hex[i*2+1] = (j + 'a' - 10); + }; + Hex[HASHHEXLEN] = '\0'; +}; + +/* calculate H(A1) as per spec */ +void DigestCalcHA1( + IN char * pszAlg, + IN char * pszUserName, + IN char * pszRealm, + IN char * pszPassword, + IN char * pszNonce, + IN char * pszCNonce, + OUT HASHHEX SessionKey + ) +{ + MD5_CTX Md5Ctx; + HASH HA1; + + MD5Init(&Md5Ctx); + MD5Update(&Md5Ctx, pszUserName, strlen(pszUserName)); + MD5Update(&Md5Ctx, ":", 1); + MD5Update(&Md5Ctx, pszRealm, strlen(pszRealm)); + MD5Update(&Md5Ctx, ":", 1); + MD5Update(&Md5Ctx, pszPassword, strlen(pszPassword)); + MD5Final(HA1, &Md5Ctx); + if (stricmp(pszAlg, "md5-sess") == 0) { + + + +Franks, et al. Standards Track [Page 28] + +RFC 2617 HTTP Authentication June 1999 + + + MD5Init(&Md5Ctx); + MD5Update(&Md5Ctx, HA1, HASHLEN); + MD5Update(&Md5Ctx, ":", 1); + MD5Update(&Md5Ctx, pszNonce, strlen(pszNonce)); + MD5Update(&Md5Ctx, ":", 1); + MD5Update(&Md5Ctx, pszCNonce, strlen(pszCNonce)); + MD5Final(HA1, &Md5Ctx); + }; + CvtHex(HA1, SessionKey); +}; + +/* calculate request-digest/response-digest as per HTTP Digest spec */ +void DigestCalcResponse( + IN HASHHEX HA1, /* H(A1) */ + IN char * pszNonce, /* nonce from server */ + IN char * pszNonceCount, /* 8 hex digits */ + IN char * pszCNonce, /* client nonce */ + IN char * pszQop, /* qop-value: "", "auth", "auth-int" */ + IN char * pszMethod, /* method from the request */ + IN char * pszDigestUri, /* requested URL */ + IN HASHHEX HEntity, /* H(entity body) if qop="auth-int" */ + OUT HASHHEX Response /* request-digest or response-digest */ + ) +{ + MD5_CTX Md5Ctx; + HASH HA2; + HASH RespHash; + HASHHEX HA2Hex; + + // calculate H(A2) + MD5Init(&Md5Ctx); + MD5Update(&Md5Ctx, pszMethod, strlen(pszMethod)); + MD5Update(&Md5Ctx, ":", 1); + MD5Update(&Md5Ctx, pszDigestUri, strlen(pszDigestUri)); + if (stricmp(pszQop, "auth-int") == 0) { + MD5Update(&Md5Ctx, ":", 1); + MD5Update(&Md5Ctx, HEntity, HASHHEXLEN); + }; + MD5Final(HA2, &Md5Ctx); + CvtHex(HA2, HA2Hex); + + // calculate response + MD5Init(&Md5Ctx); + MD5Update(&Md5Ctx, HA1, HASHHEXLEN); + MD5Update(&Md5Ctx, ":", 1); + MD5Update(&Md5Ctx, pszNonce, strlen(pszNonce)); + MD5Update(&Md5Ctx, ":", 1); + if (*pszQop) { + + + +Franks, et al. Standards Track [Page 29] + +RFC 2617 HTTP Authentication June 1999 + + + MD5Update(&Md5Ctx, pszNonceCount, strlen(pszNonceCount)); + MD5Update(&Md5Ctx, ":", 1); + MD5Update(&Md5Ctx, pszCNonce, strlen(pszCNonce)); + MD5Update(&Md5Ctx, ":", 1); + MD5Update(&Md5Ctx, pszQop, strlen(pszQop)); + MD5Update(&Md5Ctx, ":", 1); + }; + MD5Update(&Md5Ctx, HA2Hex, HASHHEXLEN); + MD5Final(RespHash, &Md5Ctx); + CvtHex(RespHash, Response); +}; + +File "digtest.c": + + +#include +#include "digcalc.h" + +void main(int argc, char ** argv) { + + char * pszNonce = "dcd98b7102dd2f0e8b11d0f600bfb0c093"; + char * pszCNonce = "0a4f113b"; + char * pszUser = "Mufasa"; + char * pszRealm = "testrealm@host.com"; + char * pszPass = "Circle Of Life"; + char * pszAlg = "md5"; + char szNonceCount[9] = "00000001"; + char * pszMethod = "GET"; + char * pszQop = "auth"; + char * pszURI = "/dir/index.html"; + HASHHEX HA1; + HASHHEX HA2 = ""; + HASHHEX Response; + + DigestCalcHA1(pszAlg, pszUser, pszRealm, pszPass, pszNonce, +pszCNonce, HA1); + DigestCalcResponse(HA1, pszNonce, szNonceCount, pszCNonce, pszQop, + pszMethod, pszURI, HA2, Response); + printf("Response = %s\n", Response); +}; + + + + + + + + + + + +Franks, et al. Standards Track [Page 30] + +RFC 2617 HTTP Authentication June 1999 + + +6 Acknowledgments + + Eric W. Sink, of AbiSource, Inc., was one of the original authors + before the specification underwent substantial revision. + + In addition to the authors, valuable discussion instrumental in + creating this document has come from Peter J. Churchyard, Ned Freed, + and David M. Kristol. + + Jim Gettys and Larry Masinter edited this document for update. + +7 References + + [1] Berners-Lee, T., Fielding, R. and H. Frystyk, "Hypertext + Transfer Protocol -- HTTP/1.0", RFC 1945, May 1996. + + [2] Fielding, R., Gettys, J., Mogul, J., Frysyk, H., Masinter, L., + Leach, P. and T. Berners-Lee, "Hypertext Transfer Protocol -- + HTTP/1.1", RFC 2616, June 1999. + + [3] Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, April + 1992. + + [4] Freed, N. and N. Borenstein. "Multipurpose Internet Mail + Extensions (MIME) Part One: Format of Internet Message Bodies", + RFC 2045, November 1996. + + [5] Dierks, T. and C. Allen "The TLS Protocol, Version 1.0", RFC + 2246, January 1999. + + [6] Franks, J., Hallam-Baker, P., Hostetler, J., Leach, P., + Luotonen, A., Sink, E. and L. Stewart, "An Extension to HTTP : + Digest Access Authentication", RFC 2069, January 1997. + + [7] Berners Lee, T, Fielding, R. and L. Masinter, "Uniform Resource + Identifiers (URI): Generic Syntax", RFC 2396, August 1998. + + [8] Kaliski, B.,Robshaw, M., "Message Authentication with MD5", + CryptoBytes, Sping 1995, RSA Inc, + (http://www.rsa.com/rsalabs/pubs/cryptobytes/spring95/md5.htm) + + [9] Klensin, J., Catoe, R. and P. Krumviede, "IMAP/POP AUTHorize + Extension for Simple Challenge/Response", RFC 2195, September + 1997. + + [10] Morgan, B., Alvestrand, H., Hodges, J., Wahl, M., + "Authentication Methods for LDAP", Work in Progress. + + + + +Franks, et al. Standards Track [Page 31] + +RFC 2617 HTTP Authentication June 1999 + + +8 Authors' Addresses + + John Franks + Professor of Mathematics + Department of Mathematics + Northwestern University + Evanston, IL 60208-2730, USA + + EMail: john@math.nwu.edu + + + Phillip M. Hallam-Baker + Principal Consultant + Verisign Inc. + 301 Edgewater Place + Suite 210 + Wakefield MA 01880, USA + + EMail: pbaker@verisign.com + + + Jeffery L. Hostetler + Software Craftsman + AbiSource, Inc. + 6 Dunlap Court + Savoy, IL 61874 + + EMail: jeff@AbiSource.com + + + Scott D. Lawrence + Agranat Systems, Inc. + 5 Clocktower Place, Suite 400 + Maynard, MA 01754, USA + + EMail: lawrence@agranat.com + + + Paul J. Leach + Microsoft Corporation + 1 Microsoft Way + Redmond, WA 98052, USA + + EMail: paulle@microsoft.com + + + + + + + +Franks, et al. Standards Track [Page 32] + +RFC 2617 HTTP Authentication June 1999 + + + Ari Luotonen + Member of Technical Staff + Netscape Communications Corporation + 501 East Middlefield Road + Mountain View, CA 94043, USA + + + Lawrence C. Stewart + Open Market, Inc. + 215 First Street + Cambridge, MA 02142, USA + + EMail: stewart@OpenMarket.com + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Franks, et al. Standards Track [Page 33] + +RFC 2617 HTTP Authentication June 1999 + + +9. Full Copyright Statement + + Copyright (C) The Internet Society (1999). All Rights Reserved. + + This document and translations of it may be copied and furnished to + others, and derivative works that comment on or otherwise explain it + or assist in its implementation may be prepared, copied, published + and distributed, in whole or in part, without restriction of any + kind, provided that the above copyright notice and this paragraph are + included on all such copies and derivative works. However, this + document itself may not be modified in any way, such as by removing + the copyright notice or references to the Internet Society or other + Internet organizations, except as needed for the purpose of + developing Internet standards in which case the procedures for + copyrights defined in the Internet Standards process must be + followed, or as required to translate it into languages other than + English. + + The limited permissions granted above are perpetual and will not be + revoked by the Internet Society or its successors or assigns. + + This document and the information contained herein is provided on an + "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING + TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING + BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION + HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF + MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Acknowledgement + + Funding for the RFC Editor function is currently provided by the + Internet Society. + + + + + + + + + + + + + + + + + + + +Franks, et al. Standards Track [Page 34] + diff --git a/docs/rfc6749.txt b/docs/rfc6749.txt new file mode 100644 index 0000000..5a0046c --- /dev/null +++ b/docs/rfc6749.txt @@ -0,0 +1,4259 @@ + + + + + + +Internet Engineering Task Force (IETF) D. Hardt, Ed. +Request for Comments: 6749 Microsoft +Obsoletes: 5849 October 2012 +Category: Standards Track +ISSN: 2070-1721 + + + The OAuth 2.0 Authorization Framework + +Abstract + + 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. + +Status of This Memo + + This is an Internet Standards Track document. + + This document is a product of the Internet Engineering Task Force + (IETF). It represents the consensus of the IETF community. It has + received public review and has been approved for publication by the + Internet Engineering Steering Group (IESG). Further information on + Internet Standards is available in Section 2 of RFC 5741. + + Information about the current status of this document, any errata, + and how to provide feedback on it may be obtained at + http://www.rfc-editor.org/info/rfc6749. + +Copyright Notice + + Copyright (c) 2012 IETF Trust and the persons identified as the + document authors. All rights reserved. + + This document is subject to BCP 78 and the IETF Trust's Legal + Provisions Relating to IETF Documents + (http://trustee.ietf.org/license-info) 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. Code Components extracted from this document must + include Simplified BSD License text as described in Section 4.e of + the Trust Legal Provisions and are provided without warranty as + described in the Simplified BSD License. + + + + +Hardt Standards Track [Page 1] + +RFC 6749 OAuth 2.0 October 2012 + + +Table of Contents + + 1. Introduction ....................................................4 + 1.1. Roles ......................................................6 + 1.2. Protocol Flow ..............................................7 + 1.3. Authorization Grant ........................................8 + 1.3.1. Authorization Code ..................................8 + 1.3.2. Implicit ............................................8 + 1.3.3. Resource Owner Password Credentials .................9 + 1.3.4. Client Credentials ..................................9 + 1.4. Access Token ..............................................10 + 1.5. Refresh Token .............................................10 + 1.6. TLS Version ...............................................12 + 1.7. HTTP Redirections .........................................12 + 1.8. Interoperability ..........................................12 + 1.9. Notational Conventions ....................................13 + 2. Client Registration ............................................13 + 2.1. Client Types ..............................................14 + 2.2. Client Identifier .........................................15 + 2.3. Client Authentication .....................................16 + 2.3.1. Client Password ....................................16 + 2.3.2. Other Authentication Methods .......................17 + 2.4. Unregistered Clients ......................................17 + 3. Protocol Endpoints .............................................18 + 3.1. Authorization Endpoint ....................................18 + 3.1.1. Response Type ......................................19 + 3.1.2. Redirection Endpoint ...............................19 + 3.2. Token Endpoint ............................................21 + 3.2.1. Client Authentication ..............................22 + 3.3. Access Token Scope ........................................23 + 4. Obtaining Authorization ........................................23 + 4.1. Authorization Code Grant ..................................24 + 4.1.1. Authorization Request ..............................25 + 4.1.2. Authorization Response .............................26 + 4.1.3. Access Token Request ...............................29 + 4.1.4. Access Token Response ..............................30 + 4.2. Implicit Grant ............................................31 + 4.2.1. Authorization Request ..............................33 + 4.2.2. Access Token Response ..............................35 + 4.3. Resource Owner Password Credentials Grant .................37 + 4.3.1. Authorization Request and Response .................39 + 4.3.2. Access Token Request ...............................39 + 4.3.3. Access Token Response ..............................40 + 4.4. Client Credentials Grant ..................................40 + 4.4.1. Authorization Request and Response .................41 + 4.4.2. Access Token Request ...............................41 + 4.4.3. Access Token Response ..............................42 + 4.5. Extension Grants ..........................................42 + + + +Hardt Standards Track [Page 2] + +RFC 6749 OAuth 2.0 October 2012 + + + 5. Issuing an Access Token ........................................43 + 5.1. Successful Response .......................................43 + 5.2. Error Response ............................................45 + 6. Refreshing an Access Token .....................................47 + 7. Accessing Protected Resources ..................................48 + 7.1. Access Token Types ........................................49 + 7.2. Error Response ............................................49 + 8. Extensibility ..................................................50 + 8.1. Defining Access Token Types ...............................50 + 8.2. Defining New Endpoint Parameters ..........................50 + 8.3. Defining New Authorization Grant Types ....................51 + 8.4. Defining New Authorization Endpoint Response Types ........51 + 8.5. Defining Additional Error Codes ...........................51 + 9. Native Applications ............................................52 + 10. Security Considerations .......................................53 + 10.1. Client Authentication ....................................53 + 10.2. Client Impersonation .....................................54 + 10.3. Access Tokens ............................................55 + 10.4. Refresh Tokens ...........................................55 + 10.5. Authorization Codes ......................................56 + 10.6. Authorization Code Redirection URI Manipulation ..........56 + 10.7. Resource Owner Password Credentials ......................57 + 10.8. Request Confidentiality ..................................58 + 10.9. Ensuring Endpoint Authenticity ...........................58 + 10.10. Credentials-Guessing Attacks ............................58 + 10.11. Phishing Attacks ........................................58 + 10.12. Cross-Site Request Forgery ..............................59 + 10.13. Clickjacking ............................................60 + 10.14. Code Injection and Input Validation .....................60 + 10.15. Open Redirectors ........................................60 + 10.16. Misuse of Access Token to Impersonate Resource + Owner in Implicit Flow ..................................61 + 11. IANA Considerations ...........................................62 + 11.1. OAuth Access Token Types Registry ........................62 + 11.1.1. Registration Template .............................62 + 11.2. OAuth Parameters Registry ................................63 + 11.2.1. Registration Template .............................63 + 11.2.2. Initial Registry Contents .........................64 + 11.3. OAuth Authorization Endpoint Response Types Registry .....66 + 11.3.1. Registration Template .............................66 + 11.3.2. Initial Registry Contents .........................67 + 11.4. OAuth Extensions Error Registry ..........................67 + 11.4.1. Registration Template .............................68 + 12. References ....................................................68 + 12.1. Normative References .....................................68 + 12.2. Informative References ...................................70 + + + + + +Hardt Standards Track [Page 3] + +RFC 6749 OAuth 2.0 October 2012 + + + Appendix A. Augmented Backus-Naur Form (ABNF) Syntax ..............71 + A.1. "client_id" Syntax ........................................71 + A.2. "client_secret" Syntax ....................................71 + A.3. "response_type" Syntax ....................................71 + A.4. "scope" Syntax ............................................72 + A.5. "state" Syntax ............................................72 + A.6. "redirect_uri" Syntax .....................................72 + A.7. "error" Syntax ............................................72 + A.8. "error_description" Syntax ................................72 + A.9. "error_uri" Syntax ........................................72 + A.10. "grant_type" Syntax .......................................73 + A.11. "code" Syntax .............................................73 + A.12. "access_token" Syntax .....................................73 + A.13. "token_type" Syntax .......................................73 + A.14. "expires_in" Syntax .......................................73 + A.15. "username" Syntax .........................................73 + A.16. "password" Syntax .........................................73 + A.17. "refresh_token" Syntax ....................................74 + A.18. Endpoint Parameter Syntax .................................74 + Appendix B. Use of application/x-www-form-urlencoded Media Type ...74 + Appendix C. Acknowledgements ......................................75 + +1. Introduction + + In the traditional client-server authentication model, the client + requests an access-restricted resource (protected resource) on the + server by authenticating with the server using the resource owner's + credentials. In order to provide third-party applications access to + restricted resources, the resource owner shares its credentials with + the third party. This creates several problems and limitations: + + o Third-party applications are required to store the resource + owner's credentials for future use, typically a password in + clear-text. + + o Servers are required to support password authentication, despite + the security weaknesses inherent in passwords. + + o Third-party applications gain overly broad access to the resource + owner's protected resources, leaving resource owners without any + ability to restrict duration or access to a limited subset of + resources. + + o Resource owners cannot revoke access to an individual third party + without revoking access to all third parties, and must do so by + changing the third party's password. + + + + + +Hardt Standards Track [Page 4] + +RFC 6749 OAuth 2.0 October 2012 + + + o Compromise of any third-party application results in compromise of + the end-user's password and all of the data protected by that + password. + + OAuth addresses these issues by introducing an authorization layer + and separating the role of the client from that of the resource + owner. In OAuth, the client requests access to resources controlled + by the resource owner and hosted by the resource server, and is + issued a different set of credentials than those of the resource + owner. + + Instead of using the resource owner's credentials to access protected + resources, the client obtains an access token -- a string denoting a + specific scope, lifetime, and other access attributes. Access tokens + are issued to third-party clients by an authorization server with the + approval of the resource owner. The client uses the access token to + access the protected resources hosted by the resource server. + + For example, an end-user (resource owner) can grant a printing + service (client) access to her protected photos stored at a photo- + sharing service (resource server), without sharing her username and + password with the printing service. Instead, she authenticates + directly with a server trusted by the photo-sharing service + (authorization server), which issues the printing service delegation- + specific credentials (access token). + + This specification is designed for use with HTTP ([RFC2616]). The + use of OAuth over any protocol other than HTTP is out of scope. + + The OAuth 1.0 protocol ([RFC5849]), published as an informational + document, was the result of a small ad hoc community effort. This + Standards Track specification builds on the OAuth 1.0 deployment + experience, as well as additional use cases and extensibility + requirements gathered from the wider IETF community. The OAuth 2.0 + protocol is not backward compatible with OAuth 1.0. The two versions + may co-exist on the network, and implementations may choose to + support both. However, it is the intention of this specification + that new implementations support OAuth 2.0 as specified in this + document and that OAuth 1.0 is used only to support existing + deployments. The OAuth 2.0 protocol shares very few implementation + details with the OAuth 1.0 protocol. Implementers familiar with + OAuth 1.0 should approach this document without any assumptions as to + its structure and details. + + + + + + + + +Hardt Standards Track [Page 5] + +RFC 6749 OAuth 2.0 October 2012 + + +1.1. Roles + + OAuth defines four roles: + + resource owner + An entity capable of granting access to a protected resource. + When the resource owner is a person, it is referred to as an + end-user. + + resource server + The server hosting the protected resources, capable of accepting + and responding to protected resource requests using access tokens. + + client + An application making protected resource requests on behalf of the + resource owner and with its authorization. The term "client" does + not imply any particular implementation characteristics (e.g., + whether the application executes on a server, a desktop, or other + devices). + + authorization server + The server issuing access tokens to the client after successfully + authenticating the resource owner and obtaining authorization. + + The interaction between the authorization server and resource server + is beyond the scope of this specification. The authorization server + may be the same server as the resource server or a separate entity. + A single authorization server may issue access tokens accepted by + multiple resource servers. + + + + + + + + + + + + + + + + + + + + + + +Hardt Standards Track [Page 6] + +RFC 6749 OAuth 2.0 October 2012 + + +1.2. Protocol Flow + + +--------+ +---------------+ + | |--(A)- Authorization Request ->| Resource | + | | | Owner | + | |<-(B)-- Authorization Grant ---| | + | | +---------------+ + | | + | | +---------------+ + | |--(C)-- Authorization Grant -->| Authorization | + | Client | | Server | + | |<-(D)----- Access Token -------| | + | | +---------------+ + | | + | | +---------------+ + | |--(E)----- Access Token ------>| Resource | + | | | Server | + | |<-(F)--- Protected Resource ---| | + +--------+ +---------------+ + + Figure 1: Abstract Protocol Flow + + The abstract OAuth 2.0 flow illustrated in Figure 1 describes the + interaction between the four roles and includes the following steps: + + (A) The client requests authorization from the resource owner. The + authorization request can be made directly to the resource owner + (as shown), or preferably indirectly via the authorization + server as an intermediary. + + (B) The client receives an authorization grant, which is a + credential representing the resource owner's authorization, + expressed using one of four grant types defined in this + specification or using an extension grant type. The + authorization grant type depends on the method used by the + client to request authorization and the types supported by the + authorization server. + + (C) The client requests an access token by authenticating with the + authorization server and presenting the authorization grant. + + (D) The authorization server authenticates the client and validates + the authorization grant, and if valid, issues an access token. + + + + + + + + +Hardt Standards Track [Page 7] + +RFC 6749 OAuth 2.0 October 2012 + + + (E) The client requests the protected resource from the resource + server and authenticates by presenting the access token. + + (F) The resource server validates the access token, and if valid, + serves the request. + + The preferred method for the client to obtain an authorization grant + from the resource owner (depicted in steps (A) and (B)) is to use the + authorization server as an intermediary, which is illustrated in + Figure 3 in Section 4.1. + +1.3. Authorization Grant + + An authorization grant is a credential representing the resource + owner's authorization (to access its protected resources) used by the + client to obtain an access token. This specification defines four + grant types -- authorization code, implicit, resource owner password + credentials, and client credentials -- as well as an extensibility + mechanism for defining additional types. + +1.3.1. Authorization Code + + The authorization code is obtained by using an authorization server + as an intermediary between the client and resource owner. Instead of + requesting authorization directly from the resource owner, the client + directs the resource owner to an authorization server (via its + user-agent as defined in [RFC2616]), which in turn directs the + resource owner back to the client with the authorization code. + + Before directing the resource owner back to the client with the + authorization code, the authorization server authenticates the + resource owner and obtains authorization. Because the resource owner + only authenticates with the authorization server, the resource + owner's credentials are never shared with the client. + + The authorization code provides a few important security benefits, + such as the ability to authenticate the client, as well as the + transmission of the access token directly to the client without + passing it through the resource owner's user-agent and potentially + exposing it to others, including the resource owner. + +1.3.2. Implicit + + The implicit grant is a simplified authorization code flow optimized + for clients implemented in a browser using a scripting language such + as JavaScript. In the implicit flow, instead of issuing the client + an authorization code, the client is issued an access token directly + + + + +Hardt Standards Track [Page 8] + +RFC 6749 OAuth 2.0 October 2012 + + + (as the result of the resource owner authorization). The grant type + is implicit, as no intermediate credentials (such as an authorization + code) are issued (and later used to obtain an access token). + + When issuing an access token during the implicit grant flow, the + authorization server does not authenticate the client. In some + cases, the client identity can be verified via the redirection URI + used to deliver the access token to the client. The access token may + be exposed to the resource owner or other applications with access to + the resource owner's user-agent. + + Implicit grants improve the responsiveness and efficiency of some + clients (such as a client implemented as an in-browser application), + since it reduces the number of round trips required to obtain an + access token. However, this convenience should be weighed against + the security implications of using implicit grants, such as those + described in Sections 10.3 and 10.16, especially when the + authorization code grant type is available. + +1.3.3. Resource Owner Password Credentials + + The resource owner password credentials (i.e., username and password) + can be used directly as an authorization grant to obtain an access + token. The credentials should only be used when there is a high + degree of trust between the resource owner and the client (e.g., the + client is part of the device operating system or a highly privileged + application), and when other authorization grant types are not + available (such as an authorization code). + + Even though this grant type requires direct client access to the + resource owner credentials, the resource owner credentials are used + for a single request and are exchanged for an access token. This + grant type can eliminate the need for the client to store the + resource owner credentials for future use, by exchanging the + credentials with a long-lived access token or refresh token. + +1.3.4. Client Credentials + + The client credentials (or other forms of client authentication) can + be used as an authorization grant when the authorization scope is + limited to the protected resources under the control of the client, + or to protected resources previously arranged with the authorization + server. Client credentials are used as an authorization grant + typically when the client is acting on its own behalf (the client is + also the resource owner) or is requesting access to protected + resources based on an authorization previously arranged with the + authorization server. + + + + +Hardt Standards Track [Page 9] + +RFC 6749 OAuth 2.0 October 2012 + + +1.4. Access Token + + Access tokens are credentials used to access protected resources. An + access token is a string representing an authorization issued to the + client. The string is usually opaque to the client. Tokens + represent specific scopes and durations of access, granted by the + resource owner, and enforced by the resource server and authorization + server. + + The token may denote an identifier used to retrieve the authorization + information or may self-contain the authorization information in a + verifiable manner (i.e., a token string consisting of some data and a + signature). Additional authentication credentials, which are beyond + the scope of this specification, may be required in order for the + client to use a token. + + The access token provides an abstraction layer, replacing different + authorization constructs (e.g., username and password) with a single + token understood by the resource server. This abstraction enables + issuing access tokens more restrictive than the authorization grant + used to obtain them, as well as removing the resource server's need + to understand a wide range of authentication methods. + + Access tokens can have different formats, structures, and methods of + utilization (e.g., cryptographic properties) based on the resource + server security requirements. Access token attributes and the + methods used to access protected resources are beyond the scope of + this specification and are defined by companion specifications such + as [RFC6750]. + +1.5. Refresh Token + + Refresh tokens are credentials used to obtain access tokens. Refresh + tokens are issued to the client by the authorization server and are + used to obtain a new access token when the current access token + becomes invalid or expires, or to obtain additional access tokens + with identical or narrower scope (access tokens may have a shorter + lifetime and fewer permissions than authorized by the resource + owner). Issuing a refresh token is optional at the discretion of the + authorization server. If the authorization server issues a refresh + token, it is included when issuing an access token (i.e., step (D) in + Figure 1). + + A refresh token is a string representing the authorization granted to + the client by the resource owner. The string is usually opaque to + the client. The token denotes an identifier used to retrieve the + + + + + +Hardt Standards Track [Page 10] + +RFC 6749 OAuth 2.0 October 2012 + + + authorization information. Unlike access tokens, refresh tokens are + intended for use only with authorization servers and are never sent + to resource servers. + + +--------+ +---------------+ + | |--(A)------- Authorization Grant --------->| | + | | | | + | |<-(B)----------- Access Token -------------| | + | | & Refresh Token | | + | | | | + | | +----------+ | | + | |--(C)---- Access Token ---->| | | | + | | | | | | + | |<-(D)- Protected Resource --| Resource | | Authorization | + | Client | | Server | | Server | + | |--(E)---- Access Token ---->| | | | + | | | | | | + | |<-(F)- Invalid Token Error -| | | | + | | +----------+ | | + | | | | + | |--(G)----------- Refresh Token ----------->| | + | | | | + | |<-(H)----------- Access Token -------------| | + +--------+ & Optional Refresh Token +---------------+ + + Figure 2: Refreshing an Expired Access Token + + The flow illustrated in Figure 2 includes the following steps: + + (A) The client requests an access token by authenticating with the + authorization server and presenting an authorization grant. + + (B) The authorization server authenticates the client and validates + the authorization grant, and if valid, issues an access token + and a refresh token. + + (C) The client makes a protected resource request to the resource + server by presenting the access token. + + (D) The resource server validates the access token, and if valid, + serves the request. + + (E) Steps (C) and (D) repeat until the access token expires. If the + client knows the access token expired, it skips to step (G); + otherwise, it makes another protected resource request. + + (F) Since the access token is invalid, the resource server returns + an invalid token error. + + + +Hardt Standards Track [Page 11] + +RFC 6749 OAuth 2.0 October 2012 + + + (G) The client requests a new access token by authenticating with + the authorization server and presenting the refresh token. The + client authentication requirements are based on the client type + and on the authorization server policies. + + (H) The authorization server authenticates the client and validates + the refresh token, and if valid, issues a new access token (and, + optionally, a new refresh token). + + Steps (C), (D), (E), and (F) are outside the scope of this + specification, as described in Section 7. + +1.6. TLS Version + + Whenever Transport Layer Security (TLS) is used by this + specification, the appropriate version (or versions) of TLS will vary + over time, based on the widespread deployment and known security + vulnerabilities. At the time of this writing, TLS version 1.2 + [RFC5246] is the most recent version, but has a very limited + deployment base and might not be readily available for + implementation. TLS version 1.0 [RFC2246] is the most widely + deployed version and will provide the broadest interoperability. + + Implementations MAY also support additional transport-layer security + mechanisms that meet their security requirements. + +1.7. HTTP Redirections + + This specification makes extensive use of HTTP redirections, in which + the client or the authorization server directs the resource owner's + user-agent to another destination. While the examples in this + specification show the use of the HTTP 302 status code, any other + method available via the user-agent to accomplish this redirection is + allowed and is considered to be an implementation detail. + +1.8. Interoperability + + OAuth 2.0 provides a rich authorization framework with well-defined + security properties. However, as a rich and highly extensible + framework with many optional components, on its own, this + specification is likely to produce a wide range of non-interoperable + implementations. + + In addition, this specification leaves a few required components + partially or fully undefined (e.g., client registration, + authorization server capabilities, endpoint discovery). Without + + + + + +Hardt Standards Track [Page 12] + +RFC 6749 OAuth 2.0 October 2012 + + + these components, clients must be manually and specifically + configured against a specific authorization server and resource + server in order to interoperate. + + This framework was designed with the clear expectation that future + work will define prescriptive profiles and extensions necessary to + achieve full web-scale interoperability. + +1.9. Notational Conventions + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + specification are to be interpreted as described in [RFC2119]. + + This specification uses the Augmented Backus-Naur Form (ABNF) + notation of [RFC5234]. Additionally, the rule URI-reference is + included from "Uniform Resource Identifier (URI): Generic Syntax" + [RFC3986]. + + Certain security-related terms are to be understood in the sense + defined in [RFC4949]. These terms include, but are not limited to, + "attack", "authentication", "authorization", "certificate", + "confidentiality", "credential", "encryption", "identity", "sign", + "signature", "trust", "validate", and "verify". + + Unless otherwise noted, all the protocol parameter names and values + are case sensitive. + +2. Client Registration + + Before initiating the protocol, the client registers with the + authorization server. The means through which the client registers + with the authorization server are beyond the scope of this + specification but typically involve end-user interaction with an HTML + registration form. + + Client registration does not require a direct interaction between the + client and the authorization server. When supported by the + authorization server, registration can rely on other means for + establishing trust and obtaining the required client properties + (e.g., redirection URI, client type). For example, registration can + be accomplished using a self-issued or third-party-issued assertion, + or by the authorization server performing client discovery using a + trusted channel. + + + + + + + +Hardt Standards Track [Page 13] + +RFC 6749 OAuth 2.0 October 2012 + + + When registering a client, the client developer SHALL: + + o specify the client type as described in Section 2.1, + + o provide its client redirection URIs as described in Section 3.1.2, + and + + o include any other information required by the authorization server + (e.g., application name, website, description, logo image, the + acceptance of legal terms). + +2.1. Client Types + + OAuth defines two client types, based on their ability to + authenticate securely with the authorization server (i.e., ability to + maintain the confidentiality of their client credentials): + + confidential + Clients capable of maintaining the confidentiality of their + credentials (e.g., client implemented on a secure server with + restricted access to the client credentials), or capable of secure + client authentication using other means. + + public + Clients incapable of maintaining the confidentiality of their + credentials (e.g., clients executing on the device used by the + resource owner, such as an installed native application or a web + browser-based application), and incapable of secure client + authentication via any other means. + + The client type designation is based on the authorization server's + definition of secure authentication and its acceptable exposure + levels of client credentials. The authorization server SHOULD NOT + make assumptions about the client type. + + A client may be implemented as a distributed set of components, each + with a different client type and security context (e.g., a + distributed client with both a confidential server-based component + and a public browser-based component). If the authorization server + does not provide support for such clients or does not provide + guidance with regard to their registration, the client SHOULD + register each component as a separate client. + + + + + + + + + +Hardt Standards Track [Page 14] + +RFC 6749 OAuth 2.0 October 2012 + + + This specification has been designed around the following client + profiles: + + web application + A web application is a confidential client running on a web + server. Resource owners access the client via an HTML user + interface rendered in a user-agent on the device used by the + resource owner. The client credentials as well as any access + token issued to the client are stored on the web server and are + not exposed to or accessible by the resource owner. + + user-agent-based application + A user-agent-based application is a public client in which the + client code is downloaded from a web server and executes within a + user-agent (e.g., web browser) on the device used by the resource + owner. Protocol data and credentials are easily accessible (and + often visible) to the resource owner. Since such applications + reside within the user-agent, they can make seamless use of the + user-agent capabilities when requesting authorization. + + native application + A native application is a public client installed and executed on + the device used by the resource owner. Protocol data and + credentials are accessible to the resource owner. It is assumed + that any client authentication credentials included in the + application can be extracted. On the other hand, dynamically + issued credentials such as access tokens or refresh tokens can + receive an acceptable level of protection. At a minimum, these + credentials are protected from hostile servers with which the + application may interact. On some platforms, these credentials + might be protected from other applications residing on the same + device. + +2.2. Client Identifier + + The authorization server issues the registered client a client + identifier -- a unique string representing the registration + information provided by the client. The client identifier is not a + secret; it is exposed to the resource owner and MUST NOT be used + alone for client authentication. The client identifier is unique to + the authorization server. + + The client identifier string size is left undefined by this + specification. The client should avoid making assumptions about the + identifier size. The authorization server SHOULD document the size + of any identifier it issues. + + + + + +Hardt Standards Track [Page 15] + +RFC 6749 OAuth 2.0 October 2012 + + +2.3. Client Authentication + + If the client type is confidential, the client and authorization + server establish a client authentication method suitable for the + security requirements of the authorization server. The authorization + server MAY accept any form of client authentication meeting its + security requirements. + + Confidential clients are typically issued (or establish) a set of + client credentials used for authenticating with the authorization + server (e.g., password, public/private key pair). + + The authorization server MAY establish a client authentication method + with public clients. However, the authorization server MUST NOT rely + on public client authentication for the purpose of identifying the + client. + + The client MUST NOT use more than one authentication method in each + request. + +2.3.1. Client Password + + Clients in possession of a client password MAY use the HTTP Basic + authentication scheme as defined in [RFC2617] to authenticate with + the authorization server. The client identifier is encoded using the + "application/x-www-form-urlencoded" encoding algorithm per + Appendix B, and the encoded value is used as the username; the client + password is encoded using the same algorithm and used as the + password. The authorization server MUST support the HTTP Basic + authentication scheme for authenticating clients that were issued a + client password. + + For example (with extra line breaks for display purposes only): + + Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3 + + Alternatively, the authorization server MAY support including the + client credentials in the request-body using the following + parameters: + + client_id + REQUIRED. The client identifier issued to the client during + the registration process described by Section 2.2. + + client_secret + REQUIRED. The client secret. The client MAY omit the + parameter if the client secret is an empty string. + + + + +Hardt Standards Track [Page 16] + +RFC 6749 OAuth 2.0 October 2012 + + + Including the client credentials in the request-body using the two + parameters is NOT RECOMMENDED and SHOULD be limited to clients unable + to directly utilize the HTTP Basic authentication scheme (or other + password-based HTTP authentication schemes). The parameters can only + be transmitted in the request-body and MUST NOT be included in the + request URI. + + For example, a request to refresh an access token (Section 6) using + the body parameters (with extra line breaks for display purposes + only): + + POST /token HTTP/1.1 + Host: server.example.com + Content-Type: application/x-www-form-urlencoded + + grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA + &client_id=s6BhdRkqt3&client_secret=7Fjfp0ZBr1KtDRbnfVdmIw + + The authorization server MUST require the use of TLS as described in + Section 1.6 when sending requests using password authentication. + + Since this client authentication method involves a password, the + authorization server MUST protect any endpoint utilizing it against + brute force attacks. + +2.3.2. Other Authentication Methods + + The authorization server MAY support any suitable HTTP authentication + scheme matching its security requirements. When using other + authentication methods, the authorization server MUST define a + mapping between the client identifier (registration record) and + authentication scheme. + +2.4. Unregistered Clients + + This specification does not exclude the use of unregistered clients. + However, the use of such clients is beyond the scope of this + specification and requires additional security analysis and review of + its interoperability impact. + + + + + + + + + + + + +Hardt Standards Track [Page 17] + +RFC 6749 OAuth 2.0 October 2012 + + +3. Protocol Endpoints + + The authorization process utilizes two authorization server endpoints + (HTTP resources): + + o Authorization endpoint - used by the client to obtain + authorization from the resource owner via user-agent redirection. + + o Token endpoint - used by the client to exchange an authorization + grant for an access token, typically with client authentication. + + As well as one client endpoint: + + o Redirection endpoint - used by the authorization server to return + responses containing authorization credentials to the client via + the resource owner user-agent. + + Not every authorization grant type utilizes both endpoints. + Extension grant types MAY define additional endpoints as needed. + +3.1. Authorization Endpoint + + The authorization endpoint is used to interact with the resource + owner and obtain an authorization grant. The authorization server + MUST first verify the identity of the resource owner. The way in + which the authorization server authenticates the resource owner + (e.g., username and password login, session cookies) is beyond the + scope of this specification. + + The means through which the client obtains the location of the + authorization endpoint are beyond the scope of this specification, + but the location is typically provided in the service documentation. + + The endpoint URI MAY include an "application/x-www-form-urlencoded" + formatted (per Appendix B) query component ([RFC3986] Section 3.4), + which MUST be retained when adding additional query parameters. The + endpoint URI MUST NOT include a fragment component. + + Since requests to the authorization endpoint result in user + authentication and the transmission of clear-text credentials (in the + HTTP response), the authorization server MUST require the use of TLS + as described in Section 1.6 when sending requests to the + authorization endpoint. + + The authorization server MUST support the use of the HTTP "GET" + method [RFC2616] for the authorization endpoint and MAY support the + use of the "POST" method as well. + + + + +Hardt Standards Track [Page 18] + +RFC 6749 OAuth 2.0 October 2012 + + + Parameters sent without a value MUST be treated as if they were + omitted from the request. The authorization server MUST ignore + unrecognized request parameters. Request and response parameters + MUST NOT be included more than once. + +3.1.1. Response Type + + The authorization endpoint is used by the authorization code grant + type and implicit grant type flows. The client informs the + authorization server of the desired grant type using the following + parameter: + + response_type + REQUIRED. The value MUST be one of "code" for requesting an + authorization code as described by Section 4.1.1, "token" for + requesting an access token (implicit grant) as described by + Section 4.2.1, or a registered extension value as described by + Section 8.4. + + Extension response types MAY contain a space-delimited (%x20) list of + values, where the order of values does not matter (e.g., response + type "a b" is the same as "b a"). The meaning of such composite + response types is defined by their respective specifications. + + If an authorization request is missing the "response_type" parameter, + or if the response type is not understood, the authorization server + MUST return an error response as described in Section 4.1.2.1. + +3.1.2. Redirection Endpoint + + After completing its interaction with the resource owner, the + authorization server directs the resource owner's user-agent back to + the client. The authorization server redirects the user-agent to the + client's redirection endpoint previously established with the + authorization server during the client registration process or when + making the authorization request. + + The redirection endpoint URI MUST be an absolute URI as defined by + [RFC3986] Section 4.3. The endpoint URI MAY include an + "application/x-www-form-urlencoded" formatted (per Appendix B) query + component ([RFC3986] Section 3.4), which MUST be retained when adding + additional query parameters. The endpoint URI MUST NOT include a + fragment component. + + + + + + + + +Hardt Standards Track [Page 19] + +RFC 6749 OAuth 2.0 October 2012 + + +3.1.2.1. Endpoint Request Confidentiality + + The redirection endpoint SHOULD require the use of TLS as described + in Section 1.6 when the requested response type is "code" or "token", + or when the redirection request will result in the transmission of + sensitive credentials over an open network. This specification does + not mandate the use of TLS because at the time of this writing, + requiring clients to deploy TLS is a significant hurdle for many + client developers. If TLS is not available, the authorization server + SHOULD warn the resource owner about the insecure endpoint prior to + redirection (e.g., display a message during the authorization + request). + + Lack of transport-layer security can have a severe impact on the + security of the client and the protected resources it is authorized + to access. The use of transport-layer security is particularly + critical when the authorization process is used as a form of + delegated end-user authentication by the client (e.g., third-party + sign-in service). + +3.1.2.2. Registration Requirements + + The authorization server MUST require the following clients to + register their redirection endpoint: + + o Public clients. + + o Confidential clients utilizing the implicit grant type. + + The authorization server SHOULD require all clients to register their + redirection endpoint prior to utilizing the authorization endpoint. + + The authorization server SHOULD require the client to provide the + complete redirection URI (the client MAY use the "state" request + parameter to achieve per-request customization). If requiring the + registration of the complete redirection URI is not possible, the + authorization server SHOULD require the registration of the URI + scheme, authority, and path (allowing the client to dynamically vary + only the query component of the redirection URI when requesting + authorization). + + The authorization server MAY allow the client to register multiple + redirection endpoints. + + Lack of a redirection URI registration requirement can enable an + attacker to use the authorization endpoint as an open redirector as + described in Section 10.15. + + + + +Hardt Standards Track [Page 20] + +RFC 6749 OAuth 2.0 October 2012 + + +3.1.2.3. Dynamic Configuration + + If multiple redirection URIs have been registered, if only part of + the redirection URI has been registered, or if no redirection URI has + been registered, the client MUST include a redirection URI with the + authorization request using the "redirect_uri" request parameter. + + When a redirection URI is included in an authorization request, the + authorization server MUST compare and match the value received + against at least one of the registered redirection URIs (or URI + components) as defined in [RFC3986] Section 6, if any redirection + URIs were registered. If the client registration included the full + redirection URI, the authorization server MUST compare the two URIs + using simple string comparison as defined in [RFC3986] Section 6.2.1. + +3.1.2.4. Invalid Endpoint + + If an authorization request fails validation due to a missing, + invalid, or mismatching redirection URI, the authorization server + SHOULD inform the resource owner of the error and MUST NOT + automatically redirect the user-agent to the invalid redirection URI. + +3.1.2.5. Endpoint Content + + The redirection request to the client's endpoint typically results in + an HTML document response, processed by the user-agent. If the HTML + response is served directly as the result of the redirection request, + any script included in the HTML document will execute with full + access to the redirection URI and the credentials it contains. + + The client SHOULD NOT include any third-party scripts (e.g., third- + party analytics, social plug-ins, ad networks) in the redirection + endpoint response. Instead, it SHOULD extract the credentials from + the URI and redirect the user-agent again to another endpoint without + exposing the credentials (in the URI or elsewhere). If third-party + scripts are included, the client MUST ensure that its own scripts + (used to extract and remove the credentials from the URI) will + execute first. + +3.2. Token Endpoint + + The token endpoint is used by the client to obtain an access token by + presenting its authorization grant or refresh token. The token + endpoint is used with every authorization grant except for the + implicit grant type (since an access token is issued directly). + + + + + + +Hardt Standards Track [Page 21] + +RFC 6749 OAuth 2.0 October 2012 + + + The means through which the client obtains the location of the token + endpoint are beyond the scope of this specification, but the location + is typically provided in the service documentation. + + The endpoint URI MAY include an "application/x-www-form-urlencoded" + formatted (per Appendix B) query component ([RFC3986] Section 3.4), + which MUST be retained when adding additional query parameters. The + endpoint URI MUST NOT include a fragment component. + + Since requests to the token endpoint result in the transmission of + clear-text credentials (in the HTTP request and response), the + authorization server MUST require the use of TLS as described in + Section 1.6 when sending requests to the token endpoint. + + The client MUST use the HTTP "POST" method when making access token + requests. + + Parameters sent without a value MUST be treated as if they were + omitted from the request. The authorization server MUST ignore + unrecognized request parameters. Request and response parameters + MUST NOT be included more than once. + +3.2.1. Client Authentication + + Confidential clients or other clients issued client credentials MUST + authenticate with the authorization server as described in + Section 2.3 when making requests to the token endpoint. Client + authentication is used for: + + o Enforcing the binding of refresh tokens and authorization codes to + the client they were issued to. Client authentication is critical + when an authorization code is transmitted to the redirection + endpoint over an insecure channel or when the redirection URI has + not been registered in full. + + o Recovering from a compromised client by disabling the client or + changing its credentials, thus preventing an attacker from abusing + stolen refresh tokens. Changing a single set of client + credentials is significantly faster than revoking an entire set of + refresh tokens. + + o Implementing authentication management best practices, which + require periodic credential rotation. Rotation of an entire set + of refresh tokens can be challenging, while rotation of a single + set of client credentials is significantly easier. + + + + + + +Hardt Standards Track [Page 22] + +RFC 6749 OAuth 2.0 October 2012 + + + A client MAY use the "client_id" request parameter to identify itself + when sending requests to the token endpoint. In the + "authorization_code" "grant_type" request to the token endpoint, an + unauthenticated client MUST send its "client_id" to prevent itself + from inadvertently accepting a code intended for a client with a + different "client_id". This protects the client from substitution of + the authentication code. (It provides no additional security for the + protected resource.) + +3.3. Access Token Scope + + The authorization and token endpoints allow the client to specify the + scope of the access request using the "scope" request parameter. In + turn, the authorization server uses the "scope" response parameter to + inform the client of the scope of the access token issued. + + The value of the scope parameter is expressed as a list of space- + delimited, case-sensitive strings. The strings are defined by the + authorization server. If the value contains multiple space-delimited + strings, their order does not matter, and each string adds an + additional access range to the requested scope. + + scope = scope-token *( SP scope-token ) + scope-token = 1*( %x21 / %x23-5B / %x5D-7E ) + + The authorization server MAY fully or partially ignore the scope + requested by the client, based on the authorization server policy or + the resource owner's instructions. If the issued access token scope + is different from the one requested by the client, the authorization + server MUST include the "scope" response parameter to inform the + client of the actual scope granted. + + If the client omits the scope parameter when requesting + authorization, the authorization server MUST either process the + request using a pre-defined default value or fail the request + indicating an invalid scope. The authorization server SHOULD + document its scope requirements and default value (if defined). + +4. Obtaining Authorization + + To request an access token, the client obtains authorization from the + resource owner. The authorization is expressed in the form of an + authorization grant, which the client uses to request the access + token. OAuth defines four grant types: authorization code, implicit, + resource owner password credentials, and client credentials. It also + provides an extension mechanism for defining additional grant types. + + + + + +Hardt Standards Track [Page 23] + +RFC 6749 OAuth 2.0 October 2012 + + +4.1. Authorization Code Grant + + The authorization code grant type is used to obtain both access + tokens and refresh tokens and is optimized for confidential clients. + Since this is a redirection-based flow, the client must be capable of + interacting with the resource owner's user-agent (typically a web + browser) and capable of receiving incoming requests (via redirection) + from the authorization server. + + +----------+ + | Resource | + | Owner | + | | + +----------+ + ^ + | + (B) + +----|-----+ Client Identifier +---------------+ + | -+----(A)-- & Redirection URI ---->| | + | User- | | Authorization | + | Agent -+----(B)-- User authenticates --->| Server | + | | | | + | -+----(C)-- Authorization Code ---<| | + +-|----|---+ +---------------+ + | | ^ v + (A) (C) | | + | | | | + ^ v | | + +---------+ | | + | |>---(D)-- Authorization Code ---------' | + | Client | & Redirection URI | + | | | + | |<---(E)----- Access Token -------------------' + +---------+ (w/ Optional Refresh Token) + + Note: The lines illustrating steps (A), (B), and (C) are broken into + two parts as they pass through the user-agent. + + Figure 3: Authorization Code Flow + + + + + + + + + + + + +Hardt Standards Track [Page 24] + +RFC 6749 OAuth 2.0 October 2012 + + + The flow illustrated in Figure 3 includes the following steps: + + (A) The client initiates the flow by directing the resource owner's + user-agent to the authorization endpoint. The client includes + its client identifier, requested scope, local state, and a + redirection URI to which the authorization server will send the + user-agent back once access is granted (or denied). + + (B) The authorization server authenticates the resource owner (via + the user-agent) and establishes whether the resource owner + grants or denies the client's access request. + + (C) Assuming the resource owner grants access, the authorization + server redirects the user-agent back to the client using the + redirection URI provided earlier (in the request or during + client registration). The redirection URI includes an + authorization code and any local state provided by the client + earlier. + + (D) The client requests an access token from the authorization + server's token endpoint by including the authorization code + received in the previous step. When making the request, the + client authenticates with the authorization server. The client + includes the redirection URI used to obtain the authorization + code for verification. + + (E) The authorization server authenticates the client, validates the + authorization code, and ensures that the redirection URI + received matches the URI used to redirect the client in + step (C). If valid, the authorization server responds back with + an access token and, optionally, a refresh token. + +4.1.1. Authorization Request + + The client constructs the request URI by adding the following + parameters to the query component of the authorization endpoint URI + using the "application/x-www-form-urlencoded" format, per Appendix B: + + response_type + REQUIRED. Value MUST be set to "code". + + client_id + REQUIRED. The client identifier as described in Section 2.2. + + redirect_uri + OPTIONAL. As described in Section 3.1.2. + + + + + +Hardt Standards Track [Page 25] + +RFC 6749 OAuth 2.0 October 2012 + + + scope + OPTIONAL. The scope of the access request as described by + Section 3.3. + + state + RECOMMENDED. An opaque value used by the client to maintain + state between the request and callback. The authorization + server includes this value when redirecting the user-agent back + to the client. The parameter SHOULD be used for preventing + cross-site request forgery as described in Section 10.12. + + The client directs the resource owner to the constructed URI using an + HTTP redirection response, or by other means available to it via the + user-agent. + + For example, the client directs the user-agent to make the following + HTTP request using TLS (with extra line breaks for display purposes + only): + + GET /authorize?response_type=code&client_id=s6BhdRkqt3&state=xyz + &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1 + Host: server.example.com + + The authorization server validates the request to ensure that all + required parameters are present and valid. If the request is valid, + the authorization server authenticates the resource owner and obtains + an authorization decision (by asking the resource owner or by + establishing approval via other means). + + When a decision is established, the authorization server directs the + user-agent to the provided client redirection URI using an HTTP + redirection response, or by other means available to it via the + user-agent. + +4.1.2. Authorization Response + + If the resource owner grants the access request, the authorization + server issues an authorization code and delivers it to the client by + adding the following parameters to the query component of the + redirection URI using the "application/x-www-form-urlencoded" format, + per Appendix B: + + code + REQUIRED. The authorization code generated by the + authorization server. The authorization code MUST expire + shortly after it is issued to mitigate the risk of leaks. A + maximum authorization code lifetime of 10 minutes is + RECOMMENDED. The client MUST NOT use the authorization code + + + +Hardt Standards Track [Page 26] + +RFC 6749 OAuth 2.0 October 2012 + + + more than once. If an authorization code is used more than + once, the authorization server MUST deny the request and SHOULD + revoke (when possible) all tokens previously issued based on + that authorization code. The authorization code is bound to + the client identifier and redirection URI. + + state + REQUIRED if the "state" parameter was present in the client + authorization request. The exact value received from the + client. + + For example, the authorization server redirects the user-agent by + sending the following HTTP response: + + HTTP/1.1 302 Found + Location: https://client.example.com/cb?code=SplxlOBeZQQYbYS6WxSbIA + &state=xyz + + The client MUST ignore unrecognized response parameters. The + authorization code string size is left undefined by this + specification. The client should avoid making assumptions about code + value sizes. The authorization server SHOULD document the size of + any value it issues. + +4.1.2.1. Error Response + + If the request fails due to a missing, invalid, or mismatching + redirection URI, or if the client identifier is missing or invalid, + the authorization server SHOULD inform the resource owner of the + error and MUST NOT automatically redirect the user-agent to the + invalid redirection URI. + + If the resource owner denies the access request or if the request + fails for reasons other than a missing or invalid redirection URI, + the authorization server informs the client by adding the following + parameters to the query component of the redirection URI using the + "application/x-www-form-urlencoded" format, per Appendix B: + + error + REQUIRED. A single ASCII [USASCII] error code from the + following: + + invalid_request + The request is missing a required parameter, includes an + invalid parameter value, includes a parameter more than + once, or is otherwise malformed. + + + + + +Hardt Standards Track [Page 27] + +RFC 6749 OAuth 2.0 October 2012 + + + unauthorized_client + The client is not authorized to request an authorization + code using this method. + + access_denied + The resource owner or authorization server denied the + request. + + unsupported_response_type + The authorization server does not support obtaining an + authorization code using this method. + + invalid_scope + The requested scope is invalid, unknown, or malformed. + + server_error + The authorization server encountered an unexpected + condition that prevented it from fulfilling the request. + (This error code is needed because a 500 Internal Server + Error HTTP status code cannot be returned to the client + via an HTTP redirect.) + + temporarily_unavailable + The authorization server is currently unable to handle + the request due to a temporary overloading or maintenance + of the server. (This error code is needed because a 503 + Service Unavailable HTTP status code cannot be returned + to the client via an HTTP redirect.) + + Values for the "error" parameter MUST NOT include characters + outside the set %x20-21 / %x23-5B / %x5D-7E. + + error_description + OPTIONAL. Human-readable ASCII [USASCII] text providing + additional information, used to assist the client developer in + understanding the error that occurred. + Values for the "error_description" parameter MUST NOT include + characters outside the set %x20-21 / %x23-5B / %x5D-7E. + + error_uri + OPTIONAL. A URI identifying a human-readable web page with + information about the error, used to provide the client + developer with additional information about the error. + Values for the "error_uri" parameter MUST conform to the + URI-reference syntax and thus MUST NOT include characters + outside the set %x21 / %x23-5B / %x5D-7E. + + + + + +Hardt Standards Track [Page 28] + +RFC 6749 OAuth 2.0 October 2012 + + + state + REQUIRED if a "state" parameter was present in the client + authorization request. The exact value received from the + client. + + For example, the authorization server redirects the user-agent by + sending the following HTTP response: + + HTTP/1.1 302 Found + Location: https://client.example.com/cb?error=access_denied&state=xyz + +4.1.3. Access Token Request + + The client makes a request to the token endpoint by sending the + following parameters using the "application/x-www-form-urlencoded" + format per Appendix B with a character encoding of UTF-8 in the HTTP + request entity-body: + + grant_type + REQUIRED. Value MUST be set to "authorization_code". + + code + REQUIRED. The authorization code received from the + authorization server. + + redirect_uri + REQUIRED, if the "redirect_uri" parameter was included in the + authorization request as described in Section 4.1.1, and their + values MUST be identical. + + client_id + REQUIRED, if the client is not authenticating with the + authorization server as described in Section 3.2.1. + + If the client type is confidential or the client was issued client + credentials (or assigned other authentication requirements), the + client MUST authenticate with the authorization server as described + in Section 3.2.1. + + + + + + + + + + + + + +Hardt Standards Track [Page 29] + +RFC 6749 OAuth 2.0 October 2012 + + + For example, the client makes the following HTTP request using TLS + (with extra line breaks for display purposes only): + + POST /token HTTP/1.1 + Host: server.example.com + Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW + Content-Type: application/x-www-form-urlencoded + + grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA + &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb + + The authorization server MUST: + + o require client authentication for confidential clients or for any + client that was issued client credentials (or with other + authentication requirements), + + o authenticate the client if client authentication is included, + + o ensure that the authorization code was issued to the authenticated + confidential client, or if the client is public, ensure that the + code was issued to "client_id" in the request, + + o verify that the authorization code is valid, and + + o ensure that the "redirect_uri" parameter is present if the + "redirect_uri" parameter was included in the initial authorization + request as described in Section 4.1.1, and if included ensure that + their values are identical. + +4.1.4. Access Token Response + + If the access token request is valid and authorized, the + authorization server issues an access token and optional refresh + token as described in Section 5.1. If the request client + authentication failed or is invalid, the authorization server returns + an error response as described in Section 5.2. + + + + + + + + + + + + + + +Hardt Standards Track [Page 30] + +RFC 6749 OAuth 2.0 October 2012 + + + An example successful response: + + HTTP/1.1 200 OK + Content-Type: application/json;charset=UTF-8 + Cache-Control: no-store + Pragma: no-cache + + { + "access_token":"2YotnFZFEjr1zCsicMWpAA", + "token_type":"example", + "expires_in":3600, + "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA", + "example_parameter":"example_value" + } + +4.2. Implicit Grant + + The implicit grant type is used to obtain access tokens (it does not + support the issuance of refresh tokens) and is optimized for public + clients known to operate a particular redirection URI. These clients + are typically implemented in a browser using a scripting language + such as JavaScript. + + Since this is a redirection-based flow, the client must be capable of + interacting with the resource owner's user-agent (typically a web + browser) and capable of receiving incoming requests (via redirection) + from the authorization server. + + Unlike the authorization code grant type, in which the client makes + separate requests for authorization and for an access token, the + client receives the access token as the result of the authorization + request. + + The implicit grant type does not include client authentication, and + relies on the presence of the resource owner and the registration of + the redirection URI. Because the access token is encoded into the + redirection URI, it may be exposed to the resource owner and other + applications residing on the same device. + + + + + + + + + + + + + +Hardt Standards Track [Page 31] + +RFC 6749 OAuth 2.0 October 2012 + + + +----------+ + | Resource | + | Owner | + | | + +----------+ + ^ + | + (B) + +----|-----+ Client Identifier +---------------+ + | -+----(A)-- & Redirection URI --->| | + | User- | | Authorization | + | Agent -|----(B)-- User authenticates -->| Server | + | | | | + | |<---(C)--- Redirection URI ----<| | + | | with Access Token +---------------+ + | | in Fragment + | | +---------------+ + | |----(D)--- Redirection URI ---->| Web-Hosted | + | | without Fragment | Client | + | | | Resource | + | (F) |<---(E)------- Script ---------<| | + | | +---------------+ + +-|--------+ + | | + (A) (G) Access Token + | | + ^ v + +---------+ + | | + | Client | + | | + +---------+ + + Note: The lines illustrating steps (A) and (B) are broken into two + parts as they pass through the user-agent. + + Figure 4: Implicit Grant Flow + + + + + + + + + + + + + + +Hardt Standards Track [Page 32] + +RFC 6749 OAuth 2.0 October 2012 + + + The flow illustrated in Figure 4 includes the following steps: + + (A) The client initiates the flow by directing the resource owner's + user-agent to the authorization endpoint. The client includes + its client identifier, requested scope, local state, and a + redirection URI to which the authorization server will send the + user-agent back once access is granted (or denied). + + (B) The authorization server authenticates the resource owner (via + the user-agent) and establishes whether the resource owner + grants or denies the client's access request. + + (C) Assuming the resource owner grants access, the authorization + server redirects the user-agent back to the client using the + redirection URI provided earlier. The redirection URI includes + the access token in the URI fragment. + + (D) The user-agent follows the redirection instructions by making a + request to the web-hosted client resource (which does not + include the fragment per [RFC2616]). The user-agent retains the + fragment information locally. + + (E) The web-hosted client resource returns a web page (typically an + HTML document with an embedded script) capable of accessing the + full redirection URI including the fragment retained by the + user-agent, and extracting the access token (and other + parameters) contained in the fragment. + + (F) The user-agent executes the script provided by the web-hosted + client resource locally, which extracts the access token. + + (G) The user-agent passes the access token to the client. + + See Sections 1.3.2 and 9 for background on using the implicit grant. + See Sections 10.3 and 10.16 for important security considerations + when using the implicit grant. + +4.2.1. Authorization Request + + The client constructs the request URI by adding the following + parameters to the query component of the authorization endpoint URI + using the "application/x-www-form-urlencoded" format, per Appendix B: + + response_type + REQUIRED. Value MUST be set to "token". + + client_id + REQUIRED. The client identifier as described in Section 2.2. + + + +Hardt Standards Track [Page 33] + +RFC 6749 OAuth 2.0 October 2012 + + + redirect_uri + OPTIONAL. As described in Section 3.1.2. + + scope + OPTIONAL. The scope of the access request as described by + Section 3.3. + + state + RECOMMENDED. An opaque value used by the client to maintain + state between the request and callback. The authorization + server includes this value when redirecting the user-agent back + to the client. The parameter SHOULD be used for preventing + cross-site request forgery as described in Section 10.12. + + The client directs the resource owner to the constructed URI using an + HTTP redirection response, or by other means available to it via the + user-agent. + + For example, the client directs the user-agent to make the following + HTTP request using TLS (with extra line breaks for display purposes + only): + + GET /authorize?response_type=token&client_id=s6BhdRkqt3&state=xyz + &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1 + Host: server.example.com + + The authorization server validates the request to ensure that all + required parameters are present and valid. The authorization server + MUST verify that the redirection URI to which it will redirect the + access token matches a redirection URI registered by the client as + described in Section 3.1.2. + + If the request is valid, the authorization server authenticates the + resource owner and obtains an authorization decision (by asking the + resource owner or by establishing approval via other means). + + When a decision is established, the authorization server directs the + user-agent to the provided client redirection URI using an HTTP + redirection response, or by other means available to it via the + user-agent. + + + + + + + + + + + +Hardt Standards Track [Page 34] + +RFC 6749 OAuth 2.0 October 2012 + + +4.2.2. Access Token Response + + If the resource owner grants the access request, the authorization + server issues an access token and delivers it to the client by adding + the following parameters to the fragment component of the redirection + URI using the "application/x-www-form-urlencoded" format, per + Appendix B: + + access_token + REQUIRED. The access token issued by the authorization server. + + token_type + REQUIRED. The type of the token issued as described in + Section 7.1. Value is case insensitive. + + expires_in + RECOMMENDED. The lifetime in seconds of the access token. For + example, the value "3600" denotes that the access token will + expire in one hour from the time the response was generated. + If omitted, the authorization server SHOULD provide the + expiration time via other means or document the default value. + + scope + OPTIONAL, if identical to the scope requested by the client; + otherwise, REQUIRED. The scope of the access token as + described by Section 3.3. + + state + REQUIRED if the "state" parameter was present in the client + authorization request. The exact value received from the + client. + + The authorization server MUST NOT issue a refresh token. + + For example, the authorization server redirects the user-agent by + sending the following HTTP response (with extra line breaks for + display purposes only): + + HTTP/1.1 302 Found + Location: http://example.com/cb#access_token=2YotnFZFEjr1zCsicMWpAA + &state=xyz&token_type=example&expires_in=3600 + + Developers should note that some user-agents do not support the + inclusion of a fragment component in the HTTP "Location" response + header field. Such clients will require using other methods for + redirecting the client than a 3xx redirection response -- for + example, returning an HTML page that includes a 'continue' button + with an action linked to the redirection URI. + + + +Hardt Standards Track [Page 35] + +RFC 6749 OAuth 2.0 October 2012 + + + The client MUST ignore unrecognized response parameters. The access + token string size is left undefined by this specification. The + client should avoid making assumptions about value sizes. The + authorization server SHOULD document the size of any value it issues. + +4.2.2.1. Error Response + + If the request fails due to a missing, invalid, or mismatching + redirection URI, or if the client identifier is missing or invalid, + the authorization server SHOULD inform the resource owner of the + error and MUST NOT automatically redirect the user-agent to the + invalid redirection URI. + + If the resource owner denies the access request or if the request + fails for reasons other than a missing or invalid redirection URI, + the authorization server informs the client by adding the following + parameters to the fragment component of the redirection URI using the + "application/x-www-form-urlencoded" format, per Appendix B: + + error + REQUIRED. A single ASCII [USASCII] error code from the + following: + + invalid_request + The request is missing a required parameter, includes an + invalid parameter value, includes a parameter more than + once, or is otherwise malformed. + + unauthorized_client + The client is not authorized to request an access token + using this method. + + access_denied + The resource owner or authorization server denied the + request. + + unsupported_response_type + The authorization server does not support obtaining an + access token using this method. + + invalid_scope + The requested scope is invalid, unknown, or malformed. + + + + + + + + + +Hardt Standards Track [Page 36] + +RFC 6749 OAuth 2.0 October 2012 + + + server_error + The authorization server encountered an unexpected + condition that prevented it from fulfilling the request. + (This error code is needed because a 500 Internal Server + Error HTTP status code cannot be returned to the client + via an HTTP redirect.) + + temporarily_unavailable + The authorization server is currently unable to handle + the request due to a temporary overloading or maintenance + of the server. (This error code is needed because a 503 + Service Unavailable HTTP status code cannot be returned + to the client via an HTTP redirect.) + + Values for the "error" parameter MUST NOT include characters + outside the set %x20-21 / %x23-5B / %x5D-7E. + + error_description + OPTIONAL. Human-readable ASCII [USASCII] text providing + additional information, used to assist the client developer in + understanding the error that occurred. + Values for the "error_description" parameter MUST NOT include + characters outside the set %x20-21 / %x23-5B / %x5D-7E. + + error_uri + OPTIONAL. A URI identifying a human-readable web page with + information about the error, used to provide the client + developer with additional information about the error. + Values for the "error_uri" parameter MUST conform to the + URI-reference syntax and thus MUST NOT include characters + outside the set %x21 / %x23-5B / %x5D-7E. + + state + REQUIRED if a "state" parameter was present in the client + authorization request. The exact value received from the + client. + + For example, the authorization server redirects the user-agent by + sending the following HTTP response: + + HTTP/1.1 302 Found + Location: https://client.example.com/cb#error=access_denied&state=xyz + +4.3. Resource Owner Password Credentials Grant + + The resource owner password credentials grant type is suitable in + cases where the resource owner has a trust relationship with the + client, such as the device operating system or a highly privileged + + + +Hardt Standards Track [Page 37] + +RFC 6749 OAuth 2.0 October 2012 + + + application. The authorization server should take special care when + enabling this grant type and only allow it when other flows are not + viable. + + This grant type is suitable for clients capable of obtaining the + resource owner's credentials (username and password, typically using + an interactive form). It is also used to migrate existing clients + using direct authentication schemes such as HTTP Basic or Digest + authentication to OAuth by converting the stored credentials to an + access token. + + +----------+ + | Resource | + | Owner | + | | + +----------+ + v + | Resource Owner + (A) Password Credentials + | + v + +---------+ +---------------+ + | |>--(B)---- Resource Owner ------->| | + | | Password Credentials | Authorization | + | Client | | Server | + | |<--(C)---- Access Token ---------<| | + | | (w/ Optional Refresh Token) | | + +---------+ +---------------+ + + Figure 5: Resource Owner Password Credentials Flow + + The flow illustrated in Figure 5 includes the following steps: + + (A) The resource owner provides the client with its username and + password. + + (B) The client requests an access token from the authorization + server's token endpoint by including the credentials received + from the resource owner. When making the request, the client + authenticates with the authorization server. + + (C) The authorization server authenticates the client and validates + the resource owner credentials, and if valid, issues an access + token. + + + + + + + +Hardt Standards Track [Page 38] + +RFC 6749 OAuth 2.0 October 2012 + + +4.3.1. Authorization Request and Response + + The method through which the client obtains the resource owner + credentials is beyond the scope of this specification. The client + MUST discard the credentials once an access token has been obtained. + +4.3.2. Access Token Request + + The client makes a request to the token endpoint by adding the + following parameters using the "application/x-www-form-urlencoded" + format per Appendix B with a character encoding of UTF-8 in the HTTP + request entity-body: + + grant_type + REQUIRED. Value MUST be set to "password". + + username + REQUIRED. The resource owner username. + + password + REQUIRED. The resource owner password. + + scope + OPTIONAL. The scope of the access request as described by + Section 3.3. + + If the client type is confidential or the client was issued client + credentials (or assigned other authentication requirements), the + client MUST authenticate with the authorization server as described + in Section 3.2.1. + + For example, the client makes the following HTTP request using + transport-layer security (with extra line breaks for display purposes + only): + + POST /token HTTP/1.1 + Host: server.example.com + Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW + Content-Type: application/x-www-form-urlencoded + + grant_type=password&username=johndoe&password=A3ddj3w + + + + + + + + + + +Hardt Standards Track [Page 39] + +RFC 6749 OAuth 2.0 October 2012 + + + The authorization server MUST: + + o require client authentication for confidential clients or for any + client that was issued client credentials (or with other + authentication requirements), + + o authenticate the client if client authentication is included, and + + o validate the resource owner password credentials using its + existing password validation algorithm. + + Since this access token request utilizes the resource owner's + password, the authorization server MUST protect the endpoint against + brute force attacks (e.g., using rate-limitation or generating + alerts). + +4.3.3. Access Token Response + + If the access token request is valid and authorized, the + authorization server issues an access token and optional refresh + token as described in Section 5.1. If the request failed client + authentication or is invalid, the authorization server returns an + error response as described in Section 5.2. + + An example successful response: + + HTTP/1.1 200 OK + Content-Type: application/json;charset=UTF-8 + Cache-Control: no-store + Pragma: no-cache + + { + "access_token":"2YotnFZFEjr1zCsicMWpAA", + "token_type":"example", + "expires_in":3600, + "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA", + "example_parameter":"example_value" + } + +4.4. Client Credentials Grant + + The client can request an access token using only its client + credentials (or other supported means of authentication) when the + client is requesting access to the protected resources under its + control, or those of another resource owner that have been previously + arranged with the authorization server (the method of which is beyond + the scope of this specification). + + + + +Hardt Standards Track [Page 40] + +RFC 6749 OAuth 2.0 October 2012 + + + The client credentials grant type MUST only be used by confidential + clients. + + +---------+ +---------------+ + | | | | + | |>--(A)- Client Authentication --->| Authorization | + | Client | | Server | + | |<--(B)---- Access Token ---------<| | + | | | | + +---------+ +---------------+ + + Figure 6: Client Credentials Flow + + The flow illustrated in Figure 6 includes the following steps: + + (A) The client authenticates with the authorization server and + requests an access token from the token endpoint. + + (B) The authorization server authenticates the client, and if valid, + issues an access token. + +4.4.1. Authorization Request and Response + + Since the client authentication is used as the authorization grant, + no additional authorization request is needed. + +4.4.2. Access Token Request + + The client makes a request to the token endpoint by adding the + following parameters using the "application/x-www-form-urlencoded" + format per Appendix B with a character encoding of UTF-8 in the HTTP + request entity-body: + + grant_type + REQUIRED. Value MUST be set to "client_credentials". + + scope + OPTIONAL. The scope of the access request as described by + Section 3.3. + + The client MUST authenticate with the authorization server as + described in Section 3.2.1. + + + + + + + + + +Hardt Standards Track [Page 41] + +RFC 6749 OAuth 2.0 October 2012 + + + For example, the client makes the following HTTP request using + transport-layer security (with extra line breaks for display purposes + only): + + POST /token HTTP/1.1 + Host: server.example.com + Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW + Content-Type: application/x-www-form-urlencoded + + grant_type=client_credentials + + The authorization server MUST authenticate the client. + +4.4.3. Access Token Response + + If the access token request is valid and authorized, the + authorization server issues an access token as described in + Section 5.1. A refresh token SHOULD NOT be included. If the request + failed client authentication or is invalid, the authorization server + returns an error response as described in Section 5.2. + + An example successful response: + + HTTP/1.1 200 OK + Content-Type: application/json;charset=UTF-8 + Cache-Control: no-store + Pragma: no-cache + + { + "access_token":"2YotnFZFEjr1zCsicMWpAA", + "token_type":"example", + "expires_in":3600, + "example_parameter":"example_value" + } + +4.5. Extension Grants + + The client uses an extension grant type by specifying the grant type + using an absolute URI (defined by the authorization server) as the + value of the "grant_type" parameter of the token endpoint, and by + adding any additional parameters necessary. + + + + + + + + + + +Hardt Standards Track [Page 42] + +RFC 6749 OAuth 2.0 October 2012 + + + For example, to request an access token using a Security Assertion + Markup Language (SAML) 2.0 assertion grant type as defined by + [OAuth-SAML2], the client could make the following HTTP request using + TLS (with extra line breaks for display purposes only): + + POST /token HTTP/1.1 + Host: server.example.com + Content-Type: application/x-www-form-urlencoded + + grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Asaml2- + bearer&assertion=PEFzc2VydGlvbiBJc3N1ZUluc3RhbnQ9IjIwMTEtMDU + [...omitted for brevity...]aG5TdGF0ZW1lbnQ-PC9Bc3NlcnRpb24- + + If the access token request is valid and authorized, the + authorization server issues an access token and optional refresh + token as described in Section 5.1. If the request failed client + authentication or is invalid, the authorization server returns an + error response as described in Section 5.2. + +5. Issuing an Access Token + + If the access token request is valid and authorized, the + authorization server issues an access token and optional refresh + token as described in Section 5.1. If the request failed client + authentication or is invalid, the authorization server returns an + error response as described in Section 5.2. + +5.1. Successful Response + + The authorization server issues an access token and optional refresh + token, and constructs the response by adding the following parameters + to the entity-body of the HTTP response with a 200 (OK) status code: + + access_token + REQUIRED. The access token issued by the authorization server. + + token_type + REQUIRED. The type of the token issued as described in + Section 7.1. Value is case insensitive. + + expires_in + RECOMMENDED. The lifetime in seconds of the access token. For + example, the value "3600" denotes that the access token will + expire in one hour from the time the response was generated. + If omitted, the authorization server SHOULD provide the + expiration time via other means or document the default value. + + + + + +Hardt Standards Track [Page 43] + +RFC 6749 OAuth 2.0 October 2012 + + + refresh_token + OPTIONAL. The refresh token, which can be used to obtain new + access tokens using the same authorization grant as described + in Section 6. + + scope + OPTIONAL, if identical to the scope requested by the client; + otherwise, REQUIRED. The scope of the access token as + described by Section 3.3. + + The parameters are included in the entity-body of the HTTP response + using the "application/json" media type as defined by [RFC4627]. The + parameters are serialized into a JavaScript Object Notation (JSON) + structure by adding each parameter at the highest structure level. + Parameter names and string values are included as JSON strings. + Numerical values are included as JSON numbers. The order of + parameters does not matter and can vary. + + The authorization server MUST include the HTTP "Cache-Control" + response header field [RFC2616] with a value of "no-store" in any + response containing tokens, credentials, or other sensitive + information, as well as the "Pragma" response header field [RFC2616] + with a value of "no-cache". + + For example: + + HTTP/1.1 200 OK + Content-Type: application/json;charset=UTF-8 + Cache-Control: no-store + Pragma: no-cache + + { + "access_token":"2YotnFZFEjr1zCsicMWpAA", + "token_type":"example", + "expires_in":3600, + "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA", + "example_parameter":"example_value" + } + + The client MUST ignore unrecognized value names in the response. The + sizes of tokens and other values received from the authorization + server are left undefined. The client should avoid making + assumptions about value sizes. The authorization server SHOULD + document the size of any value it issues. + + + + + + + +Hardt Standards Track [Page 44] + +RFC 6749 OAuth 2.0 October 2012 + + +5.2. Error Response + + The authorization server responds with an HTTP 400 (Bad Request) + status code (unless specified otherwise) and includes the following + parameters with the response: + + error + REQUIRED. A single ASCII [USASCII] error code from the + following: + + invalid_request + The request is missing a required parameter, includes an + unsupported parameter value (other than grant type), + repeats a parameter, includes multiple credentials, + utilizes more than one mechanism for authenticating the + client, or is otherwise malformed. + + invalid_client + Client authentication failed (e.g., unknown client, no + client authentication included, or unsupported + authentication method). The authorization server MAY + return an HTTP 401 (Unauthorized) status code to indicate + which HTTP authentication schemes are supported. If the + client attempted to authenticate via the "Authorization" + request header field, the authorization server MUST + respond with an HTTP 401 (Unauthorized) status code and + include the "WWW-Authenticate" response header field + matching the authentication scheme used by the client. + + invalid_grant + The provided authorization grant (e.g., authorization + code, resource owner credentials) or refresh token is + invalid, expired, revoked, does not match the redirection + URI used in the authorization request, or was issued to + another client. + + unauthorized_client + The authenticated client is not authorized to use this + authorization grant type. + + unsupported_grant_type + The authorization grant type is not supported by the + authorization server. + + + + + + + + +Hardt Standards Track [Page 45] + +RFC 6749 OAuth 2.0 October 2012 + + + invalid_scope + The requested scope is invalid, unknown, malformed, or + exceeds the scope granted by the resource owner. + + Values for the "error" parameter MUST NOT include characters + outside the set %x20-21 / %x23-5B / %x5D-7E. + + error_description + OPTIONAL. Human-readable ASCII [USASCII] text providing + additional information, used to assist the client developer in + understanding the error that occurred. + Values for the "error_description" parameter MUST NOT include + characters outside the set %x20-21 / %x23-5B / %x5D-7E. + + error_uri + OPTIONAL. A URI identifying a human-readable web page with + information about the error, used to provide the client + developer with additional information about the error. + Values for the "error_uri" parameter MUST conform to the + URI-reference syntax and thus MUST NOT include characters + outside the set %x21 / %x23-5B / %x5D-7E. + + The parameters are included in the entity-body of the HTTP response + using the "application/json" media type as defined by [RFC4627]. The + parameters are serialized into a JSON structure by adding each + parameter at the highest structure level. Parameter names and string + values are included as JSON strings. Numerical values are included + as JSON numbers. The order of parameters does not matter and can + vary. + + For example: + + HTTP/1.1 400 Bad Request + Content-Type: application/json;charset=UTF-8 + Cache-Control: no-store + Pragma: no-cache + + { + "error":"invalid_request" + } + + + + + + + + + + + +Hardt Standards Track [Page 46] + +RFC 6749 OAuth 2.0 October 2012 + + +6. Refreshing an Access Token + + If the authorization server issued a refresh token to the client, the + client makes a refresh request to the token endpoint by adding the + following parameters using the "application/x-www-form-urlencoded" + format per Appendix B with a character encoding of UTF-8 in the HTTP + request entity-body: + + grant_type + REQUIRED. Value MUST be set to "refresh_token". + + refresh_token + REQUIRED. The refresh token issued to the client. + + scope + OPTIONAL. The scope of the access request as described by + Section 3.3. The requested scope MUST NOT include any scope + not originally granted by the resource owner, and if omitted is + treated as equal to the scope originally granted by the + resource owner. + + Because refresh tokens are typically long-lasting credentials used to + request additional access tokens, the refresh token is bound to the + client to which it was issued. If the client type is confidential or + the client was issued client credentials (or assigned other + authentication requirements), the client MUST authenticate with the + authorization server as described in Section 3.2.1. + + For example, the client makes the following HTTP request using + transport-layer security (with extra line breaks for display purposes + only): + + POST /token HTTP/1.1 + Host: server.example.com + Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW + Content-Type: application/x-www-form-urlencoded + + grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA + + + + + + + + + + + + + +Hardt Standards Track [Page 47] + +RFC 6749 OAuth 2.0 October 2012 + + + The authorization server MUST: + + o require client authentication for confidential clients or for any + client that was issued client credentials (or with other + authentication requirements), + + o authenticate the client if client authentication is included and + ensure that the refresh token was issued to the authenticated + client, and + + o validate the refresh token. + + If valid and authorized, the authorization server issues an access + token as described in Section 5.1. If the request failed + verification or is invalid, the authorization server returns an error + response as described in Section 5.2. + + The authorization server MAY issue a new refresh token, in which case + the client MUST discard the old refresh token and replace it with the + new refresh token. The authorization server MAY revoke the old + refresh token after issuing a new refresh token to the client. If a + new refresh token is issued, the refresh token scope MUST be + identical to that of the refresh token included by the client in the + request. + +7. Accessing Protected Resources + + The client accesses protected resources by presenting the access + token to the resource server. The resource server MUST validate the + access token and ensure that it has not expired and that its scope + covers the requested resource. The methods used by the resource + server to validate the access token (as well as any error responses) + are beyond the scope of this specification but generally involve an + interaction or coordination between the resource server and the + authorization server. + + The method in which the client utilizes the access token to + authenticate with the resource server depends on the type of access + token issued by the authorization server. Typically, it involves + using the HTTP "Authorization" request header field [RFC2617] with an + authentication scheme defined by the specification of the access + token type used, such as [RFC6750]. + + + + + + + + + +Hardt Standards Track [Page 48] + +RFC 6749 OAuth 2.0 October 2012 + + +7.1. Access Token Types + + The access token type provides the client with the information + required to successfully utilize the access token to make a protected + resource request (along with type-specific attributes). The client + MUST NOT use an access token if it does not understand the token + type. + + For example, the "bearer" token type defined in [RFC6750] is utilized + by simply including the access token string in the request: + + GET /resource/1 HTTP/1.1 + Host: example.com + Authorization: Bearer mF_9.B5f-4.1JqM + + while the "mac" token type defined in [OAuth-HTTP-MAC] is utilized by + issuing a Message Authentication Code (MAC) key together with the + access token that is used to sign certain components of the HTTP + requests: + + GET /resource/1 HTTP/1.1 + Host: example.com + Authorization: MAC id="h480djs93hd8", + nonce="274312:dj83hs9s", + mac="kDZvddkndxvhGRXZhvuDjEWhGeE=" + + The above examples are provided for illustration purposes only. + Developers are advised to consult the [RFC6750] and [OAuth-HTTP-MAC] + specifications before use. + + Each access token type definition specifies the additional attributes + (if any) sent to the client together with the "access_token" response + parameter. It also defines the HTTP authentication method used to + include the access token when making a protected resource request. + +7.2. Error Response + + If a resource access request fails, the resource server SHOULD inform + the client of the error. While the specifics of such error responses + are beyond the scope of this specification, this document establishes + a common registry in Section 11.4 for error values to be shared among + OAuth token authentication schemes. + + New authentication schemes designed primarily for OAuth token + authentication SHOULD define a mechanism for providing an error + status code to the client, in which the error values allowed are + registered in the error registry established by this specification. + + + + +Hardt Standards Track [Page 49] + +RFC 6749 OAuth 2.0 October 2012 + + + Such schemes MAY limit the set of valid error codes to a subset of + the registered values. If the error code is returned using a named + parameter, the parameter name SHOULD be "error". + + Other schemes capable of being used for OAuth token authentication, + but not primarily designed for that purpose, MAY bind their error + values to the registry in the same manner. + + New authentication schemes MAY choose to also specify the use of the + "error_description" and "error_uri" parameters to return error + information in a manner parallel to their usage in this + specification. + +8. Extensibility + +8.1. Defining Access Token Types + + Access token types can be defined in one of two ways: registered in + the Access Token Types registry (following the procedures in + Section 11.1), or by using a unique absolute URI as its name. + + Types utilizing a URI name SHOULD be limited to vendor-specific + implementations that are not commonly applicable, and are specific to + the implementation details of the resource server where they are + used. + + All other types MUST be registered. Type names MUST conform to the + type-name ABNF. If the type definition includes a new HTTP + authentication scheme, the type name SHOULD be identical to the HTTP + authentication scheme name (as defined by [RFC2617]). The token type + "example" is reserved for use in examples. + + type-name = 1*name-char + name-char = "-" / "." / "_" / DIGIT / ALPHA + +8.2. Defining New Endpoint Parameters + + New request or response parameters for use with the authorization + endpoint or the token endpoint are defined and registered in the + OAuth Parameters registry following the procedure in Section 11.2. + + Parameter names MUST conform to the param-name ABNF, and parameter + values syntax MUST be well-defined (e.g., using ABNF, or a reference + to the syntax of an existing parameter). + + param-name = 1*name-char + name-char = "-" / "." / "_" / DIGIT / ALPHA + + + + +Hardt Standards Track [Page 50] + +RFC 6749 OAuth 2.0 October 2012 + + + Unregistered vendor-specific parameter extensions that are not + commonly applicable and that are specific to the implementation + details of the authorization server where they are used SHOULD + utilize a vendor-specific prefix that is not likely to conflict with + other registered values (e.g., begin with 'companyname_'). + +8.3. Defining New Authorization Grant Types + + New authorization grant types can be defined by assigning them a + unique absolute URI for use with the "grant_type" parameter. If the + extension grant type requires additional token endpoint parameters, + they MUST be registered in the OAuth Parameters registry as described + by Section 11.2. + +8.4. Defining New Authorization Endpoint Response Types + + New response types for use with the authorization endpoint are + defined and registered in the Authorization Endpoint Response Types + registry following the procedure in Section 11.3. Response type + names MUST conform to the response-type ABNF. + + response-type = response-name *( SP response-name ) + response-name = 1*response-char + response-char = "_" / DIGIT / ALPHA + + If a response type contains one or more space characters (%x20), it + is compared as a space-delimited list of values in which the order of + values does not matter. Only one order of values can be registered, + which covers all other arrangements of the same set of values. + + For example, the response type "token code" is left undefined by this + specification. However, an extension can define and register the + "token code" response type. Once registered, the same combination + cannot be registered as "code token", but both values can be used to + denote the same response type. + +8.5. Defining Additional Error Codes + + In cases where protocol extensions (i.e., access token types, + extension parameters, or extension grant types) require additional + error codes to be used with the authorization code grant error + response (Section 4.1.2.1), the implicit grant error response + (Section 4.2.2.1), the token error response (Section 5.2), or the + resource access error response (Section 7.2), such error codes MAY be + defined. + + + + + + +Hardt Standards Track [Page 51] + +RFC 6749 OAuth 2.0 October 2012 + + + Extension error codes MUST be registered (following the procedures in + Section 11.4) if the extension they are used in conjunction with is a + registered access token type, a registered endpoint parameter, or an + extension grant type. Error codes used with unregistered extensions + MAY be registered. + + Error codes MUST conform to the error ABNF and SHOULD be prefixed by + an identifying name when possible. For example, an error identifying + an invalid value set to the extension parameter "example" SHOULD be + named "example_invalid". + + error = 1*error-char + error-char = %x20-21 / %x23-5B / %x5D-7E + +9. Native Applications + + Native applications are clients installed and executed on the device + used by the resource owner (i.e., desktop application, native mobile + application). Native applications require special consideration + related to security, platform capabilities, and overall end-user + experience. + + The authorization endpoint requires interaction between the client + and the resource owner's user-agent. Native applications can invoke + an external user-agent or embed a user-agent within the application. + For example: + + o External user-agent - the native application can capture the + response from the authorization server using a redirection URI + with a scheme registered with the operating system to invoke the + client as the handler, manual copy-and-paste of the credentials, + running a local web server, installing a user-agent extension, or + by providing a redirection URI identifying a server-hosted + resource under the client's control, which in turn makes the + response available to the native application. + + o Embedded user-agent - the native application obtains the response + by directly communicating with the embedded user-agent by + monitoring state changes emitted during the resource load, or + accessing the user-agent's cookies storage. + + When choosing between an external or embedded user-agent, developers + should consider the following: + + o An external user-agent may improve completion rate, as the + resource owner may already have an active session with the + authorization server, removing the need to re-authenticate. It + provides a familiar end-user experience and functionality. The + + + +Hardt Standards Track [Page 52] + +RFC 6749 OAuth 2.0 October 2012 + + + resource owner may also rely on user-agent features or extensions + to assist with authentication (e.g., password manager, 2-factor + device reader). + + o An embedded user-agent may offer improved usability, as it removes + the need to switch context and open new windows. + + o An embedded user-agent poses a security challenge because resource + owners are authenticating in an unidentified window without access + to the visual protections found in most external user-agents. An + embedded user-agent educates end-users to trust unidentified + requests for authentication (making phishing attacks easier to + execute). + + When choosing between the implicit grant type and the authorization + code grant type, the following should be considered: + + o Native applications that use the authorization code grant type + SHOULD do so without using client credentials, due to the native + application's inability to keep client credentials confidential. + + o When using the implicit grant type flow, a refresh token is not + returned, which requires repeating the authorization process once + the access token expires. + +10. Security Considerations + + As a flexible and extensible framework, OAuth's security + considerations depend on many factors. The following sections + provide implementers with security guidelines focused on the three + client profiles described in Section 2.1: web application, + user-agent-based application, and native application. + + A comprehensive OAuth security model and analysis, as well as + background for the protocol design, is provided by + [OAuth-THREATMODEL]. + +10.1. Client Authentication + + The authorization server establishes client credentials with web + application clients for the purpose of client authentication. The + authorization server is encouraged to consider stronger client + authentication means than a client password. Web application clients + MUST ensure confidentiality of client passwords and other client + credentials. + + + + + + +Hardt Standards Track [Page 53] + +RFC 6749 OAuth 2.0 October 2012 + + + The authorization server MUST NOT issue client passwords or other + client credentials to native application or user-agent-based + application clients for the purpose of client authentication. The + authorization server MAY issue a client password or other credentials + for a specific installation of a native application client on a + specific device. + + When client authentication is not possible, the authorization server + SHOULD employ other means to validate the client's identity -- for + example, by requiring the registration of the client redirection URI + or enlisting the resource owner to confirm identity. A valid + redirection URI is not sufficient to verify the client's identity + when asking for resource owner authorization but can be used to + prevent delivering credentials to a counterfeit client after + obtaining resource owner authorization. + + The authorization server must consider the security implications of + interacting with unauthenticated clients and take measures to limit + the potential exposure of other credentials (e.g., refresh tokens) + issued to such clients. + +10.2. Client Impersonation + + A malicious client can impersonate another client and obtain access + to protected resources if the impersonated client fails to, or is + unable to, keep its client credentials confidential. + + The authorization server MUST authenticate the client whenever + possible. If the authorization server cannot authenticate the client + due to the client's nature, the authorization server MUST require the + registration of any redirection URI used for receiving authorization + responses and SHOULD utilize other means to protect resource owners + from such potentially malicious clients. For example, the + authorization server can engage the resource owner to assist in + identifying the client and its origin. + + The authorization server SHOULD enforce explicit resource owner + authentication and provide the resource owner with information about + the client and the requested authorization scope and lifetime. It is + up to the resource owner to review the information in the context of + the current client and to authorize or deny the request. + + The authorization server SHOULD NOT process repeated authorization + requests automatically (without active resource owner interaction) + without authenticating the client or relying on other measures to + ensure that the repeated request comes from the original client and + not an impersonator. + + + + +Hardt Standards Track [Page 54] + +RFC 6749 OAuth 2.0 October 2012 + + +10.3. Access Tokens + + Access token credentials (as well as any confidential access token + attributes) MUST be kept confidential in transit and storage, and + only shared among the authorization server, the resource servers the + access token is valid for, and the client to whom the access token is + issued. Access token credentials MUST only be transmitted using TLS + as described in Section 1.6 with server authentication as defined by + [RFC2818]. + + When using the implicit grant type, the access token is transmitted + in the URI fragment, which can expose it to unauthorized parties. + + The authorization server MUST ensure that access tokens cannot be + generated, modified, or guessed to produce valid access tokens by + unauthorized parties. + + The client SHOULD request access tokens with the minimal scope + necessary. The authorization server SHOULD take the client identity + into account when choosing how to honor the requested scope and MAY + issue an access token with less rights than requested. + + This specification does not provide any methods for the resource + server to ensure that an access token presented to it by a given + client was issued to that client by the authorization server. + +10.4. Refresh Tokens + + Authorization servers MAY issue refresh tokens to web application + clients and native application clients. + + Refresh tokens MUST be kept confidential in transit and storage, and + shared only among the authorization server and the client to whom the + refresh tokens were issued. The authorization server MUST maintain + the binding between a refresh token and the client to whom it was + issued. Refresh tokens MUST only be transmitted using TLS as + described in Section 1.6 with server authentication as defined by + [RFC2818]. + + The authorization server MUST verify the binding between the refresh + token and client identity whenever the client identity can be + authenticated. When client authentication is not possible, the + authorization server SHOULD deploy other means to detect refresh + token abuse. + + For example, the authorization server could employ refresh token + rotation in which a new refresh token is issued with every access + token refresh response. The previous refresh token is invalidated + + + +Hardt Standards Track [Page 55] + +RFC 6749 OAuth 2.0 October 2012 + + + but retained by the authorization server. If a refresh token is + compromised and subsequently used by both the attacker and the + legitimate client, one of them will present an invalidated refresh + token, which will inform the authorization server of the breach. + + The authorization server MUST ensure that refresh tokens cannot be + generated, modified, or guessed to produce valid refresh tokens by + unauthorized parties. + +10.5. Authorization Codes + + The transmission of authorization codes SHOULD be made over a secure + channel, and the client SHOULD require the use of TLS with its + redirection URI if the URI identifies a network resource. Since + authorization codes are transmitted via user-agent redirections, they + could potentially be disclosed through user-agent history and HTTP + referrer headers. + + Authorization codes operate as plaintext bearer credentials, used to + verify that the resource owner who granted authorization at the + authorization server is the same resource owner returning to the + client to complete the process. Therefore, if the client relies on + the authorization code for its own resource owner authentication, the + client redirection endpoint MUST require the use of TLS. + + Authorization codes MUST be short lived and single-use. If the + authorization server observes multiple attempts to exchange an + authorization code for an access token, the authorization server + SHOULD attempt to revoke all access tokens already granted based on + the compromised authorization code. + + If the client can be authenticated, the authorization servers MUST + authenticate the client and ensure that the authorization code was + issued to the same client. + +10.6. Authorization Code Redirection URI Manipulation + + When requesting authorization using the authorization code grant + type, the client can specify a redirection URI via the "redirect_uri" + parameter. If an attacker can manipulate the value of the + redirection URI, it can cause the authorization server to redirect + the resource owner user-agent to a URI under the control of the + attacker with the authorization code. + + An attacker can create an account at a legitimate client and initiate + the authorization flow. When the attacker's user-agent is sent to + the authorization server to grant access, the attacker grabs the + authorization URI provided by the legitimate client and replaces the + + + +Hardt Standards Track [Page 56] + +RFC 6749 OAuth 2.0 October 2012 + + + client's redirection URI with a URI under the control of the + attacker. The attacker then tricks the victim into following the + manipulated link to authorize access to the legitimate client. + + Once at the authorization server, the victim is prompted with a + normal, valid request on behalf of a legitimate and trusted client, + and authorizes the request. The victim is then redirected to an + endpoint under the control of the attacker with the authorization + code. The attacker completes the authorization flow by sending the + authorization code to the client using the original redirection URI + provided by the client. The client exchanges the authorization code + with an access token and links it to the attacker's client account, + which can now gain access to the protected resources authorized by + the victim (via the client). + + In order to prevent such an attack, the authorization server MUST + ensure that the redirection URI used to obtain the authorization code + is identical to the redirection URI provided when exchanging the + authorization code for an access token. The authorization server + MUST require public clients and SHOULD require confidential clients + to register their redirection URIs. If a redirection URI is provided + in the request, the authorization server MUST validate it against the + registered value. + +10.7. Resource Owner Password Credentials + + The resource owner password credentials grant type is often used for + legacy or migration reasons. It reduces the overall risk of storing + usernames and passwords by the client but does not eliminate the need + to expose highly privileged credentials to the client. + + This grant type carries a higher risk than other grant types because + it maintains the password anti-pattern this protocol seeks to avoid. + The client could abuse the password, or the password could + unintentionally be disclosed to an attacker (e.g., via log files or + other records kept by the client). + + Additionally, because the resource owner does not have control over + the authorization process (the resource owner's involvement ends when + it hands over its credentials to the client), the client can obtain + access tokens with a broader scope than desired by the resource + owner. The authorization server should consider the scope and + lifetime of access tokens issued via this grant type. + + The authorization server and client SHOULD minimize use of this grant + type and utilize other grant types whenever possible. + + + + + +Hardt Standards Track [Page 57] + +RFC 6749 OAuth 2.0 October 2012 + + +10.8. Request Confidentiality + + Access tokens, refresh tokens, resource owner passwords, and client + credentials MUST NOT be transmitted in the clear. Authorization + codes SHOULD NOT be transmitted in the clear. + + The "state" and "scope" parameters SHOULD NOT include sensitive + client or resource owner information in plain text, as they can be + transmitted over insecure channels or stored insecurely. + +10.9. Ensuring Endpoint Authenticity + + In order to prevent man-in-the-middle attacks, the authorization + server MUST require the use of TLS with server authentication as + defined by [RFC2818] for any request sent to the authorization and + token endpoints. The client MUST validate the authorization server's + TLS certificate as defined by [RFC6125] and in accordance with its + requirements for server identity authentication. + +10.10. Credentials-Guessing Attacks + + The authorization server MUST prevent attackers from guessing access + tokens, authorization codes, refresh tokens, resource owner + passwords, and client credentials. + + The probability of an attacker guessing generated tokens (and other + credentials not intended for handling by end-users) MUST be less than + or equal to 2^(-128) and SHOULD be less than or equal to 2^(-160). + + The authorization server MUST utilize other means to protect + credentials intended for end-user usage. + +10.11. Phishing Attacks + + Wide deployment of this and similar protocols may cause end-users to + become inured to the practice of being redirected to websites where + they are asked to enter their passwords. If end-users are not + careful to verify the authenticity of these websites before entering + their credentials, it will be possible for attackers to exploit this + practice to steal resource owners' passwords. + + Service providers should attempt to educate end-users about the risks + phishing attacks pose and should provide mechanisms that make it easy + for end-users to confirm the authenticity of their sites. Client + developers should consider the security implications of how they + interact with the user-agent (e.g., external, embedded), and the + ability of the end-user to verify the authenticity of the + authorization server. + + + +Hardt Standards Track [Page 58] + +RFC 6749 OAuth 2.0 October 2012 + + + To reduce the risk of phishing attacks, the authorization servers + MUST require the use of TLS on every endpoint used for end-user + interaction. + +10.12. Cross-Site Request Forgery + + Cross-site request forgery (CSRF) is an exploit in which an attacker + causes the user-agent of a victim end-user to follow a malicious URI + (e.g., provided to the user-agent as a misleading link, image, or + redirection) to a trusting server (usually established via the + presence of a valid session cookie). + + A CSRF attack against the client's redirection URI allows an attacker + to inject its own authorization code or access token, which can + result in the client using an access token associated with the + attacker's protected resources rather than the victim's (e.g., save + the victim's bank account information to a protected resource + controlled by the attacker). + + The client MUST implement CSRF protection for its redirection URI. + This is typically accomplished by requiring any request sent to the + redirection URI endpoint to include a value that binds the request to + the user-agent's authenticated state (e.g., a hash of the session + cookie used to authenticate the user-agent). The client SHOULD + utilize the "state" request parameter to deliver this value to the + authorization server when making an authorization request. + + Once authorization has been obtained from the end-user, the + authorization server redirects the end-user's user-agent back to the + client with the required binding value contained in the "state" + parameter. The binding value enables the client to verify the + validity of the request by matching the binding value to the + user-agent's authenticated state. The binding value used for CSRF + protection MUST contain a non-guessable value (as described in + Section 10.10), and the user-agent's authenticated state (e.g., + session cookie, HTML5 local storage) MUST be kept in a location + accessible only to the client and the user-agent (i.e., protected by + same-origin policy). + + A CSRF attack against the authorization server's authorization + endpoint can result in an attacker obtaining end-user authorization + for a malicious client without involving or alerting the end-user. + + The authorization server MUST implement CSRF protection for its + authorization endpoint and ensure that a malicious client cannot + obtain authorization without the awareness and explicit consent of + the resource owner. + + + + +Hardt Standards Track [Page 59] + +RFC 6749 OAuth 2.0 October 2012 + + +10.13. Clickjacking + + In a clickjacking attack, an attacker registers a legitimate client + and then constructs a malicious site in which it loads the + authorization server's authorization endpoint web page in a + transparent iframe overlaid on top of a set of dummy buttons, which + are carefully constructed to be placed directly under important + buttons on the authorization page. When an end-user clicks a + misleading visible button, the end-user is actually clicking an + invisible button on the authorization page (such as an "Authorize" + button). This allows an attacker to trick a resource owner into + granting its client access without the end-user's knowledge. + + To prevent this form of attack, native applications SHOULD use + external browsers instead of embedding browsers within the + application when requesting end-user authorization. For most newer + browsers, avoidance of iframes can be enforced by the authorization + server using the (non-standard) "x-frame-options" header. This + header can have two values, "deny" and "sameorigin", which will block + any framing, or framing by sites with a different origin, + respectively. For older browsers, JavaScript frame-busting + techniques can be used but may not be effective in all browsers. + +10.14. Code Injection and Input Validation + + A code injection attack occurs when an input or otherwise external + variable is used by an application unsanitized and causes + modification to the application logic. This may allow an attacker to + gain access to the application device or its data, cause denial of + service, or introduce a wide range of malicious side-effects. + + The authorization server and client MUST sanitize (and validate when + possible) any value received -- in particular, the value of the + "state" and "redirect_uri" parameters. + +10.15. Open Redirectors + + The authorization server, authorization endpoint, and client + redirection endpoint can be improperly configured and operate as open + redirectors. An open redirector is an endpoint using a parameter to + automatically redirect a user-agent to the location specified by the + parameter value without any validation. + + Open redirectors can be used in phishing attacks, or by an attacker + to get end-users to visit malicious sites by using the URI authority + component of a familiar and trusted destination. In addition, if the + authorization server allows the client to register only part of the + redirection URI, an attacker can use an open redirector operated by + + + +Hardt Standards Track [Page 60] + +RFC 6749 OAuth 2.0 October 2012 + + + the client to construct a redirection URI that will pass the + authorization server validation but will send the authorization code + or access token to an endpoint under the control of the attacker. + +10.16. Misuse of Access Token to Impersonate Resource Owner in Implicit + Flow + + For public clients using implicit flows, this specification does not + provide any method for the client to determine what client an access + token was issued to. + + A resource owner may willingly delegate access to a resource by + granting an access token to an attacker's malicious client. This may + be due to phishing or some other pretext. An attacker may also steal + a token via some other mechanism. An attacker may then attempt to + impersonate the resource owner by providing the access token to a + legitimate public client. + + In the implicit flow (response_type=token), the attacker can easily + switch the token in the response from the authorization server, + replacing the real access token with the one previously issued to the + attacker. + + Servers communicating with native applications that rely on being + passed an access token in the back channel to identify the user of + the client may be similarly compromised by an attacker creating a + compromised application that can inject arbitrary stolen access + tokens. + + Any public client that makes the assumption that only the resource + owner can present it with a valid access token for the resource is + vulnerable to this type of attack. + + This type of attack may expose information about the resource owner + at the legitimate client to the attacker (malicious client). This + will also allow the attacker to perform operations at the legitimate + client with the same permissions as the resource owner who originally + granted the access token or authorization code. + + Authenticating resource owners to clients is out of scope for this + specification. Any specification that uses the authorization process + as a form of delegated end-user authentication to the client (e.g., + third-party sign-in service) MUST NOT use the implicit flow without + additional security mechanisms that would enable the client to + determine if the access token was issued for its use (e.g., audience- + restricting the access token). + + + + + +Hardt Standards Track [Page 61] + +RFC 6749 OAuth 2.0 October 2012 + + +11. IANA Considerations + +11.1. OAuth Access Token Types Registry + + This specification establishes the OAuth Access Token Types registry. + + Access token types are registered with a Specification Required + ([RFC5226]) after a two-week review period on the + oauth-ext-review@ietf.org mailing list, on the advice of one or more + Designated Experts. However, to allow for the allocation of values + prior to publication, the Designated Expert(s) may approve + registration once they are satisfied that such a specification will + be published. + + Registration requests must be sent to the oauth-ext-review@ietf.org + mailing list for review and comment, with an appropriate subject + (e.g., "Request for access token type: example"). + + Within the review period, the Designated Expert(s) will either + approve or deny the registration request, communicating this decision + to the review list and IANA. Denials should include an explanation + and, if applicable, suggestions as to how to make the request + successful. + + IANA must only accept registry updates from the Designated Expert(s) + and should direct all requests for registration to the review mailing + list. + +11.1.1. Registration Template + + Type name: + The name requested (e.g., "example"). + + Additional Token Endpoint Response Parameters: + Additional response parameters returned together with the + "access_token" parameter. New parameters MUST be separately + registered in the OAuth Parameters registry as described by + Section 11.2. + + HTTP Authentication Scheme(s): + The HTTP authentication scheme name(s), if any, used to + authenticate protected resource requests using access tokens of + this type. + + Change controller: + For Standards Track RFCs, state "IETF". For others, give the name + of the responsible party. Other details (e.g., postal address, + email address, home page URI) may also be included. + + + +Hardt Standards Track [Page 62] + +RFC 6749 OAuth 2.0 October 2012 + + + Specification document(s): + Reference to the document(s) that specify the parameter, + preferably including a URI that can be used to retrieve a copy of + the document(s). An indication of the relevant sections may also + be included but is not required. + +11.2. OAuth Parameters Registry + + This specification establishes the OAuth Parameters registry. + + Additional parameters for inclusion in the authorization endpoint + request, the authorization endpoint response, the token endpoint + request, or the token endpoint response are registered with a + Specification Required ([RFC5226]) after a two-week review period on + the oauth-ext-review@ietf.org mailing list, on the advice of one or + more Designated Experts. However, to allow for the allocation of + values prior to publication, the Designated Expert(s) may approve + registration once they are satisfied that such a specification will + be published. + + Registration requests must be sent to the oauth-ext-review@ietf.org + mailing list for review and comment, with an appropriate subject + (e.g., "Request for parameter: example"). + + Within the review period, the Designated Expert(s) will either + approve or deny the registration request, communicating this decision + to the review list and IANA. Denials should include an explanation + and, if applicable, suggestions as to how to make the request + successful. + + IANA must only accept registry updates from the Designated Expert(s) + and should direct all requests for registration to the review mailing + list. + +11.2.1. Registration Template + + Parameter name: + The name requested (e.g., "example"). + + Parameter usage location: + The location(s) where parameter can be used. The possible + locations are authorization request, authorization response, token + request, or token response. + + Change controller: + For Standards Track RFCs, state "IETF". For others, give the name + of the responsible party. Other details (e.g., postal address, + email address, home page URI) may also be included. + + + +Hardt Standards Track [Page 63] + +RFC 6749 OAuth 2.0 October 2012 + + + Specification document(s): + Reference to the document(s) that specify the parameter, + preferably including a URI that can be used to retrieve a copy of + the document(s). An indication of the relevant sections may also + be included but is not required. + +11.2.2. Initial Registry Contents + + The OAuth Parameters registry's initial contents are: + + o Parameter name: client_id + o Parameter usage location: authorization request, token request + o Change controller: IETF + o Specification document(s): RFC 6749 + + o Parameter name: client_secret + o Parameter usage location: token request + o Change controller: IETF + o Specification document(s): RFC 6749 + + o Parameter name: response_type + o Parameter usage location: authorization request + o Change controller: IETF + o Specification document(s): RFC 6749 + + o Parameter name: redirect_uri + o Parameter usage location: authorization request, token request + o Change controller: IETF + o Specification document(s): RFC 6749 + + o Parameter name: scope + o Parameter usage location: authorization request, authorization + response, token request, token response + o Change controller: IETF + o Specification document(s): RFC 6749 + + o Parameter name: state + o Parameter usage location: authorization request, authorization + response + o Change controller: IETF + o Specification document(s): RFC 6749 + + o Parameter name: code + o Parameter usage location: authorization response, token request + o Change controller: IETF + o Specification document(s): RFC 6749 + + + + + +Hardt Standards Track [Page 64] + +RFC 6749 OAuth 2.0 October 2012 + + + o Parameter name: error_description + o Parameter usage location: authorization response, token response + o Change controller: IETF + o Specification document(s): RFC 6749 + + o Parameter name: error_uri + o Parameter usage location: authorization response, token response + o Change controller: IETF + o Specification document(s): RFC 6749 + + o Parameter name: grant_type + o Parameter usage location: token request + o Change controller: IETF + o Specification document(s): RFC 6749 + + o Parameter name: access_token + o Parameter usage location: authorization response, token response + o Change controller: IETF + o Specification document(s): RFC 6749 + + o Parameter name: token_type + o Parameter usage location: authorization response, token response + o Change controller: IETF + o Specification document(s): RFC 6749 + + o Parameter name: expires_in + o Parameter usage location: authorization response, token response + o Change controller: IETF + o Specification document(s): RFC 6749 + + o Parameter name: username + o Parameter usage location: token request + o Change controller: IETF + o Specification document(s): RFC 6749 + + o Parameter name: password + o Parameter usage location: token request + o Change controller: IETF + o Specification document(s): RFC 6749 + + o Parameter name: refresh_token + o Parameter usage location: token request, token response + o Change controller: IETF + o Specification document(s): RFC 6749 + + + + + + + +Hardt Standards Track [Page 65] + +RFC 6749 OAuth 2.0 October 2012 + + +11.3. OAuth Authorization Endpoint Response Types Registry + + This specification establishes the OAuth Authorization Endpoint + Response Types registry. + + Additional response types for use with the authorization endpoint are + registered with a Specification Required ([RFC5226]) after a two-week + review period on the oauth-ext-review@ietf.org mailing list, on the + advice of one or more Designated Experts. However, to allow for the + allocation of values prior to publication, the Designated Expert(s) + may approve registration once they are satisfied that such a + specification will be published. + + Registration requests must be sent to the oauth-ext-review@ietf.org + mailing list for review and comment, with an appropriate subject + (e.g., "Request for response type: example"). + + Within the review period, the Designated Expert(s) will either + approve or deny the registration request, communicating this decision + to the review list and IANA. Denials should include an explanation + and, if applicable, suggestions as to how to make the request + successful. + + IANA must only accept registry updates from the Designated Expert(s) + and should direct all requests for registration to the review mailing + list. + +11.3.1. Registration Template + + Response type name: + The name requested (e.g., "example"). + + Change controller: + For Standards Track RFCs, state "IETF". For others, give the name + of the responsible party. Other details (e.g., postal address, + email address, home page URI) may also be included. + + Specification document(s): + Reference to the document(s) that specify the type, preferably + including a URI that can be used to retrieve a copy of the + document(s). An indication of the relevant sections may also be + included but is not required. + + + + + + + + + +Hardt Standards Track [Page 66] + +RFC 6749 OAuth 2.0 October 2012 + + +11.3.2. Initial Registry Contents + + The OAuth Authorization Endpoint Response Types registry's initial + contents are: + + o Response type name: code + o Change controller: IETF + o Specification document(s): RFC 6749 + + o Response type name: token + o Change controller: IETF + o Specification document(s): RFC 6749 + +11.4. OAuth Extensions Error Registry + + This specification establishes the OAuth Extensions Error registry. + + Additional error codes used together with other protocol extensions + (i.e., extension grant types, access token types, or extension + parameters) are registered with a Specification Required ([RFC5226]) + after a two-week review period on the oauth-ext-review@ietf.org + mailing list, on the advice of one or more Designated Experts. + However, to allow for the allocation of values prior to publication, + the Designated Expert(s) may approve registration once they are + satisfied that such a specification will be published. + + Registration requests must be sent to the oauth-ext-review@ietf.org + mailing list for review and comment, with an appropriate subject + (e.g., "Request for error code: example"). + + Within the review period, the Designated Expert(s) will either + approve or deny the registration request, communicating this decision + to the review list and IANA. Denials should include an explanation + and, if applicable, suggestions as to how to make the request + successful. + + IANA must only accept registry updates from the Designated Expert(s) + and should direct all requests for registration to the review mailing + list. + + + + + + + + + + + + +Hardt Standards Track [Page 67] + +RFC 6749 OAuth 2.0 October 2012 + + +11.4.1. Registration Template + + Error name: + The name requested (e.g., "example"). Values for the error name + MUST NOT include characters outside the set %x20-21 / %x23-5B / + %x5D-7E. + + Error usage location: + The location(s) where the error can be used. The possible + locations are authorization code grant error response + (Section 4.1.2.1), implicit grant error response + (Section 4.2.2.1), token error response (Section 5.2), or resource + access error response (Section 7.2). + + Related protocol extension: + The name of the extension grant type, access token type, or + extension parameter that the error code is used in conjunction + with. + + Change controller: + For Standards Track RFCs, state "IETF". For others, give the name + of the responsible party. Other details (e.g., postal address, + email address, home page URI) may also be included. + + Specification document(s): + Reference to the document(s) that specify the error code, + preferably including a URI that can be used to retrieve a copy of + the document(s). An indication of the relevant sections may also + be included but is not required. + +12. References + +12.1. Normative References + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", + RFC 2246, January 1999. + + [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., + Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext + Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. + + [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., + Leach, P., Luotonen, A., and L. Stewart, "HTTP + Authentication: Basic and Digest Access Authentication", + RFC 2617, June 1999. + + + +Hardt Standards Track [Page 68] + +RFC 6749 OAuth 2.0 October 2012 + + + [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. + + [RFC3629] Yergeau, F., "UTF-8, a transformation format of + ISO 10646", STD 63, RFC 3629, November 2003. + + [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform + Resource Identifier (URI): Generic Syntax", STD 66, + RFC 3986, January 2005. + + [RFC4627] Crockford, D., "The application/json Media Type for + JavaScript Object Notation (JSON)", RFC 4627, July 2006. + + [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", + RFC 4949, August 2007. + + [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an + IANA Considerations Section in RFCs", BCP 26, RFC 5226, + May 2008. + + [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax + Specifications: ABNF", STD 68, RFC 5234, January 2008. + + [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security + (TLS) Protocol Version 1.2", RFC 5246, August 2008. + + [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and + Verification of Domain-Based Application Service Identity + within Internet Public Key Infrastructure Using X.509 + (PKIX) Certificates in the Context of Transport Layer + Security (TLS)", RFC 6125, March 2011. + + [USASCII] American National Standards Institute, "Coded Character + Set -- 7-bit American Standard Code for Information + Interchange", ANSI X3.4, 1986. + + [W3C.REC-html401-19991224] + Raggett, D., Le Hors, A., and I. Jacobs, "HTML 4.01 + Specification", World Wide Web Consortium + Recommendation REC-html401-19991224, December 1999, + . + + [W3C.REC-xml-20081126] + Bray, T., Paoli, J., Sperberg-McQueen, C., Maler, E., + and F. Yergeau, "Extensible Markup Language (XML) 1.0 + (Fifth Edition)", World Wide Web Consortium + Recommendation REC-xml-20081126, November 2008, + . + + + + +Hardt Standards Track [Page 69] + +RFC 6749 OAuth 2.0 October 2012 + + +12.2. Informative References + + [OAuth-HTTP-MAC] + Hammer-Lahav, E., Ed., "HTTP Authentication: MAC Access + Authentication", Work in Progress, February 2012. + + [OAuth-SAML2] + Campbell, B. and C. Mortimore, "SAML 2.0 Bearer Assertion + Profiles for OAuth 2.0", Work in Progress, September 2012. + + [OAuth-THREATMODEL] + Lodderstedt, T., Ed., McGloin, M., and P. Hunt, "OAuth 2.0 + Threat Model and Security Considerations", Work + in Progress, October 2012. + + [OAuth-WRAP] + Hardt, D., Ed., Tom, A., Eaton, B., and Y. Goland, "OAuth + Web Resource Authorization Profiles", Work in Progress, + January 2010. + + [RFC5849] Hammer-Lahav, E., "The OAuth 1.0 Protocol", RFC 5849, + April 2010. + + [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization + Framework: Bearer Token Usage", RFC 6750, October 2012. + + + + + + + + + + + + + + + + + + + + + + + + + + +Hardt Standards Track [Page 70] + +RFC 6749 OAuth 2.0 October 2012 + + +Appendix A. Augmented Backus-Naur Form (ABNF) Syntax + + This section provides Augmented Backus-Naur Form (ABNF) syntax + descriptions for the elements defined in this specification using the + notation of [RFC5234]. The ABNF below is defined in terms of Unicode + code points [W3C.REC-xml-20081126]; these characters are typically + encoded in UTF-8. Elements are presented in the order first defined. + + Some of the definitions that follow use the "URI-reference" + definition from [RFC3986]. + + Some of the definitions that follow use these common definitions: + + VSCHAR = %x20-7E + NQCHAR = %x21 / %x23-5B / %x5D-7E + NQSCHAR = %x20-21 / %x23-5B / %x5D-7E + UNICODECHARNOCRLF = %x09 /%x20-7E / %x80-D7FF / + %xE000-FFFD / %x10000-10FFFF + + (The UNICODECHARNOCRLF definition is based upon the Char definition + in Section 2.2 of [W3C.REC-xml-20081126], but omitting the Carriage + Return and Linefeed characters.) + +A.1. "client_id" Syntax + + The "client_id" element is defined in Section 2.3.1: + + client-id = *VSCHAR + +A.2. "client_secret" Syntax + + The "client_secret" element is defined in Section 2.3.1: + + client-secret = *VSCHAR + +A.3. "response_type" Syntax + + The "response_type" element is defined in Sections 3.1.1 and 8.4: + + response-type = response-name *( SP response-name ) + response-name = 1*response-char + response-char = "_" / DIGIT / ALPHA + + + + + + + + + +Hardt Standards Track [Page 71] + +RFC 6749 OAuth 2.0 October 2012 + + +A.4. "scope" Syntax + + The "scope" element is defined in Section 3.3: + + scope = scope-token *( SP scope-token ) + scope-token = 1*NQCHAR + +A.5. "state" Syntax + + The "state" element is defined in Sections 4.1.1, 4.1.2, 4.1.2.1, + 4.2.1, 4.2.2, and 4.2.2.1: + + state = 1*VSCHAR + +A.6. "redirect_uri" Syntax + + The "redirect_uri" element is defined in Sections 4.1.1, 4.1.3, + and 4.2.1: + + redirect-uri = URI-reference + +A.7. "error" Syntax + + The "error" element is defined in Sections 4.1.2.1, 4.2.2.1, 5.2, + 7.2, and 8.5: + + error = 1*NQSCHAR + +A.8. "error_description" Syntax + + The "error_description" element is defined in Sections 4.1.2.1, + 4.2.2.1, 5.2, and 7.2: + + error-description = 1*NQSCHAR + +A.9. "error_uri" Syntax + + The "error_uri" element is defined in Sections 4.1.2.1, 4.2.2.1, 5.2, + and 7.2: + + error-uri = URI-reference + + + + + + + + + + +Hardt Standards Track [Page 72] + +RFC 6749 OAuth 2.0 October 2012 + + +A.10. "grant_type" Syntax + + The "grant_type" element is defined in Sections 4.1.3, 4.3.2, 4.4.2, + 4.5, and 6: + + grant-type = grant-name / URI-reference + grant-name = 1*name-char + name-char = "-" / "." / "_" / DIGIT / ALPHA + +A.11. "code" Syntax + + The "code" element is defined in Section 4.1.3: + + code = 1*VSCHAR + +A.12. "access_token" Syntax + + The "access_token" element is defined in Sections 4.2.2 and 5.1: + + access-token = 1*VSCHAR + +A.13. "token_type" Syntax + + The "token_type" element is defined in Sections 4.2.2, 5.1, and 8.1: + + token-type = type-name / URI-reference + type-name = 1*name-char + name-char = "-" / "." / "_" / DIGIT / ALPHA + +A.14. "expires_in" Syntax + + The "expires_in" element is defined in Sections 4.2.2 and 5.1: + + expires-in = 1*DIGIT + +A.15. "username" Syntax + + The "username" element is defined in Section 4.3.2: + + username = *UNICODECHARNOCRLF + +A.16. "password" Syntax + + The "password" element is defined in Section 4.3.2: + + password = *UNICODECHARNOCRLF + + + + + +Hardt Standards Track [Page 73] + +RFC 6749 OAuth 2.0 October 2012 + + +A.17. "refresh_token" Syntax + + The "refresh_token" element is defined in Sections 5.1 and 6: + + refresh-token = 1*VSCHAR + +A.18. Endpoint Parameter Syntax + + The syntax for new endpoint parameters is defined in Section 8.2: + + param-name = 1*name-char + name-char = "-" / "." / "_" / DIGIT / ALPHA + +Appendix B. Use of application/x-www-form-urlencoded Media Type + + At the time of publication of this specification, the + "application/x-www-form-urlencoded" media type was defined in + Section 17.13.4 of [W3C.REC-html401-19991224] but not registered in + the IANA MIME Media Types registry + (). Furthermore, that + definition is incomplete, as it does not consider non-US-ASCII + characters. + + To address this shortcoming when generating payloads using this media + type, names and values MUST be encoded using the UTF-8 character + encoding scheme [RFC3629] first; the resulting octet sequence then + needs to be further encoded using the escaping rules defined in + [W3C.REC-html401-19991224]. + + When parsing data from a payload using this media type, the names and + values resulting from reversing the name/value encoding consequently + need to be treated as octet sequences, to be decoded using the UTF-8 + character encoding scheme. + + For example, the value consisting of the six Unicode code points + (1) U+0020 (SPACE), (2) U+0025 (PERCENT SIGN), + (3) U+0026 (AMPERSAND), (4) U+002B (PLUS SIGN), + (5) U+00A3 (POUND SIGN), and (6) U+20AC (EURO SIGN) would be encoded + into the octet sequence below (using hexadecimal notation): + + 20 25 26 2B C2 A3 E2 82 AC + + and then represented in the payload as: + + +%25%26%2B%C2%A3%E2%82%AC + + + + + + +Hardt Standards Track [Page 74] + +RFC 6749 OAuth 2.0 October 2012 + + +Appendix C. Acknowledgements + + The initial OAuth 2.0 protocol specification was edited by David + Recordon, based on two previous publications: the OAuth 1.0 community + specification [RFC5849], and OAuth WRAP (OAuth Web Resource + Authorization Profiles) [OAuth-WRAP]. Eran Hammer then edited many + of the intermediate drafts that evolved into this RFC. The Security + Considerations section was drafted by Torsten Lodderstedt, Mark + McGloin, Phil Hunt, Anthony Nadalin, and John Bradley. The section + on use of the "application/x-www-form-urlencoded" media type was + drafted by Julian Reschke. The ABNF section was drafted by Michael + B. Jones. + + The OAuth 1.0 community specification was edited by Eran Hammer and + authored by Mark Atwood, Dirk Balfanz, Darren Bounds, Richard M. + Conlan, Blaine Cook, Leah Culver, Breno de Medeiros, Brian Eaton, + Kellan Elliott-McCrea, Larry Halff, Eran Hammer, Ben Laurie, Chris + Messina, John Panzer, Sam Quigley, David Recordon, Eran Sandler, + Jonathan Sergent, Todd Sieling, Brian Slesinsky, and Andy Smith. + + The OAuth WRAP specification was edited by Dick Hardt and authored by + Brian Eaton, Yaron Y. Goland, Dick Hardt, and Allen Tom. + + This specification is the work of the OAuth Working Group, which + includes dozens of active and dedicated participants. In particular, + the following individuals contributed ideas, feedback, and wording + that shaped and formed the final specification: + + Michael Adams, Amanda Anganes, Andrew Arnott, Dirk Balfanz, Aiden + Bell, John Bradley, Marcos Caceres, Brian Campbell, Scott Cantor, + Blaine Cook, Roger Crew, Leah Culver, Bill de hOra, Andre DeMarre, + Brian Eaton, Wesley Eddy, Wolter Eldering, Brian Ellin, Igor + Faynberg, George Fletcher, Tim Freeman, Luca Frosini, Evan Gilbert, + Yaron Y. Goland, Brent Goldman, Kristoffer Gronowski, Eran Hammer, + Dick Hardt, Justin Hart, Craig Heath, Phil Hunt, Michael B. Jones, + Terry Jones, John Kemp, Mark Kent, Raffi Krikorian, Chasen Le Hara, + Rasmus Lerdorf, Torsten Lodderstedt, Hui-Lan Lu, Casey Lucas, Paul + Madsen, Alastair Mair, Eve Maler, James Manger, Mark McGloin, + Laurence Miao, William Mills, Chuck Mortimore, Anthony Nadalin, + Julian Reschke, Justin Richer, Peter Saint-Andre, Nat Sakimura, Rob + Sayre, Marius Scurtescu, Naitik Shah, Luke Shepard, Vlad Skvortsov, + Justin Smith, Haibin Song, Niv Steingarten, Christian Stuebner, + Jeremy Suriel, Paul Tarjan, Christopher Thomas, Henry S. Thompson, + Allen Tom, Franklin Tse, Nick Walker, Shane Weeden, and Skylar + Woodward. + + + + + + +Hardt Standards Track [Page 75] + +RFC 6749 OAuth 2.0 October 2012 + + + This document was produced under the chairmanship of Blaine Cook, + Peter Saint-Andre, Hannes Tschofenig, Barry Leiba, and Derek Atkins. + The area directors included Lisa Dusseault, Peter Saint-Andre, and + Stephen Farrell. + +Author's Address + + Dick Hardt (editor) + Microsoft + + EMail: dick.hardt@gmail.com + URI: http://dickhardt.org/ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Hardt Standards Track [Page 76] + diff --git a/docs/rfc6750.txt b/docs/rfc6750.txt new file mode 100644 index 0000000..b433c72 --- /dev/null +++ b/docs/rfc6750.txt @@ -0,0 +1,1011 @@ + + + + + + +Internet Engineering Task Force (IETF) M. Jones +Request for Comments: 6750 Microsoft +Category: Standards Track D. Hardt +ISSN: 2070-1721 Independent + October 2012 + + + The OAuth 2.0 Authorization Framework: Bearer Token Usage + +Abstract + + 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. + +Status of This Memo + + This is an Internet Standards Track document. + + This document is a product of the Internet Engineering Task Force + (IETF). It represents the consensus of the IETF community. It has + received public review and has been approved for publication by the + Internet Engineering Steering Group (IESG). Further information on + Internet Standards is available in Section 2 of RFC 5741. + + Information about the current status of this document, any errata, + and how to provide feedback on it may be obtained at + http://www.rfc-editor.org/info/rfc6750. + +Copyright Notice + + Copyright (c) 2012 IETF Trust and the persons identified as the + document authors. All rights reserved. + + This document is subject to BCP 78 and the IETF Trust's Legal + Provisions Relating to IETF Documents + (http://trustee.ietf.org/license-info) 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. Code Components extracted from this document must + include Simplified BSD License text as described in Section 4.e of + the Trust Legal Provisions and are provided without warranty as + described in the Simplified BSD License. + + + + + +Jones & Hardt Standards Track [Page 1] + +RFC 6750 OAuth 2.0 Bearer Token Usage October 2012 + + +Table of Contents + + 1. Introduction ....................................................2 + 1.1. Notational Conventions .....................................3 + 1.2. Terminology ................................................3 + 1.3. Overview ...................................................3 + 2. Authenticated Requests ..........................................4 + 2.1. Authorization Request Header Field .........................5 + 2.2. Form-Encoded Body Parameter ................................5 + 2.3. URI Query Parameter ........................................6 + 3. The WWW-Authenticate Response Header Field ......................7 + 3.1. Error Codes ................................................9 + 4. Example Access Token Response ..................................10 + 5. Security Considerations ........................................10 + 5.1. Security Threats ..........................................10 + 5.2. Threat Mitigation .........................................11 + 5.3. Summary of Recommendations ................................13 + 6. IANA Considerations ............................................14 + 6.1. OAuth Access Token Type Registration ......................14 + 6.1.1. The "Bearer" OAuth Access Token Type ...............14 + 6.2. OAuth Extensions Error Registration .......................14 + 6.2.1. The "invalid_request" Error Value ..................14 + 6.2.2. The "invalid_token" Error Value ....................15 + 6.2.3. The "insufficient_scope" Error Value ...............15 + 7. References .....................................................15 + 7.1. Normative References ......................................15 + 7.2. Informative References ....................................17 + Appendix A. Acknowledgements ......................................18 + +1. Introduction + + OAuth enables clients to access protected resources by obtaining an + access token, which is defined in "The OAuth 2.0 Authorization + Framework" [RFC6749] as "a string representing an access + authorization issued to the client", rather than using the resource + owner's credentials directly. + + Tokens are issued to clients by an authorization server with the + approval of the resource owner. The client uses the access token to + access the protected resources hosted by the resource server. This + specification describes how to make protected resource requests when + the OAuth access token is a bearer token. + + This specification defines the use of bearer tokens over HTTP/1.1 + [RFC2616] using Transport Layer Security (TLS) [RFC5246] to access + protected resources. TLS is mandatory to implement and use with this + specification; other specifications may extend this specification for + use with other protocols. While designed for use with access tokens + + + +Jones & Hardt Standards Track [Page 2] + +RFC 6750 OAuth 2.0 Bearer Token Usage October 2012 + + + resulting from OAuth 2.0 authorization [RFC6749] flows to access + OAuth protected resources, this specification actually defines a + general HTTP authorization method that can be used with bearer tokens + from any source to access any resources protected by those bearer + tokens. The Bearer authentication scheme is intended primarily for + server authentication using the WWW-Authenticate and Authorization + HTTP headers but does not preclude its use for proxy authentication. + +1.1. Notational Conventions + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in "Key words for use in + RFCs to Indicate Requirement Levels" [RFC2119]. + + This document uses the Augmented Backus-Naur Form (ABNF) notation of + [RFC5234]. Additionally, the following rules are included from + HTTP/1.1 [RFC2617]: auth-param and auth-scheme; and from "Uniform + Resource Identifier (URI): Generic Syntax" [RFC3986]: URI-reference. + + Unless otherwise noted, all the protocol parameter names and values + are case sensitive. + +1.2. Terminology + + Bearer Token + A security token with the property that any party in possession of + the token (a "bearer") can use the token in any way that any other + party in possession of it can. Using a bearer token does not + require a bearer to prove possession of cryptographic key material + (proof-of-possession). + + All other terms are as defined in "The OAuth 2.0 Authorization + Framework" [RFC6749]. + +1.3. Overview + + OAuth provides a method for clients to access a protected resource on + behalf of a resource owner. In the general case, before a client can + access a protected resource, it must first obtain an authorization + grant from the resource owner and then exchange the authorization + grant for an access token. The access token represents the grant's + scope, duration, and other attributes granted by the authorization + grant. The client accesses the protected resource by presenting the + access token to the resource server. In some cases, a client can + directly present its own credentials to an authorization server to + obtain an access token without having to first obtain an + authorization grant from a resource owner. + + + +Jones & Hardt Standards Track [Page 3] + +RFC 6750 OAuth 2.0 Bearer Token Usage October 2012 + + + The access token provides an abstraction, replacing different + authorization constructs (e.g., username and password, assertion) for + a single token understood by the resource server. This abstraction + enables issuing access tokens valid for a short time period, as well + as removing the resource server's need to understand a wide range of + authentication schemes. + + +--------+ +---------------+ + | |--(A)- Authorization Request ->| Resource | + | | | Owner | + | |<-(B)-- Authorization Grant ---| | + | | +---------------+ + | | + | | +---------------+ + | |--(C)-- Authorization Grant -->| Authorization | + | Client | | Server | + | |<-(D)----- Access Token -------| | + | | +---------------+ + | | + | | +---------------+ + | |--(E)----- Access Token ------>| Resource | + | | | Server | + | |<-(F)--- Protected Resource ---| | + +--------+ +---------------+ + + Figure 1: Abstract Protocol Flow + + The abstract OAuth 2.0 flow illustrated in Figure 1 describes the + interaction between the client, resource owner, authorization server, + and resource server (described in [RFC6749]). The following two + steps are specified within this document: + + (E) The client requests the protected resource from the resource + server and authenticates by presenting the access token. + + (F) The resource server validates the access token, and if valid, + serves the request. + + This document also imposes semantic requirements upon the access + token returned in step (D). + +2. Authenticated Requests + + This section defines three methods of sending bearer access tokens in + resource requests to resource servers. Clients MUST NOT use more + than one method to transmit the token in each request. + + + + + +Jones & Hardt Standards Track [Page 4] + +RFC 6750 OAuth 2.0 Bearer Token Usage October 2012 + + +2.1. Authorization Request Header Field + + When sending the access token in the "Authorization" request header + field defined by HTTP/1.1 [RFC2617], the client uses the "Bearer" + authentication scheme to transmit the access token. + + For example: + + GET /resource HTTP/1.1 + Host: server.example.com + Authorization: Bearer mF_9.B5f-4.1JqM + + The syntax of the "Authorization" header field for this scheme + follows the usage of the Basic scheme defined in Section 2 of + [RFC2617]. Note that, as with Basic, it does not conform to the + generic syntax defined in Section 1.2 of [RFC2617] but is compatible + with the general authentication framework being developed for + HTTP 1.1 [HTTP-AUTH], although it does not follow the preferred + practice outlined therein in order to reflect existing deployments. + The syntax for Bearer credentials is as follows: + + b64token = 1*( ALPHA / DIGIT / + "-" / "." / "_" / "~" / "+" / "/" ) *"=" + credentials = "Bearer" 1*SP b64token + + Clients SHOULD make authenticated requests with a bearer token using + the "Authorization" request header field with the "Bearer" HTTP + authorization scheme. Resource servers MUST support this method. + +2.2. Form-Encoded Body Parameter + + When sending the access token in the HTTP request entity-body, the + client adds the access token to the request-body using the + "access_token" parameter. The client MUST NOT use this method unless + all of the following conditions are met: + + o The HTTP request entity-header includes the "Content-Type" header + field set to "application/x-www-form-urlencoded". + + o The entity-body follows the encoding requirements of the + "application/x-www-form-urlencoded" content-type as defined by + HTML 4.01 [W3C.REC-html401-19991224]. + + o The HTTP request entity-body is single-part. + + + + + + + +Jones & Hardt Standards Track [Page 5] + +RFC 6750 OAuth 2.0 Bearer Token Usage October 2012 + + + o The content to be encoded in the entity-body MUST consist entirely + of ASCII [USASCII] characters. + + o The HTTP request method is one for which the request-body has + defined semantics. In particular, this means that the "GET" + method MUST NOT be used. + + The entity-body MAY include other request-specific parameters, in + which case the "access_token" parameter MUST be properly separated + from the request-specific parameters using "&" character(s) (ASCII + code 38). + + For example, the client makes the following HTTP request using + transport-layer security: + + POST /resource HTTP/1.1 + Host: server.example.com + Content-Type: application/x-www-form-urlencoded + + access_token=mF_9.B5f-4.1JqM + + The "application/x-www-form-urlencoded" method SHOULD NOT be used + except in application contexts where participating browsers do not + have access to the "Authorization" request header field. Resource + servers MAY support this method. + +2.3. URI Query Parameter + + When sending the access token in the HTTP request URI, the client + adds the access token to the request URI query component as defined + by "Uniform Resource Identifier (URI): Generic Syntax" [RFC3986], + using the "access_token" parameter. + + For example, the client makes the following HTTP request using + transport-layer security: + + GET /resource?access_token=mF_9.B5f-4.1JqM HTTP/1.1 + Host: server.example.com + + The HTTP request URI query can include other request-specific + parameters, in which case the "access_token" parameter MUST be + properly separated from the request-specific parameters using "&" + character(s) (ASCII code 38). + + + + + + + + +Jones & Hardt Standards Track [Page 6] + +RFC 6750 OAuth 2.0 Bearer Token Usage October 2012 + + + For example: + + https://server.example.com/resource?access_token=mF_9.B5f-4.1JqM&p=q + + Clients using the URI Query Parameter method SHOULD also send a + Cache-Control header containing the "no-store" option. Server + success (2XX status) responses to these requests SHOULD contain a + Cache-Control header with the "private" option. + + Because of the security weaknesses associated with the URI method + (see Section 5), including the high likelihood that the URL + containing the access token will be logged, it SHOULD NOT be used + unless it is impossible to transport the access token in the + "Authorization" request header field or the HTTP request entity-body. + Resource servers MAY support this method. + + This method is included to document current use; its use is not + recommended, due to its security deficiencies (see Section 5) and + also because it uses a reserved query parameter name, which is + counter to URI namespace best practices, per "Architecture of the + World Wide Web, Volume One" [W3C.REC-webarch-20041215]. + +3. The WWW-Authenticate Response Header Field + + If the protected resource request does not include authentication + credentials or does not contain an access token that enables access + to the protected resource, the resource server MUST include the HTTP + "WWW-Authenticate" response header field; it MAY include it in + response to other conditions as well. The "WWW-Authenticate" header + field uses the framework defined by HTTP/1.1 [RFC2617]. + + All challenges defined by this specification MUST use the auth-scheme + value "Bearer". This scheme MUST be followed by one or more + auth-param values. The auth-param attributes used or defined by this + specification are as follows. Other auth-param attributes MAY be + used as well. + + A "realm" attribute MAY be included to indicate the scope of + protection in the manner described in HTTP/1.1 [RFC2617]. The + "realm" attribute MUST NOT appear more than once. + + The "scope" attribute is defined in Section 3.3 of [RFC6749]. The + "scope" attribute is a space-delimited list of case-sensitive scope + values indicating the required scope of the access token for + accessing the requested resource. "scope" values are implementation + defined; there is no centralized registry for them; allowed values + are defined by the authorization server. The order of "scope" values + is not significant. In some cases, the "scope" value will be used + + + +Jones & Hardt Standards Track [Page 7] + +RFC 6750 OAuth 2.0 Bearer Token Usage October 2012 + + + when requesting a new access token with sufficient scope of access to + utilize the protected resource. Use of the "scope" attribute is + OPTIONAL. The "scope" attribute MUST NOT appear more than once. The + "scope" value is intended for programmatic use and is not meant to be + displayed to end-users. + + Two example scope values follow; these are taken from the OpenID + Connect [OpenID.Messages] and the Open Authentication Technology + Committee (OATC) Online Multimedia Authorization Protocol [OMAP] + OAuth 2.0 use cases, respectively: + + scope="openid profile email" + scope="urn:example:channel=HBO&urn:example:rating=G,PG-13" + + If the protected resource request included an access token and failed + authentication, the resource server SHOULD include the "error" + attribute to provide the client with the reason why the access + request was declined. The parameter value is described in + Section 3.1. In addition, the resource server MAY include the + "error_description" attribute to provide developers a human-readable + explanation that is not meant to be displayed to end-users. It also + MAY include the "error_uri" attribute with an absolute URI + identifying a human-readable web page explaining the error. The + "error", "error_description", and "error_uri" attributes MUST NOT + appear more than once. + + Values for the "scope" attribute (specified in Appendix A.4 of + [RFC6749]) MUST NOT include characters outside the set %x21 / %x23-5B + / %x5D-7E for representing scope values and %x20 for delimiters + between scope values. Values for the "error" and "error_description" + attributes (specified in Appendixes A.7 and A.8 of [RFC6749]) MUST + NOT include characters outside the set %x20-21 / %x23-5B / %x5D-7E. + Values for the "error_uri" attribute (specified in Appendix A.9 of + [RFC6749]) MUST conform to the URI-reference syntax and thus MUST NOT + include characters outside the set %x21 / %x23-5B / %x5D-7E. + + For example, in response to a protected resource request without + authentication: + + HTTP/1.1 401 Unauthorized + WWW-Authenticate: Bearer realm="example" + + + + + + + + + + +Jones & Hardt Standards Track [Page 8] + +RFC 6750 OAuth 2.0 Bearer Token Usage October 2012 + + + And in response to a protected resource request with an + authentication attempt using an expired access token: + + HTTP/1.1 401 Unauthorized + WWW-Authenticate: Bearer realm="example", + error="invalid_token", + error_description="The access token expired" + +3.1. Error Codes + + When a request fails, the resource server responds using the + appropriate HTTP status code (typically, 400, 401, 403, or 405) and + includes one of the following error codes in the response: + + invalid_request + The request is missing a required parameter, includes an + unsupported parameter or parameter value, repeats the same + parameter, uses more than one method for including an access + token, or is otherwise malformed. The resource server SHOULD + respond with the HTTP 400 (Bad Request) status code. + + invalid_token + The access token provided is expired, revoked, malformed, or + invalid for other reasons. The resource SHOULD respond with + the HTTP 401 (Unauthorized) status code. The client MAY + request a new access token and retry the protected resource + request. + + insufficient_scope + The request requires higher privileges than provided by the + access token. The resource server SHOULD respond with the HTTP + 403 (Forbidden) status code and MAY include the "scope" + attribute with the scope necessary to access the protected + resource. + + If the request lacks any authentication information (e.g., the client + was unaware that authentication is necessary or attempted using an + unsupported authentication method), the resource server SHOULD NOT + include an error code or other error information. + + For example: + + HTTP/1.1 401 Unauthorized + WWW-Authenticate: Bearer realm="example" + + + + + + + +Jones & Hardt Standards Track [Page 9] + +RFC 6750 OAuth 2.0 Bearer Token Usage October 2012 + + +4. Example Access Token Response + + Typically, a bearer token is returned to the client as part of an + OAuth 2.0 [RFC6749] access token response. An example of such a + response is: + + HTTP/1.1 200 OK + Content-Type: application/json;charset=UTF-8 + Cache-Control: no-store + Pragma: no-cache + + { + "access_token":"mF_9.B5f-4.1JqM", + "token_type":"Bearer", + "expires_in":3600, + "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA" + } + +5. Security Considerations + + This section describes the relevant security threats regarding token + handling when using bearer tokens and describes how to mitigate these + threats. + +5.1. Security Threats + + The following list presents several common threats against protocols + utilizing some form of tokens. This list of threats is based on NIST + Special Publication 800-63 [NIST800-63]. Since this document builds + on the OAuth 2.0 Authorization specification [RFC6749], we exclude a + discussion of threats that are described there or in related + documents. + + Token manufacture/modification: An attacker may generate a bogus + token or modify the token contents (such as the authentication or + attribute statements) of an existing token, causing the resource + server to grant inappropriate access to the client. For example, + an attacker may modify the token to extend the validity period; a + malicious client may modify the assertion to gain access to + information that they should not be able to view. + + Token disclosure: Tokens may contain authentication and attribute + statements that include sensitive information. + + + + + + + + +Jones & Hardt Standards Track [Page 10] + +RFC 6750 OAuth 2.0 Bearer Token Usage October 2012 + + + Token redirect: An attacker uses a token generated for consumption + by one resource server to gain access to a different resource + server that mistakenly believes the token to be for it. + + Token replay: An attacker attempts to use a token that has already + been used with that resource server in the past. + +5.2. Threat Mitigation + + A large range of threats can be mitigated by protecting the contents + of the token by using a digital signature or a Message Authentication + Code (MAC). Alternatively, a bearer token can contain a reference to + authorization information, rather than encoding the information + directly. Such references MUST be infeasible for an attacker to + guess; using a reference may require an extra interaction between a + server and the token issuer to resolve the reference to the + authorization information. The mechanics of such an interaction are + not defined by this specification. + + This document does not specify the encoding or the contents of the + token; hence, detailed recommendations about the means of + guaranteeing token integrity protection are outside the scope of this + document. The token integrity protection MUST be sufficient to + prevent the token from being modified. + + To deal with token redirect, it is important for the authorization + server to include the identity of the intended recipients (the + audience), typically a single resource server (or a list of resource + servers), in the token. Restricting the use of the token to a + specific scope is also RECOMMENDED. + + The authorization server MUST implement TLS. Which version(s) ought + to be implemented will vary over time and will depend on the + widespread deployment and known security vulnerabilities at the time + of implementation. At the time of this writing, TLS version 1.2 + [RFC5246] is the most recent version, but it has very limited actual + deployment and might not be readily available in implementation + toolkits. TLS version 1.0 [RFC2246] is the most widely deployed + version and will give the broadest interoperability. + + To protect against token disclosure, confidentiality protection MUST + be applied using TLS [RFC5246] with a ciphersuite that provides + confidentiality and integrity protection. This requires that the + communication interaction between the client and the authorization + server, as well as the interaction between the client and the + resource server, utilize confidentiality and integrity protection. + Since TLS is mandatory to implement and to use with this + specification, it is the preferred approach for preventing token + + + +Jones & Hardt Standards Track [Page 11] + +RFC 6750 OAuth 2.0 Bearer Token Usage October 2012 + + + disclosure via the communication channel. For those cases where the + client is prevented from observing the contents of the token, token + encryption MUST be applied in addition to the usage of TLS + protection. As a further defense against token disclosure, the + client MUST validate the TLS certificate chain when making requests + to protected resources, including checking the Certificate Revocation + List (CRL) [RFC5280]. + + Cookies are typically transmitted in the clear. Thus, any + information contained in them is at risk of disclosure. Therefore, + bearer tokens MUST NOT be stored in cookies that can be sent in the + clear. See "HTTP State Management Mechanism" [RFC6265] for security + considerations about cookies. + + In some deployments, including those utilizing load balancers, the + TLS connection to the resource server terminates prior to the actual + server that provides the resource. This could leave the token + unprotected between the front-end server where the TLS connection + terminates and the back-end server that provides the resource. In + such deployments, sufficient measures MUST be employed to ensure + confidentiality of the token between the front-end and back-end + servers; encryption of the token is one such possible measure. + + To deal with token capture and replay, the following recommendations + are made: First, the lifetime of the token MUST be limited; one means + of achieving this is by putting a validity time field inside the + protected part of the token. Note that using short-lived (one hour + or less) tokens reduces the impact of them being leaked. Second, + confidentiality protection of the exchanges between the client and + the authorization server and between the client and the resource + server MUST be applied. As a consequence, no eavesdropper along the + communication path is able to observe the token exchange. + Consequently, such an on-path adversary cannot replay the token. + Furthermore, when presenting the token to a resource server, the + client MUST verify the identity of that resource server, as per + Section 3.1 of "HTTP Over TLS" [RFC2818]. Note that the client MUST + validate the TLS certificate chain when making these requests to + protected resources. Presenting the token to an unauthenticated and + unauthorized resource server or failing to validate the certificate + chain will allow adversaries to steal the token and gain unauthorized + access to protected resources. + + + + + + + + + + +Jones & Hardt Standards Track [Page 12] + +RFC 6750 OAuth 2.0 Bearer Token Usage October 2012 + + +5.3. Summary of Recommendations + + Safeguard bearer tokens: Client implementations MUST ensure that + bearer tokens are not leaked to unintended parties, as they will + be able to use them to gain access to protected resources. This + is the primary security consideration when using bearer tokens and + underlies all the more specific recommendations that follow. + + Validate TLS certificate chains: The client MUST validate the TLS + certificate chain when making requests to protected resources. + Failing to do so may enable DNS hijacking attacks to steal the + token and gain unintended access. + + Always use TLS (https): Clients MUST always use TLS [RFC5246] + (https) or equivalent transport security when making requests with + bearer tokens. Failing to do so exposes the token to numerous + attacks that could give attackers unintended access. + + Don't store bearer tokens in cookies: Implementations MUST NOT store + bearer tokens within cookies that can be sent in the clear (which + is the default transmission mode for cookies). Implementations + that do store bearer tokens in cookies MUST take precautions + against cross-site request forgery. + + Issue short-lived bearer tokens: Token servers SHOULD issue + short-lived (one hour or less) bearer tokens, particularly when + issuing tokens to clients that run within a web browser or other + environments where information leakage may occur. Using + short-lived bearer tokens can reduce the impact of them being + leaked. + + Issue scoped bearer tokens: Token servers SHOULD issue bearer tokens + that contain an audience restriction, scoping their use to the + intended relying party or set of relying parties. + + Don't pass bearer tokens in page URLs: Bearer tokens SHOULD NOT be + passed in page URLs (for example, as query string parameters). + Instead, bearer tokens SHOULD be passed in HTTP message headers or + message bodies for which confidentiality measures are taken. + Browsers, web servers, and other software may not adequately + secure URLs in the browser history, web server logs, and other + data structures. If bearer tokens are passed in page URLs, + attackers might be able to steal them from the history data, logs, + or other unsecured locations. + + + + + + + +Jones & Hardt Standards Track [Page 13] + +RFC 6750 OAuth 2.0 Bearer Token Usage October 2012 + + +6. IANA Considerations + +6.1. OAuth Access Token Type Registration + + This specification registers the following access token type in the + OAuth Access Token Types registry defined in [RFC6749]. + +6.1.1. The "Bearer" OAuth Access Token Type + + Type name: + Bearer + + Additional Token Endpoint Response Parameters: + (none) + + HTTP Authentication Scheme(s): + Bearer + + Change controller: + IETF + + Specification document(s): + RFC 6750 + +6.2. OAuth Extensions Error Registration + + This specification registers the following error values in the OAuth + Extensions Error registry defined in [RFC6749]. + +6.2.1. The "invalid_request" Error Value + + Error name: + invalid_request + + Error usage location: + Resource access error response + + Related protocol extension: + Bearer access token type + + Change controller: + IETF + + Specification document(s): + RFC 6750 + + + + + + +Jones & Hardt Standards Track [Page 14] + +RFC 6750 OAuth 2.0 Bearer Token Usage October 2012 + + +6.2.2. The "invalid_token" Error Value + + Error name: + invalid_token + + Error usage location: + Resource access error response + + Related protocol extension: + Bearer access token type + + Change controller: + IETF + + Specification document(s): + RFC 6750 + +6.2.3. The "insufficient_scope" Error Value + + Error name: + insufficient_scope + + Error usage location: + Resource access error response + + Related protocol extension: + Bearer access token type + + Change controller: + IETF + + Specification document(s): + RFC 6750 + +7. References + +7.1. Normative References + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", + RFC 2246, January 1999. + + [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., + Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext + Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. + + + + +Jones & Hardt Standards Track [Page 15] + +RFC 6750 OAuth 2.0 Bearer Token Usage October 2012 + + + [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, + S., Leach, P., Luotonen, A., and L. Stewart, "HTTP + Authentication: Basic and Digest Access Authentication", + RFC 2617, June 1999. + + [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. + + [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform + Resource Identifier (URI): Generic Syntax", STD 66, + RFC 3986, January 2005. + + [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax + Specifications: ABNF", STD 68, RFC 5234, January 2008. + + [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer + Security (TLS) Protocol Version 1.2", RFC 5246, + August 2008. + + [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., + Housley, R., and W. Polk, "Internet X.509 Public Key + Infrastructure Certificate and Certificate Revocation + List (CRL) Profile", RFC 5280, May 2008. + + [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, + April 2011. + + [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", + RFC 6749, October 2012. + + [USASCII] American National Standards Institute, "Coded Character + Set -- 7-bit American Standard Code for Information + Interchange", ANSI X3.4, 1986. + + [W3C.REC-html401-19991224] + Raggett, D., Le Hors, A., and I. Jacobs, "HTML 4.01 + Specification", World Wide Web Consortium + Recommendation REC-html401-19991224, December 1999, + . + + [W3C.REC-webarch-20041215] + Jacobs, I. and N. Walsh, "Architecture of the World Wide + Web, Volume One", World Wide Web Consortium + Recommendation REC-webarch-20041215, December 2004, + . + + + + + + + +Jones & Hardt Standards Track [Page 16] + +RFC 6750 OAuth 2.0 Bearer Token Usage October 2012 + + +7.2. Informative References + + [HTTP-AUTH] Fielding, R., Ed., and J. Reschke, Ed., "Hypertext + Transfer Protocol (HTTP/1.1): Authentication", Work + in Progress, October 2012. + + [NIST800-63] Burr, W., Dodson, D., Newton, E., Perlner, R., Polk, T., + Gupta, S., and E. Nabbus, "NIST Special Publication + 800-63-1, INFORMATION SECURITY", December 2011, + . + + [OMAP] Huff, J., Schlacht, D., Nadalin, A., Simmons, J., + Rosenberg, P., Madsen, P., Ace, T., Rickelton-Abdi, C., + and B. Boyer, "Online Multimedia Authorization Protocol: + An Industry Standard for Authorized Access to Internet + Multimedia Resources", April 2012, + . + + [OpenID.Messages] + Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., + Mortimore, C., and E. Jay, "OpenID Connect Messages + 1.0", June 2012, . + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Jones & Hardt Standards Track [Page 17] + +RFC 6750 OAuth 2.0 Bearer Token Usage October 2012 + + +Appendix A. Acknowledgements + + The following people contributed to preliminary versions of this + document: Blaine Cook (BT), Brian Eaton (Google), Yaron Y. Goland + (Microsoft), Brent Goldman (Facebook), Raffi Krikorian (Twitter), + Luke Shepard (Facebook), and Allen Tom (Yahoo!). The content and + concepts within are a product of the OAuth community, the Web + Resource Authorization Profiles (WRAP) community, and the OAuth + Working Group. David Recordon created a preliminary version of this + specification based upon an early draft of the specification that + evolved into OAuth 2.0 [RFC6749]. Michael B. Jones in turn created + the first version (00) of this specification using portions of + David's preliminary document and edited all subsequent versions. + + The OAuth Working Group has dozens of very active contributors who + proposed ideas and wording for this document, including Michael + Adams, Amanda Anganes, Andrew Arnott, Derek Atkins, Dirk Balfanz, + John Bradley, Brian Campbell, Francisco Corella, Leah Culver, Bill de + hOra, Breno de Medeiros, Brian Ellin, Stephen Farrell, Igor Faynberg, + George Fletcher, Tim Freeman, Evan Gilbert, Yaron Y. Goland, Eran + Hammer, Thomas Hardjono, Dick Hardt, Justin Hart, Phil Hunt, John + Kemp, Chasen Le Hara, Barry Leiba, Amos Jeffries, Michael B. Jones, + Torsten Lodderstedt, Paul Madsen, Eve Maler, James Manger, Laurence + Miao, William J. Mills, Chuck Mortimore, Anthony Nadalin, Axel + Nennker, Mark Nottingham, David Recordon, Julian Reschke, Rob + Richards, Justin Richer, Peter Saint-Andre, Nat Sakimura, Rob Sayre, + Marius Scurtescu, Naitik Shah, Justin Smith, Christian Stuebner, + Jeremy Suriel, Doug Tangren, Paul Tarjan, Hannes Tschofenig, Franklin + Tse, Sean Turner, Paul Walker, Shane Weeden, Skylar Woodward, and + Zachary Zeltsan. + +Authors' Addresses + + Michael B. Jones + Microsoft + + EMail: mbj@microsoft.com + URI: http://self-issued.info/ + + + Dick Hardt + Independent + + EMail: dick.hardt@gmail.com + URI: http://dickhardt.org/ + + + + + + +Jones & Hardt Standards Track [Page 18] + diff --git a/docs/rfc7235.txt b/docs/rfc7235.txt new file mode 100644 index 0000000..551fb53 --- /dev/null +++ b/docs/rfc7235.txt @@ -0,0 +1,1067 @@ + + + + + + +Internet Engineering Task Force (IETF) R. Fielding, Ed. +Request for Comments: 7235 Adobe +Obsoletes: 2616 J. Reschke, Ed. +Updates: 2617 greenbytes +Category: Standards Track June 2014 +ISSN: 2070-1721 + + + Hypertext Transfer Protocol (HTTP/1.1): Authentication + +Abstract + + The Hypertext Transfer Protocol (HTTP) is a stateless application- + level protocol for distributed, collaborative, hypermedia information + systems. This document defines the HTTP Authentication framework. + +Status of This Memo + + This is an Internet Standards Track document. + + This document is a product of the Internet Engineering Task Force + (IETF). It represents the consensus of the IETF community. It has + received public review and has been approved for publication by the + Internet Engineering Steering Group (IESG). Further information on + Internet Standards is available in Section 2 of RFC 5741. + + Information about the current status of this document, any errata, + and how to provide feedback on it may be obtained at + http://www.rfc-editor.org/info/rfc7235. + +Copyright Notice + + Copyright (c) 2014 IETF Trust and the persons identified as the + document authors. All rights reserved. + + This document is subject to BCP 78 and the IETF Trust's Legal + Provisions Relating to IETF Documents + (http://trustee.ietf.org/license-info) 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. Code Components extracted from this document must + include Simplified BSD License text as described in Section 4.e of + the Trust Legal Provisions and are provided without warranty as + described in the Simplified BSD License. + + This document may contain material from IETF Documents or IETF + Contributions published or made publicly available before November + 10, 2008. The person(s) controlling the copyright in some of this + + + +Fielding & Reschke Standards Track [Page 1] + +RFC 7235 HTTP/1.1 Authentication June 2014 + + + material may not have granted the IETF Trust the right to allow + modifications of such material outside the IETF Standards Process. + Without obtaining an adequate license from the person(s) controlling + the copyright in such materials, this document may not be modified + outside the IETF Standards Process, and derivative works of it may + not be created outside the IETF Standards Process, except to format + it for publication as an RFC or to translate it into languages other + than English. + +Table of Contents + + 1. Introduction ....................................................3 + 1.1. Conformance and Error Handling .............................3 + 1.2. Syntax Notation ............................................3 + 2. Access Authentication Framework .................................3 + 2.1. Challenge and Response .....................................3 + 2.2. Protection Space (Realm) ...................................5 + 3. Status Code Definitions .........................................6 + 3.1. 401 Unauthorized ...........................................6 + 3.2. 407 Proxy Authentication Required ..........................6 + 4. Header Field Definitions ........................................7 + 4.1. WWW-Authenticate ...........................................7 + 4.2. Authorization ..............................................8 + 4.3. Proxy-Authenticate .........................................8 + 4.4. Proxy-Authorization ........................................9 + 5. IANA Considerations .............................................9 + 5.1. Authentication Scheme Registry .............................9 + 5.1.1. Procedure ...........................................9 + 5.1.2. Considerations for New Authentication Schemes ......10 + 5.2. Status Code Registration ..................................11 + 5.3. Header Field Registration .................................11 + 6. Security Considerations ........................................12 + 6.1. Confidentiality of Credentials ............................12 + 6.2. Authentication Credentials and Idle Clients ...............12 + 6.3. Protection Spaces .........................................13 + 7. Acknowledgments ................................................14 + 8. References .....................................................14 + 8.1. Normative References ......................................14 + 8.2. Informative References ....................................14 + Appendix A. Changes from RFCs 2616 and 2617 .......................16 + Appendix B. Imported ABNF .........................................16 + Appendix C. Collected ABNF ........................................17 + Index .............................................................18 + + + + + + + + +Fielding & Reschke Standards Track [Page 2] + +RFC 7235 HTTP/1.1 Authentication June 2014 + + +1. Introduction + + HTTP provides a general framework for access control and + authentication, via an extensible set of challenge-response + authentication schemes, which can be used by a server to challenge a + client request and by a client to provide authentication information. + This document defines HTTP/1.1 authentication in terms of the + architecture defined in "Hypertext Transfer Protocol (HTTP/1.1): + Message Syntax and Routing" [RFC7230], including the general + framework previously described in "HTTP Authentication: Basic and + Digest Access Authentication" [RFC2617] and the related fields and + status codes previously defined in "Hypertext Transfer Protocol -- + HTTP/1.1" [RFC2616]. + + The IANA Authentication Scheme Registry (Section 5.1) lists + registered authentication schemes and their corresponding + specifications, including the "basic" and "digest" authentication + schemes previously defined by RFC 2617. + +1.1. Conformance and Error Handling + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in [RFC2119]. + + Conformance criteria and considerations regarding error handling are + defined in Section 2.5 of [RFC7230]. + +1.2. Syntax Notation + + This specification uses the Augmented Backus-Naur Form (ABNF) + notation of [RFC5234] with a list extension, defined in Section 7 of + [RFC7230], that allows for compact definition of comma-separated + lists using a '#' operator (similar to how the '*' operator indicates + repetition). Appendix B describes rules imported from other + documents. Appendix C shows the collected grammar with all list + operators expanded to standard ABNF notation. + +2. Access Authentication Framework + +2.1. Challenge and Response + + HTTP provides a simple challenge-response authentication framework + that can be used by a server to challenge a client request and by a + client to provide authentication information. It uses a case- + insensitive token as a means to identify the authentication scheme, + followed by additional information necessary for achieving + + + + +Fielding & Reschke Standards Track [Page 3] + +RFC 7235 HTTP/1.1 Authentication June 2014 + + + authentication via that scheme. The latter can be either a comma- + separated list of parameters or a single sequence of characters + capable of holding base64-encoded information. + + Authentication parameters are name=value pairs, where the name token + is matched case-insensitively, and each parameter name MUST only + occur once per challenge. + + auth-scheme = token + + auth-param = token BWS "=" BWS ( token / quoted-string ) + + token68 = 1*( ALPHA / DIGIT / + "-" / "." / "_" / "~" / "+" / "/" ) *"=" + + The token68 syntax allows the 66 unreserved URI characters + ([RFC3986]), plus a few others, so that it can hold a base64, + base64url (URL and filename safe alphabet), base32, or base16 (hex) + encoding, with or without padding, but excluding whitespace + ([RFC4648]). + + A 401 (Unauthorized) response message is used by an origin server to + challenge the authorization of a user agent, including a + WWW-Authenticate header field containing at least one challenge + applicable to the requested resource. + + A 407 (Proxy Authentication Required) response message is used by a + proxy to challenge the authorization of a client, including a + Proxy-Authenticate header field containing at least one challenge + applicable to the proxy for the requested resource. + + challenge = auth-scheme [ 1*SP ( token68 / #auth-param ) ] + + Note: Many clients fail to parse a challenge that contains an + unknown scheme. A workaround for this problem is to list well- + supported schemes (such as "basic") first. + + A user agent that wishes to authenticate itself with an origin server + -- usually, but not necessarily, after receiving a 401 (Unauthorized) + -- can do so by including an Authorization header field with the + request. + + A client that wishes to authenticate itself with a proxy -- usually, + but not necessarily, after receiving a 407 (Proxy Authentication + Required) -- can do so by including a Proxy-Authorization header + field with the request. + + + + + +Fielding & Reschke Standards Track [Page 4] + +RFC 7235 HTTP/1.1 Authentication June 2014 + + + Both the Authorization field value and the Proxy-Authorization field + value contain the client's credentials for the realm of the resource + being requested, based upon a challenge received in a response + (possibly at some point in the past). When creating their values, + the user agent ought to do so by selecting the challenge with what it + considers to be the most secure auth-scheme that it understands, + obtaining credentials from the user as appropriate. Transmission of + credentials within header field values implies significant security + considerations regarding the confidentiality of the underlying + connection, as described in Section 6.1. + + credentials = auth-scheme [ 1*SP ( token68 / #auth-param ) ] + + Upon receipt of a request for a protected resource that omits + credentials, contains invalid credentials (e.g., a bad password) or + partial credentials (e.g., when the authentication scheme requires + more than one round trip), an origin server SHOULD send a 401 + (Unauthorized) response that contains a WWW-Authenticate header field + with at least one (possibly new) challenge applicable to the + requested resource. + + Likewise, upon receipt of a request that omits proxy credentials or + contains invalid or partial proxy credentials, a proxy that requires + authentication SHOULD generate a 407 (Proxy Authentication Required) + response that contains a Proxy-Authenticate header field with at + least one (possibly new) challenge applicable to the proxy. + + A server that receives valid credentials that are not adequate to + gain access ought to respond with the 403 (Forbidden) status code + (Section 6.5.3 of [RFC7231]). + + HTTP does not restrict applications to this simple challenge-response + framework for access authentication. Additional mechanisms can be + used, such as authentication at the transport level or via message + encapsulation, and with additional header fields specifying + authentication information. However, such additional mechanisms are + not defined by this specification. + +2.2. Protection Space (Realm) + + The "realm" authentication parameter is reserved for use by + authentication schemes that wish to indicate a scope of protection. + + A protection space is defined by the canonical root URI (the scheme + and authority components of the effective request URI; see Section + 5.5 of [RFC7230]) of the server being accessed, in combination with + the realm value if present. These realms allow the protected + resources on a server to be partitioned into a set of protection + + + +Fielding & Reschke Standards Track [Page 5] + +RFC 7235 HTTP/1.1 Authentication June 2014 + + + spaces, each with its own authentication scheme and/or authorization + database. The realm value is a string, generally assigned by the + origin server, that can have additional semantics specific to the + authentication scheme. Note that a response can have multiple + challenges with the same auth-scheme but with different realms. + + The protection space determines the domain over which credentials can + be automatically applied. If a prior request has been authorized, + the user agent MAY reuse the same credentials for all other requests + within that protection space for a period of time determined by the + authentication scheme, parameters, and/or user preferences (such as a + configurable inactivity timeout). Unless specifically allowed by the + authentication scheme, a single protection space cannot extend + outside the scope of its server. + + For historical reasons, a sender MUST only generate the quoted-string + syntax. Recipients might have to support both token and + quoted-string syntax for maximum interoperability with existing + clients that have been accepting both notations for a long time. + +3. Status Code Definitions + +3.1. 401 Unauthorized + + The 401 (Unauthorized) status code indicates that the request has not + been applied because it lacks valid authentication credentials for + the target resource. The server generating a 401 response MUST send + a WWW-Authenticate header field (Section 4.1) containing at least one + challenge applicable to the target resource. + + If the request included authentication credentials, then the 401 + response indicates that authorization has been refused for those + credentials. The user agent MAY repeat the request with a new or + replaced Authorization header field (Section 4.2). If the 401 + response contains the same challenge as the prior response, and the + user agent has already attempted authentication at least once, then + the user agent SHOULD present the enclosed representation to the + user, since it usually contains relevant diagnostic information. + +3.2. 407 Proxy Authentication Required + + The 407 (Proxy Authentication Required) status code is similar to 401 + (Unauthorized), but it indicates that the client needs to + authenticate itself in order to use a proxy. The proxy MUST send a + Proxy-Authenticate header field (Section 4.3) containing a challenge + applicable to that proxy for the target resource. The client MAY + repeat the request with a new or replaced Proxy-Authorization header + field (Section 4.4). + + + +Fielding & Reschke Standards Track [Page 6] + +RFC 7235 HTTP/1.1 Authentication June 2014 + + +4. Header Field Definitions + + This section defines the syntax and semantics of header fields + related to the HTTP authentication framework. + +4.1. WWW-Authenticate + + The "WWW-Authenticate" header field indicates the authentication + scheme(s) and parameters applicable to the target resource. + + WWW-Authenticate = 1#challenge + + A server generating a 401 (Unauthorized) response MUST send a + WWW-Authenticate header field containing at least one challenge. A + server MAY generate a WWW-Authenticate header field in other response + messages to indicate that supplying credentials (or different + credentials) might affect the response. + + A proxy forwarding a response MUST NOT modify any WWW-Authenticate + fields in that response. + + User agents are advised to take special care in parsing the field + value, as it might contain more than one challenge, and each + challenge can contain a comma-separated list of authentication + parameters. Furthermore, the header field itself can occur multiple + times. + + For instance: + + WWW-Authenticate: Newauth realm="apps", type=1, + title="Login to \"apps\"", Basic realm="simple" + + This header field contains two challenges; one for the "Newauth" + scheme with a realm value of "apps", and two additional parameters + "type" and "title", and another one for the "Basic" scheme with a + realm value of "simple". + + Note: The challenge grammar production uses the list syntax as + well. Therefore, a sequence of comma, whitespace, and comma can + be considered either as applying to the preceding challenge, or to + be an empty entry in the list of challenges. In practice, this + ambiguity does not affect the semantics of the header field value + and thus is harmless. + + + + + + + + +Fielding & Reschke Standards Track [Page 7] + +RFC 7235 HTTP/1.1 Authentication June 2014 + + +4.2. Authorization + + The "Authorization" header field allows a user agent to authenticate + itself with an origin server -- usually, but not necessarily, after + receiving a 401 (Unauthorized) response. Its value consists of + credentials containing the authentication information of the user + agent for the realm of the resource being requested. + + Authorization = credentials + + If a request is authenticated and a realm specified, the same + credentials are presumed to be valid for all other requests within + this realm (assuming that the authentication scheme itself does not + require otherwise, such as credentials that vary according to a + challenge value or using synchronized clocks). + + A proxy forwarding a request MUST NOT modify any Authorization fields + in that request. See Section 3.2 of [RFC7234] for details of and + requirements pertaining to handling of the Authorization field by + HTTP caches. + +4.3. Proxy-Authenticate + + The "Proxy-Authenticate" header field consists of at least one + challenge that indicates the authentication scheme(s) and parameters + applicable to the proxy for this effective request URI (Section 5.5 + of [RFC7230]). A proxy MUST send at least one Proxy-Authenticate + header field in each 407 (Proxy Authentication Required) response + that it generates. + + Proxy-Authenticate = 1#challenge + + Unlike WWW-Authenticate, the Proxy-Authenticate header field applies + only to the next outbound client on the response chain. This is + because only the client that chose a given proxy is likely to have + the credentials necessary for authentication. However, when multiple + proxies are used within the same administrative domain, such as + office and regional caching proxies within a large corporate network, + it is common for credentials to be generated by the user agent and + passed through the hierarchy until consumed. Hence, in such a + configuration, it will appear as if Proxy-Authenticate is being + forwarded because each proxy will send the same challenge set. + + Note that the parsing considerations for WWW-Authenticate apply to + this header field as well; see Section 4.1 for details. + + + + + + +Fielding & Reschke Standards Track [Page 8] + +RFC 7235 HTTP/1.1 Authentication June 2014 + + +4.4. Proxy-Authorization + + The "Proxy-Authorization" header field allows the client to identify + itself (or its user) to a proxy that requires authentication. Its + value consists of credentials containing the authentication + information of the client for the proxy and/or realm of the resource + being requested. + + Proxy-Authorization = credentials + + Unlike Authorization, the Proxy-Authorization header field applies + only to the next inbound proxy that demanded authentication using the + Proxy-Authenticate field. When multiple proxies are used in a chain, + the Proxy-Authorization header field is consumed by the first inbound + proxy that was expecting to receive credentials. A proxy MAY relay + the credentials from the client request to the next proxy if that is + the mechanism by which the proxies cooperatively authenticate a given + request. + +5. IANA Considerations + +5.1. Authentication Scheme Registry + + The "Hypertext Transfer Protocol (HTTP) Authentication Scheme + Registry" defines the namespace for the authentication schemes in + challenges and credentials. It has been created and is now + maintained at . + +5.1.1. Procedure + + Registrations MUST include the following fields: + + o Authentication Scheme Name + + o Pointer to specification text + + o Notes (optional) + + Values to be added to this namespace require IETF Review (see + [RFC5226], Section 4.1). + + + + + + + + + + + +Fielding & Reschke Standards Track [Page 9] + +RFC 7235 HTTP/1.1 Authentication June 2014 + + +5.1.2. Considerations for New Authentication Schemes + + There are certain aspects of the HTTP Authentication Framework that + put constraints on how new authentication schemes can work: + + o HTTP authentication is presumed to be stateless: all of the + information necessary to authenticate a request MUST be provided + in the request, rather than be dependent on the server remembering + prior requests. Authentication based on, or bound to, the + underlying connection is outside the scope of this specification + and inherently flawed unless steps are taken to ensure that the + connection cannot be used by any party other than the + authenticated user (see Section 2.3 of [RFC7230]). + + o The authentication parameter "realm" is reserved for defining + protection spaces as described in Section 2.2. New schemes MUST + NOT use it in a way incompatible with that definition. + + o The "token68" notation was introduced for compatibility with + existing authentication schemes and can only be used once per + challenge or credential. Thus, new schemes ought to use the + auth-param syntax instead, because otherwise future extensions + will be impossible. + + o The parsing of challenges and credentials is defined by this + specification and cannot be modified by new authentication + schemes. When the auth-param syntax is used, all parameters ought + to support both token and quoted-string syntax, and syntactical + constraints ought to be defined on the field value after parsing + (i.e., quoted-string processing). This is necessary so that + recipients can use a generic parser that applies to all + authentication schemes. + + Note: The fact that the value syntax for the "realm" parameter is + restricted to quoted-string was a bad design choice not to be + repeated for new parameters. + + o Definitions of new schemes ought to define the treatment of + unknown extension parameters. In general, a "must-ignore" rule is + preferable to a "must-understand" rule, because otherwise it will + be hard to introduce new parameters in the presence of legacy + recipients. Furthermore, it's good to describe the policy for + defining new parameters (such as "update the specification" or + "use this registry"). + + o Authentication schemes need to document whether they are usable in + origin-server authentication (i.e., using WWW-Authenticate), + and/or proxy authentication (i.e., using Proxy-Authenticate). + + + +Fielding & Reschke Standards Track [Page 10] + +RFC 7235 HTTP/1.1 Authentication June 2014 + + + o The credentials carried in an Authorization header field are + specific to the user agent and, therefore, have the same effect on + HTTP caches as the "private" Cache-Control response directive + (Section 5.2.2.6 of [RFC7234]), within the scope of the request in + which they appear. + + Therefore, new authentication schemes that choose not to carry + credentials in the Authorization header field (e.g., using a newly + defined header field) will need to explicitly disallow caching, by + mandating the use of either Cache-Control request directives + (e.g., "no-store", Section 5.2.1.5 of [RFC7234]) or response + directives (e.g., "private"). + +5.2. Status Code Registration + + The "Hypertext Transfer Protocol (HTTP) Status Code Registry" located + at has been + updated with the registrations below: + + +-------+-------------------------------+-------------+ + | Value | Description | Reference | + +-------+-------------------------------+-------------+ + | 401 | Unauthorized | Section 3.1 | + | 407 | Proxy Authentication Required | Section 3.2 | + +-------+-------------------------------+-------------+ + +5.3. Header Field Registration + + HTTP header fields are registered within the "Message Headers" + registry maintained at + . + + This document defines the following HTTP header fields, so the + "Permanent Message Header Field Names" registry has been updated + accordingly (see [BCP90]). + + +---------------------+----------+----------+-------------+ + | Header Field Name | Protocol | Status | Reference | + +---------------------+----------+----------+-------------+ + | Authorization | http | standard | Section 4.2 | + | Proxy-Authenticate | http | standard | Section 4.3 | + | Proxy-Authorization | http | standard | Section 4.4 | + | WWW-Authenticate | http | standard | Section 4.1 | + +---------------------+----------+----------+-------------+ + + The change controller is: "IETF (iesg@ietf.org) - Internet + Engineering Task Force". + + + + +Fielding & Reschke Standards Track [Page 11] + +RFC 7235 HTTP/1.1 Authentication June 2014 + + +6. Security Considerations + + This section is meant to inform developers, information providers, + and users of known security concerns specific to HTTP authentication. + More general security considerations are addressed in HTTP messaging + [RFC7230] and semantics [RFC7231]. + + Everything about the topic of HTTP authentication is a security + consideration, so the list of considerations below is not exhaustive. + Furthermore, it is limited to security considerations regarding the + authentication framework, in general, rather than discussing all of + the potential considerations for specific authentication schemes + (which ought to be documented in the specifications that define those + schemes). Various organizations maintain topical information and + links to current research on Web application security (e.g., + [OWASP]), including common pitfalls for implementing and using the + authentication schemes found in practice. + +6.1. Confidentiality of Credentials + + The HTTP authentication framework does not define a single mechanism + for maintaining the confidentiality of credentials; instead, each + authentication scheme defines how the credentials are encoded prior + to transmission. While this provides flexibility for the development + of future authentication schemes, it is inadequate for the protection + of existing schemes that provide no confidentiality on their own, or + that do not sufficiently protect against replay attacks. + Furthermore, if the server expects credentials that are specific to + each individual user, the exchange of those credentials will have the + effect of identifying that user even if the content within + credentials remains confidential. + + HTTP depends on the security properties of the underlying transport- + or session-level connection to provide confidential transmission of + header fields. In other words, if a server limits access to + authenticated users using this framework, the server needs to ensure + that the connection is properly secured in accordance with the nature + of the authentication scheme used. For example, services that depend + on individual user authentication often require a connection to be + secured with TLS ("Transport Layer Security", [RFC5246]) prior to + exchanging any credentials. + +6.2. Authentication Credentials and Idle Clients + + Existing HTTP clients and user agents typically retain authentication + information indefinitely. HTTP does not provide a mechanism for the + origin server to direct clients to discard these cached credentials, + since the protocol has no awareness of how credentials are obtained + + + +Fielding & Reschke Standards Track [Page 12] + +RFC 7235 HTTP/1.1 Authentication June 2014 + + + or managed by the user agent. The mechanisms for expiring or + revoking credentials can be specified as part of an authentication + scheme definition. + + Circumstances under which credential caching can interfere with the + application's security model include but are not limited to: + + o Clients that have been idle for an extended period, following + which the server might wish to cause the client to re-prompt the + user for credentials. + + o Applications that include a session termination indication (such + as a "logout" or "commit" button on a page) after which the server + side of the application "knows" that there is no further reason + for the client to retain the credentials. + + User agents that cache credentials are encouraged to provide a + readily accessible mechanism for discarding cached credentials under + user control. + +6.3. Protection Spaces + + Authentication schemes that solely rely on the "realm" mechanism for + establishing a protection space will expose credentials to all + resources on an origin server. Clients that have successfully made + authenticated requests with a resource can use the same + authentication credentials for other resources on the same origin + server. This makes it possible for a different resource to harvest + authentication credentials for other resources. + + This is of particular concern when an origin server hosts resources + for multiple parties under the same canonical root URI (Section 2.2). + Possible mitigation strategies include restricting direct access to + authentication credentials (i.e., not making the content of the + Authorization request header field available), and separating + protection spaces by using a different host name (or port number) for + each party. + + + + + + + + + + + + + + +Fielding & Reschke Standards Track [Page 13] + +RFC 7235 HTTP/1.1 Authentication June 2014 + + +7. Acknowledgments + + This specification takes over the definition of the HTTP + Authentication Framework, previously defined in RFC 2617. We thank + John Franks, Phillip M. Hallam-Baker, Jeffery L. Hostetler, Scott D. + Lawrence, Paul J. Leach, Ari Luotonen, and Lawrence C. Stewart for + their work on that specification. See Section 6 of [RFC2617] for + further acknowledgements. + + See Section 10 of [RFC7230] for the Acknowledgments related to this + document revision. + +8. References + +8.1. Normative References + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax + Specifications: ABNF", STD 68, RFC 5234, January 2008. + + [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer + Protocol (HTTP/1.1): Message Syntax and Routing", + RFC 7230, June 2014. + + [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer + Protocol (HTTP/1.1): Semantics and Content", RFC 7231, + June 2014. + + [RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, + Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching", + RFC 7234, June 2014. + +8.2. Informative References + + [BCP90] Klyne, G., Nottingham, M., and J. Mogul, "Registration + Procedures for Message Header Fields", BCP 90, RFC 3864, + September 2004. + + [OWASP] van der Stock, A., Ed., "A Guide to Building Secure Web + Applications and Web Services", The Open Web Application + Security Project (OWASP) 2.0.1, July 2005, + . + + [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., + Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext + Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. + + + +Fielding & Reschke Standards Track [Page 14] + +RFC 7235 HTTP/1.1 Authentication June 2014 + + + [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., + Leach, P., Luotonen, A., and L. Stewart, "HTTP + Authentication: Basic and Digest Access Authentication", + RFC 2617, June 1999. + + [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform + Resource Identifier (URI): Generic Syntax", STD 66, + RFC 3986, January 2005. + + [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data + Encodings", RFC 4648, October 2006. + + [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an + IANA Considerations Section in RFCs", BCP 26, RFC 5226, + May 2008. + + [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security + (TLS) Protocol Version 1.2", RFC 5246, August 2008. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Fielding & Reschke Standards Track [Page 15] + +RFC 7235 HTTP/1.1 Authentication June 2014 + + +Appendix A. Changes from RFCs 2616 and 2617 + + The framework for HTTP Authentication is now defined by this + document, rather than RFC 2617. + + The "realm" parameter is no longer always required on challenges; + consequently, the ABNF allows challenges without any auth parameters. + (Section 2) + + The "token68" alternative to auth-param lists has been added for + consistency with legacy authentication schemes such as "Basic". + (Section 2) + + This specification introduces the Authentication Scheme Registry, + along with considerations for new authentication schemes. + (Section 5.1) + +Appendix B. Imported ABNF + + The following core rules are included by reference, as defined in + Appendix B.1 of [RFC5234]: ALPHA (letters), CR (carriage return), + CRLF (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double + quote), HEXDIG (hexadecimal 0-9/A-F/a-f), LF (line feed), OCTET (any + 8-bit sequence of data), SP (space), and VCHAR (any visible US-ASCII + character). + + The rules below are defined in [RFC7230]: + + BWS = + OWS = + quoted-string = + token = + + + + + + + + + + + + + + + + + + + +Fielding & Reschke Standards Track [Page 16] + +RFC 7235 HTTP/1.1 Authentication June 2014 + + +Appendix C. Collected ABNF + + In the collected ABNF below, list rules are expanded as per Section + 1.2 of [RFC7230]. + + Authorization = credentials + + BWS = + + OWS = + + Proxy-Authenticate = *( "," OWS ) challenge *( OWS "," [ OWS + challenge ] ) + Proxy-Authorization = credentials + + WWW-Authenticate = *( "," OWS ) challenge *( OWS "," [ OWS challenge + ] ) + + auth-param = token BWS "=" BWS ( token / quoted-string ) + auth-scheme = token + + challenge = auth-scheme [ 1*SP ( token68 / [ ( "," / auth-param ) *( + OWS "," [ OWS auth-param ] ) ] ) ] + credentials = auth-scheme [ 1*SP ( token68 / [ ( "," / auth-param ) + *( OWS "," [ OWS auth-param ] ) ] ) ] + + quoted-string = + + token = + token68 = 1*( ALPHA / DIGIT / "-" / "." / "_" / "~" / "+" / "/" ) + *"=" + + + + + + + + + + + + + + + + + + + + +Fielding & Reschke Standards Track [Page 17] + +RFC 7235 HTTP/1.1 Authentication June 2014 + + +Index + + 4 + 401 Unauthorized (status code) 6 + 407 Proxy Authentication Required (status code) 6 + + A + Authorization header field 8 + + C + Canonical Root URI 5 + + G + Grammar + auth-param 4 + auth-scheme 4 + Authorization 8 + challenge 4 + credentials 5 + Proxy-Authenticate 8 + Proxy-Authorization 9 + token68 4 + WWW-Authenticate 7 + + P + Protection Space 5 + Proxy-Authenticate header field 8 + Proxy-Authorization header field 9 + + R + Realm 5 + + W + WWW-Authenticate header field 7 + + + + + + + + + + + + + + + + + +Fielding & Reschke Standards Track [Page 18] + +RFC 7235 HTTP/1.1 Authentication June 2014 + + +Authors' Addresses + + Roy T. Fielding (editor) + Adobe Systems Incorporated + 345 Park Ave + San Jose, CA 95110 + USA + + EMail: fielding@gbiv.com + URI: http://roy.gbiv.com/ + + + Julian F. Reschke (editor) + greenbytes GmbH + Hafenweg 16 + Muenster, NW 48155 + Germany + + EMail: julian.reschke@greenbytes.de + URI: http://greenbytes.de/tech/webdav/ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Fielding & Reschke Standards Track [Page 19] + -- cgit v1.2.3