Policy Server Guides › Policy Server Configuration Guide › Authentication Schemes › HTML Forms Authentication Schemes

HTML Forms Authentication Schemes

HTML Forms authentication schemes provide a method for authentication based on credentials 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 user name and password collection (for example, if users think in terms of an account number and a PIN rather than a name and password).
• Provide authentication based on credentials other than a user name and password (via user directory attributes). In this case, an authentication scheme library on the Policy Server machine maps the user’s 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 called back-end mapping.
• Provide authentication based on credentials that include user attributes in addition to the user name and password. This is considered additional attribute verification. A custom authentication scheme library is not required for additional 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, forgotten passwords, etc.

  Note: HTML Forms authentication schemes are supported with multi-byte characters.

Multiple Forms-based Authentication Schemes can be configured in a Policy Server installation. Each scheme consists of the following components:

Forms Credential Collector (FCC)

The FCC process files are composed in a simple mark-up language that includes HTML and some custom notation.

Each HTML Forms scheme must have its own .fcc file. This file contains the custom form definition and additional information that the FCC uses to process HTML Forms authentication. The FCC extracts credentials that a user enters in the custom form generated from the .fcc file.

For the HTML Forms authentication scheme, the default extension for .fcc files is .fcc. If you want to use a different extension:

• For Apache or iPlanet Web servers, configure your Web server to use that extension.
• For Domino or IIS Web servers, specify that extension in the FCCExtensions parameter of your Web Agent configuration file or object. For more information on Web Agent configuration parameters, see the Web Agent Configuration Guide.

.unauth file

SiteMinder displays the contents of this file to users who exceed the maximum number of failed authentication attempts specified by the authentication scheme. A .unauth file should exist for each .fcc file. For example, if you have a login.fcc file on a Web server, you should also have a login.unauth file in the same location.

If an smerrorpage variable has been defined in the .fcc file, the .unauth file is not required.

Authentication Scheme Library

This is a shared library that runs on the Policy Server machine and performs authentications.

The previous diagram describes the process for HTML Forms authentication.

1. A user requests a resource contained in a realm protected by HTML Forms authentication.
2. The Web Agent contacts the Policy Server and determines that the user’s request must be redirected to the credential collector.
3. The Web Agent redirects the request to the URL of the credential collectorfile.
4. The credential collector displays the form described in the .fcc file in the user’s browser.
5. The user fills out the custom form and Posts (submits) the form. The credential collector processes the credentials.
6. The credential collector (FCC) logs the user into the Policy Server. The Policy Server returns user session data to the credential collector.
7. If the user is authenticated, the credential collector creates a session cookie, passes the session cookie to the browser and redirects the user to the resource that he or she originally requested.
8. The user uses the session cookie to authenticate. Then, the Web Agent handles user authorization.

More information:

SiteMinder FCC Files

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:

SiteMinder FCC Files

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 have written a custom Authentication Scheme and you want to gather more data than the username and password, the FCC should pack that data into the username and password fields (each of which 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.