Single-Page Apps

3.2

Single-page apps (or browser-based apps) run entirely in the browser after loading the Javascript and HTML source code from a web page. Since the entire source is available to the browser, they cannot maintain the confidentiality of a client secret, so the secret is not used for these apps. The flow is exactly the same as the authorization code flow, but at the last step, the authorization code is exchanged for an access token without using the client secret.

The diagram below illustrates an example where the user interacts with their browser, which in turn makes API requests directly to the service. After first downloading the Javascript and HTML source code from the client, the browser then makes direct API requests to the service. In this case, the app’s server never makes API requests to the service, since everything is handled directly in the browser.

The user’s browser communicates directly with the API server

Authorization

The authorization code is a temporary code that the client will exchange for an access token. The code itself is obtained from the authorization server where the user gets a chance to see what the information the client is requesting, and approve or deny the request.

The first step of the web flow is to request authorization from the user. This is accomplished by creating an authorization request link for the user to click on.

The authorization URL is usually in a format such as:

https://authorization-server.com/oauth/authorize
  ?client_id=a17c21ed
  &response_type=code
  &state=5ca75bd30
  &redirect_uri=https%3A%2F%2Fexample-app.com%2Fauth

After the user visits the authorization page, the service shows the user an explanation of the request, including application name, scope, etc. If the user clicks “approve”, the server will redirect back to the website, with an authorization code and the state value in the URL query string.

Authorization Grant Parameters

The following parameters are used to make the authorization request.

client_id

The client_id is the identifier for your app. You will have received a client_id when first registering your app with the service.

response_type

response_type is set to code indicating that you want an authorization code as the response.

redirect_uri (optional)

The redirect_uri is optional in the spec, but some services require it. This is the URL to which you want the user to be redirected after the authorization is complete. This must match the redirect URL that you have previously registered with the service.

scope (optional)

Include one or more scope values to request additional levels of access. The values will depend on the particular service.

state (recommended)

The state parameter serves two functions. When the user is redirected back to your app, whatever value you include as the state will also be included in the redirect. This gives your app a chance to persist data between the user being directed to the authorization server and back again, such as using the state parameter as a session key. This may be used to indicate what action in the app to perform after authorization is complete, for example, indicating which of your app’s pages to redirect to after authorization. This also serves as a CSRF protection mechanism. When the user is redirected back to your app, double check that the state value matches what you set it to originally. This will ensure an attacker can’t intercept the authorization flow.

Note that the lack of using a client secret means that using the state parameter is even more important for the single-page apps.

Example

The following step-by-step example illustrates using the authorization grant type for single-page apps.

Step-by-step

The app initiates the authorization request

The app initiates the flow by crafting a URL containing ID, and optionally scope and state. The app can put this into an <a href=""> tag.

<a href="https://authorization-server.com/authorize?response_type=code
     &client_id=mRkZGFjM&state=TY2OTZhZGFk">Connect Your Account</a>

The user approves the request

Upon being directed to the auth server, the user sees the authorization request.

Example Authorization Request

After the user is taken to the service and sees the request, they will either allow or deny the request. If they allow the request, they will be redirected back to the redirect URL specified along with an authorization code in the query string. The app then needs to exchange this authorization code for an access token.

https://example-app.com/cb?code=Yzk5ZDczMzRlNDEwY&state=TY2OTZhZGFk

If you include a “state” parameter in the initial authorization URL, the service will return it to you after the user authorizes your app. Your app should compare the state with the state it created in the initial request. This helps ensure that you only exchange authorization codes that you requested, preventing attackers from redirecting to your callback URL with arbitrary or stolen authorization codes.

Exchange the authorization code for an access token

To exchange the authorization code for an access token, the app makes a POST request to the service’s token endpoint. The request will have the following parameters.

grant_type (required)

The grant_type parameter must be set to “authorization_code”.

code (required)

This parameter is for the authorization code received from the authorization server which will be in the query string parameter “code” in this request.

redirect_uri (possibly required)

If the redirect URL was included in the initial authorization request, it must be included in the token request as well, and must be identical. Some services support registering multiple redirect URLs, and some require the redirect URL to be specified on each request. Check the service’s documentation for the specifics.

Client Identification (required)

Despite the client secret not being used in this flow, the request requires sending the client ID to identify the application making the request. This means the client must include the client ID as a POST body parameter rather than using HTTP Basic Authentication like it can when including the client secret as well.

POST /oauth/token HTTP/1.1
  Host: authorization-endpoint.com
  grant_type=code
  &code=Yzk5ZDczMzRlNDEwY
  &redirect_uri=https://example-app.com/cb
  &client_id=mRkZGFjM

Security Considerations

The only way the authorization code grant with no client secret can be secure is by using the “state” parameter and restricting the redirect URL to trusted clients. Since the secret is not used, there is no way to verify the identity of the client other than by using a registered redirect URL. This is why you need to pre-register your redirect URL with the OAuth 2.0 service.

While the OAuth 2.0 spec does not specifically require that redirect URLs use TLS encryption, it is highly recommended. The only reason it is not required is because deploying an SSL website is still somewhat of a hurdle for many developers and this would discourage wide adoption of the spec. Some APIs do require https for their redirect endpoints, but many still do not.