Configure HTML Forms Authentication

The HTML forms authentication schemes authenticate users with credentials that are gathered in a custom HTML form. This flexible means of credential collection allows you to:
sm1252sp1
The HTML forms authentication schemes authenticate users with credentials that are gathered in a custom HTML form. This flexible means of credential collection allows you to:
  • Provide a “branded” look, perhaps including a company logo.
  • Substitute custom labels for collecting the user name and password. For example, if users think in terms of an account number and a PIN rather than a name and password.
  • Provide authentication that is based on credentials other than a user name and password (using user directory attributes). An authentication scheme library on the Policy Server system maps the user data to a DN. By mapping the user to a DN, the Policy Server can match an attribute list to the appropriate values in a user directory. This process is named back-end mapping.
  • Provide authentication that is based on credentials that include user attributes in addition to the user name and password. A custom authentication scheme library is not required for attribute verification. For example, a custom form can be used to collect a name and a secret phrase for users who forget their password.
  • Provide multiple HTML forms for login, logout, and forgotten passwords.
    HTML Forms authentication schemes are supported with multibyte characters.
HTML Forms authentication can be configured to run over a Secure Sockets Layer (SSL) connection, but this is optional.
To configure the Policy Server to use HTML Forms authentication, the policy administrator and agent owner must both perform configuration processes. This scenario describes the process that a policy administrator must follow to configure HTML Forms authentication.
This content describes the following configuration procedures:
2
For information about how to configure a web agent to support HTML Forms authentication, see the companion scenario: How to Configure an Agent to Support HTML Forms Authentication.
 
The following graphic shows how to configure HTML forms authentication.
How to configure HTML Forms authentication
How to configure HTML Forms authentication
Inform the Agent Owner that HTML Forms Authentication is Required
In addition to the steps outlined in this scenario, the agent owner must configure agents to validate identities using the HTML forms authentication scheme.
Inform the agent owner or owners responsible for the agents to configure agents to use the HTML forms authentication scheme.
Configure HTML Forms Authentication Template Files
Web Agents feature a
Forms Credential Collector
(
FCC
) component that handles HTML forms authentication. When a user requests a resource that an HTML forms scheme protects, the Agent redirects the user to a forms authentication template file.
The forms authentication template file invokes the FCC. The FCC then generates a browser page that is based on the contents of the forms authentication template file. The template file resides in the namespace of the web server and is accessed like any HTML file.
Forms authentication template files are written in a simple mark-up language that includes HTML and some custom notation.
The template FCC files are located in the following directories:
  • Windows
    :
    webagent\samples\forms
  • UNIX: webagent/samples/forms
To use these sample forms authentication template files, specify the appropriate target directory when you configure the HTML Forms Authentication scheme.
Agents also provide localized sample forms authentication template files for several other languages. By default,
CA Single Sign-On
uses the English forms authentication template files. For information about configuring localized forms authentication template files, see FCC Internationalization.
Use Secure HTML Forms Authentication Templates
Secure versions of the HTML forms authentication templates are also available. The secure HTML forms authentication templates differ from the standard versions in the following ways:
  • Secure versions do not display the username in returned messages
  • Secure versions include a Logout hyperlink in the top right side corner of the form template which logs out the user and redirects them to the custom logoff page
  • Autocomplete is turned off for all text fields in secure versions
Default secure template files which you can customize are located in the following directories:
  • Windows
    :
    webagent\secureforms
  • UNIX: webagent/secureforms
To use the secure versions of the HTML forms authentication templates, copy the files from the secureforms directory to the following location, replacing the standard versions there:
  • Windows
    : weba
    gent\samples\forms
  • UNIX: webagent/samples/forms
A set of secure forms for the US English (en-US) locale is also available in the following directories:
  • Windows: webagent\secureforms_en-US
  • UNIX: webagent/secureforms_en-US
To use the secure versions of the US English locale forms, copy the files from the secureforms_en-US directory to the following location, replacing the standard versions there:
  • Windows
    : weba
    gent\samples\forms_en-US
  • UNIX: webagent/samples/forms_en-US
Use a Different File Extension for Forms Authentication Template Files
The default extension for forms authentication template files is .fcc. Forms authentication template files are therefore sometimes referred to as .fcc files. However, you can use a different extension.
Follow these steps:
  1. On Apache Web servers, configure your web server to use the extension you want.
  2. On Domino or IIS web servers, specify the extension that you want in the FCCExtensions parameter of your web agent configuration file or object.
Customize Forms Authentication Templates
The Forms authentication template (.fcc) files are written using standard HTML tags and a small amount of proprietary notation that is required to verify attributes and take advantage of custom features.
If you create or edit an .fcc file on a Windows system and move that file to a UNIX system, the file can have newline characters that are incompatible with UNIX systems. Non-UNIX newline characters on a UNIX system cause .fcc files to fail during authentication. When moving files from Windows text editors to UNIX systems, examine the files and remove the appended characters. To avoid this situation, create and edit .fcc files for use in a UNIX environment on a UNIX system.
The first part of the FCC contains directives during a POST operation on the .fcc file. The directives are never passed to the client. They must be at the beginning of the file and are of the form: @name=value.
The name is the name of a variable. The value is the value of the variable. The value can contain strings of the form: %name1%. The FCC replaces this string with the value of the variable that is associated with name1.
The second part of the .fcc file contains HTML code that is returned when a GET operation is performed on the .fcc file. This part can include text in the form "$$name$$", including the quotation marks (") that the FCC replaces with the value that is associated with name. The name is not case-sensitive.
The hidden inputs in the following table hold state for the credential collectors. Include the quotation marks (") with each value.
Name
Dynamic Value
Data preserved
target
"$$target$$"
Resource that a user wants to access
smquerydata
"$$smquerydata$$"
If SecureURLs is enabled, contain the encrypted query parameters in a redirect URL
smauthreason
"$$smauthreason$$"
Reason for a login failure
postpreservationdata
"$$postpreservationdata$$"
Data that a user submits through a post request
smagentname
"$$smagentname$$"
Agent name that is used for logging the user in
At a minimum, an .fcc file must collect the following items:
  • User name
  • Password
  • Target
If a user submits post requests to a resource protected by any of the authentication schemes in the following list, use the postpreservationdata input. Otherwise, data that users attempt to post to the requested resource gets lost.
Schemes
Basic Over SSL Authentication Schemes
HTML Forms Authentication Schemes
X.509 Client Certificate Authentication Schemes
X.509 Client Certificate and Basic Authentication Schemes
X.509 Certificate or Basic Authentication Schemes
X.509 Client Certificate and HTML Forms Authentication Schemes
X.509 Client Certificate or HTML Forms Authentication Schemes
The following example is a valid (though simple) .fcc file:
Sample .fcc file
Sample .fcc file
The previous file is the usermap.fcc sample file that is included with the default installation of the Agents. This .fcc file creates a distinguished name (DN) for the user that is based on the information the user enters in the User Name field and the Organization list of the HTML form. This DN is the user name authentication credential. The user password is collected from the Password field of the HTML form. The hidden realm and target input values are also collected so that the user can be directed to the appropriate resource when authentication is complete.
Special Name Value Pairs for Customizing Forms
An FCC can interpret a number of special name/value pairs (@directives) that invoke nonstandard processing. The special @directives and their meanings follow:
The “sm” prefix for name/value pairs is reserved for additional special names that the system requires. When creating names for your login page do not use the “sm” prefix.
  • username
    Name for the login user name.
  • password
    Password to perform the login.
  • target
    Resource to access after login.
  • smquerydata 
    If the SecureURLs ACO parameter is enabled, contains the encrypted query parameters in a redirect URL. If you are using a custom login.fcc file, add this value in the file in the following format:
    <input type=hidden name=smquerydata value="$$smquerydata$$">
  • smheaders
    Colon separated list of response names to include in the namespace. The colon separated list must contain an entry for each header that you want to include in a transaction. For example, if you want to pass the value of header1 and header2 as part of a transaction, include the following line in your FCC:
    @smheaders=header1:header2
  • smerrorpage
    If there is an error on a POST to the custom form, the user browser is redirected to this page. If this special value is not specified in a .fcc file, the system uses the .unauth file that is associated with the .fcc file as the error page.
  • smretries
    Indicates the number of times a browser can try to log in. This directive acts as a counter; it is not a security mechanism.  If you set this directive to 0, the number of log-in attempts is unlimited. If you set the number to 1 or greater, that indicates the number of log-in retries allowed. After you reach the limit, the browser displays the DynamicRetry.unauth page. This page can display a configured message explaining why the login failed. For smretries to be useful, configure this unauthorized file.
    You can use smretries to improve the user experience, for example:
    • After a failed log-in attempt, you can display a message in the browser instructing the user what action to take.
    • After a specific number is reached, display an invalid login message and redirect the user back to the login page to try again.
      If users log in using a POST to an .fcc form, it appears that the user is given more attempts to log in beyond the value of the smretries directive. However, the user is allowed access only if they enter valid credentials within the number of attempts allowed by smretries.
    If you use the smretries directive in the login.fcc file, the Web Agent updates the SMTRYNO cookie in the browser for each failed login attempt. This cookie tracks the current number of failed login attempts. You can make your login.fcc form intelligent by adding javascript that looks for the SMTRYNO cookie then displays a message in the login screen itself.
  • smpasswordfcc
    Determines whether data is posted from the Password Services FCC file or from a different FCC file.
    Default
    : 1
    Use the default value. The SafeWord authentication scheme works properly as long as you use the default value.
  • smusrmsg
    Text that describes why the user was challenged or failed to log in.
  • smauthreason
    Reason code that is associated with a login failure.
  • smsavecreds
    Set to Yes to save user credentials in a persistent cookie on the user browser.
  • smsave
    Colon separated list of names to be saved as persistent cookies.
  • save
    Another name for smsave.
  • smtransient
    Colon separated list of names to be saved as transient cookies.
  • smagentname
    Specifies the agent name that is supplied to the Policy Server when a user enters credentials and submits the form for authentication. If the Agent parameter, FCCCompatMode=NO, specify a value using this directive.
  • smlogout
    Logs a user out of the system, similar to the LogoffUri parameter. By placing @smlogout=true in your .fcc template, the FCC logs a user out and redirect the user to the target. As such, the @smlogout directive is typically used with the @target directive
    (@target=<yoururlhere>
    ).
  • urlencode(name)
    Replaced by the URL encoded value of the named variable.
    If you expect the additional attributes or the Password to contain special characters (" . & = + ? ; / : @ = , $ %), URL-encode each additional attribute value in the .fcc template file. The template uses US-ASCII encoding.
  • urldecode(name)
    Replaced by the URL decoded value of the named variable.
How Name Value Pairs are Generated in FCC Files
The login.fcc template generates a namespace for use in $$
name
$$ expansions and for use by special name value pairs. If a name is entered more than once the last value wins. Name/value pairs are added to this namespace in the following order:
  1. Name/Values from the query string (on Get only).
  2. The name smtarget is created by copying the value of the target (on Get only).
  3. Name/Values from the post data.
  4. Name/Values from the cookies.
  5. Name/Values from the @ directives (on POST only).
  6. Responses named in the “smheaders” name value pair (on POST only).
Localization Name Value Pairs
The .fcc template files include two localization parameters:
  • smlocale
    Used to determine the language used in the HTML forms that collect user information or display status messages.
    The value that is paired with
    smlocale
    corresponds to part of the name of a localization properties file. The localization properties file contains IDs mapped to text strings in the specified language.
    smlocale
    values have the following format:
    COUNTRY-LANGUAGE
    For example, the value for
    smlocale
    for United States English is:
    SMLOCALE=US-EN
  • smenc
    Contains information that tells the browser what language encoding to use. Changing the default value for this variable overrides the encoding set in the following META tag:
    <meta http-equiv="Content-Type" content="text/html;charset=ISO-8859-1">
Collect Additional Attributes
In addition to the user name and password, you can collect other attributes from users, such as an email address or job title.
Follow these steps:
  1. Specify the attribute or attributes by configuring the HTML forms authentication scheme and the associated .fcc template file.
  2. Configure the HTML forms authentication scheme by specifying new attributes in the Additional Attribute List fields of the Scheme Setup dialog.
    If you expect the additional attributes or the Password to contain special characters (" . & = + ? ; / : @ = , $ %), URL-encode each additional attribute value in the .fcc template file. The template uses US-ASCII encoding.
  3. Modify the .fcc template file to collect additional attributes.
    Add the following line at the beginning of the file:
    @password=PASSWORD=%PASSWORD%&newattr1=%newattr1%&newattr2=%newattr2%
    If the additional attributes have special characters, the line looks like the following sample:
    @password=PASSWORD=%urlencode(PASSWORD)%&newattr1%=%urlencode(newattr1)%&newattr2=%urlencode(newattr2)%
    • newattr1=%newattr1%
      Represents the first additional attribute. The value before the equal sign is the attribute name and the value between the percent sign (%) sign is the attribute value.
    • newattr2=%newattr2%
      Represents the second additional attribute. The value before the equal sign is the attribute name and the value between the percent sign (%) sign is the attribute value.
    The FCC parses the names of the new attributes from the attribute values. Append additional attributes to the @password directive with the ampersand (&) character.
When you add attributes to the template file, note the following conditions:
  • The attribute name, which the %
    attribute_name
    % format identifies, must match the input name entry that you also add to the file. For example, if you add the new attribute address:
    @password=PASSWORD=%PASSWORD%&mail=%address%
    or
    @password=PASSWORD=%urlencode(PASSWORD)%&mail=%urlencode(address)%
    you add a line to the .fcc file similar to the following string:
    <input name="address" type="text">
  • The name of the additional attribute must match the name of the attribute in the user directory. For example, to collect email addresses from an LDAP directory, specify one of the following strings:
    @password=PASSWORD=%PASSWORD%&mail=%address%
    or
    @password=PASSWORD=%urlencode(PASSWORD)%&mail=%urlencode(address)%
    where
    mail
    is the name of the LDAP attribute that stores email addresses.
  • Do not add more spaces after the value you specify for the @password directive. Additional spaces can be interpreted as meaningful characters and can prevent users from being authenticated.
  • The name of the attribute in the HTML forms authentication scheme must match the name of the additional attribute in the .fcc file. For example, to add the attribute mail (from the previous example ) to the authentication scheme, enter the string
    AL=PASSWORD,mail
    in the Additional Attributes List field.
    The additional attribute names are case-sensitive.
Tell Users Why Login Failed
The default behavior of forms-based authentication is to redirect unauthenticated or unauthorized users back to the original login form. The default behavior does not let the software display a message informing users why the login failed.
The Web Agent ships with the
DynamicRetry.fcc
and
DynamicRetry.unauth
files. These two files change how the browser redirects a user after a failed login attempt. After one failed login attempt (the directive smretries=1), the DynamicRetry.fcc page sends users to the unauthorized page, DynamicRetry.unauth. The unauthorized page is
not
an FCC file, so the page can display a message stating why the login failed. By default, the unauthorized page displays a message telling users that they entered invalid credentials for the requested resource. You can change this message by opening DynamicRetry.unauth and updating the text in between the
h3
tags.
You can change the prefix of the retry file names; however, the prefixes must match and the files must be in the same directory. If one file name is changed or the files exist in different directories, the Failed Login page shows a "page not found" error.
To tell users why login failed, specify the target path to the DynamicRetry.fcc file when configuring the authentication scheme. The default path to the DynamicRetry.fcc file is:
agent_home
\samples\forms\DynamicRetry.fcc
agent_home
specifies the Web Agent installation path.
The following limitations exist when using the DynamicRetry pair of files:
  • You cannot count user login attempts based on the SMTRYNO cookie.
  • You cannot limit the number of login attempts.
You can use these two files in combination with Password Services to disable users with a password policy, after a specified number of failed login attempts.
Configure an HTML Forms Authentication Scheme
HTML Forms authentication schemes provide a method for authentication that is based on credentials gathered in a custom HTML form.
You can configure multiple f
orms-based
authentication schemes in the same policy store.
The following steps are required to set up a forms authentication scheme:
  1. Review the HTML Forms scheme prerequisites.
  2. Configure an HTML Forms authentication scheme.
Review the HTML Forms Scheme Prerequisites
Verify that the following prerequisites are met before configuring an HTML Forms authentication scheme:
  • A customized .fcc file resides on a Web Agent server in the cookie domain in which you want to implement HTML Forms authentication. CA provides sample .fcc files under the Samples/Forms subdirectory where you installed your Web Agent.
  • A customized .unauth file resides on the Web Agent server.
    This file is not required if the .fcc file uses the smerrorpage directive.
  • A directory connection exists between the Policy Server and the user directory.
  • The default HTML forms library is installed. This library handles HTML Forms authentication processing:
    • SmAuthHTML.dll on Windows
    • smauthhtml.so on Solaris
    These files are installed automatically when you configure a Web Agent.
  • (Sun Java Systems) If you are using a Sun Java Systems web server, increase the value of the StackSize parameter in the magnus.conf file to a value greater than 131072. Failing to change the value causes the web server to dump its core and restart each time an authentication request is made using forms.
Custom Authentication Scheme Library Writing and Installation
The user name and password data that the FCC collects are passed to the Policy Server, which passes them to the authentication scheme library.
Unless back-end mapping is required, the SmAuthHTML authentication scheme library can be used. SmAuthHTML it is distributed with the Policy Server and already installed on the Policy Server system.
Back-end mapping requires a custom authentication scheme library (included in the the software development kit).
If you write a custom authentication scheme and you want to gather more data than the user name and password, the FCC must pack that data into the user name and password fields. These fields must be fewer than 511 characters long. The custom authentication scheme library must then be able to unpack the data and map it to the user name and password.
The FCC can be installed on the same system as the Policy Server.
Configure an HTML Form Authentication Scheme
You can use an HTML Forms authentication scheme to authenticate users with a custom HTML form.
The following procedure assumes that you are creating an object. You can also copy the properties of an existing object to create an object. For more information, see Duplicate Policy Server Objects.
Follow these steps:
  1. Click Infrastructure, Authentication.
  2. Click Authentication Schemes.
  3. Click Create Authentication Scheme.
    Verify that the Create a new object of type Authentication Scheme is selected.
  4. Click OK. 
  5. Enter a name and protection level.
  6. Select HTML Form Template from the Authentication Scheme Type list.
  7. Enter Web Server Name, Target, and Additional Attribute List information.
    Verify that the .fcc file you specify in the Target field complies with the guidelines for this field.
  8. Click Submit.
    The authentication scheme is saved and can be assigned to a realm.
Enable Non-browser Client Support
You can configure HTML Form schemes that collect Basic credentials (user name and password) using non-browser HTTP clients. These clients can be developed using Perl scripts, C++, and Java programs that communicate using HTTP protocol.
Custom clients must send the basic credentials with the initial request through an HTTP authorization header or the Policy Server does not authenticate the users. If the credentials are not sent through an HTTP authorization header, the Policy Server redirects to the HTML Form scheme without non-browser client support.
Follow these steps:
  1. Open the HTML Form authentication scheme.
  2. Select the Support non-browser clients check box.
  3. Click Submit.
    Non-browser client support is enabled.
Follow these steps:
  1. Click Infrastructure, Authentication.
  2. Click Authentication Schemes.
  3. Click Create Authentication Scheme.
    Verify that the Create a new object of type Authentication Scheme is selected.
  4. Click OK.