FCC Internationalization

This content describes how to configure FCC internationalization. Web Agents (12.51 and later) support internationalization by default and provide the following localized FCC-related content in locale-specific directories:
sm1252sp1
This content describes how to configure FCC internationalization. Web Agents (12.51 and later) support internationalization by default and provide the following localized FCC-related content in locale-specific directories:
  • FCCs for authentication schemes
  • Basic password services files
  • Error response pages
The default internationalization support introduced in 12.51 agents prevents customized FCCs created for agent versions prior to 12.51 from working upon upgrade. If you have upgraded such an agent and want to continue using your customized FCCs, disable agent internationalization by setting the
Localization
ACO parameter. For more information, see Web Agent Installation and Upgrade Considerations.
To configure FCC Internationalization, do the following procedures:
2
Set Preferred Locales
A preferred locale specifies the language in which
CA Single Sign-On
displays HTML pages for login, basic password services, and error responses. You can define multiple preferred locales in the Accept-Language HTTP header format.
textExample: 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 using one or more of the following configuration modes:
  • Using a user agent.
  • Using the Administrative UI.
  • Using the WebAgent.conf file
Set Preferred Locale in the Web Browser
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 this header 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 the 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 SMSERVERLOCALE Response Header Variable in the UI
A policy administrator can use the Administrative UI to set the preferred locales in which the Policy Server serves a request.
To set preferred locales as a 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 in the UI
A policy administrator can use the Administrative UI to set the preferred locales in which the Policy Server serves a request. 
Though the Administrative UI, 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. The default value of the ClientLocalePreferred is no. If you set the value to yes, 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. Navigate to the ClientLocalePreferred parameter.
  7. Modify the parameter value.
  8. 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 Single Sign-On
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
    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.
    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 from agent 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 complete.