Creating a custom HTML authorization form for user security

Custom HTML forms can be created for user security during the authorization stage in OAuth.

Before you begin

The Native OAuth provider configuration includes user authorization when using the Implicit, Access code, or Resource owner password grant types. You have the option to select how to authorize application users and one of the choices is Custom HTML Form. For more information, see Configuring a native OAuth provider when using API Manager or Configuring a native OAuth provider when using Cloud Manager. This topic describes how to create the Custom HTML form for authorization.

About this task

During three-legged OAuth definitions (Implicit flow, Resource owner password flow, and Access (Authorization) code flow, the user is presented with a form through which they grant permission to an application to access their data through the API on their behalf. You can present a custom form or a default form. Your custom form must fulfill certain requirements.

Important: The fields used by IBM® API Connect to inject information into your form have case-sensitive field names.

Procedure

To create a custom authorization form for your Native OAuth provider, complete the following steps:

Create a well-formed XHTML document. This will be parsed and transformed by API Connect to inject hidden fields.
For your XHTML 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 API Connect will replace with input fields necessary for the completion of the OAuth process.

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: Display an error message 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.
Optional: You can add to the form HTML elements that will load features 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 6 results in a form similar to the following example:

<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 Native OAuth provider to use a Custom HTML Form for authorization for User Security. Provide the URL as the endpoint at which your form is available. For more information, see Configuring a native OAuth provider when using API Manager or Configuring a native OAuth provider when using Cloud Manager.