This may be a little trivial, but it could cause a little confusion for some so we're going to go into it briefly. The client is the thing running the code that talks to the authorization and resource servers on behalf of the user. If the code is running on a web server, the web server is the client. If it's running in a web browser, the user agent running on the user's machine is the client. If it is a native app running on a smart phone, the native app is the client. Seems obvious, but the nature of the client has important OAuth considerations attached to it.

Clients and Confidentiality

As we've discussed, there are a few different types of authorization grants defined in the spec. Because of the extensibility provisions, there are actually a lot more that could exist. The credentials those grants represent have the potential to have very powerful authorization rights attached to them that go well beyond the
protected resources we're considering. For example, a username and password might unlock access to a lot of things. Accordingly, we have to think about how credentials are handled and secured by clients.

OAuth defines two types of clients, those that can be trusted to keep a secret and those that cannot. If the client is running on a server in a data center someplace, OAuth considers that client capable of keeping a secret and refers to it as a Confidential client. If, however, the client is running on a piece of hardware that the user has direct access to, like a web browser or a native client, OAuth doesn't trust those clients to be able to keep secrets and calls those Public clients. After all, not all users are trustworthy. If the user has the code and can sniff the traffic between the client and the servers, they can probably crack it open and reverse engineer the credentials. 

Registration

The spec says that the following client types must register in advance:

• Public clients
• Confidential clients using implicit grants

It is possible for there to be such a thing as an unregistered client but "the use of such clients is beyond the scope of this specification and requires additional security analysis and review of its interoperability impact". This sounds like a case of a thing being both possible and a bad idea at the same time. We're going to proceed under the assumption that all clients must be registered with the authorization server first from here on out. The client needs to provide the authorization server with a couple of things:

• The client type (confidential or public) so the authorization server knows the limitations of the client's secret keeping abilities.
• Client redirection URLs - At the end of the authorization process, the authorization server is going to send the client something (an authorization code or a token of some sort). This URL is where that something is going to be sent. This is only required for the authorization code and implicit grants.
• The spec allows for the authorization server to demand additional information too as a part of the registration process.

In exchange, the authorization server will issue the client a client ID. This ID is unique to the registration, so a client capable of registering with more than one authorization server will need to juggle more than one client ID. This ID is not considered a secret by the spec so it should never be used as if it were. If the client is a confidential client, it's going to be issued a set of secrets during the registration process to authenticate with.

Client Profiles

The spec is flexible enough that a lot of possible types of client could be imagined and still be valid, but it explicitly addresses three. Quoting from the spec:

• Web Application - A web application is a confidential client running on a web server. Resource owners access the client via an HTML user interface rendered in a user-agent on the device used by the resource owner. The client credentials as well as any access token issued to the client are stored on the web server and are not exposed to or accessible by the resource owner.
• User-agent-based Application - A user-agent-based application is a public client in which the client code is downloaded from a web server and executes within a user-agent (e.g., web browser) on the device used by the resource owner. Protocol data and credentials are easily accessible (and often visible) to the resource owner. Since such applications reside within the user-agent, they can make seamless use of the user-agent capabilities when requesting authorization.
• Native Application - A native application is a public client installed and executed on the device used by the resource owner. Protocol data and credentials are accessible to the resource owner. It is assumed that any client authentication credentials included in the application can be extracted. On the other hand, dynamically issued credentials such as access tokens or refresh tokens can receive an acceptable level of protection. At a minimum, these credentials are protected from hostile servers with which the application may interact. On some platforms, these credentials might be protected from other applications residing on the same device.

Protocol Endpoints

How do the various parties communicate with each other? This has been alluded to a few times now, but the spec calls it out specifically. There are three different endpoints defined which, depending on the nature of the client, are not all necessarily used.

• Authorization - Exposed by the authorization server to issue authorization grants to clients
• Redirection - Exposed by the client to receive authorization grants
• Token - Exposed by the authorization server to exchange authorization grants and refresh tokens for access tokens.

There are a lot of MUSTs and SHOULDs in the spec in this section to define the nature of the endpoints, their registration and their security. The key thing to understand is that this whole endpoint dance is part of how OAuth attempts to keep everything secure. We'll see how this works when we unpack each of the flows, but suffice it to say, this dance is necessary.

The Authorization Endpoint

This endpoint is exposed by the authorization server and is where the client comes to obtain an authorization grant. The resource owner will authenticate here using whatever mechanism the authorization server requires. At the end, it's going to respond with some sort of token, depending on the grant type.

The Redirection Endpoint

When the authorization server responds via the authorization endpoint, it's going to issue a redirect (normally a 302 but that's actually an implementation detail) to the client's redirection endpoint. This is where the client is going to receive whatever token or code the authorization sent in response to the call on the authorization endpoint. This needs to be defined in advance during client registration.

The Token Endpoint

The token endpoint is where the client is going to take whatever grant it finally received and try to exchange it for an access token. Alternately, if the client has a refresh token, it uses this same endpoint to try to exchange it for a fresh access token.

We've finally finished setting the table in terms of concepts and terminology so in the next couple of posts we actually get to look at the actual flows. Whew...

In the last post, we made it through defining the four roles represented in the four party diagram. Now we're going to dig into the arrows that represent information flowing between the parties.

Authorization Request

This is conceptually straightforward. The client needs to ask the resource owner for permission to access a resource. This needs to be explicit in terms of the type of access the client wants to get. For example, the client could present the resource owner with a request for read-only access to a repository of photos. How exactly does the client do this? The spec is opinionated but not demanding here. The client can communicate directly with the resource owner and still be compliant with the spec, but the preference is to use the authorization server as an intermediary. This makes sense if you think about it. The authorization server is going need to trust the authorization grant in order to issue the access token. It sure is easier to sort that out if the authorization server is actually the party issuing the authorization grant on behalf of the resource owner.

Those Authorization Grant arrows look like they're hiding something…

The rest of the arrows are simple in concept; a request and a token that gives access to a resource. Once I have a valid authorization grant, I'm getting access to that protected resource, so you're probably thinking something pretty special has to happen in that arrow. That turns out to be correct. It's very important to understand what an authorization grant really is. Authorization grants are really credentials. The authorization server is going to inspect the credential the client sends, determines if it trusts it and, if it does, issue an access token to the client in response. If you are thinking "Hmmm, that sounds like authentication to me. I thought OAuth didn't do authentication…" you are correct on both counts. Hold that thought for a moment.

This is why it's very helpful to have the authorization server issue the authorization grant on behalf of the resource owner in the first place. The authorization server needs to authenticate the credential to make sure it's valid and then issue the right sort of token to give the client the subset of rights the resource owner approved. If the authorization server issued the credential in the first place, it's easy for the authorization server to validate it.

I think this is where the confusion of OAuth and authentication comes from because we see it happening right here. How can we say that OAuth only addresses authorization? The important thing to remember here is, the OAuth spec doesn't say much beyond generalities about the nature of the credentials and their format and it says nothing about how authentication should take place, how to keep it secure, etc. It just recognizes that some form of authentication must take place here in order to then proceed with the authorization part. There are a number of valid, secure ways to define and then authenticate the authorization grant and OAuth really doesn't have an opinion on which you use.

There are a few grant types defined in the spec. These are:

• Authorization Code - This is probably the most common OAuth scenario. The client realizes that it needs an authorization grant and redirects the user to the authorization server. The authorization server authenticates the user and redirects back to the client. When this redirect happens, the authorization server sends a special, short lived authorization code to the client.

• Implicit - This is a simplified version of the Authorization Code grant that is optimized for browser-based (think JavaScript/SPA) clients. The client redirects to the authorization server and the resource owner authenticates as before. This time, instead of sending an authorization code in the redirect it simply sends the access token. This simplification introduces some significant security implications here, so care needs to be taken. This actually has less to do with OAuth and more to do with the nature of JavaScript-based clients and their inability to keep secrets. We'll discuss this more in a future post.
• Resource Owner Password Credentials - This is exactly what it sounds like, the username and password of the resource owner. It's arguably here for backward compatibility. The Authorization Code approach would be better if you were starting from scratch.
• Client Credentials - This is an interesting one. In this case, the client itself, independent of any user, has its own credentials that it can pass to the authorization server and act on its own behalf. Assuming the authorization server recognizes those credentials, the client would be given an access token to the protected resource.
• TBD - The spec also allows for extension. If these four grant types don't fit the bill, it doesn't mean OAuth 2.0 doesn't help you. You can plug in a different credential type and still conform to the OAuth spec. For example, a common scenario is using a SAML 2.0 token as an authorization grant.

Access Tokens

This is the thing that the client is going to present to the resource server. The actual format of the token is irrelevant to the spec. As long as the resource server understands and trusts it, it works. The client, on the other hand, never needs to understand it. It just needs to send it along when it requests the resource.

Usually this is going to be a string of some sort. It probably will not contain any information from the original access grant itself. For example, the grant might have been the username and password of the resource owner but the requested permission was read only. The token isn't going to have the resource owner's password anymore, it's just going to have some way of specifying which resources the token applies to, what rights the client has over those resources and for how long. For obvious reasons, these should be cryptographically secured somehow. However all of this is beyond the scope of the spec itself.

Refresh Tokens

Once the client has an access token, the client has access to the protected resource. If it never expires, the client can never lose access to the resource. So, obviously, we want these to expire and we probably want them to expire frequently to make sure we are checking back with the resource owner to ensure that the client should still have access. However we don't want to pester the resource owner every couple of hours with an authentication request. So the authorization server can issue something else called a refresh token with the access token.

The refresh token is essentially a record of the approved grant. When the access token expires, the client can send the refresh token to the authorization server to request a fresh access token. The authorization server can take the refresh token, verify that the resource owner hasn't revoked the client's authorization grant, and issue the new access token. If the grant has been revoked, that's it. The client can't access the protected resource anymore. The spec has a more extensive description, but you get the idea.

At this point, we've covered the conceptual flow in the four party diagram. Hopefully it all makes sense now. Next up we are going to delve into the client role further.

I never really found the OAuth post that explained it at the level of detail I wanted so I really understood it. I'm attacking this using the actual spec itself as there is a ton of interesting stuff in there. You really should read it, it's actually not that bad to go through. I'm going to break this down into a number of posts to keep things bite-sized. This initial post is just going to level set on what OAuth is and to define a few terms that we are going to use over and over.

 OAuth at 10,000 feet

Before we even start with OAuth 2.0, we should answer the more general question of what is OAuth? Referring to Wikipedia for starters:

OAuth is an open standard for authorization.

It's useful to get right to the heart of a common source of confusion about OAuth. OAuth is about solving authorization problems. Period, end of sentence. Authentication is explicitly not an OAuth concern. Wikipedia goes on:

OAuth provides client applications a 'secure delegated access' to server resources on behalf of a resource owner. It specifies a process for resource owners to authorize third-party access to their server resources without sharing their credentials.

Accurate, but a little terse for my tastes. If we unpack this, what are we really saying here? OAuth is targeted at untangling a very specific but very common problem in authorization on the internet; there is a fundamental difference between me accessing my data and some other program that I want to give access to my data. The reason for wanting to make this distinction makes a lot of sense when you think about it. An example (oft cited at this point), is in order:

 For example…

We all have large libraries of photographs up on the web someplace. From time to time, it's nice to get high quality prints made. Assume that a service exists that can print these for me, I now need to give the service access to the files. How should I do this?

• I could grant anonymous access to my photographs.
• I could give the service my credentials to my cloud storage so it can sign in as me.

Both of these approaches work but come along with obvious baggage. Granting anonymous access to the photos works, but I probably don't want them accessible by 7 billion of my closest friends. I also probably don't want to give my credentials to the service.

• The service would be able to act as me which gives it complete control of my photos. That sounds … really bad.
• What if I want to prevent the service from accessing my photos anymore? The only way to do that is to change my password.

What I really want is a way to give some of my rights to the service without having to share my credentials. Not coincidentally, that sounds a lot like how Wikipedia defined OAuth.

 The OAuth 2.0 Authorization Dance

In the interest of being precise, the spec has specific names that it assigns to the different roles to make sure there isn't any confusion when describing how things work. Understanding these is pretty important so here they are directly from the spec:

• Resource Owner - 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.

 These are combined into the fancy-sounding 'Four Party Diagram' to show the overall idea. The client asks for and obtains permission to access a resource on the resource server from the resource owner, exchanges that permission for an access token issued by the authorization server and then exchanges that access token for the protected resource.

 One important observation here: up until now we've spoken of these resources like they were files. For the purposes of OAuth, a resource is anything addressable using a URI. That can obviously be a photo pulled via an HTTP GET or it can be a REST API endpoint which adds a photo to a repository using an HTTP POST. We are definitely talking about authorizing access to more than files here.

 In the next post, we're going to unpack the four party diagram further and what is really happening here.