Web Form

What Is Web Form?

Web Form is the Authentication Providers type that sends the information the user writes in the login form to the own login form of an existing web application and accepts the login according to the response of the application. It is used for applications that do not offer a separate authentication API and have only a login page. Success is determined by the status code, the cookie, the redirect address or the JSONata expression of the response; a server profile is not required, the request goes out from the Namespace route table of the profile.

How does it work?

1. Web Form is selected as the Provider Type on this screen; the login form address of the application and the form fields are entered.
2. The profile is added to the access flow as an Authentication Provider step after the login form.
3. TR7 sends the user information to the login form of the application.
4. If the response of the application satisfies the success conditions (usually the redirect made on a successful login) the flow continues from the success transition, and if it does not, from the fail transition.

Operational Best Practices

• The form field names exactly. The field names in the Login Form Fields table must be the same as the name attributes in the login form of the application.
• The success condition a redirect. Most applications make a 301 or 302 redirect on a successful login; on a failed login they return the same page with 200. The condition must be selected accordingly.
• The attributes are mapped manually. There is no automatic attribute mapping in this type; the No automatic mapping for this provider - every attribute has to be mapped below information is displayed in the User Attribute Mapping section in the form.
• The lockout. In this type, which verifies a password, Account Lockout Policies must be assigned.

How to Add?

A new Web Form provider is added through the TR7 web management interface with the following steps:

1. The Configuration Menu is opened by clicking the TR7 logo at the bottom left.
2. The AGS → Authentication → Authentication Providers → Add steps are followed.
3. A unique and descriptive name is entered for the profile; Web Form is selected as the Provider Type.
4. The Login Form URL, the form fields and the success conditions are entered.
5. The profile is added by clicking the Add button.

Profile Add Form

When the AGS → Authentication → Authentication Providers → Add steps are followed and Web Form is selected in the Provider Type field, the form opens with the following fields.

The Form While Web Form Is Selected

INFO

Provider Name Required

The name of the profile; it identifies the profile in the list, in the step selection in the flowchart, in the session list and in the logs. The name must be unique on the device; a second profile with the same name is not saved and the Name is used warning is displayed. When it is left empty, the Required field warning is displayed.

INFO

Provider Type Required

The provider type; Web Form is selected on this page. When the type is changed, only the fields of the new type are displayed and saved; the type is changed in the edit form as well.

INFO

Namespace Default: the default route table

The Route Tables record from which the login form request of TR7 goes out; a route table that has access to the application must be selected. The field comes filled with the default route table of the device; the name of this table varies by device (e.g. DEFAULT or DEFAULT_ROUTE).

INFO

Login Form URL Required

The action address of the login form of the application to which the user information is sent; a smart variable is added with the ƒx icon. When it is left empty, the Required field warning is displayed.

INFO

Login Form Fields Required

The fields to be sent to the form are entered in the Field Name and Field Value table. The form opens with two rows: the username field comes filled with the AGS input (username) variable and the password field with the AGS input (password) variable. New rows are added with the + icon next to the label, the rows are ordered by dragging from the handle on the left and are deleted with the × icon on the right; at least one row is present. A smart variable is selected in the value field with the ƒx icon.

INFO

Success Conditions Default: Status code

The conditions to be sought in the response for the login to be considered successful; more than one is selected and each selection opens its own field:

Option	Meaning
Status Code	The status code of the response must be in the Expected Status Codes list.
Cookie	The response must contain the cookie named in Expected Cookie Name (e.g. the session cookie of the application).
Redirect URL	The response must redirect to the Expected Redirect URL address.
JSONata	The JSONata Success Expression expression must give a true result on the response.

Expected Status Codes Default: 301, 302

Displayed while Status Code is selected; the status codes considered successful are selected in multiples. In the Web Form type it comes filled with the redirect codes of a successful login (301: Moved Permanently, 302: Found (Moved Temporarily)).

Expected Cookie Name Required

Displayed while Cookie is selected; the name of the session cookie the application is expected to return in the response on a successful login.

Expected Redirect URL Required

Displayed while Redirect URL is selected; the address the application is expected to redirect to on a successful login. The field accepts a smart variable with the ƒx icon.

JSONata Success Expression Required

Displayed while JSONata is selected. The expression is evaluated at the root of the response envelope; the fields at the root are status (the last status code after the redirects are followed), initialStatus (the first status code that starts the chain), finalUrl, headers, cookies, body and redirects. In this type body is the raw HTML text; the page content is queried with the $htmlQuery and $htmlQueryAll functions.

Examples: $count($htmlQueryAll(body, ".login-error")) = 0, $htmlQuery(body, "#welcome-banner") != null, $contains(finalUrl, "/home").

User Attribute Mapping

INFO

Custom User Attribute Mapping Default: No customisation

How the fields in the provider response are mapped to the session attributes is managed. There is no automatic mapping in this type; No automatic mapping for this provider - every attribute has to be mapped below is written on the information bar to the left of the field and every required attribute is mapped manually in this field.

When the switch on the right is moved to the Customised position, the AGS Attribute and Source Attribute table is displayed: the session attribute (with a suggestion list) is entered in the left column and the JSONata expression in the right column. The expression works on the submitted form and on the page reached after the login; the fields at the root are res.data (the raw HTML), res.finalUrl, res.cookies, res.status, req.form and req.url. The attributes are taken either from a submitted form field (req.form.username) or by scraping from within the HTML: $htmlQuery(res.data, ".user-name"), $htmlQuery(res.data, ".user-meta", "data-mail"), $htmlQueryAll(res.data, "li.group"). When the switch is turned on, the + Add link that adds a row appears on the right of the bar. When a name outside the standard attributes of AGS is entered, this attribute is defined as a custom user field on the vService; names that start with _ are considered hidden fields and do not produce a custom user field.

Lockout Configuration

INFO

Lockout Behavior Default: Use gateway defaults

With which lockout policies the failed attempts on this provider are counted is selected:

Option	Meaning
Use Gateway Defaults	The policies in the Default Lockout Policies list of the vService are used.
Replace Defaults	Only the policies selected in the Lockout Policies field are used.
Add to Defaults	In addition to the default policies of the vService, the ones selected in the Lockout Policies field are used as well.
No Lockout	Failed attempts are not counted on this provider, no lockout is performed.

Lockout Policies

Displayed while Replace Defaults or Add to Defaults is selected; the built-in and defined policies on the Account Lockout Policies screen are selected.

INFO

Add

The profile is added by clicking the Add button; the tab closes and the profile is displayed in the list.