Policy Server Guides › Policy Server Configuration Guide › Authentication Schemes › HTML Forms Authentication Schemes › HTML Forms Authentication Templates › SiteMinder FCC Files

SiteMinder FCC Files

The SiteMinder Forms Credential Collector (FCC) incorporated into SiteMinder Web Agents reads template files called .fcc files. The .fcc files are written using standard HTML tags and a small amount of proprietary notation required by SiteMinder to verify attributes and take advantage of custom features described later in this section.

Important! If you create or edit an .fcc file on a Windows system and move that file to a UNIX system, your UNIX system may append ^M at the end of lines of text. These characters, which identify the file as a Windows text file, cause .fcc files to fail during authentication. When moving files from Windows text editors to UNIX systems, be sure to examine the files and remove the appended characters. To avoid this situation, create and edit .fcc files that will be used in a UNIX environment on a UNIX system.

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

When a user requests a resource protected by an HTML Forms scheme, the Web Agent redirects the user to an .fcc file. The .fcc file invokes the FCC on the Web server in order to collect credentials from the user via a customized form. The FCC generates a browser page and builds a user name and password based on the contents of the .fcc file. The file resides in a Web server’s name space and is accessed like any HTML file. The .fcc file may contain two parts. Both parts are optional.

The first part of the FCC contains directives that are used when executing 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 variable’s value. The value may contain strings of the form: %name1%. This will be replaced by the value of the variable 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 may include text in the form "$$name$$", including the quotation marks (") that will be replaced by the value associated with name. The name is not case sensitive.

The hidden inputs listed in the following figure are used to hold state for the credential collectors:

*Be sure to enter the quotation marks (").

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

• User name
• Password
• Target

Important! If users will be submitting post requests to a resource protected by an authentication scheme that uses a credential collector (see the following figure), use the postpreservationdata input. Otherwise, data that users attempt to post to the requested resource will be lost.

The following is an example of a valid (though simple) .fcc file:

The file above is the usermap.fcc sample file included with the default installation of SiteMinder Web Agents.

The .fcc file above creates a distinguished name (DN) for the user based on the information the user enters in the User Name field and the Organization drop-down list of the HTML form. This DN is the user name authentication credential. The user’s 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.

More information:

HTML Forms Authentication Schemes

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

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 may appear that the user is given additional 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! We recommend that you use the default value. The SafeWord authentication scheme may not work properly if the default value is changed.

smusrmsg

Text that describes why the user was challenged / failed to login.

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.

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 username and password, you can collect additional attributes from users, such as an email address or job title.

To collect additional attributes

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 should look 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 is identified by the %attribute_name% format, 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 would add a line to the .fcc file similar to the following:

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

  @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 additional spaces after the value you specify for the @password directive. Additional spaces may be interpreted as meaningful characters and may 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 example above) to the authentication scheme, enter the following in the Additional Attributes List field:

  AL=PASSWORD,mail

  Note: The additional attribute names are case-sensitive.

More information:

HTML Forms Authentication Schemes

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. You can configure the smretries directive (@smretries) to provide users with additional login attempts. However, the default behavior does not let you display a message that informs 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 configured with 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.