RFC 7617
The 'Basic' HTTP Authentication Scheme
The 'Basic' HTTP Authentication Scheme 🎀
okay bestie, this one is by J. Reschke over at greenbytes 🦋 and it dropped in September 2015 as RFC 7617. It's a Standards Track doc, so it's the real deal: IETF consensus, public review, and IESG approval ✨. It obsoletes RFC 2617 and is the updated take on the 'Basic' scheme, so if you've seen the old version, this is the glow-up 💅. The ISSN is 2070-1721 if you want to look it up.
Abstract 💜
this doc defines the "Basic" HTTP authentication scheme 🔐. it sends credentials as user-id/password pairs, encoded with Base64. it's giving simple, but it comes with some very real caveats (more on that later 👀).
Status of This Memo 📜
this is an Internet Standards Track document 💅.
it's a product of the Internet Engineering Task Force (IETF) and represents the consensus of the IETF community. it got public review and was approved for publication by the Internet Engineering Steering Group (IESG). if you want more on Internet Standards, check Section 2 of RFC 5741.
for the current status, any errata, and how to send feedback, go to http://www.rfc-editor.org/info/rfc7617 🌸.
Copyright Notice ⚖️
Copyright (c) 2015 IETF Trust and the persons identified as the document authors. All rights reserved.
this doc is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) as they stand on the publication date. please actually read these, because they spell out your rights and restrictions for this doc. any Code Components pulled out of this doc must include Simplified BSD License text, as described in Section 4.e of the Trust Legal Provisions, and they come with no warranty, as described in that license.
this doc may contain material from IETF Documents or IETF Contributions that were published or made publicly available before November 10, 2008. the people who control the copyright in some of that material may not have granted the IETF Trust the right to allow modifications outside the IETF Standards Process. unless you get an adequate license from them, this doc may not be modified outside the IETF Standards Process, and derivative works of it may not be created outside that process. the exception is formatting it for publication as an RFC or translating it into languages other than English 🌈.
Table of Contents 🗂️
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Terminology and Notation . . . . . . . . . . . . . . . . 3
2. The 'Basic' Authentication Scheme . . . . . . . . . . . . . . 3
2.1. The 'charset' auth-param . . . . . . . . . . . . . . . . 5
2.2. Reusing Credentials . . . . . . . . . . . . . . . . . . . 7
3. Internationalization Considerations . . . . . . . . . . . . . 8
4. Security Considerations . . . . . . . . . . . . . . . . . . . 8
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9
6. References . . . . . . . . . . . . . . . . . . . . . . . . . 10
6.1. Normative References . . . . . . . . . . . . . . . . . . 10
6.2. Informative References . . . . . . . . . . . . . . . . . 11
Appendix A. Changes from RFC 2617 . . . . . . . . . . . . . . . 13
Appendix B. Deployment Considerations for the 'charset'
Parameter . . . . . . . . . . . . . . . . . . . . . 13
B.1. User Agents . . . . . . . . . . . . . . . . . . . . . . . 13
B.2. Servers . . . . . . . . . . . . . . . . . . . . . . . . . 13
B.3. Why not simply switch the default encoding to UTF-8? . . 14
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 14
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 151. Introduction ✨
okay so this doc defines the "Basic" HTTP authentication scheme, which sends credentials as user-id/password pairs encoded with Base64. (the HTTP authentication schemes themselves are defined in [RFC7235].)
real talk: this scheme is not considered secure on its own. it only makes sense alongside some external secure system like TLS ([RFC5246]), because the user-id and password go over the network as cleartext 😭. so yeah, don't skip the encryption layer, bestie 🔒.
the "Basic" scheme was previously defined in Section 2 of [RFC2617]. this doc updates that definition, and it also tackles internationalization problems by introducing the 'charset' authentication parameter (Section 2.1) 🌍.
other docs updating RFC 2617 are "Hypertext Transfer Protocol (HTTP/1.1): Authentication" ([RFC7235], which defines the authentication framework), "HTTP Digest Access Authentication" ([RFC7616], which updates the "Digest" scheme), and "HTTP Authentication-Info and Proxy-Authentication-Info Response Header Fields" ([RFC7615]). put together, these four docs obsolete RFC 2617 💅.
1.1. Terminology and Notation 📖
the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this doc are to be interpreted as described in [RFC2119] 🫶.
the terms "protection space" and "realm" are defined in Section 2.2 of [RFC7235].
the terms "(character) repertoire" and "character encoding scheme" are defined in Section 2 of [RFC6365].
2. The 'Basic' Authentication Scheme 🔐
the Basic scheme is built on the idea that the client needs to authenticate itself with a user-id and a password for each protection space ("realm") 🏰. the realm value is a free-form string, and it can only be compared for equality with other realms on that server. the server will only service the request if it can validate the user-id and password for the protection space that applies to the requested resource 🙌.
the Basic scheme uses the Authentication Framework like this:
In challenges:
- the scheme name is "Basic".
- the authentication parameter 'realm' is REQUIRED ([RFC7235], Section 2.2).
- the authentication parameter 'charset' is OPTIONAL (see Section 2.1).
- no other authentication parameters are defined. unknown parameters MUST be ignored by recipients, and new parameters can only be defined by revising this specification 🚫.
also see Section 4.1 of [RFC7235], which talks about how complicated it is to parse challenges properly 🤯.
note that both scheme and parameter names are matched case-insensitively 🔤.
for credentials, the "token68" syntax defined in Section 2.1 of [RFC7235] is used. the value is computed from the user-id and password as defined below 🧁.
when a server gets a request for a URI inside the protection space that doesn't have credentials, it can reply with a challenge using the 401 (Unauthorized) status code ([RFC7235], Section 3.1) and the WWW-Authenticate header field ([RFC7235], Section 4.1). for instance:
HTTP/1.1 401 Unauthorized
Date: Mon, 04 Feb 2014 16:50:53 GMT
WWW-Authenticate: Basic realm="WallyWorld""WallyWorld" is the string the server assigned to identify the protection space 🌟.
a proxy can respond with a similar challenge using the 407 (Proxy Authentication Required) status code ([RFC7235], Section 3.2) and the Proxy-Authenticate header field ([RFC7235], Section 4.3) 🚪.
to get authorization, the client:
- gets the user-id and password from the user,
- builds the user-pass by concatenating the user-id, a single colon (":") character, and the password,
- encodes the user-pass into an octet sequence (see below for a discussion of character encoding schemes),
- and gets the basic-credentials by encoding this octet sequence using Base64 ([RFC4648], Section 4) into a sequence of US-ASCII characters ([RFC0020]) 🧠.
the original definition of this scheme didn't specify which character encoding to use when converting the user-pass into an octet sequence 🙈. in practice, most implementations picked either a locale-specific encoding like ISO-8859-1 ([ISO-8859-1]) or UTF-8 ([RFC3629]). for backwards compatibility, this spec still leaves the default encoding undefined, as long as it stays compatible with US-ASCII (mapping any US-ASCII character to a single octet that matches its US-ASCII character code) 🕰️.
the user-id and password MUST NOT contain any control characters (see "CTL" in Appendix B.1 of [RFC5234]) 🚨.
also, a user-id containing a colon character is invalid. the first colon in a user-pass string separates the user-id from the password, so any text after the first colon counts as part of the password. user-ids that contain colons can't be encoded in user-pass strings 💀.
heads up: a lot of user agents build user-pass strings without checking whether the user-ids people typed contain colons. recipients will then treat part of the username as part of the password 😬.
if the user agent wants to send the user-id "Aladdin" and the password "open sesame", it would use this header field:
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==2.1. The 'charset' auth-param 🌏
in challenges, servers can use the 'charset' authentication parameter to say which character encoding scheme they expect the user agent to use when generating "user-pass" (a sequence of octets). this info is purely advisory 💁♀️.
the only allowed value is "UTF-8", and it's matched case-insensitively (see [RFC2978], Section 2.3). it tells the client that the server expects character data to be converted to Unicode Normalization Form C ("NFC"; see Section 3 of [RFC5198]) and then encoded into octets using the UTF-8 character encoding scheme ([RFC3629]) 🧩.
for the user-id, recipients MUST support all characters defined in the "UsernameCasePreserved" profile in Section 3.3 of [RFC7613], except for the colon (":") character 👤.
for the password, recipients MUST support all characters defined in the "OpaqueString" profile in Section 4.2 of [RFC7613] 🔑.
other values are reserved for future use 🔮.
Note: the 'charset' is only defined on challenges, because Basic authentication uses a single token for credentials ('token68' syntax). so the credentials syntax isn't extensible.
Note: the name 'charset' was picked for consistency with Section 2.1.1 of [RFC2831]. a better name would have been 'accept-charset', since it isn't about the message it shows up in, but about what the server expects 🤓.
in the example below, the server asks for authentication in the "foo" realm using Basic auth, and it prefers the UTF-8 character encoding scheme:
WWW-Authenticate: Basic realm="foo", charset="UTF-8"the parameter value can be either a token or a quoted string. in this case, the server went with the quoted-string notation 🎀.
the user's name is "test", and the password is the string "123" followed by the Unicode character U+00A3 (POUND SIGN) 💷. using the UTF-8 character encoding scheme, the user-pass becomes:
't' 'e' 's' 't' ':' '1' '2' '3' pound
74 65 73 74 3A 31 32 33 C2 A3encoding this octet sequence in Base64 ([RFC4648], Section 4) gives:
dGVzdDoxMjPCow==so the Authorization header field would be:
Authorization: Basic dGVzdDoxMjPCow==or, for proxy authentication:
Proxy-Authorization: Basic dGVzdDoxMjPCow==2.2. Reusing Credentials ✨
okay so bestie, this bit is about how long a client can keep using the same login for a whole neighbourhood of URLs 🗺️💅. Take the absolute URI of an authenticated request (that's the one with [RFC3986], Section 4.3 vibes 🎀) and chop off everything after the last slash ("/") in the path component (the "hier_part", see [RFC3986], Section 3). What's left is the authentication scope 🦋. A client SHOULD assume that any resource whose URI prefix-matches that scope is also inside the protection space named by the realm value of that request. Lowkey the whole point is that you don't have to re-ask 🫶.
A client MAY preemptively send the matching Authorization header field with requests for resources in that space, even if the server never sent another challenge 🔥. Same deal for proxies: when a client talks to a proxy, it MAY reuse a user-id and password in the Proxy-Authorization header field without getting another challenge from the proxy server 🌸.
Here's an example bestie 🧚. Say you made an authenticated request to:
http://example.com/docs/index.html
Then these URIs could use the same known credentials:
http://example.com/docs/ http://example.com/docs/test.doc http://example.com/docs/?page=1
But these ones are totally outside the authentication scope 🙈:
http://example.com/other/ https://example.com/docs/
Also, a URI can live in more than one authentication scope (like "http://example.com/" and "http://example.com/docs/") 🌈. This specification does not define which of these should get higher priority, so that's a mystery for another day 💀.
3. Internationalization Considerations 🌍
Okay so, user-ids or passwords with characters outside the US-ASCII character repertoire will cause interoperability issues, unless both communication partners agree on which character encoding scheme to use 😭. Servers can use the new 'charset' parameter (Section 2.1) to show a preference for "UTF-8", which makes it more likely that clients will switch to that encoding 💜.
The 'realm' parameter carries data that counts as textual, but [RFC7235] doesn't define a reliable way to transport non-US-ASCII characters 🙃. That's a known issue, and it would need to be fixed in a revision to that specification 🛠️.
4. Security Considerations 🚨
Real talk, bestie: the Basic authentication scheme is not a secure method of user authentication 💀. It doesn't protect the entity either, which gets sent in cleartext across the physical network used as the carrier. HTTP doesn't stop people from adding enhancements (like schemes that use one-time passwords) to Basic authentication 🔐.
The most serious flaw is that it results in the cleartext transmission of the user's password over the physical network 😱. Many other authentication schemes address this problem, so go shopping 🛍️.
Because Basic authentication involves cleartext passwords, it SHOULD NOT be used (without enhancements such as HTTPS [RFC2818]) to protect sensitive or valuable information 🚫🔒.
A common use of Basic authentication is for identification purposes, like requiring a user-id and password just to identify someone, for example to gather accurate usage statistics on a server 📊. When used this way it's tempting to think there's no danger if illicit access to the protected documents isn't a major concern 🤔. That's only correct if the server issues both the user-id and password to users and, in particular, does not let the user choose their own password. The danger is that naive users frequently reuse a single password so they don't have to maintain multiple passwords 😩.
If a server lets users select their own passwords, the threat isn't just 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 😳. Plus, 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 other sites if this information isn't kept secure 🫣. This raises both security and privacy concerns ([RFC6973]). If the same user-id and password combination is used to access other accounts, such as an email or health portal account, personal information could be exposed 🥺.
Basic authentication is also vulnerable to spoofing by counterfeit servers 👀. If a user can be led to believe they're connecting to a host with information protected by Basic authentication when they're actually connecting to a hostile server or gateway, the attacker can request a password, store it for later use, and feign an error 😈. Server implementers ought to guard against this sort of counterfeiting. In particular, software components that can take over control of the message framing on an existing connection need to be used carefully or not at all (for instance: NPH ("Non-Parsed Header") scripts as described in Section 5 of [RFC3875]) 🧯.
Servers and proxies implementing Basic authentication need to store user passwords in some form in order to authenticate a request 🗄️. These passwords ought to be stored so that a leak of the password data doesn't make them trivially recoverable 🔑. This matters even more when users can set their own passwords, since users are known to choose weak passwords and to reuse them across authentication realms 🙃. A full discussion of good password hashing techniques is beyond the scope of this document, but server operators ought to make an effort to minimize risks to their users if there's a password data leak 🛡️. For example, servers ought to avoid storing user passwords in plaintext or as unsalted digests 🚩. For more discussion about modern password hashing techniques, check out the "Password Hashing Competition" (<https://password-hashing.net>) 🔗.
The use of the UTF-8 character encoding scheme and of normalization introduces additional security considerations; see Section 10 of [RFC3629] and Section 6 of [RFC5198] for more information 📚.
5. IANA Considerations 🗂️
IANA maintains the "Hypertext Transfer Protocol (HTTP) Authentication Scheme Registry" ([RFC7235]) at http://www.iana.org/assignments/http-authschemes 🎀.
The entry for the "Basic" authentication scheme has been updated to reference this specification ✅.
6. References 📖
6.1. Normative References
[RFC20] Cerf, V., "ASCII format for network interchange", STD 80,
RFC 20, DOI 10.17487/RFC0020, October 1969,
<http://www.rfc-editor.org/info/rfc20>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<http://www.rfc-editor.org/info/rfc2119>.
[RFC2978] Freed, N. and J. Postel, "IANA Charset Registration
Procedures", BCP 19, RFC 2978, DOI 10.17487/RFC2978,
October 2000, <http://www.rfc-editor.org/info/rfc2978>.
[RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November
2003, <http://www.rfc-editor.org/info/rfc3629>.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, DOI 10.17487/RFC3986, January 2005,
<http://www.rfc-editor.org/info/rfc3986>.
[RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data
Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006,
<http://www.rfc-editor.org/info/rfc4648>.
[RFC5198] Klensin, J. and M. Padlipsky, "Unicode Format for Network
Interchange", RFC 5198, DOI 10.17487/RFC5198, March 2008,
<http://www.rfc-editor.org/info/rfc5198>.
[RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", STD 68, RFC 5234,
DOI 10.17487/RFC5234, January 2008,
<http://www.rfc-editor.org/info/rfc5234>.
[RFC6365] Hoffman, P. and J. Klensin, "Terminology Used in
Internationalization in the IETF", BCP 166, RFC 6365,
DOI 10.17487/RFC6365, September 2011,
<http://www.rfc-editor.org/info/rfc6365>.
[RFC7235] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
Protocol (HTTP/1.1): Authentication", RFC 7235,
DOI 10.17487/RFC7235, June 2014,
<http://www.rfc-editor.org/info/rfc7235>.
[RFC7613] Saint-Andre, P. and A. Melnikov, "Preparation,
Enforcement, and Comparison of Internationalized Strings
Representing Usernames and Passwords", RFC 7613,
DOI 10.17487/RFC7613, August 2015,
<http://www.rfc-editor.org/info/rfc7613>.6.2. Informative References
[ISO-8859-1]
International Organization for Standardization,
"Information technology -- 8-bit single-byte coded graphic
character sets -- Part 1: Latin alphabet No. 1", ISO/IEC
8859-1:1998, 1998.
[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, DOI 10.17487/RFC2617, June 1999,
<http://www.rfc-editor.org/info/rfc2617>.
[RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818,
DOI 10.17487/RFC2818, May 2000,
<http://www.rfc-editor.org/info/rfc2818>.
[RFC2831] Leach, P. and C. Newman, "Using Digest Authentication as a
SASL Mechanism", RFC 2831, DOI 10.17487/RFC2831, May 2000,
<http://www.rfc-editor.org/info/rfc2831>.
[RFC3875] Robinson, D. and K. Coar, "The Common Gateway Interface
(CGI) Version 1.1", RFC 3875, DOI 10.17487/RFC3875,
October 2004, <http://www.rfc-editor.org/info/rfc3875>.
[RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
(TLS) Protocol Version 1.2", RFC 5246,
DOI 10.17487/RFC5246, August 2008,
<http://www.rfc-editor.org/info/rfc5246>.
[RFC6973] Cooper, A., Tschofenig, H., Aboba, B., Peterson, J.,
Morris, J., Hansen, M., and R. Smith, "Privacy
Considerations for Internet Protocols", RFC 6973,
DOI 10.17487/RFC6973, July 2013,
<http://www.rfc-editor.org/info/rfc6973>.
[RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
Protocol (HTTP/1.1): Semantics and Content", RFC 7231,
DOI 10.17487/RFC7231, June 2014,
<http://www.rfc-editor.org/info/rfc7231>.
[RFC7615] Reschke, J., "HTTP Authentication-Info and Proxy-
Authentication-Info Response Header Fields", RFC 7615,
DOI 10.17487/RFC7615, September 2015,
<http://www.rfc-editor.org/info/rfc7615>.
[RFC7616] Shekh-Yusef, R., Ed., Ahrens, D., and S. Bremer, "HTTP
Digest Access Authentication", RFC 7616,
DOI 10.17487/RFC7616, September 2015,
<http://www.rfc-editor.org/info/rfc7616>.Part 2 of 3 done, bestie 💜 more coming, so stay tuned 🧚
Appendix A. Changes from RFC 2617 ✨
okay so the scheme definition got a glow-up 💅 It's been rewritten to match newer specs like [RFC7235], so it's all consistent now 🎀
there's also a brand new authentication parameter, 'charset' 🦋 and it's purely advisory, so existing implementations don't have to change anything 🫶 unless they want the extra info that used to be unavailable 🌸
Appendix B. Deployment Considerations for the 'charset' Parameter 🍓
B.1. User Agents
user agents that don't implement 'charset' are totally fine 💖 they'll keep working like before and just ignore the new parameter 🙈
user agents that already default to UTF-8 implement 'charset' by definition, so they're already the main characters 👑
other user agents can keep their default behavior 💅 or switch to UTF-8 when they see the new parameter ✨
B.2. Servers
servers that don't support non-US-ASCII characters in credentials don't need any changes to support 'charset' 🧚
servers that need non-US-ASCII characters but can't use UTF-8 won't be affected 💀 they'll keep functioning as well or as badly as before 🫠
finally, servers that need non-US-ASCII characters and can use UTF-8 can opt in by putting the 'charset' parameter in the authentication challenge 🔥 clients that understand 'charset' will start using UTF-8, while other clients keep sending credentials in their default encoding, broken credentials, or no credentials at all 😭
until every client is upgraded to UTF-8, servers are likely to see both UTF-8 and "legacy" encodings in requests 🌈 when processing as UTF-8 fails (because it can't decode as UTF-8, or because the user-id/password doesn't match), a server might try a fallback to the previously supported legacy encoding to accommodate those legacy clients 🫶
⚠️ bestie, implicit retries need to be done carefully! for instance, some subsystems might detect repeated login failures and treat them as a potential credentials-guessing attack 🙈
B.3. Why not simply switch the default encoding to UTF-8?
ngl this is the tea ☕ there are sites in use today that default to a local character encoding scheme, such as ISO-8859-1 ([ISO-8859-1]), and they expect user agents to use that encoding 💅 authentication on these sites will stop working if the user agent switches to a different encoding, like UTF-8 💀
also, sites might even inspect the User-Agent header field ([RFC7231], Section 5.5.3) to decide which character encoding scheme to expect from the client 👀 so they might support UTF-8 for some user agents but default to something else for others 🦋 user agents in that latter group have to keep doing what they do today until the majority of these servers have been upgraded to always use UTF-8 🌸
Acknowledgements 🫶
this specification takes over the definition of the "Basic" HTTP Authentication Scheme, which was 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 spec, since a ton of text was borrowed from it 💖 see Section 6 of [RFC2617] for further acknowledgements ✨
the internationalization problem with the character encoding scheme used for user-pass was reported as a Mozilla bug back in the year 2000 🕰️ (see https://bugzilla.mozilla.org/show_bug.cgi?id=41489 and also the more recent https://bugzilla.mozilla.org/show_bug.cgi?id=656213) 🦋 and it was Andrew Clover's idea to fix it with a new auth-param 🧠👑
we also thank the members of the HTTPAUTH Working Group and the other reviewers 🌟 namely Stephen Farrell, Roy Fielding, Daniel Kahn Gillmor, Tony Hansen, Bjoern Hoehrmann, Kari Hurtta, Amos Jeffries, Benjamin Kaduk, Michael Koeller, Eric Lawrence, Barry Leiba, James Manger, Alexey Melnikov, Kathleen Moriarty, Juergen Schoenwaelder, Yaron Sheffer, Meral Shirazipour, Michael Sweet, and Martin Thomson, for their feedback on this revision 💜 iykyk the reviewer list is iconic 😭
Author's Address 🌸
Julian F. Reschke
greenbytes GmbH
Hafenweg 16
Muenster, NW 48155
Germany
Email: julian.reschke@greenbytes.de
URI: http://greenbytes.de/tech/webdav/📦 where this page comes from
- ietf: rfc7617 2015-09
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms