Forms Login

resource_servers[]/forms_login

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

Login Form Field Types

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.

Login Form Field Values

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

Name	Type	Constraints	Description
credential_learning	boolean	Values: `true` or `false` Default value: `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	Array of login_resources

resource_servers[]/forms_login/login_resources[]

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

Properties

Name	Type	Description
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.
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 `<form>` node.
form_response_pattern	string	This optional entry specifies a pattern which is used to determine if the page contains the login form or not. If the page content does not include this pattern, it will be returned to the client. By default, the gateway will only examine the first 32,768 bytes of the response for the pattern. Because the pattern is checked against the entire cached response it will usually start and end with a '*'.
service	string	The name of the credential service which is used to store and retrieve credentials for this resource.
resource_name	string	The resource name which will be used when making requests to the configured credential service.
fields	Array of fields
response_rules	Array of response_rules

resource_servers[]/forms_login/login_resources[]/fields[]

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

Properties

Name	Type	Constraints	Description
name	string		The name of the form field that will be populated.
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.
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.

resource_servers[]/forms_login/login_resources[]/response_rules[]

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.

Properties

Name	Type	Constraints	Description
success	boolean	Values: `true` or `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.
response_code	string		The HTTP status code expected in the response for this rule.
headers	Array of headers

resource_servers[]/forms_login/login_resources[]/response_rules[]/headers[]

The HTTP headers expected in the response.

Properties

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
          form_response_pattern: "*login_prompt*"
          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"