Creating a custom authorization form

You can create a custom authorization form for the OAuth authorization stage.

Before you begin

You need an existing API. For more information, see Creating API definitions.
You need an OAuth security definition that uses Implicit Flow, Password Flow, or Authorization Code Flow. For more information, see Protecting an API with OAuth security definition.

About this task

During the OAuth processing, you can configure the OAuth 2.0 provider API to present users with a form that grants permission to an application that accesses their data through the API on their behalf. You can present a custom form or the default form. A custom form must fulfill certain requirements.

The names of the fields that inject information into your form are case-sensitive.

Procedure

Create a well formed HTML document that is parsed and transformed by IBM® API Connect to inject hidden fields.
For your HTML form, set the method as POST, the encoding type as application/x-www-form-urlencoded, and the action as authorize. Add any other parameters that you require.
For example:
```
<form method="POST" enctype="application/x-www-form-urlencoded" action="authorize">
```
Add the line <AZ-INJECT-HIDDEN-INPUT-FIELDS/>. This line is a placeholder that IBM API Connect will replace with input fields necessary for the completion of the OAuth processing.

Create two buttons with the following code so that the user can grant or deny permission. Edit the text to suit your preferences.

<button class="cancel" type="submit" name="approve" value="false">No Thanks</button>
<button class="submit" type="submit" name="approve" value="true">Allow Access</button>

Optional: Have an error message displayed when an error in the custom form prevents it from being displayed to the user correctly. Use the tag <AZ-INTERNAL-CUSTOM-FORM-ERROR/>; the message text is generated automatically. You should detect such errors during testing to prevent this error message being displayed to the end user.
Include additional hidden fields to provide context for the OAuth processing.
Although you will likely want to include additional text to provide context for the user, use the following commands to include information relevant to the OAuth flow.
- <input type="hidden" name="dp-state" value="A"/>
- <input type="hidden" name="resource-owner" value="A"/>
- <input type="hidden" name="dp-data" value="A"/>
- <input type="hidden" name="redirect_uri" value="A"/>
- <input type="hidden" name="scope" value="A"/>
- <input type="hidden" name="original-url" value="A"/>
- <input type="hidden" name="client_id" value="A"/>
- <input type="hidden" name="miscinfo" value="A"/>
Optional: Based on the value of the Content-Security-Policy response header, add elements that are loaded from external sources, such as images or JavaScript.
For example, <script src="http://www.example.com/example.js" />

Insert spacing and additional elements as you require. Completing Steps 1 through to 7 results in a form similar to the following example.

<html lang="en" xml:lang="en">
  <head>
    <title>Request for permission</title>
  </head>
  <body class="login">
    <div>
      <div>
        <form method="post" enctype="application/x-www-form-urlencoded" action="authorize">
          <input type="hidden" name="dp-state" value="A"/>
          <input type="hidden" name="resource-owner" value="A"/>
          <input type="hidden" name="dp-data" value="A"/>
          <input type="hidden" name="redirect_uri" value="A"/>
          <input type="hidden" name="scope" value="A"/>
          <input type="hidden" name="original-url" value="A"/>
          <input type="hidden" name="client_id" value="A"/>
          <input type="hidden" name="miscinfo" value="A"/>
          <AZ-INJECT-HIDDEN-INPUT-FIELDS/>
          <p>Greeting </p><DISPLAY-RESOURCE-OWNER/>
          <p>This application </p><OAUTH-APPLICATION-NAME/><p> would like to access your data.</p>
          <div>
            <button class="cancel" type="submit" name="approve" value="false">No Thanks</button>
            <button class="submit" type="submit" name="approve" value="true">Allow Access</button>
          </div>
        </form>
      </div>
      <AZ-INTERNAL-CUSTOM-FORM-ERROR/>
    </div>
  </body>
</html>

<html lang="en" xml:lang="en">
  <head><title>Request for permission</title></head>
  <body class="customconsent">
    <div>
      <div>
        <form method="post" enctype="application/x-www-form-urlencoded" action="authorize">
          <AZ-INJECT-HIDDEN-INPUT-FIELDS/>
          <p>Greeting...</p><DISPLAY-RESOURCE-OWNER/>
          <p>This app </p><OAUTH-APPLICATION-NAME/><p> would like to access your data.</p>
          <div>
            <button class="cancel" type="submit" name="approve" value="false">No Thanks</button>
            <button class="submit" type="submit" name="approve" value="true">Allow Access</button>
          </div>
        </form>
      </div>
      <AZ-INTERNAL-CUSTOM-FORM-ERROR/>
    </div>
  </body>
</html>

Make your form available at a URL of your choice.
If you have not already done so, configure your OAuth 2.0 provider API to use custom forms for authorization and provide the URL at which your form is available. For more information, see Step 10.f of Creating an OAuth provider API.