OAuth2 "response_mode" Query Parameter

The "response_mode" query parameter in OAuth2 is used to control how the authorization server returns the authorization response to the client application.

Why It Is Used

  • It specifies the method by which the authorization server should return the authorization code or access token to the client.
  • It enhances security by allowing the client to choose the most secure way to receive the response.

Common Values for "response_mode"

  1. "query"
    • Returns the response parameters in the URL query string.
    • Example: 
      https://yourapp.com/callback?code=AUTH_CODE&state=RANDOM_STATE
  2. Use Case -
    • Typically used with Authorization Code Flow.
    • Should only be used over HTTPS to protect query parameters.
  3. "fragment"
    • Returns the response parameters in the URL fragment.
    • Example: 
      https://yourapp.com/callback#access_token=ACCESS_TOKEN&state=RANDOM_STATE
  4. Use Case -
    • Used with Implicit Flow because fragments are not sent to the server, increasing security for tokens.
    • Suitable for Single Page Applications (SPAs).
  5. "form_post"
    • Returns the response parameters in a form POST body.
    • Example: 
      <form method="post" action="https://yourapp.com/callback">
<input type="hidden" name="code" value="AUTH_CODE">
<input type="hidden" name="state" value="RANDOM_STATE">
</form>
  6. Use Case -
    • More secure than query or fragment because parameters are sent in the HTTP POST body.
    • Recommended when returning sensitive data, like ID tokens.

Example Request with "response_mode"

https://auth.example.com/oauth2/authorize?
response_type=code&
client_id=YOUR_CLIENT_ID&
redirect_uri=https%3A%2F%2Fyourapp.com%2Fcallback&
scope=openid+profile&
state=RANDOM_STATE&
response_mode=form_post

Which OAuth2 Flows Use "response_mode"?

  • Authorization Code Flow - Typically uses "query" or "form_post".
  • Implicit Flow - Uses "fragment" to return tokens in the URL hash.
  • Hybrid Flow (OpenID Connect) - Often uses "form_post" for enhanced security.

Is It Required?

  • No, it is optional.
  • If not specified, the default is:
    • "query" for Authorization Code Flow.
    • "fragment" for Implicit Flow.

Security Notes

  • "form_post" is the most secure because data is sent in the HTTP POST body, protecting tokens from URL leaks.
  • Always use "https://" when using "query" or "fragment" to protect tokens from network sniffing.

Summary

  • "response_mode" controls how the response is sent to the client.
  • "query" - Parameters in the URL query string.
  • "fragment" - Parameters in the URL hash (not sent to the server).
  • "form_post" - Parameters in a hidden form POST body (most secure).
  • It enhances security and flexibility for different client types (SPA, mobile, server).