The OAuth 2.0 Authorization Framework
Extracted elements (31)
OAuth 2.0 was designed to replace direct credential sharing between clients and resource owners. The traditional model forced third parties to store passwords in clear-text, gave overly broad access, and prevented per-client revocation; OAuth replaces credentials with scoped, time-limited access tokens issued by an authorization server.
As a highly extensible framework with many optional components and several undefined required components (e.g., client registration, endpoint discovery, authorization server capabilities), OAuth 2.0 on its own is likely to produce non-interoperable implementations without additional profiles.
OAuth 2.0 is not backward compatible with OAuth 1.0 (RFC 5849) and shares very few implementation details with it. The two versions may coexist on the network; implementers familiar with OAuth 1.0 should treat this specification as entirely new.
If the issued access token scope differs from the requested scope, the authorization server MUST include the 'scope' response parameter. If the client omits scope, the authorization server MUST either use a pre-defined default or fail the request.
In the implicit grant flow, the authorization server MUST verify the redirection URI matches a registered URI before delivering the access token in the URI fragment. The authorization server MUST NOT issue a refresh token in the implicit grant.
In the resource owner password credentials grant, the client MUST discard the resource owner's credentials once an access token has been obtained. The authorization server MUST protect the token endpoint against brute force attacks.
The authorization code MUST expire shortly after issuance (maximum lifetime of 10 minutes RECOMMENDED) and MUST NOT be used more than once. If reuse is detected, the authorization server MUST deny the request and SHOULD revoke all tokens previously issued based on that code.
The authorization server MUST NOT rely on public client authentication for the purpose of identifying the client. A client MUST NOT use more than one authentication method in each request.
The authorization server MUST require TLS when sending requests to the authorization endpoint, MUST support HTTP GET for the authorization endpoint, and MUST ignore unrecognized request parameters. Request and response parameters MUST NOT be included more than once.
The authorization server MUST support HTTP Basic authentication for clients with a client password, and MUST require TLS when password authentication is used. Including credentials in the request-body is NOT RECOMMENDED and parameters MUST NOT be included in the request URI.
The client credentials grant type MUST only be used by confidential clients.
The client identifier (client_id) MUST NOT be used alone for client authentication; it is not a secret and is exposed to the resource owner.
The redirection endpoint URI MUST be an absolute URI and MUST NOT include a fragment component. Public clients and confidential clients using the implicit grant MUST register their redirection endpoint. If a redirect URI is missing, invalid, or mismatching, the authorization server MUST NOT automatically redirect the user-agent.
The token endpoint MUST require TLS and the client MUST use HTTP POST. Confidential clients or clients issued credentials MUST authenticate with the authorization server when making token requests.
A refresh token is an opaque string used to obtain new access tokens when the current one expires or to obtain tokens with narrower scope. Unlike access tokens, refresh tokens are sent only to the authorization server and never to resource servers; issuance is optional at the authorization server's discretion.
An access token is an opaque string representing a specific scope and duration of access, issued to the client by the authorization server. Tokens may be identifiers or self-contained signed assertions; their format is defined by companion specifications such as RFC 6750.
Four authorization grant types are defined: authorization code (for confidential clients using redirection), implicit (simplified browser-based flow returning the token directly in the URI fragment), resource owner password credentials (direct username/password exchange), and client credentials (client acting on its own behalf).
OAuth 2.0 defines four roles: resource owner (entity granting access), resource server (hosts protected resources), client (application requesting access on behalf of the resource owner), and authorization server (issues access tokens after authenticating the resource owner).
OAuth defines two client types: confidential clients (capable of maintaining credential confidentiality, e.g., server-side web apps) and public clients (incapable, e.g., browser-based or native apps). The authorization server SHOULD NOT make assumptions about client type.
IANA created the OAuth Access Token Types Registry for registering access token type names; registration requires a type name, additional endpoint parameters, HTTP authentication scheme, change controller, and specification document.
IANA created the OAuth Authorization Endpoint Response Types Registry. Initial contents include 'code' (authorization code grant) and 'token' (implicit grant). New response types require a specification and change controller.
IANA created the OAuth Extensions Error Registry for error codes used in authorization endpoint responses, token endpoint responses, and resource access error responses. Registration requires an error name, usage location, related protocol extension, change controller, and specification document.
IANA created the OAuth Parameters Registry for authorization endpoint, token endpoint, and redirection endpoint request and response parameters. Initial contents include code, token_type, expires_in, username, password, client_id, client_secret, redirect_uri, scope, state, error, error_description, error_uri, grant_type, refresh_token, and access_token.
An attacker may manipulate the redirection URI in an authorization code request to cause the authorization server to deliver the code to an attacker-controlled endpoint. Authorization servers MUST require pre-registration of complete redirect URIs and perform strict URI matching per RFC 3986 Section 6.
Clients should request the minimum scope necessary and resource owners should be informed of the scope granted. Authorization servers must ensure that access tokens cannot be used to impersonate the resource owner to a greater degree than the original authorization grant permitted.
Cross-site request forgery (CSRF) against the redirection endpoint can allow attackers to inject authorization codes or access tokens. The 'state' request parameter SHOULD be used by clients to bind the request to the user-agent session and validate it on callback; its value SHOULD be unguessable.
In the implicit grant, the access token is delivered in the URI fragment and may be exposed to the resource owner, browser history, and third-party scripts in the redirection endpoint. Clients MUST NOT include third-party scripts in the redirection response without ensuring their own credential-extraction scripts execute first.
Open redirectors at the authorization or redirection endpoint can be used by attackers to redirect users to phishing sites after authorization. Authorization servers SHOULD require full redirect URI registration and MUST NOT allow open redirect behavior via the authorization endpoint.
Access token response is a JSON object (Content-Type: application/json) with Cache-Control: no-store. Required fields: access_token, token_type. Recommended: expires_in (seconds). Optional: refresh_token, scope. The response MUST NOT be cached.
Authorization code grant request uses query parameters: response_type=code (REQUIRED), client_id (REQUIRED), redirect_uri (OPTIONAL), scope (OPTIONAL), state (RECOMMENDED). Parameters are application/x-www-form-urlencoded in the authorization endpoint URI query component.
Error responses from the authorization or token endpoint include: error (REQUIRED, ASCII code such as invalid_request, unauthorized_client, access_denied, invalid_scope, server_error), error_description (OPTIONAL, human-readable), error_uri (OPTIONAL), state (REQUIRED if present in request). Character set is restricted to %x20-21 / %x23-5B / %x5D-7E.