Home / IBM Application Gateway / References / Yaml / Forms Login

We Have Moved

The IBM Application Gateway has a new home - docs.verify.ibm.com/gateway

The documentation on this site will no longer be maintained after v21.02, please update your bookmarks.

Description

Specifies the configuration information used for performing form-based single sign-on to the protected application.

Source	Usage
service	Data from the credential service will be used to populate this field.
attribute	A credential attribute value will be used to populate the field.
static	A static string will be used to populate this field.

Depending on the type of 'source' used, the usage of the 'value' can differ.

Source	Usage
service	The field from the credential service data to use. This can be either 'username' or 'password'
attribute	The name of a credential attribute for which the value of will be used to populate this field.
static	A static string literal which will be used to populate this field.

In the below example:

Forms login will be attempted automatically on requests to the URL 'authenticate/login'
On the page, the HTML form with 'action="login.jsp"' will be detected as the login form
Credentials will be retrieved from the service named 'testCredentialService' service provided in the 'services/credential' YAML. When requests are made to this service, the '{resource}' token will be substituted with 'jspApp'.
To complete the login, IAG will send a forms POST to the URL indicated by the HTML form, containing the fields:
- 'username', which is populated by the 'username' retrieved from the credential service.
- 'password', which is populated by the decrypted version 'password' of the 'password' retrieved from the credential service.
- 'SSO_SOURCE' which is a static field always containing the string 'IAG-SSO'
- 'LOGIN_ORIGIN' which is populated using the value of the credential attribute 'AZN_CRED_MECH_ID' for the current user session.
When IAG submits the forms-based login, it will consider a response from the application with a HTTP status code 302 and a location header matching "*/loginSuccess" to be a successful login.
If the response does not look like a successful login, IAG will present the login form to the client.
As credential learning is enabled, when IAG observes the client POST to '/login.jsp', it will extract the 'username' and 'password' fields and store them with the credential service for future use.

Properties

The following table(s) describe the configuration properties for this component:

Name	Type	Constraints	Description
login_resources	array[LOGIN_RESOURCES Object]
credential_learning	boolean	Values: true,false Default:false	A boolean flag indicating whether or not credential learning is enabled for this resource server. If credential learning is enabled, when IAG is unable to automatically complete the forms login but observes a successful manual login, the credentials used will be encrypted and stored in the credential service for future use.

LOGIN_RESOURCES Object

This entry is a list of login resources which each contain configuration for each forms-based login page.

Name	Type	Description
resource_name	string	The resource name which will be used when making requests to the configured credential service.
resource	string	This entry specifies a pattern that uniquely identifies requests for an application's login page. The page will then be intercepted to begin the forms-login sign-on process. The pattern provided is compared to the request URI.
service	string	The name of the credential service which is used to store and retrieve credentials for this resource.
form_action	string	This entry specifies a pattern that identifies which form contained in the intercepted page is the login form. The matching is performed based on the 'action' attribute of the HTML ' ' node.
fields	array[FIELDS Object]
response_rules	array[RESPONSE_RULES Object]

FIELDS Object

This entry is a list of the form fields which are need to complete the form-based login.

Name	Type	Constraints	Description
source	string	Values: static,attribute,service	The data source which will be used to populate this form field. See the 'Login Form Field Types' table for an explanation of the values.
name	string		The name of the form field that will be populated.
value	string		This entry defines what information for the given source will be used to populate this form field. See the 'Login Form Field Values' table for an explanation of the values.

RESPONSE_RULES Object

A list of rules which are used to determine if the forms-based was successful or not. These rules are evaluated in the order they are provided here.

Name	Type	Constraints	Description
headers	array[HEADERS Object]
response_code	string		The HTTP status code expected in the response for this rule.
success	boolean	Values: true,false	A boolean to indicate whether this rule is used to detect a successful login or not. 'true' indicates a successful login, 'false' indicates a failed login attempt.

HEADERS Object

The HTTP headers expected in the response.

Name	Type	Constraints	Description
name	string		The name of the HTTP header to examine in the response. HTTP header names are not case sensitive.
value	string		The expected value of the HTTP header. Header values are case sensitive.

Example

 resource_servers:
         - path: "/jspApp"
           ...
           forms_login:
               credential_learning: true
               login_resources:
                   - resource:      authenticate/login
                     form_action:   /login.jsp
                     service:       testCredentialService
                     resource_name: jspApp
                     fields:
                         - name:   username
                           source: service
                           value:  username
                         - name:   password
                           source: service
                           value:  password
                         - name:   SSO_SOURCE
                           source: static
                           value:  "IAG-SSO"
                         - name:   LOGIN_ORIGIN
                           source: credential
                           value:  AZN_CRED_MECH_ID
                     response_rules:
                         - success: true
                           response_code: 302
                           headers:
                               - name: Location
                                 value: "*/loginSuccessful"