OAuth 2.0 Concepts

Internal

• OAuth 2.0

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.

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

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

Resource Owner

The Resource Owner 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. This process is called authorization grant.

The Resource Owner is generally assumed to have access to a web browser.

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.

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.

Client

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. Some, if not most Clients are pieces of software running in the 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.

Authorization Server (AS)

The Authorization Server (AS) is the OAuth component trusted by the Protected Resource to issue OAuth Access Tokens to Clients. 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.

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.

OAuth Access Token

An OAuth access token is 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 the token format. JSON Web Token (JWT) does.

There are several token types:

Bearer Token

Bearer tokens are defined by RFC 6750. A bearer token 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.

JSON Web Token (JWT)

JWT

OAuth Grant Types

There are four OAuth2 grant types:

1. Authorization Code Grant Type
2. second
3. third
4. fourth

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.

Issuing the Token

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

Step 1. 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.

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

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

Step 3. 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.

/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.

Using the Token

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

GET /resource 
Authorization: Bearer: ….

Step 9. Protected Resource returns resource to Client.

OAuth Scope

The OAuth scope is an indication of what kind of access a Client is requesting.

JSON Object Signing and Encryption (JOSE)

JOSE

To Process

Identity. Identity Management.

Identity Federation and Single Sign-On are related concepts.

Single Sign-On (SSO) systems allow a single user authentication process across multiple IT systems and organizations. SSO is a subset of federated identity management, as it relates only to authentication and technical interoperability.

User's presence in the system - means that the user identity is associated with the thread that is processing the user's request, and in a way, it is the user that "drives" the thread. The identity is associated with the thread in the form of a security context.

There are software agents that perform actions on behalf of the user, and this is where OAuth is relevant - a user can delegate in a standard and secure way the authority of performing certain actions. Even the software agent (the OAuth 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.

Authentication. The whole point of an authentication protocol is to tell whether the user is present in the system.

Identity Provider (IdP) and Relying Party (RP).

Authentication protocols, single sign-on, SAML.

Authorization.