Skip to main content

Forms Login

Description

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:

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

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 Constraints 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"