Terminology

Client, Server, and Resource Owner

OAuth defines three roles: client, server, and resource owner (nicknamed the OAuth Love Triangle by Leah Culver). These three roles are present in any OAuth transaction; in some cases the client is also the resource owner. The original version of the specification used a different set of terms for these roles: consumer (client), service provider (server), and user (resource owner).

In the traditional client-server authentication model, the client uses its credentials to access its resources hosted on the server. As far as the server is concerned, the shared secret used by the client belongs to the client. The server doesn’t really care where it came from or if the client is acting on behalf of some other entity. As long as the shared secret matches the server’s expectation, the request is processed.

There are many times when the client is acting on behalf of another entity. That entity can be another machine or person. When such a third actor is involved, typically a user interacting with the client, the client is acting on the user’s behalf. In these cases, the client is not accessing its own resource but those of the user – the resource owner.

Instead of using the client’s credentials, the client is using the resource owner’s credentials to make requests – pretending to be the resource owner. User credentials typically include a username or screen-name and a password, but resource owners are not limited to users, they can be any entity controlling the server resources.

The model gets a bit more detailed when the client is a web-based application. In that case, the client is split between a front-end component, usually running within a web browser on the resource owner’s desktop, and a back-end component, running on the client’s server.

The resource owner is interacting with one part of the client application while the server is receiving requests from another part. However, no matter what internal architecture the client uses, it is still acting as a single entity and on behalf of the resource owner.

Protected Resources

A protected resource is a resource stored on (or provided by) the server which requires authentication in order to access it. Protected resources are owned or controlled by the resource owner. Anyone requesting access to a protected resource must be authorized to do so by the resource owner (enforced by the server).

A protected resource can be data (photos, documents, contacts), services (posting blog item, transferring funds), or any resource requiring access restrictions. While OAuth can be used with other transport protocols, it is only defined for HTTP(S) resources.

2-Legged, 3-Legged, n-Legged

The number of legs used to describe an OAuth request typically refers to the number of parties involved. In the simple OAuth flow: a client, a server, and a resource owner, the flow is described as 3-legged. When the client is also the resource owner (that is, acting on behalf of itself), it is described as 2-legged. Additional legs usually mean different things to different people, but in general mean that access is shared by the client with other clients (re-delegation).

Credentials and Tokens

OAuth uses three kinds of credentials: client credentials, temporary credentials, and token credentials. The original version of the specification used a different set of terms for these credentials: consumer key and secret (client credentials), request token and secret (temporary credentials), and access token and secret (token credentials). The specification still uses a parameter name ‘oauth_consumer_key‘ for backwards compatibility.

The client credentials are used to authenticate the client. This allows the server to collect information about the clients using its services, offer some clients special treatment such as throttling-free access, or provide the resource owner with more information about the clients seeking to access its protected resources. In some cases, the client credentials cannot be trusted and can only be used for informational purposes only, such as in desktop application clients.

Token credentials are used in place of the resource owner’s username and password. Instead of having the resource owner share its credentials with the client, it authorizes the server to issue a special class of credentials to the client which represent the access grant given to the client by the resource owner. The client uses the token credentials to access the protected resource without having to know the resource owner’s password.

Token credentials include a token identifier, usually (but not always) a random string of letters and numbers that is unique, hard to guess, and paired with a secret to protect the token from being used by unauthorized parties. Token credentials are usually limited in scope and duration, and can be revoked at any time by the resource owner without affecting other token credentials issued to other clients.

The OAuth authorization process also uses a set of temporary credentials which are used to identify the authorization request. In order to accommodate different kind of clients (web-based, desktop, mobile, etc.), the temporary credentials offer additional flexibility and security.

In OAuth 1.0, the secret half of each set of credentials is defined as a symmetric shared secret. This means that both the client and server must have access to the same secret string. However, OAuth supports an RSA-based authentication method which uses an asymmetric client secret. The different credentials are explained in more detailed later on.