Policy Server Guides › Policy Server Configuration Guide › Authentication Schemes › How to Configure HTML Forms Authentication

How to 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:

• 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.

  Note: 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.

Note: For information about how to configure a web agent to support HTML Forms authentication, see the companion scenario: Configure a Web Agent to Support HTML Forms Authentication.

1. Inform the agent owner that some or all agents must support HTML Forms authentication.
2. Configure HTML Forms authentication template files.
3. Configure an HTML Forms authentication scheme.

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.

More information:

How to Configure a CA SiteMinder® Agent to Support HTML Forms Authentication

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 SiteMinder® uses the English forms authentication template files. For information about configuring localized forms authentication template files, see How to Enable FCC Internationalization.

More information:

Localize Forms-based Authentication and Basic Password Services Files

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

The secure template files 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: webagent\samples\forms
• UNIX: webagent/samples/forms

Note: Localized versions of the secure HTML forms authentication templates are not available; only English language versions are supplied.

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:

• On Apache Web servers, configure your web server to use the extension you want.

  Note: For more information, see the Web Agent Installation Guide.

• On Domino or IIS web servers, specify the extension that you want in the FCCExtensions parameter of your web agent configuration file or object.

  Note: For more information about web agent configuration parameters, see the Web Agent Configuration Guide.

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.

Important! 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.

At a minimum, an .fcc file must collect the following items:

• User name
• Password
• Target

Important! 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.

The following example is a valid (though simple) .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

An FCC can interpret a number of special name/value pairs (@directives) that invoke nonstandard processing. The special @directives and their meanings follow:

username

Name for the login user name.

password

Password to perform the login.

target

Resource to access after login.

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

Specifies the maximum number of login attempts allowed. If you set this directive to 0, the number of retries is unlimited. If you set the number to 1 or greater, that is the number of retries allowed.

Note: 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 valid credentials are entered in the number of attempts that smretries specifies.

smpasswordfcc

Determines whether data is posted from the Password Services FCC file or from a different FCC file.

Default: 1

Important! 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 / 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.

Note: 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 the named variable.

Note: 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.

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.

   Note: 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.

   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.

   Note: Append additional attributes to the @password directive with the ampersand (&) character.

When you add attributes to the template file, consider the following points:

• 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 following string in the Additional Attributes List field:

  AL=PASSWORD,mail

  Note: 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. To provide users with more login attempts, configure the smretries directive (@smretries). Be aware that 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. This pair of .fcc files changes the behavior of the redirect. The login page (DynamicRetry.fcc) is configured to send users to the unauthorized page (DynamicRetry.unauth) after one failed login attempt. The unauthorized page is a different template file than the login file. As a result, the unauthorized page can contain a message stating why the login failed. By default, the unauthorized page is displays a message that informs users that they have entered invalid credentials for the resource they are attempting to access.

Note: You can change this message by opening DynamicRetry.unauth and updating the text in between the h3 tags.

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.

Consider the following limitations when using the DynamicRetry pair of .fcc files:

• You cannot count user login attempts based on the SMTRYNO cookie.
• You cannot limit the number of login attempts.

  Note: You can use this method in combination with Password Services to disable users with a password policy after a specified number of failed attempts. More information about password policies exists in the Password Policies.

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 forms-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.

  Note: 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.

More information:

User Directories

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.

Note: Back-end mapping requires a custom authentication scheme library. If you have installed the software development kit, see the API Reference Guide for C.

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 less 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.

Note: 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.

   Click OK

4. Enter a name and protection level.
5. Select HTML Form Template from the Authentication Scheme Type list.
6. Enter Web Server Name, Target, and Additional Attribute List information.

   Note: Verify that the .fcc file you specify in the Target field complies with the guidelines for this field.

7. 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.