OAuth 2.0 Concepts

Internal

• OAuth 2.0
• Security Concepts

Overview

According to RFC 6749 - The OAuth 2.0 Authorization Framework, OAuth 2.0 is an authorization framework that enables a third-party application - the Client - to obtain limited access to an HTTP service - the Protected Resource - 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.

Many materials refer to OAuth 2.0 as an authorization protocol. Other materials refer to it as an delegation protocol, because offers means of letting someone who controls a resource to allow software applications to access that resource on their behalf without impersonating them. Delegation is fundamental to the power of OAuth. Even if the RFC calls OAuth an authorization protocol, it is actually a delegation protocol. The distinction between a delegation and authorization protocol is important.

The protocol works by allowing the application to requests authorization from the owner of the resource and receive a token it can use to get access to resource, without needing to impersonate the owner. The token represents a delegated right of access, which can be as granular as needed: some actions may be permitted, and some not. OAuth is all about how to get a token and how to use a token. The tokens are issued by an Authorization Server, which is a component that acts as an intermediary between resource owner and client.

OAuth was designed from the outset as a protocol for use with APIs: the primary use case is software client access to APIs.

A notable aspect of OAuth 2.0 is that when it was designed, the working group made a distinct decision to threat the core protocol as a framework instead of a single protocol. The framework allows extensions.

Trust On First Use (TOFU)

The OAuth delegation process involves the Resource Owner, so important security decisions can be driven by end user choice, instead of being configured in a centralized manner somewhere else. OAuth supports Trust On First Use, which is a model in which first time security decisions are being made at runtime, with the user's involvement: the user is prompted and makes choices. The system then remembers the decision for later use. The decisions are usually presented in terms of functionality, not security.

OAuth Primitives

An OAuth-based system has four main primitives: Resource Owners, Clients, Authorization Servers and Protected Resources:

Resource Owner

The Resource Owner is the entity that has the authority to delegate access to the Client, and it is usually the end user. The Resource Owner has access to the Protected Resource API and can delegate that access, or some part of their authority, to a third-party Client, but it does not do that directly, it does it via a Token issued by an Authorization Server. The Resource Owner authorizes specific Clients, at the Authorization Server. The extent of trust (permissions) a specific Client is supposed to have is specified during the conversation between Resource Owner and Authorization Server, in a process called authorization grant.

The Resource Owner is generally assumed to have access to a web browser and it uses it to interact with the Authorization_Server and possibly the Client - this last part is totally dependent on the nature of the Client.

Resource Owner Authentication Against Authorization Server

Resource Owner authenticates against the Authorization Server, as an essential step to determine who the Resource Owner is and what rights they are allowed to delegate to the Client. The Resource Owner authentication exchange passes directly between the user (user’s browser) and the Authorization Server and it is never seen by the Client. OAuth has nothing to say on authentication methodology. This isolates the Client from changes in Resource Owner’s authentication method against Authorization Server.

Client

Software agents may perform actions on behalf of the user, and this is where OAuth is relevant: it provides the mechanism by which a user can delegate in a standard and secure way the authority of performing certain actions. In the OAuth context, the software agent is known as Client. Even if the Client operates under a different identity, it can still perform action on behalf of a user that may not be even logged in anymore. An example of such identity is an OpenShift service account.

Formally, the Client is a piece of software that consumes the protected API and wants to gain access to a Protected Resource in behalf of a Resource Owner. The OAuth protocol is employed to help the Client get the authorization to do so. Some, if not most Clients are pieces of software that that have at a component running in a browser (user agent) the Resource Owner has access to. From the point of view of the Resource Owner, the Client is potentially untrusted, so the owner may not want to share with it the credentials protecting the resource. OAuth facilitates the generation of limited credentials issued separately for each Client and Resource Owner combination. A specific Client is authorized by the Resource Owner at the Authorization Server. The process of defining the authorization boundaries for a specific Client is called authorization grant. This mechanism insures that a breached Client can not expose the Resource Owners’ credentials, since the Client never sees them in the first place.

The Client may optionally authenticate against the Authorization Server.

By design, the Clients are intended to be simple, while the burden of complexity is shifted towards the Authorization Server - see Authorization Server below for an explanation of this decision. The main function of a Client, from an OAuth protocol point of view, is to obtain a Token, handle it as an opaque piece of information and forward it to the Protected Resource, as a proof of the Client's authority to obtain information or do things. The Client does not have to understand the Token, and does not have to inspect its content.

Authorization Server (AS)

The Authorization Server (AS) is the central component of an OAuth system. It is trusted by the Protected Resource to issue OAuth Access Tokens to Clients. The Authorization Server's functions are to authenticate the Resource Owner and the Client, provide mechanisms for allowing Resource Owners to authorize Clients and issue OAuth Access Tokens to Clients. The Authorization Server interacts with the Resource Owner and Client via HTTP. A single Authorization Server can protect multiple resource servers. This is an explicit architectural decision that shifts the complexity away from Clients and towards servers (Authorization and resource servers). This makes the servers more likely targets for attack but it is significantly easier to make a single Authorization Server highly secure that it is to make a large number of Clients written by independent developers just as secure.

The Authorization Server provides a token endpoint used by Clients to request Access Tokens and Refresh Tokens. The Client calls this endpoint presenting a form-encoded set of parameters. The Authorization Server response with a JSON object representing the token.

Authorization Decision Storage

Some Authorization Servers allow the storage of the authorization decision the Resource Owner takes the first time is faced with the situation. This is to support Trust On First Use policy. The stored decisions are used during the authorization grant step.

Protected Resource

A Protected Resource is the component the Resource Owner has access to. Usually it is an API of some kind, and it is exposed by a protected resource server, which is a HTTP server. The authorization carried by the OAuth Token is opaque to most of the system. Only the Protected Resource needs to know authorization details, and it can find those details either from the token, or from the presentation context – using a service of some type to obtain the information.

How a Protected Resource uses the OAuth Access Token

The Protected Resource needs to validate the Token presented to it, and determine how to serve the associated request. Thus, the Protected Resource has the final say as to whether or not to honor the token.

TODO: How various degree of authorization reflect in the token, given the fact that the token is the only piece of information provided by the Client to the Protected Resource. OAuth 2 in Action Chapter 11: A protected resource has a number of options for doing the token lookup.

OAuth Components

The OAuth primitives interact with each other via specific mechanisms, bits that make the primitives actors of the larger protocol: access tokens, scopes and authorization grants.

OAuth Access Token

An OAuth access token is an artifact, a special-purpose security credential issued by the Authorization Server to the Client, embodying authorization delegation. Conceptually, the token represents a delegated right of access. The Client will use the OAuth access token to access the Protected Resource. RFC 6749 specifies how to get a token. Also see Authorization Code Grant Type - Issuing the Token below. The user generally does not have to see or deal with the access token directly – the Client requests and gets it from the Authorization Server, if authorized by the Resource Owner. Moreover, the token is opaque to the Client, this is specifically stated in the specification. The client can store the access token in a secure place for as long as it wants – the token can be presented to the Protected Resource even long after the Resource Owner left the session.

OAuth does not define authorization processing mechanisms, it only provides a means to convey the fact that an authorization delegation has taken place, The context of the authorization is left to the Protected Resource.

OAuth does not define the content or the format of the token, however JSON Web Token (JWT) does. Regardless of the fact that the protocol does not specify the format, the Tokens must logically contain data representing the Client's requested access, the Resource Owner identity, and the rights conferred during the authorization process. The tokens are opaque to Client, which does. not need to be able to understand token's contents; it should only be capable of obtaining the token from the Authorization Server and present it to the Protected Resource. Since the Authorization Server issues the token, it is naturally capable of understanding it, and so should be the Protected Resource.

There are several token types:

Bearer Token

Bearer tokens are defined by RFC 6750.

A bearer token is a piece of information that can be presented to some service that by virtue of you having it (you being the "bearer") grants you access to something. That means that anyone carrying the token has the right to use it, and it will be granted access to the Protected Resource without demonstrating possession of a cryptographic key. Because of their generality, bearer tokens need to be protected from disclosure in storage and in transport.

This is how a bearer token returned within the body of the response looks like:

{
  "token_type":"Bearer",
  "access_token":"ba80.Al...777",
  "scope":"email profile https://www.googleapis.com/auth/userinfo.profile https://www.googleapis.com/auth/userinfo.email openid",
  "login_hint":"Bh3...",
  "expires_in":3600,
  "id_token":"azJhb...777",
  "session_state":{"extraQueryParams":{"authuser":"0"}}
}

Refresh Token

Refresh Tokens: When to Use Them and How They Interact with JWTs

A refresh token is similar in concept to the access token, being issued to the Client by the Authorization_Server. However, the token is never sent to the Protected Resource. The Client uses the refresh token to request new access tokens without involving the Resource Owner. Section 2.4.3 in OAuth 2 in Action.

JSON Web Token (JWT)

JWT is an encoding standard for tokens that contain a JSON data payload. The payload can be signed and encrypted.

JWT

OAuth Scope

The OAuth scope is a representation of a set of rights at the Protected Resource, an indication of what kind of access a Client is requesting. The OAuth protocol represents scopes by strings, and they can be combined into a set by using a space-separated list. Because of that a scope value cannot contain spaces. OAuth does not provide more details than that, the format and the structure is unspecified. Scopes are defined by the Protected Resource. Clients can request certain scopes, and the Authorization Server can allow the Resource Owner to grant or deny particular scopes to a given Client. Scopes are usually additive in nature.

Front-Channel and Back-Channel Communication

OAuth is an HTTP-based protocol, and HTTP requests and responses are exchanged between various primitives. Those exchanges can be split in two broad categories: exchanges that take place via Resource Owners's user agent - these make the front-channel communication - and exchanges that occur outside the purview of the Resource Owners: the back-channel communication.

Front-channel communication is a method employed by Client and Authorization Server to communicate indirectly, of using HTTP redirect requests and by Resource Owner to communicate with the Authorization Server and the Client. All these exchanges take place via an intermediary user agent (browser). This technique isolates the sessions on either side of the browser, which allows it to work across different security domains.

Back-channel communication consists in invocation made by the Client into the Authorization Server token endpoint and into the Protected Resource.

For a graphical representation of these channels, see Authorization Code Grant Type below.

OAuth Authorization Grant

An authorization grant is the means by which a Client is given access to a Protected Resource using the OAuth protocol. If successful, the authorization grant results in the Client getting a Token. The term defines both the specific mechanism by which the user delegates authority as well as the act of the delegation itself. While the authorization code is part of an authorization grant, the authorization code is not in itself the authorization grant - the entire OAuth process is. In other words, the authorization grant is a method of getting a token. Also see Authorization Grant Step.

Sometimes, an authorization grant is referred to as an OAuth flow.

There are several types of authorization grant in OAuth:

1. Authorization Code Grant Type - this is the most common.
2. Implicit Grant Type
3. Client Credentials Grant Type
4. Resource Owner Credentials Grant Type
5. Assertion Grant Types

Authorization Code Grant Type

Authorization code grant type is the most canonical and complete grant type. The authorization code grant uses a temporary credential, the authorization code, which represents the Resource Owner’s delegation to the client. At no time the Resource Owner’s credentials are exposed to the Client.

Also see:

Google OAuth 2 Call Sequences

Issuing the Token

Step 1. The Resource Owner indicates to the Client that they would like the Client to act on their behalf.

Step 2. The Client requests that the Resource Owner authorizes the Client at the Authorization Server. This is usually a HTTP redirect to the Authorization Server's endpoint. The Client also communicates as part of this redirect, as query parameters, some information identifying itself.

/authorize?response_type=…&scope=…&client_id=…&redirect-uri-

Step 3. Resource Owner loads the Authorization Server’s endpoint.

Step 4. Resource Owner authenticates against the Authorization Server. See Resource Owner Authentication against Authorization Server.

Step 4 - Authorization Grant. Resource Owner grants authority to the Client via the Authorization Server. Usually, the Resource Owner is given choices as to how much authority to grant: this is where finely grained authorization permissions can be specified. The Client is usually able to ask for a subset of functionality – or scopes which the Resource Owner may be able to further diminish. The Resource Owner ends up granting some degree of authorization – some portion of their authority - to the Client. This process is named authorization grant. If the user expressed their choices during a previous session, and the choices are stored, the user may not need to select the scope again, but they are still required to authenticate. See Authorization Decision Storage. Regardless of how the user's options are retrieved, the Authorization Server generates an authorization code.

Step 5. Authorization Server redirects the user agent to Client. The redirect request contains the authorization code and the client's redirect-uri as base. When the browser follows this redirect, it will be served by the client application.

/oauth_callback?code=
/callback?code=…

Step 6. The Client requests an Access Token form the Authorization Server, by sending the authorization code and its own credentials. This is usually done with a POST request.

POST /token
Authorization: Basic:
body:
grant_type=authorization_code ,,,

Step 7. The Authorization Server returns an Access Token as result of the request:

HTTP 200 OK 
{
“access_token”: …
“token_type”: “Bearer”
}

Authorization Code

The authorization code is a short lived, one-time-use credential, representing the result of Resource Owner’s authorization decision. Authorization codes are issued by Authorization Server and passed to Clients, which use them to get OAuth Access Tokens. The authorization code represents a user's authorization decision and is part of an authorization grant, but it is not in itself an authorization grant. The authorization code transits the Resource Owner's browser, so it is accessible to it, but it can't be used directly by the Client to access the Protected Resource, it will have to be exchanged for an Access Token, which is provided to the Client on a back-channel.

response_type

Using the Token

Step 8. The Client sends the access token to the Protected Resource.

GET /resource 
Authorization: Bearer: ….

More details on how the Protected Resource uses the Token are available in the How a Protected Resource uses the OAuth Access Token section.

Step 9. Protected Resource returns resource to Client.

Implicit Grant Type

TODO OAuth 2 In Action Section 6.1.1

Client Credentials Grant Type

TODO OAuth 2 In Action Section 6.1.2

Resource Owner Credentials Grant Type

TODO OAuth 2 In Action Section 6.1.3

Assertion Grant Types

TODO OAuth 2 In Action Section 6.1.4

OAuth Threat Model

Process https://tools.ietf.org/html/rfc6819.

JSON Object Signing and Encryption (JOSE)

JOSE

OpenID Connect

OpenID Connect