Form Post Response Mode with WSO2 Identity Server

4 min readJun 19, 2022

What is Form Post Response Mode?

Form Post response mode is an additional response mode defined by the Auth 2.0 specification which allows Authorization response parameters to be sent to the client as HTML form values via a HTTP POST request.

Normally, if you have tried the OIDC flow, when requesting the authorization code, it is received as a query parameter appended to the redirect URL of the response received from the Identity Provider. But if the form post response mode is used, instead of sending the requested response parameters as a part of the redirect URL, the Identity Provider generates a HTML form with the response parameters added as hidden HTML elements and sends it to the client using the HTTP POST method.

Here is an example of the generated HTML form:

<html>
   <head><title>Submit This Form</title></head>
   <body onload="javascript:document.forms[0].submit()">
    <form method="post" action="https://client.example.org/callback">
      <input type="hidden" name="state"
       value="DcP7csa3hMlvybERqcieLHrRzKBra"/>
      <input type="hidden" name="id_token"
       value="eyJhbGciOiJSUzI1NiIsImtpZCI6IjEifQ.eyJzdWIiOiJqb2huIiw
         iYXVkIjoiZmZzMiIsImp0aSI6ImhwQUI3RDBNbEo0c2YzVFR2cllxUkIiLC
         Jpc3MiOiJodHRwczpcL1wvbG9jYWxob3N0OjkwMzEiLCJpYXQiOjEzNjM5M
         DMxMTMsImV4cCI6MTM2MzkwMzcxMywibm9uY2UiOiIyVDFBZ2FlUlRHVE1B
         SnllRE1OOUlKYmdpVUciLCJhY3IiOiJ1cm46b2FzaXM6bmFtZXM6dGM6U0F
         NTDoyLjA6YWM6Y2xhc3NlczpQYXNzd29yZCIsImF1dGhfdGltZSI6MTM2Mz
         kwMDg5NH0.c9emvFayy-YJnO0kxUNQqeAoYu7sjlyulRSNrru1ySZs2qwqq
         wwq-Qk7LFd3iGYeUWrfjZkmyXeKKs_OtZ2tI2QQqJpcfrpAuiNuEHII-_fk
         IufbGNT_rfHUcY3tGGKxcvZO9uvgKgX9Vs1v04UaCOUfxRjSVlumE6fWGcq
         XVEKhtPadj1elk3r4zkoNt9vjUQt9NGdm1OvaZ2ONprCErBbXf1eJb4NW_h
         nrQ5IKXuNsQ1g9ccT5DMtZSwgDFwsHMDWMPFGax5Lw6ogjwJ4AQDrhzNCFc
         0uVAwBBb772-86HpAkGWAKOK-wTC6ErRTcESRdNRe0iKb47XRXaoz5acA"/>
    </form>
   </body>
  </html>

The client’s redirect URL is added as the action attribute of this HTML form and the result parameters will be encoded in the body using the ‘application/x-www-form-urlencoded’ format.

Why do we need Form Post Response Mode?

Form Post response mode has been introduced to address some of the security concerns related to encoding response values in the default query response mode. Since the default mode sends the response parameters as a part of the redirect URL, they can get stored in HTTP logs, referral headers and browser histories. This creates security problems as sensitive data such codes and tokens sent through these responses can be leaked to third parties.

By using the form post response mode, these codes and tokens would be encoded as HTML form values and sent in the body of a POST request. Sending the response parameters inside the body of the request prevent them getting recorded or stored making them not accessible to third parties. The authorization response is intended to be used only once as per the specification. Therefore the user-agent is instructed not to store or reuse the content of the response.

With these extra measures on safety, the Auth 2.0 specification has declared it is safe to use this response mode to return authorization response parameters whose default response modes are query or fragment encoding.

Trying out Form Post Response Mode with WSO2 Identity Server

Configure WSO2 Identity Server:

Download the latest WSO2 Identity Server (IS 6.0.0-m5 as of now) from product IS releases.
Start the Identity Server and access the management console at https://localhost:9443/carbon.
Add a new service provider by going to Home → Identity → Service Providers → Add and provide a suitable app name and click Register.
Add the Oauth configurations by going to Inbound Authentication Configurations → OAuth/OpenID Connect Configuration → Configure.
Add the Callback Url as http://localhost.com:8080/pickup-dispatch/oauth2client and click Update.
Copy the OAuth Client Key as it will be required for the authorization request.

Deploy the pickup dispatch sample app:

Download and deploy the pickup dispatch application from the WSO2 IS sample applications.
(This step is optional since we are only checking the authorization response in this article.)
Open a browser with the network tab open and use the following authorization request to log into the deployed application.
(Add the OAuth Client Key obtained while creating the Service Provider, as the <client-id>)

https://localhost:9443/oauth2/authorize?client_id=<client-id>&redirect_uri=http://localhost.com:8080/pickup-dispatch/oauth2client&scope=openid&response_type=code&response_mode=form_post

3. Click on the POST request to the oauth2client endpoint at network tab. The code will be available as Form data under the Request tab as follows:

Under the Headers section, observe that the request will be a POST request.

In the above request, we are using the response_type as code and the response_mode as form_post. The default response_mode for authorization requests is query and if you try the above request without specifying the response_mode, the code will be received as a query parameter.

Try the request with the default response_mode:

https://localhost:9443/oauth2/authorize?client_id=<client-id>&redirect_uri=http://localhost.com:8080/pickup-dispatch/oauth2client&scope=openid&response_type=code

Under the Headers section of the GET request to redirect URL, notice how the code parameter is appended to the URL.

Form post response mode can be used with all of the response types: ‘code,’ ‘token’, ‘code id_token’, ‘code token’, ‘id_token token’ and ‘code token id_token’.

Try the following authorization request changing the <response_type> parameter with the above response types and observe how the requested code/tokens will be received in the response as form data.

https://localhost:9443/oauth2/authorize?client_id=<client-id>&redirect_uri=http://localhost.com:8080/pickup-dispatch/oauth2client&scope=openid profile&nonce=vo46KcYXSv&response_type=<response-type>&response_mode=form_post

Hope you have got a comprehensive idea on what form post response mode is and why it should be used in your applications from this article.

Happy coding! :P

Form Post Response Mode with WSO2 Identity Server

What is Form Post Response Mode?

Why do we need Form Post Response Mode?

Trying out Form Post Response Mode with WSO2 Identity Server

References

Written by Imalsha Gunasekara