Scenarios › FCC Internationalization Scenario › 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 each user must perform for FCC internationalization.

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 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.
4. Navigate to the Agent configuration object of your web agent.
5. Click the name of the Agent Configuration object.
6. Click Modify.
7. Navigate to the Localization parameter, and click the right arrow next to the parameter.

   The Edit Parameter page opens.

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

Set Preferred Locales

You can define multiple preferred locales in the Accept-Language HTTP header format.

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

The locale is dynamically determined 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 Administrative UI.
• Using the WebAgent.conf file

Set Preferred Locale Using a User Agent

A user can configure the web browser settings for the preferred locale. The Policy Server sends a request related to the supported features using the preferred locale.

The user can employ the following methods to set the locale:

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

Use HTTP Header SMCLIENTLOCALE

Use the HTTP header SMCLIENTLOCALE for a web request to set preferred locales. If a web application provides an option to set preferred locales, the user can select a locale. The Policy Server receives the locale using the SMCLIENTLOCALE header in the web request. If the locale is available, pages listing the supported features are displayed in the requested locale.

Use HTTP Header Accept-Language

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

Set the Preferred Locale through the Administrative UI

A policy administrator can use the Administrative UI to set the preferred locales in which the Policy Server serves a request related to the supported features.

Set the SMSERVERLOCALE Response Header Variable

To set preferred locales as the response, use the SMSERVERLOCALE response attribute.

Follow these steps:

1. Log on to the Administrative UI.
2. Click Policies, Domain.
3. Click Responses.
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.
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

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.
4. Navigate to the Agent configuration object of your web agent.
5. Click the name of the Agent Configuration object.
6. Click Modify.

   The settings and controls become active.

7. Navigate to the DefaultLocale parameter, and click the right arrow next to 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

To set the Locale property as an agent owner, configure the WebAgent.conf file. This file 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 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

To determine the order of precedence of the five configuration modes, a policy administrator must set the ClientLocalePreferred ACO parameter. If ClientLocalePreferred parameter is set to true, the system verifies the configuration modes and determines the locale in the following order:

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 the ClientLocalePreferred is set to false, the system verifies the configuration modes and determes the locale in the following order:

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

The Policy Server processes the preferred locales using the defined modes, creates a list of preferred locales. This list is sorted based on the q factor of each preferred locale. When a web request is sent, the list indicates the locale in which the HTML pages of the supported features are displayed.

Set the ClientLocalePreferred parameter to the preferred order of locales.

Follow these steps:

1. Click Infrastructure, Agent.
2. Click Agent Configuration Objects.
3. Navigate to the Agent configuration object of your web agent.
4. Click the name of the Agent Configuration object.
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. By default, sample forms in various locales are provided. These samples are in the directory 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 English, the folder name is samples/forms_en-US, the login.fcc file name is login_en-US.fcc, the WebAgent.properties file name is WebAGent_en-US.properties.

Besides the sample forms folders, a default forms folder is provided. This folder contains files with no locale language code. When the Web Agent receives a request for a locale, the Policy Server verifies whether the requested locale is available against the list of preferred locales. The system then performs one of the following tasks:

• If the requested locale matches a locale in the list, the request is processed in the requested locale.
• If the requested locale does not match a locale in the list, the request is processed using the locale of the default forms folder.

Customize a Folder to Support a New Locale

The default form folder is in en-US. An agent owner must customize the default folder and the files to support a new locale other than en-US.

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. 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. Customize the properties files:
   1. Place a copy of the relevant .properties files from the default forms folder to the new locale folder.
   2. Append each file with the language code for the new 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 the new locale.
7. Save the changes.

Localize Error Response Files

An agent owner can localize error response files. Sample error response files in various locales are provided in the following directory:

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, there is 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, the Policy Server performs one of the following tasks:

• If the locale is available and an error occurs, the error response files are used from the corresponding locale folder to display the error response.
• If the locale is not available and an error occurs, the files in the default error responses folder are used 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 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:

Tthe error response files are stored for the English locale in the ErrorResponseLocation_home/responses_en-US folder. When a cookie error occurs, the cookieerror_en-US.err error response file is retrieved from this 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 from the default responses folder into the new folder.
5. Append each error response file with the language code for the new locale in the following format:

   filename_<locale language code>

6. Modify the files to accommodate the new locale. For example, change the English messages to the language for the new locale.

Configure the Web Agent ACO

To localize the error response files, a policy administrator must configure the agent ACO parameter.

Follow these steps:

1. Log on to the Administrative UI.
2. Click Infrastructure, Agent.
3. Click Agent Configuration Objects.
4. Navigate to the Agent configuration object of your web agent.
5. Click the name of the Agent Configuration object.
6. Click Modify.
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 next to 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 FCC files, basic password services, and error response files in releases earlier than 12.51 are available, an agent owner can migrate them to 12.51 or later releases 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. Create a folder or skip to the next step and rename the existing locale folder. Perform only one of these 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 for 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 the new locale.
   5. Append each file with the language code for your locale in the following format:

      filename_<locale language code>.properties
      

4. (Optional) Rename the existing folder (this step is an alternative to creating a folder.)
   1. Rename the existing folder in the following format:

      forms_<locale language code>
      

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

      filename_<locale language code>.fcc
      

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

      filename_<locale language code>.properties
      

5. In the FCC files, perform the following steps:
   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.
6. 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. To create a folder, perform the following steps. Optionally, skip to the next step to rename the existing folder.
   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. (Optional) To rename the existing folder:
   1. Rename the existing file in the following format:

      responses_<locale language code>
      

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

      filename_<locale language code>
      

FCC Internationalization is now completed.