OAuth2: the Implicit Flow, aka as the Client-Side Flow

In this part of the OAuth2 series we’ll be looking at the Implicit Flow, which is also known as the  Client-Side Flow.

Let’s get started .The Implicit Flow (some call it Implicit Grant Flow, too) is called like that, as the required access token is sent back to the client application without the need for an authorization request token. This makes the whole flow pretty easy, but also less secure. As the client application, which is typically JavaScript running within a Browser is less trusted, no refresh tokens for long-lived access are returned. You should use this flow for client-side web applications (JavaScript clients) that need temporary access (a few hours) to the user’s data. Returning an access token to JavaScript clients also means that your browser-based application needs to take special care – think of XSS (Cross-Site Scripting) Attacks that could leak the access token to other systems. We don’t deal with these issues here in this post, but be warned!

The basic flow for the OAuth2 Implicit Grant (again, taken straight from the OAuth2 Spec is below. We’ll step through the flow with examples.

(A) Just as in the OAuth2 server-side flow (authorization grant flow) we send off the user to  the authorization server. As the chart shows it, we need to send along the client identifier and the redirection URI (the latter is optional, but we strongly recommend it). Please note that there is no client_secret this time. That’s simply because a browser-based client could not keep that secret, hence it is not used.  These are all the parameters:

  • response_type: This time, it needs to be set to ‘token’ which tells the authorization server that it should respond directly with an access token.
  • client_id: The server needs to know which client is requesting access for a user – this is done via the client_id parameter.
  • redirect_uri: The server configured a redirect_uri (which we strongly recommend) which needs to match the settings for the client_id. Client_id and redirect_uri are both server-side settings that the app developer needs to get at beforehand.
  • scope: The client can specify the scope he wants to get access to. This is optional and for the hybris OCC Web Services currently not required, as we have a single ‘customer’ scope.
  • state: again optional, but we recommend to use it. To mitigate XSS (Cross Site Scripting Attacks) we calculate a pseudo-random state and pass it on to the authorization server. At a later point, this state is passed back to us and we can compare the values.

Again this looks more complicated than it is. Here’s our piece of Groovy code taken from a Gaelyk Controller that sends off the user to the authorization server:

(B) The user may now have to log in first and will then be presented with an authorization screen: “The app client-side is requesting access to ‘customer’ scope – do you wish to grant access?”. Let’s assume the user grants access.

(C) The authorization server now redirects back to the client web application. the access token will be part of this redirect URI, but in the #hash fragment of the URI. Interestingly, this makes it invisible for some server-side code, like the J2EE spec which does not allow access to the hash fragment (as it is only intended for the client). Nothing to do here for the redirection request, but as it will hit our web application again at the redirect_uri, we need to make sure this request will work.  For the purpose of a demo client, we’ve still used a controller endpoint that more or less forwards directly to a HTML page. The remaining logic (getting access to the access_token, verifying the state parameter) will all happen in JavaScript), but we chose to extract the state from the users’s session for which we need to route the redirect request through our controller:

(D) The authorization server sent a redirect response in (C), so the user-agent (browser) will now follow the redirect and our client-side web application server will respond with a HTML page (that in turn includes javascript to parse the hash fragment).
NOTE: the one thing that really bugs me here a bit is this: the spec reads “Redirection URI without Fragment”. That would mean that the browser sends out the request without revealing the access_token in the hash fragment. Looking at the Chrome Developer Tools, it seems to pass the fragment, too. So I doubt this works in real life…  

(E) The HTML page is served and either includes some javascript inline or links to another javascript resource. For the purpose of our demo app we chose to keep the HTML and JavaScript seperate. First, let’s see the HMTL page returned (slightly shortened):

This is really one of the smallest HTML5 pages you can imagine, but note a few things:

  • state: we extracted the state that we saved into the user’s session in our controller and passed it on via the J2EE HttpServletRequest as an attribute. We extract this state and pass it on to a data-* field of the oauthParams HMTL div element. We can now later extract the state and verify the state that we got in the redirection URI.
  • scripts: we include two script sources – one is the CDN-hosted jquery and the second in our own oauth javascript. That’s where the magic is…

(F) The javascript /js/oauth.js is now kicking in and will access the #hash fragment to extract the access token and to compare the state value. Our little javascript resource looks like this (script adapted to fit the page width):

The OAuth2 parameters are part of the hash fragment, that’s the part of a URL after the # sign. The key values themselves follow the url-encoded key/value syntax for regular query parameters. With a little regex magic we extract all  key/value pairs and build up a oauthParams object. We also make use of the state parameter and compare the session state parameter (that we extract from a div in the HTML code) to the passed state parameter.

(G) Well, to be exact, the javascript that could now use the access token is the ‘client’, so don’t let the overview chart confuse you.

Done. We covered the implicit grant flow in this second blog post of the OAuth2 series. Next up is the Resource Owner Password Flow. This one will be a surprise to many, as it is not well known. But it happens to be the flow that fits best to a typical user of the hybris OCC Web Services. Stay tuned!