Creating a custom HTML login form for user security

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

Before you begin

The Native OAuth provider configuration includes Identity Extraction when using the Implicit, Access code, or Resource owner password grant types. You have the option to select how to extract the user credential and one of the choices is Custom HTML Form. For more information, see Configuring a native OAuth provider. This topic describes how to create the Custom HTML form for identity extraction.

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 for signing in to the service provided by the API. 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 sign-in form for your Native OAuth provider, complete the following steps:

Create a well formed XHTML document that 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">
```
Create a text input field that is named username and create a password input field named password.
Add the line <EI-INJECT-HIDDEN-INPUT-FIELDS>. This third element is a placeholder that API Connect replaces with input fields to complement the user-submitted data.

Create a button to initiate the sign-in process.

For example:

<button id="login_button" type="submit" name="login" value="true">Log in</button>

Optional: Add text that is displayed the first time that the user visits the sign-in page. Use the tag <EI-LOGINFIRSTTIME> for the text that you want to display.
Optional: Add text that appears when the user is returned to the sign-in page if they fail to authenticate. Use the tag <EI-LOGINFAILED> for the text that you want to display.
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 <EI-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 elements that are loaded from external sources, such as images or JavaScript.

Insert spacing and other features as you require. Completing Steps 1 through to 8 results in a form similar to the following example:

<html lang="en" xml:lang="en">
  <head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/></head>
  <body>
    <form method="POST" enctype="application/x-www-form-urlencoded" action="authorize">
      <h1>Please sign in</h1>
      <p>Username </p>
      <p style="text-indent: 0em;"><input type="text" name="username" required="required" /> </p>
      <p>Password </p>
      <p style="text-indent: 0em;"><input type="password" name="password" required="required" /> </p>
      <EI-INJECT-HIDDEN-INPUT-FIELDS/>
      <p style="text-indent: 2em;"> <button id="login_button" type="submit" name="login" value="true">Log in</button> </p>

      <EI-LOGINFIRSTTIME>
        <p>If you have forgotten your user name or password, contact your system administrator.</p>
      </EI-LOGINFIRSTTIME>

      <EI-LOGINFAILED>
        <p style="color: red">At least one of your entries does not match our records. 
          If you have forgotten your user name or password, contact your system administrator.</p>
      </EI-LOGINFAILED>

      <EI-INTERNAL-CUSTOM-FORM-ERROR/>

    </form>
  </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 identity extraction and provide the URL at which your form is available. For more information, see Configuring a native OAuth provider .