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

How to Enable FCC Internationalization

CA SiteMinder® supports the following features for FCC internationalization:

• FCC for authentication schemes
• Basic password services
• Error response pages

You can set a preferred locale in which SiteMinder must display HTML pages for login, basic password services, and error responses. To implement the scenario in your organization, the following user roles are required:

• Policy Administrator
• Agent Owner
• SiteMinder User

The following diagram describes the steps that must be performed by each user to support the feature:

Note: In the following diagram, the blue color denotes the tasks of a policy administrator, the green color denotes the tasks of an agent owner, and the black color denotes the tasks of a SiteMinder user.

To enable FCC internationalization, the following steps must be performed:

1. Enable the Localization ACO parameter using the Administrative UI. A policy administrator must perform this task.
2. Select a configuration mode to set preferred locales. This task can be performed in the following ways:
   • Using user agent. A SiteMinder user can use a user agent to set preferred locales in the following ways:
     • Use HTTP Header SMCLIENTLOCALE.
     • Use HTTP Header Accept-Language.
   • Using Administrative UI. A policy administrator can use the Administrative UI to set preferred locales in the following ways:
     • Use the SMSERVERLOCALE response attribute.
     • Use the DefaultLocale ACO parameter.
   • Using the WebAgent.conf file. An agent owner can configure the Locale parameter in the WebAgent.conf file to set preferred locales.
3. Define the order of precedence of the configuration modes. A policy administrator must perform this task using the Administrative UI.
4. Perform one of the following steps:
   • If you want to localize the HTML pages for the first time, an agent owner must perform the following steps:
     1. Localize the forms-based authentication files and basic password services files.
     2. Localize the error responses files.
   • If you want to migrate localized files, an agent owner must perform the following steps:
     1. Migrate the localized forms-based authentication files and basic password services files.
     2. Migrate the localized error responses files.

   CA SiteMinder® is configured to enable FCC internationalization.

Enable the Localization Parameter

A policy administrator must set the value of the Localization ACO parameter to true to localize the supported features.

Follow these steps:

1. Log on to the Administrative UI.
2. Click Infrastructure, Agent.
3. Click Agent Configuration Objects.

   The Agent Configuration Objects page opens.

4. Navigate to the Agent configuration object of your web agent.
5. Click the name of the Agent Configuration object.

   The View Agent Configuration page opens.

6. Click Modify.

   The settings and controls become active.

7. Navigate to the Localization parameter, and click the right arrow to the left of the parameter.

   The Edit Parameter page opens.

8. Set the value of the parameter to yes.
9. Save the change.

Set Preferred Locales

CA SiteMinder® lets you define multiple preferred locales in the Accept-Language HTTP header format.

Example: ja-JP,en-US;q=0.8,as-IN;q=0.6,fr-FR;q=0.4,en-IN;q=0.2

CA SiteMinder® dynamically determines the locale during run time but the locale can be changed while processing a request. For example, the locale can change after a successful authentication.

Define preferred locales in the following configuration modes:

• Using a user agent
• Using the Administrative UI
• Using the WebAgent.conf file

Set Preferred Locale Using a User Agent

A SiteMinder user can configure the web browser settings to set the preferred locale in which SiteMinder must serve a request related to the supported features. The SiteMinder user can use the following methods to set the locale:

• Use the HTTP header SMCLIENTLOCALE
• Use the HTTP header Accept-Language

Use HTTP Header SMCLIENTLOCALE

A SiteMinder user can use the HTTP header SMCLIENTLOCALE of a web request to set preferred locales. If a web application provides an option to set preferred locales, the SiteMinder user can select a locale. CA SiteMinder® receives the locale using the SMCLIENTLOCALE header in the web request. If the locale is available, CA SiteMinder® displays the pages of the supported features in the requested locale.

Use HTTP Header Accept-Language

A SiteMinder user can set preferred locales using the local web browser settings. The HTTP header Accept-Language of a web request specifies the locales.

Set Preferred Locale using the Administrative UI

A policy administrator can use the Administrative UI to set the preferred locales in which SiteMinder must serve a request related to the supported features.

Set the SMSERVERLOCALE Response Header Variable

A policy administrator can use the SMSERVERLOCALE response attribute that is based on the WebAgent-HTTP-Header variable attribute type to set preferred locales as the SiteMinder response.

Follow these steps:

1. Log on to the Administrative UI.
2. Click Policies, Domain.
3. Click Responses.

   The Responses page appears.

4. Edit a response that you want to modify.
5. Click the Define Response tab.
6. Edit the Response Attribute that you want to modify.

   The View Response Attribute page appears.

7. Select the Attribute Type as WebAgent-HTTP-Header Variable.
8. Type SMSERVERLOCALE in Variable Name.
9. Type the preferred locales in Variable Value.
10. Save the changes.

Set the DefaultLocale ACO Property

A policy administrator can set the preferred locales information in the DefaultLocale ACO parameter.

Follow these steps:

1. Log on to the Administrative UI.
2. Click Infrastructure, Agent.
3. Click Agent Configuration Objects.

   The Agent Configuration Objects page opens.

4. Navigate to the Agent configuration object of your web agent.
5. Click the name of the Agent Configuration object.

   The View Agent Configuration page opens.

6. Click Modify.

   The settings and controls become active.

7. Navigate to the DefaultLocale parameter, and click the right arrow to the left of the parameter.

   The Edit Parameter page opens.

8. Update the property with preferred locales.
9. Save the change.

Set Preferred Locale Using the WebAgent.conf File

An agent owner must configure the WebAgent.conf file to set the Locale property, which contains the locale information that is specified during the installation.

Follow these steps:

1. Log on to the web agent machine.
2. Open the WebAgent.conf file of your web agent with a text editor.
3. Navigate to the Locale property, and set the value to the preferred locales.
4. Save the changes.

Define the Configuration Modes Order of Precedence

A policy administrator must set the ClientLocalePreferred ACO parameter to determine the order of precedence of the five configuration modes. If this value is set to true, CA SiteMinder® verifies the configuration modes for determining the locale in the following order of precedence:

1. HTTP header SMCLIENTLOCALE
2. HTTP header Accept-Language
3. Response header variable SMSERVERLOCALE
4. The DefaultLocale ACO parameter
5. The Locale property in the WebAgent.conf file

If this value is set to false, CA SiteMinder® verifies the configuration modes for determining the locale in the following order of precedence:

1. Response header variable SMSERVERLOCALE
2. HTTP header SMCLIENTLOCALE
3. HTTP header Accept-Language
4. The DefaultLocale ACO parameter
5. The Locale property in the WebAgent.conf file

CA SiteMinder® processes the preferred locales defined using the five configuration modes, and creates a list of preferred locales that is sorted based on the q factor of each preferred locale. When a web request is sent, CA SiteMinder® uses the list of preferred locales to determine the locale in which the HTML pages of the supported features must be displayed.

Follow these steps:

1. Click Infrastructure, Agent.
2. Click Agent Configuration Objects.

   The Agent Configuration Objects page opens.

3. Navigate to the Agent configuration object of your web agent.
4. Click the name of the Agent Configuration object.

   The View Agent Configuration page opens.

5. Click Modify.
6. The settings and controls become active.
7. Navigate to the ClientLocalePreferred parameter.

   The Edit Parameter page opens.

8. Modify the parameter value.
9. Save the change.

Localize Forms-based Authentication and Basic Password Services Files

An agent owner can localize the forms-based authentication and basic password services files displayed by CA SiteMinder®. By default, CA SiteMinder® provides sample forms in various locales in the following location of the web agent:

webagent_home/samples

Each locale has a folder for the locale-specific files. Each folder and file is appended with a locale language code that conforms to the RFC 3066 standard of naming convention of the following format:

forms_<locale language code>

forms_<locale language code>/filename_<locale language code>.fcc

For example:

For Japanese, the folder name is samples/forms_ja-JP, the login.fcc file name is login_ja-JP.fcc, the WebAgent.properties file name is WebAGent_ja-JP.properties.

Besides the sample forms folders, CA SiteMinder® also provides a default forms folder that contains files with no locale language code. When the Web Agent receives a request for a locale, CA SiteMinder® processes the locale in the list of preferred locales to verify if the requested locale is available and performs one of the following tasks:

• If the requested locale matches a locale in the preferred locales list, CA SiteMinder® processes the request in the requested locale.
• If the requested locale does not match the preferred locales list, CA SiteMinder® uses the locale of the default forms folder to process the request.

Customize CA SiteMinder® to Support a New Locale

By default, the default form folder is in en-US. An agent owner must customize the default folder and the files to support a new locale that is not provided by CA SiteMinder® by default.

Follow these steps:

1. Log on to the Web Agent machine.
2. Navigate to the following location:

   webagent_home/samples
   

3. Create a folder for the new locale in the following format:

   forms_<locale language code>
   

4. Perform the following steps to customize .fcc files:
   1. Place a copy of the relevant FCC files from the default forms folder to the new folder.
   2. Append each FCC file with the language code of your locale in the following format:

      filename_<locale language code>.fcc
      

5. Perform the following steps to customize .properties files:
   1. Place a copy of the relevant .properties files from the default forms folder to the forms folder of your locale.
   2. Append each file with the language code your locale in the following format:

      filename_<locale language code>.properties
      

6. Modify the files to accommodate the locale, such as changing the English messages to the language of your locale.
7. Save the changes.

Localize Error Response Files

An agent owner can localize error response files displayed by CA SiteMinder®. By default, CA SiteMinder® provides sample error response in various locales in the following location:

webagent_home/samples/error-responses

Each locale has a folder for the locale-specific files. Each folder and file is appended with a locale language code that conforms to the RFC 3066 standard of naming convention of the following format:

responses_<locale language code>
filename_<locale language code>.err

Besides the sample error response folders, CA SiteMinder® also provides a default error responses folder and files that do not contain a locale language code. When the Web Agent receives a request in a locale, CA SiteMinder® performs one of the following tasks:

• If the locale is available and an error occurs, CA SiteMinder® uses the error response files from the corresponding locale folder to display the error response.
• If the locale is not available and an error occurs, CA SiteMinder® uses the files in the default error responses folder to display the error response.

Customize CA SiteMinder® to Support a New Locale

Customize the default folder and the files to support a new locale that is not provided by CA SiteMinder® by default.

The following error responses files can be customized to suit your preferred locale:

• csserror.err generated for the CSS errors
• servererror.err generated for the server errors
• cookieerror.err generated for the cookie errors
• custom401error.err generated for the authentication and authorization errors

When an error occurs, the error page is retrieved from the following location:

ErrorResponseLocation_home/responses_<locale language code>

Example:

CA SiteMinder® stores the error response files for the Japanese locale in the ErrorResponseLocation_home /responses_ja-JP folder. When a cookie error occurs, the cookierror_ja-JP.err error response file is retrieved from the ErrorResponseLocation_home/responses_ja-JP folder.

To customize the error responses, perform the following steps:

1. Configure the Web Agent.
2. Configure the Web Agent ACO.

Configure the Web Agent

An agent owner must configure the web agent to localize the error response files.

Follow these steps:

1. Log on to the Web Agent machine.
2. Navigate to the following location:

   webagent_home/samples/error-responses
   

3. Create a folder for the new locale in the following format:

   responses_<locale language code>
   

4. Place a copy of the response files in the new folder from the default responses folder.
5. Append each error response file with the language code your locale in the following format:

   filename_<locale language code>
   

6. Modify the files to accommodate the locale, such as changing the English messages to the language for your locale.

Configure the Web Agent ACO

A policy administrator must configure the ACO parameter of the Web Agent to localize the error response files.

Follow these steps:

1. Log on to the Administrative UI.
2. Click Infrastructure, Agent.
3. Click Agent Configuration Objects.

   The Agent Configuration Objects page appears.

4. Navigate to the Agent configuration object of your web agent.
5. Click the name of the Agent Configuration object.

   The View Agent Configuration page appears.

6. Click Modify.

   The settings and controls become active.

7. Ensure that the value of the following parameters is set to no:
   • servererrorfile
   • csserrorfile
   • reqcookieerrorfile
   • custom401errorfile

   Note: These properties have higher precedence over the ErrorResponseLocation parameter. To localize the error response files, ensure that these properties are disabled.

8. Navigate to the ErrorResponseLocation parameter, and click the right arrow to the left of the parameter.

   The Edit Parameter page appears.

9. Type the new path of the error response files.

   Note: The value of the ErrorResponseLocation property must not be a URL.

10. Save the changes.

Migrate Localized Files

If localized files of FCC, basic password services, and error responses in releases earlier to SiteMinder 12.51 are available, an agent owner can migrate them to SiteMinder 12.51 or later to reuse the files.

Migrate the Forms-based Authentication Files and Basic Password Services Files

An agent owner can migrate forms-based authentication files and basic password services files.

Follow these steps:

1. Log on to the Web Agent machine.
2. Navigate to the location where the localized files exist.

   Default Path: webagent_home/samples

3. Perform one of the following steps:
   • If you want to create a folder in the location, perform the following steps:
     1. Create a folder in the following format:

        forms_<locale language code>
        

     2. Place a copy of the existing localized FCC files to the new folder.
     3. Append each file with the language code your locale in the following format:

        filename_<locale language code>.fcc
        

     4. Place a copy of the relevant .properties files from the existing folder to the forms folder of your locale.
     5. Append each file with the language code your locale in the following format:

        filename_<locale language code>.properties
        

   • If you want to rename the existing folder in the location, perform the following steps:
     1. Rename the existing folder in the following format:

        forms_<locale language code>
        

     2. Rename each file with the language code your locale in the following format:

        filename_<locale language code>.fcc
        

     3. Rename each file with the language code your locale in the following format:

        filename_<locale language code>.properties
        

4. Perform the following steps in the FCC files:
   1. Replace the hard coded encoding parameters with the $$SMENC$$ tag.

      Examples:

      • <meta http-equiv="Content-Type" content="text/html;charset=$$SMENC$$">
      • <INPUT TYPE=HIDDEN NAME="SMENC" VALUE="$$SMENC$$">
   2. The first line of each file must have the name of the charset that is used for encoding the form. Example: <!-- SiteMinder Encoding=UTF-8; -->, where UTF-8 is used for encoding the form.
5. Save the changes.

Migrate the Error Responses Files

An agent owner can migrate the localized error responses files.

Follow these steps:

1. Log on to the Web Agent machine.
2. Navigate to the location where the localized files exist.

   Default Path: webagent_home/samples/error-responses

3. If you want to create a folder, perform the following steps:
   1. Create a folder in the following format:

      responses_<locale language code>
      

   2. Place a copy of the existing localized error response files to the new folder.
   3. Append each file with the language code your locale in the following format:

      filename_<locale language code>
      

4. If you want to rename the existing folder, perform the following steps:
   1. Rename the existing file in the following format:

      responses_<locale language code>
      

   2. Rename each file with the language code your locale in the following format:

      filename_<locale language code>
      

   CA SiteMinder® is configured to enable FCC Internationalization.