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

Login form fields can be populated with data from three possible sources, indicated by the source field:

SourceUsage
serviceData from the credential service will be used to populate this field.
attributeA credential attribute value will be used to populate the field.
staticA 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.

SourceUsage
serviceThe field from the credential service data to use. This can be either username or password
attributeThe name of a credential attribute for which the value of will be used to populate this field.
staticA 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

NameTypeConstraintsDescription
credential_learningbooleanValues: 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_resourcesArray 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

NameTypeConstraintsDescription
resourcestringThis 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_actionstringThis 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_patternstringThis 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 '*'.
servicestringThe name of the credential service which is used to store and retrieve credentials for this resource.
resource_namestringThe resource name which will be used when making requests to the configured credential service.
fieldsArray of fields
response_rulesArray 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

NameTypeConstraintsDescription
namestringThe name of the form field that will be populated.
sourcestringValues: static, attribute, serviceThe data source which will be used to populate this form field.
See the Login Form Field Types table for an explanation of the values.
valuestringThis 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

NameTypeConstraintsDescription
successbooleanValues: true or falseA 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_codestringThe HTTP status code expected in the response for this rule.
headersArray of headers

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

The HTTP headers expected in the response.

Properties

NameTypeConstraintsDescription
namestringThe name of the HTTP header to examine in the response.
HTTP header names are not case sensitive.
valuestringThe 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"