A Set of Simple Authentication and Security Layer (SASL) Mechanisms for OAuth
Extracted elements (25)
Default HTTP request values (POST, '/', empty body and query string) are defined as extension points so that no changes are needed if a future SASL revision supports more specific resource authorization (e.g., IMAP access to a specific folder).
SASL mechanisms defined here do not provide a data security layer (no integrity or confidentiality for post-authentication messages). TLS or a similar solution must be used separately if per-message protection is needed.
The error sequence requires an extra client dummy message because some protocols and SASL implementations do not support both sending a SASL message and finalizing a SASL negotiation simultaneously; RFC 4422 Section 3.6 prohibits additional information in an unsuccessful authentication outcome, so the error is sent as a normal challenge.
The SASL OAuth mechanism names (OAUTHBEARER, OAUTH10A) are case insensitive; implementations MUST accept any casing such as 'bearer', 'BEARER', or 'BeArEr'.
When SASL OAuth is used over IMAP, all client response and server challenge payloads MUST be base64 encoded as required by IMAP (RFC 3501); the dummy error-completion response 'AQ==' is the base64 encoding of the ASCII value 0x01.
A space-separated list of scopes in the server error response's 'scope' field is NOT RECOMMENDED because several implementations do not properly support it; a single scope is preferred.
For OAuth token types that use keyed message digests (such as OAuth 1.0a), the client MUST send host and port key/value pairs, and the server MUST fail authorization requests requiring keyed message digests that are not accompanied by host and port values.
For OAUTH10A, the use of TLS is RECOMMENDED. The mechanism only supports client authentication; server-side authentication must be provided by the application layer beneath SASL.
If the resource server provides a scope in its error response, the client MUST always request scoped tokens from the token endpoint; if no scope is returned, the client SHOULD presume an unscoped token is required.
The returned openid-configuration discovery document SHOULD contain the 'registration_endpoint' element to enable Dynamic Client Registration (RFC 7591), and the 'offline_access' scope is RECOMMENDED to allow clients to explicitly request refresh tokens.
The server MUST validate kvpairs in the client response (such as host and port) against values known by other means (e.g., application protocol data or preconfiguration); mismatches must cause failure.
TLS MUST be used for OAUTHBEARER to protect the bearer token; without TLS at the application layer, the OAUTHBEARER mechanism is completely insecure.
Unknown key/value pairs in the client response MUST be ignored by the server, allowing forward compatibility with future extensions.
For OAuth 1.0a keyed message digest computation in SASL, default HTTP values are: method=POST, scheme=http (with non-80 ports included), path='/', query string=''. These defaults allow construction of the OAuth 1.0a signature base string without HTTP context.
Four keys are reserved for future OAuth authorization scheme use: 'mthd' (HTTP method, default POST), 'path' (HTTP path, default '/'), 'post' (HTTP post data, default empty string), and 'qs' (HTTP query string, default empty string).
On failed authentication the server returns a JSON-format error result containing: 'status' (REQUIRED, an OAuth Extensions error code), 'scope' (OPTIONAL, a valid OAuth scope for the service), and 'openid-configuration' (OPTIONAL, an HTTPS URL to an OpenID Provider Configuration document).
The client response defines three keys: 'auth' (REQUIRED, carries the OAuth Authorization header payload), 'host' (the hostname connected to), and 'port' (decimal destination port string without leading zeros).
Two SASL mechanisms are defined: OAUTHBEARER for OAuth 2.0 bearer tokens (per RFC 6750, requiring TLS) and OAUTH10A for OAuth 1.0a MAC tokens using HMAC-SHA1 keyed message digests (per RFC 5849 Section 3.4.2).
The SASL Mechanisms registry is updated with two new entries: OAUTHBEARER (OAuth 2.0 bearer tokens, intended usage COMMON) and OAUTH10A (OAuth 1.0a HMAC-SHA1 MAC tokens, intended usage COMMON), both owned by the IESG.
An access token is not equivalent to the user's long-term password. Resource servers should ensure that actions taken in an authenticated channel (e.g., changing passwords via XMPP) are appropriate to the strength of the presented credential.
Connection lifetime may outlast access token lifetime when SASL authenticates a long-lived connection; resource servers may unilaterally disconnect clients. The client MAY request a new access token per connection but SHOULD cache and reuse valid credentials.
OAUTHBEARER is completely insecure without TLS; the bearer token is transmitted in the clear otherwise. TLS MUST be provided by the application when this mechanism is chosen.
Reducing access token lifetime provides security benefits. A previously obtained token may be revoked at any time; OAuth 2.0 refresh tokens enable obtaining new access tokens without human interaction.
On authentication failure, the server sends a JSON error message; the client MUST then send either a dummy response consisting of a single %x01 byte or a SASL abort message (e.g., IMAP 'BAD' response or '*') to allow the server to complete the exchange.
The initial client response is a GS2 header followed by zero or more key/value pairs separated by %x01 (kvsep). ABNF: client-resp = (gs2-header kvsep *kvpair kvsep) / kvsep, where kvpair = key "=" value kvsep.