loading...

Demystifying OAuth2 Flows

grahamcox82 profile image Graham Cox ・3 min read

The next big confusion is over what all the various OAuth2 flows are. In some ways, OAuth2 is simpler to understand than OAuth 1. In other ways, it's more complicated - and this is one of those ways. OAuth2 introduces a number of different flows that can be used to obtain an Access Token, and picking the correct flow isn't always easy.

  • Authorization Code Grant. If you have a server component to your application, use this one. Essentially, this one means that the user is redirected to the authenticating system where they will log in, and on success they will be sent back to you. When they are sent back, they will provide you with an Authorization Code, which you can then exchange for an Access Token with the authenticating system.
  • Implicit Grant. If you don't have a server component to your application - e.g. you are a single page webapp written in pure HTML/Javascript - then use this one. This is exactly the same as the above, except that the return back to your application will include the Access Token directly, and will not contain an Authorization Code at all.
  • Resource Owner Password Credentials Grant. Don't use this one ever. It's a very strange thing for them to have included. Basically, this one requires you to capture the users Username and Password yourself, and you've got no right to be asking for those details.
  • Client Credentials Grant. This one is for when you want to authenticate your system against another system, but not on behalf of a user. You might need this to obtain an Access Token for some background administration tasks, but mostly I don't find much use for this.
  • Refresh Token Grant. This is a special case. Once you've obtained an Access Token, it has a lifetime. When the lifetime has expired, the Access Token is useless. You will also potentially get a Refresh Token though, and using this you can get a new Access Token without the user having to be present. There are no real standards on how long a Refresh Token is valid for, but it should be longer than the Access Token.

OAuth2 defines two different parts of the flow, but not all of the flows use both parts. There is the Authorization Endpoint, and the Token Endpoint. The Authorization Endpoint is the part where the user is involved directly - and is used by the Authorization Code Grant and Implicit Grant flows. The Token Endpoint is the part where the system requests an Access Token on behalf of the user, and is used by everything except for the Implicit Grant flow.

On top of OAuth2 there is also something called OpenID Connect. This solidifies some of the ways that you can use OAuth2, and adds extra functionality specifically aimed around Authentication - such as the concept of the ID Token. OpenID Connect is a very large standard - actually it's 8 specs that all work together - but it can be very useful if done right. For this post though, the important thing is that it introduces some extra ways of working with Response Types.

In OAuth2, the Response Type is used to select between Authorization Code Grant - response_type=code, or Implicit Grant - response_type=token. In OpenID Connect there is a third Response Type added - response_type=id_token - and the ability for you to combine them together depending on what you want to achieve. As such, the following are all perfectly valid:

  • code
  • token
  • id_token
  • code token
  • code id_token
  • id_token token
  • code id_token token

Any time the Response Type requested contains "code", you will be supplied with an Authorization Code to exchange for an Access Token. Any time it contains "token" you will be supplied directly with an Access Token. Any time it contains "id_token" you will be supplied with the ID Token.

So why would you want an Authorization Code and an Access Token? The obvious reason is the duration of access. Implicit Grant - meaning that you get an Access Token directly - must not issue a Refresh Token, because you are issuing it across a potentially insecure channel. It's also likely that the Access Tokens that are issued are going to be much shorter lived - maybe only a couple of minutes. If you request an Authorization Code and an Access Token then you get the Access Token right now for anything you need immediately, but you also get an Authorization Code to trade in for a longer lived Access Token for the server to use.

Discussion

markdown guide