RFC6749 - The OAuth 2.0 Authorization Framework

Abstract

[...] 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.

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.

Some problems arise with this approach:

• Third-party apps need to store the resource owner credentials.
• Servers need to support password authentication.
• Third-party apps gain overly broad access to the resource owner's protected resources.
• Resource owners cannot revoke access to specific third-parties.
• Compromise of third-parties results in compromise of resource owner's credentials and the data protected by that credentials.

OAuth introduces an authorization layer and separates the roles of the client from that of the resource owner. Using OAuth a different set of credentials is issued for the client.

Instead of using the resource owner's credentials, the client obtains an access tokens. Access tokens are issued to third-party clients by an authorization server with the approval of the resource owner.

OAuth is designed for use with HTTP.

OAuth 2.0 is not retrocompatible with OAuth 1.0.

1.1 Roles

OAuth defines four roles:

Resource Owner / End-user

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.

1.2 Protocol flow

1. The client requests authorization from the resource owner. The authorization request can be directly to the resource owner or preferably indirectly via the authorization server as intermediary.
2. The client receives an authorization grant, which is a credential representing the resource owner's authorization. There are four types of authorization grant defined in this spec, it might exist extensions.
3. The client requests an access token by authenticating with the authorization server and presenting the authorization grant.
4. The authorization server authenticates the client and validates the authorization grant, and if valid, issues an access token.
5. The client requests the protected resource from the resource server and authenticates by presenting the access token.
6. The resource server validates the access token, and if valid, serves the request.

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 the access token.

The RFC 6749 defines four grant types: authorization code, implicit, resource owner password credentials and client credentials.

1.3.1 Authorization Code

The client redirects the resource owner to an authentication server, which acts as intermediary. The authentication server authenticates the resource owner and the resource owner can authorize the client. Once the client is authorized, the authorization server directs the resource owner back to the client with the authorization code.

Because the resource owner only authenticates with the authorization server, the resource owner's credentials are never shared with the client.

Pros:

• Authenticates the client
• Transmission of the token directly to the client

Cons:

• Two step authentication, therefore, more round trips.

1.3.2 Implicit

NOT IN THE RFC: Currently this flow is considered legacy due the lack of client authentication.

The implicit grant is a simplified version of the authorization code.

[...] (it's) optimized for clients implemented in a browser using a scripting language such as Javascript.

Instead of the authentication server issuing an authorization code, in the Implicit Grant flow, the authentication server issues directly the access token.

It's called implicit because there is no need of intermediary credentials such as authorization code.

Cons:

• The authentication server doesn't authenticates the client

  • It might be possible to identify based on the redirect uri
• The access token may be exposed to the resource owner or other apps running in the user-agent.

Pro:

• One step authentication, therefore, less round trips. Improve responsiveness and efficiency.

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.

Resource owner password credentials should only be used when there is a high degree of trust between the resource owner and the client or if you don't have the option for other grant types.

The resource owner's credentials are used only once to exchange for the 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 is acting on its own behalf (the client is also the resource owner)[...]

or

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.

Either the client is acting as resource owner, or the client's authorization scope is restricted to access protected resources which the client manages.

Pro:

• One step authentication, therefore, less round trips. Improve responsiveness and efficiency.

1.4 Access Token

Access tokens are credentials used to access protected resources.

It represents an authorization issue to the client with a specific scope and durations of access. The token is granted by the resource owner and enforced by the resource server and authorization server.

The access token provides an abstraction layer, replacing different authorization constructs, like username and password with a single token understood by the resource server. It enables to issue token with different authorizations than the authorization grant used to obtain the token.

Access tokens can have different formats, structures, and methods of utilization.

1.5 Refresh Token

Refresh token are credentials used to obtain access tokens when the current access token becomes invalid or expires. Or to require tokens with different authorization scope.

The authorization server issues the refresh token together with the access token. They are intended for us only with authorization servers and are never sent to the resource server.

A refresh token acts as an authorization granted to the client by the resource owner.

1. The client requests an access token by authenticating with the authorization server and presenting an authorization grant.
2. The authorization server authenticates the client and validates the authorization grant, and if valid, issues an access token and a refresh token.
3. The client can requests a protected resource (sending the access token) and the resource server validates the access token, and if valid, provides the protected resource the client requested.
4. (Once the access token expires) The client requests a protected resource and the resource server reject to serve because the access token expired.
5. The client requests a new access token by authenticating with the authentication server and presenting the refresh token.
6. The authentication server validates the client and its refresh token, and if valid, issues a new access token (and, optionally, a new refresh token).

1.6 TLS Version

The TLS version varies. At the time of the writing the TLS 1.2 was the most recent, but with a more restricted base of deployments. While the TLS 1.0 provided the broader interoperability.

1.7 HTTP Redirections

OAuth 2.0 makes heavy usage of HTTP redirection. HTTP redirection code are considered implementation detail.

1.8 Interoperability

OAuth 2.0 provides a rich authorization framework. The framework is hightly extensible and flexible and is expected to have a wide range of non-interoperable implementations.

This specification also lets few require components partially or fully undefined. Therefore, it was designed with the clear expectation that future work will come to fulfill this gaps.

1.9 Notational conventions

Uses keywords as decribed in RFC 2119.

2. Client Registration

Before initiating the protocol, the client registers with the authorization server.

The client registration is beyond the scope of this specification.

When registering a client, the client must:

• specify the client type
• provide its client redirection URI
• include any other information required by the authorization server

2.1 Client Types

OAuth 2.0 defines two client types based on their ability to authenticate securely with the authorization server.

• confidential: Clients capable of maintaining the confidentiality of their credentials, or capable of secure client authentication by other means. E.g. secure server.
• public: Clients incapable of maintaining the confidentiality of their credentials, and incapable of secure client authentication via any other means. E.g. native apps or web-broser based.

A client may be implemented as a distributed set of components, each with a different client type. Either the authorization server should provide support for such clients or the clients should be registered as separeta clients.

These are the clients profiles considered:

• web application: It's considered a confidential client running on a web server. The client credentials as well as any access token issued to the client are stored on the web server and are not exposed nor accessible by the resource owner. This refers to server side web apps.
• user-agent-based application: It's considered a public client in which the client code is downloaded from a web server and executes within a user-agent on the device used by the resource owner. Protocol data and credentials are easily accessible and often visible to the resource owner. This refers to static site apps.
• native application: It's considered a public client installed and executed on the device used by the resource owner. Protocol data and credentials are easily accessible and often visible to the resource owner.

2.2 Client identifier

Each client will have its own client identifier issued by the authentication server. The client identifier is not a secret. It's exposed to the resource owner and must not be used to authenticate without additional information.

2.3 Client Authentication

For confidential clients, the client authenticates with the authentication server. The means of that are provided by the authorization server.

Authentication servers will issue a set of client credentials for confidential clients (password, public and private key pairs) to use during the client authentication with the authorization server.

For public clients, it's up to the authentication server to determine whether they will require the client authentication or not. Either way, the authentication server must not rely on this authentication.

2.3.1 Client Password

Clients with a client password can use the Basic authentication as authentication method with authentication server.

The request's content type is application/x-www-form-urlencoded.

The client identifier encoded value used as username.

The client password encoded value used as password.

Accordingly to RFC2617:

To receive authorization, the client sends the userid and password, separated by a single colon (":") character, within base64 encoded string in the credentials.

Although not recommend, but for cases where basic authentication is not possible, as an alternative the authentication server can support in the request-body the parameters:

• client_id: The client identifier
• client_secret: The client secret

The endpoints used for client authentication are protected by the authentication server from brute force attacks.

2.3.2 Other Authentication Methods

The authorization server can support other authentication methods. But, when using other client authentication methods, it's required to have a mapping of the client identifier to the authentication scheme.

2.4 Unregistered Clients

It's beyond the scope of this RFC.

3. Protocol Endpoints

There are 3 endpoints to consider:

• Authorization server endpoints

  • Authorization endpoint: used by the client to obtain the authorization grant.
  • Token endpoint: used by the client to exchange the authorization grant for an access token.

• Client endpoint

  • Redirection endpoint: The authorization server redirects the resource owner to it with the authorization grant.

3.1 Authorization Endpoint

The authorization endpoint is used to interact with the resource owner and obtain an authorization grant.

3.1.1 Response Type

The authorization endpoint is used by the authorization code grant type and implicit grant type flows.

The client must inform the response_type as a HTTP parameter specifying either code for the authorization code grant type or token for an implicit grant type.

3.1.2 Redirection Endpoint

After the Resource owner authentication, the authentication servers redirects the client to the client's endpoint. The client's endpoint was previously established with the authorization server, usually during the client registration in the authorization server.

3.1.2.1 Endpoint Request Confidentiality

Redirection endpoint should use TLS (HTTPS) if the authentication server will send sensitive credentials, tokens or code.

3.1.2.2 Registration Requirements

Both public clients and any client using implicit grant type flow are required to register redirection endpoints.

3.1.2.3 Dynamic Configuration

If the client didn't configured, or misconfigured the redirection endpoint. It can still send it through the redirect_url request parameter.

3.1.2.4 Invalid Endpoint

In case the redirect fails, the resource owner is notified and the authorization server does not redirects.

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.

Therefore, the client should extract the credentials and redirect again to another endpoint without exposing the credentials. Also this initial page should not have any third party scripts.

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 endpoint uses the HTTP "Post" method.

3.2.1 Client Authentication

Confidential clients or clients with client credentials must authenticate in the authentication server.

That way even if the authorization code was issued through an insecure channel, only with the client authentication the authorization code will generate the access token.

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.

4. Obtaining Authorization

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.

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.

4.1.1 Authorization Request

Request parameters must be encoded by "application/x-www-form-urlencoded".

• response_type - required: Defines which is the authorization grant flow to be used. This RFC defines both code and token representing respectively authorization code and implicit flow.
• client_id - required: The id of the Client. Every client is issued an id when they do the registration in the authorization server.
• redirect_uri- optional: The URI where the authorization server will redirect the client after the authorization is granted.
• scope - optional: Client's scope request which might not be fully attended by the authorization server.
• state - recommended: A value sent in order to ensure the code received in the redirect is from the same state you sent in your /authorize request.

The authorization server validates the request to ensure that all required parameters are present and valid.

See section 2.3 for more information about client authentication.

4.1.2 Authorization Response

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"

• code - required: The authorization code generated by the authorization server bound to the client id and redirect uri.
• state - required if Client sent this data: Same value sent by the client.

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.

• error - required: One of the following: invalidrequest, unauthorizedclient, accessdenied, unsupportedresponsetype, invalidscope, servererror or temporarilyunavailable.
• error_description - optional: Human readable information.
• error_uri - optional: An URI with more information about the error.
• state - required if Client sent this data: Same value sent by the client.

4.1.3 Access Token Request

The token endpoint is used by the client to obtain an access token by presenting its authorization grant or refresh token.

• grant_type - required: Which type of authorization grant you are using. 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: Same value as the value sent in the authorization request.
• client_id required: The client identifier.

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

4.2 Implicit Grant

Deprecated

4.3 Resource Owner Password Credentials Grant

Deprecated

4.4 Client Credentials Grant

The client can request an access token using only its client credentials

The client credentials grant type MUST only be used by confidential clients.

4.4.2 Access Token Request

• grant_type - required: Which type of authorization grant you are using. client_credentials
• scope - optional: Client's scope request which might not be fully attended by the authorization server.

The authorization server MUST authenticate the client.

See section 2.3 for more information about client authentication.

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

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

5.1 Successful Response

• access_token - required: The access token issued by the authorization server.
• token_type - required: The type of the token issued
• expires_in - recommended: The lifetime in seconds of the access token
• refresh_token - optional: It can be used to obtain new access tokens using the same authorization grant. Must not be availabe in the client credentials grant flow.
• scope - optional, if identical to the scope requested by the client; otherwise, required. The scope of the access token.

The parameters are included in the entity-body of the HTTP response using the "application/json" media type