UI Fields and Controls for Configuring Connectors

The
PAM
 UI must be able to render the tabs and input controls for the target application and account. The UI fields and controls are defined in a JSON file named uiDefinitions.json. When an administrator selects a custom connector, the appliance contacts the TCF. The TCF then returns the JSON payload to the appliance and the UI. The UI displays the tabs and settings that are defined in the JSON file.
capam33
The
PAM
 UI must be able to render the tabs and input controls for the target application and account. The UI fields and controls are defined in a JSON file named
uiDefinitions.json
. When an administrator selects a custom connector, the appliance contacts the TCF. The TCF then returns the JSON payload to the appliance and the UI. The UI displays the tabs and settings that are defined in the JSON file.
This topic provides reference information that describes the uiDefinitions.json file. The contents of this file determines how UI panels and controls for your custom target connector are displayed. When you are ready to build a custom target connector, modify the uiDefinitions.json file and then validate your changes with the UI validator utility. These tasks are explained in the topic Build Your Custom Connector.
2
Structure of the uiDefinitions.json File
The uiDefinitions.json file is organized into three main sections:
  • account 
     
    specifies the target account at the appliance
    A single "account" attribute definition that contains a single child "uiDefinition" attribute are required.
  • application
     
    specifies the target application at the applianceA single "application" attribute definition that contains a single child "uiDefinition" attribute are required.
  • locale
     
    specifies the language of the field labels when the UI controls are shown in different languages. See Define the Locale for UI Field Labels later in this topic.
Account and Applications Sections
The account and applications sections can include one or more tabbed panels. Each panel can contain groups of related target application or target account attributes. For example, the uiDefinitions.json file for the Example Target Connector contains an "application" section. This section defines a panel with an
Example - Application
tab and a series of fields that define the UI controls. The controls identify details about the connector. The JSON file also has an "account" section with a tab
Example - Account, 
a description field and a target account drop-down list. 
The JSON file must include an "account" and "application" section.
The following two panels are rendered by the uiDefinitions.json file that follows the panels.
example_account.png    example_target_app.png
{
  "account": {                                                                
      "uiDefinition": {
          "tabs": [{
             "id": "ExampleAccDetail",
             "label": "Example - Account",
             "fields": [{
                 "type": "TEXT",
                 "field": "description",
                 "label": "Description",
                 "maxLength": 60
             },{
                 "type": "TARGETACCOUNT",
                 "field":"anotherAccount",
                 "label": "Master Account"
                 }]
           }]
      }
},
  "application": {
      "uiDefinition": {
           "tabs": [{
              "id": "ExampleAppDetail",
              "label": "Example - Application",
              "fields": [{
                  "type": "NUMBER",
                  "field": "connectTimeout",
                  "label": "Connect Timeout",
                  "minValue": 1,
                  "value": 60000
              }, {
                  "type": "NUMBER",
                  "field": "readTimeout",
                  "label": "Read Timeout",
                  "minValue": 1,
                  "value": 5000
             }, {
                  "type": "NUMBER",
                  "field": "sshPort",
                  "label": "SSH Port",
                  "minValue": 0,
                  "maxValue": 65535,
                  "value": 22
             }, {
                  "type": "RADIO",
                  "field": "connector_protocol",
                  "label": "Connector Protocol",
                  "value": "TLS_1.2",
                  "values": [{
                       "label": "TLS 1.0",
                       "value": "TLS_1"
                  },{
                       "label": "TLS 1.2",
                       "value": "TLS_1.2"
                  },{
                       "label": "TLS 1.3",
                       "value": "TLS_1.3"
                  }]
            }, {
                 "type": "COMBOBOX",
                 "field": "additionalEncryption",
                 "label": "Additional Encryption",
                 "value": "AES",
                 "values": [{
                      "label": "Triple DES",
                      "value": "TRIPLEDES"
                 }, {
                      "label": "RSA",
                      "value": "RSA"
                 }, {
                      "label": "Blowfish",
                      "value": "BLOWFISH"
                 }, {
                      "label": "Twofish",
                      "value": "TWOFISH"
                 }, {
                      "label": "AES",
                      "value": "AES"
                 }]
           }, {
                "type": "CHECKBOX",
                "field": "useCertificate",
                "label": "Use Certificate",
                "value": false
           }, {
                "type": "TEXTAREA",
                "field": "certificate",
                "label": "Certificate"
               }]
            }]
        }
    }
}
How the Web Service Java Code Uses the UI Definitions
The "account" and "application" sections of the uiDefinitions.json file have a "uiDefinitions" attribute with a single "tabs" attribute. The tabs attribute allows you to define high-level tabs to group related fields together. Each tab contains a "fields" section, which defines all the individual configurable settings and controls for all connector-relevant data. Under the "fields" section are the individual connector-specific attributes, one of which is named "field". 
The "field" attribute is used in the following ways:
  • Each field serves as a unique identifier that allows the TCF to access data values.
  • For all field attributes in the uiDefinitions.json file, validation of field values occurs automatically based on the definitions file. To execute any custom validation, such as cross-field validation for fields dependent on one another, you must add validation logic to the 
    Validations.java
     file. In the topic Build Your Custom Connector, see the section, "Edit Web Service Endpoints" for instructions about adding validation logic.
  • If you remove a field from the uiDefinitions.json file, edit your Java code so it no longer references the field. This instruction applies to the Credentials.java file and the Validations.java file.
  • All field values are defined as strings in the JSON payload. You might need to do some data type conversions in your Java code.
The remainder of this topic describes the different attributes and constraints for each field type.
UI Tabs and Controls for Target Applications and Accounts
The following table describes the characteristics of the UI tabs and controls for the custom target connector-specific settings that you see in
PAM
UI. Specific details for each type are described later in this topic.
Attribute
Description
type
(Required) Identifies the kind of field and the type of data value entry and validation options are allowed.
Options:
  • TEXT – plain text entries for fields like user names
  • TEXTAREA – displays a block of text, such as a certificate
  • NUMBER – for integer data, such as port numbers
  • PASSWORD – for passwords that are entered in plain text that are masked in the UI.
  • CHECKBOX – provides a selectable box next to each option so a user can make a binary true or false choice.
  • COMBOBOX – provides a drop-down list for selecting only one of a predefined set of mutually exclusive options
  • RADIO – provides a radio button for selecting only one of a predefined set of mutually exclusive options
  • TARGETACCOUNT – provides a drop-down list of configured target accounts from which to select an account.
field
(Required) Unique identifier for referencing the field and accessing data values. Identifiers must be unique for the defined target application or account. Every identifier must begin with a letter or underscore, followed by one or more letters, underscores or digits. You can follow an initial underscore with another underscore. Valid entries for this attribute are case-sensitive. A field value cannot contain embedded spaces.
label
(Required) Labels the control, such as the field name, the radio button label, or the checkbox label. If the value of the label is an identifier from the "locale" section of the file, the language-specific string is used. If a locale identifier is not specified, the literal string value is used. For more details, see Define the Locale for UI Field Labels later in this topic.
value
(Optional) Designates the initial default value for new records.
values
(Required) An array of objects which contain a label and a value. This attribute is used by the RADIO and COMBOBOX attribute types.
Constraints for Specific Field Types
For many of the attribute types, you can specify certain constraints for the field values. Pattern constraints let you require and restrict what values can be entered by the user. If the value provided does not meet the constraints, the UI displays a message with the valid entry criteria.
The following table lists the constraints that are allowed in the uiDefinitions.json file:
Constraint
Description
Used by Field Type
required
(Optional) Specifies whether a field value must be provided. A red asterisk displays next to the field label, indicating the field required.
Valid entries:
  • false (default value). The field value is not required
  • true. The field value is required for basic field validation
TEXT, TEXTAREA, PASSWORD, NUMBER, TARGETACCOUNT
maxLength
(Optional) Maximum length for the field value
TEXT, TEXTAREA, PASSWORD
minLength
(Optional) Minimum length for the field value
TEXT, TEXTAREA, PASSWORD
minValue
(Optional) Minimum field value allowed
NUMBER 
maxValue
(Optional) Maximum field value allowed
NUMBER 
patternConstraint
(Optional) Specifies a regular expression that the connector tests against the field value during validation. If the test fails, the UI marks the field invalid when the user enters or saves the invalid entry.
TEXT, TEXTAREA, PASSWORD
patternConstraintMessage
(Optional) Contains the error message that the connector displays when a patternConstraint is used and the validation test fails. By default, this attribute is set to: "
The value in this field is invalid"
TEXT, TEXTAREA, PASSWORD
Examples of pattern constraints: 
"patternConstraint": "^(today|tomorrow|yesterday)$"
"patternConstraintMessage": "Enter today, tomorrow or yesterday"
"patternConstraint": "^(?:(25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])(\.(?!$)|$)){4}$"
"patternConstraintMessage": "Enter a valid IPV4 address 12.22.111.132" 
"patternConstraint" = "^\\(?([0-9]{3})\\)?[-. ]?([0-9]{3})[-. ]?([0-9]{4})$";
"patternConstraintMessage" = 'Enter a valid phone number 555-555-5555 or (555)555-5555";
"patternConstraint": "^(5[0-9]{3,4}|[1-4]\d{3,4}|[6-9]\d{3})?$"
"patternConstraintMessage": - "Enter integer in the range [5000..59999]"
To see pattern constraint examples within a JSON file, go to Create a TEXT, TEXTAREA, and PASSWORD Attributes.
Review UI Definitions using an Example JSON File
To show how the UI definitions render the UI panels, examine the JSON file for the Example Target Connector. One "application" section and one "account"  section are in the file. 
To explain each attribute type, this topic uses the
Example - Application
panel. However, all the UI definition guidelines apply to the "account" and the "application" sections of the file.
On the Application tab, there is an
Application Type
 field. When you select the Example Target Connector for the application type, the 
Example - Application
tab becomes available.
The following screen image shows the 
Example - Application 
tab:
example_target_app.png
How to define the tabs and fields is described in these topics:
Define Required uiDefinition and Tabs Attributes
Each application and accounts section requires a "uiDefinitions" attribute followed by a single "tabs" attribute. These attributes designate the following information:
  • uiDefinition - For each application and account section, this attribute is the parent for the "tabs" definition.
  • tabs - This section lists an array of tab objects that contain the tab identifier, label, and corresponding "fields" displayed on each tab.  This attribute lets you define high-level tabs to group related fields.
The following code example shows these two sections:
"application": {
    "uiDefinition": {
       "tabs": [{
         "id": "ExampleAppDetail",
         "label": "Example - Application",
         "fields": [{...}]
Define Custom Connector Tabs
A tab contains all the target application or target account attributes for your target connector. To group related attributes, create one or more tabs as needed.
The following graphic shows the Example - Application tab.
two_custom_tabs.png
Each tab must have the following attributes:
Attribute
Description
id 
Unique identifier for the tab. This identifier must be unique on the UI panel where the tab is rendered. Every identifier must begin with a letter or underscore, followed by one or more letters, underscores or digits. You can follow an initial underscore with another underscore. Valid identifiers are case-sensitive. Tab identifiers cannot contain embedded spaces.
label
The text on the tab itself, such as Example - Application, which is shown in the previous graphic. If the value of the label is an identifier from the "locale" section of the file, the language-specific string is used. If a locale identifier is not specified, the literal string value is used. For more details, see Define the Locale for UI Field Labels later in this topic.
fields
Specifies an array of field objects to display on the tab panel.
To add a target application tab that is labeled Example - Application, use the following JSON syntax:
"application": {
    "uiDefinition": {
       "tabs": [{
         "id": "ExampleAppDetail",
         "label": "Example - Application",
         "fields": [{...}]
To add the two tabs, 
Example - Application
and
User Information
, use the following JSON syntax:
"application": {
    "uiDefinition": {
       
"tabs": [{
          "id": "ExampleAppDetail",
          "label": "Example - Application",
          "fields": [{
              "type": "NUMBER",
              "field": "connectTimeout",
              "label": "Connect Timeout",
              "required": false,
              "minValue": 1,
              "value": 60000
              }]
          }, {
           
"id": "ExampleAppUserInfo",
           "label": "User Information",
           "fields": [{
               "type": "TEXT",
               "field": "firstName",
               "label": "First Name",
               "required": true
            }, {
                "type": "TEXT",
                "field": "lastName",
                "label": "Last Name",
                "required": true
            }, {
                "type": "NUMBER",
                "field": "age",
                "label": "Age",
                "required": false,
                "minValue": 1,
                "value": 1
                }]
          }]
       } 
    }
Create a Number Field
To display fields that require numerical entries, such as ports, timeouts, add a
NUMBER
 field type. You can restrict NUMBER fields by specifying a minimum ("minValue") or maximum ("maxValue") constraint.
The following JSON syntax creates the Connect Timeout, Read Timeout, and SSH Port fields in the Example - Application panel. Based on the JSON, this panel includes initial default values for each field. The example shows how to provide minimum and maximum restrictions on the specified values. Also, the example has the "required" attribute set to true, which indicates that you must specify a value. You cannot leave the attribute blank.
 "fields": [{
           "type": "NUMBER",
           "field": "connectTimeout",
           "label": "Connect Timeout",
           "required": true,
           "minValue": 1,
           "value": 60000
      }, {
           "type": "NUMBER",
           "field": "readTimeout",
           "label": "Read Timeout",
           "required": true,
           "minValue": 1,
           "value": 5000
      }, {
           "type": "NUMBER",
           "field": "sshPort",
           "label": "SSH Port",
           "required": true,
           "minValue": 0,
           "maxValue": 65535,
           "value": 22
           }]
Create a Text, Text Area, and Password Attributes
The following excerpt shows the definition for the following field types:
  • TEXT: A field that requires text.
  • TEXTAREA: A field that can accommodate a large amount of text.
  • PASSWORD: A field for a user password. 
The TEXT type use pattern constraints. The TEXT type sets the
required
attribute to true, indicating that the field cannot be left blank. The TEXTAREA does not have any pattern constraints.
{                                                                                                              
  "type": "TEXT",
  "field": "userName",
  "label": "User Name",
  "required": true,
  "minLength": 1,                       
  "maxLength": 200                           
},{
    "type": "TEXT",
    "field": "admin",
    "label": "Administrator",
    "required": true,
    "maxLength": 16,
    "patternConstraint": "^[A-Za-z0-9]+$",
    "patternConstraintMessage": "Administrator name consists of letters and numbers only",
    "value": "admin"
},{                                                                                                               
    "type": "TEXTAREA", 
    "field": "certificate",
    "label": "Certificate"
},{                                                                                                              
    "type": "TEXT",
    "field": "occurance",
    "label": "Activity from",                  
    "patternConstraint": "^(today|tomorrow|yesterday)$",
    "patternConstraintMessage": "Enter today, tomorrow or yesterday"
},{                                                                                                               
    "type": "PASSWORD",
    "field": "user_password",
    "label": "User Password"                       
}                       
Display a Field with Radio Buttons
The 
RADIO
 attribute type displays a control for selecting only one option from a set of a predefined and mutually exclusive option. The
RADIO
 type is recommended for a configuration setting with only a few options. The
RADIO
type requires a "
values
" attribute followed by two or more unique "
label
" and "
value
" options for the control.
The following JSON syntax creates the Connector Protocol setting with three options: TLS 1.0, 1.2. and 1.3. When you create a Target Application or Account, the TLS 1.2 option is set by default. If no initial value is specified, the first option, in this example TLS 1.0, is selected by default.
{
      "type": "RADIO",
      "field": "connector_protocol",
      "label": "Connector Protocol",
      "value": "TLS_1.2",
      "values": [{
            "label": "TLS 1.0",
            "value": "TLS_1"
       },{
            "label": "TLS 1.2",
            "value": "TLS_1.2"
       },{
            "label": "TLS 1.3",
            "value": "TLS_1.3"
       }]
 }
Use a Checkbox to Select an Option
To display a field with a checkbox for a true or false choice, use the CHECKBOX parameter type. 
The following JSON syntax creates the Use Certificate field in the Example - Application panel. By default, this panel has the option set to true (selected) by default. If no initial value is provided, the control is false (not selected).
{
 "type": "CHECKBOX",
 "field": "certificate",
 "label": "Use Certificate",
 "value": true
}
Create a Field with a Drop-down List of Values
To display a field with values selectable from a drop-down list, add a COMBOBOX parameter type. 
The following JSON syntax creates the Additional Encryption field in the Example - Application panel. When creating a target application or account, this example shows AES set as the default value. If no initial value is specified, the first item, in this example Triple DES, is selected by default.
{
   "type": "COMBOBOX",
   "field": "additionalEncryption",
   "label": "Additional Encryption",
   "value": "AES",
   "values": [{
     "label": "Triple DES",
     "value": "TRIPLEDES"
  }, {
     "label": "RSA",
     "value": "RSA"
  }, {
     "label": "Blowfish",
     "value": "BLOWFISH"
  }, {
     "label": "Twofish",
     "value": "TWOFISH"
  }, {
     "label": "AES",
     "value": "AES"
   }]
}
Create a Target Account Selection Field
To create a field where a user can select a target account, use the TARGETACCOUNT field type. This field displays a field with a drop-down list from which to select an account. The field also lets a user search and select a target account. In the following example, on the Example - Account panel, there are two fields, one labeled Description and the other field labeled Master Account.
"fields": [{
            "type": "TEXT",
            "field": "description",
            "label": "Description",
            "maxLength": 60
           },{
            "type": "TARGETACCOUNT",
            "field":"anotherAccount",
            "label": "Master Account"
           }]
Define the Locale for UI Field Labels
To localize how field labels display in a web browser, add a
locale 
section to the uiDefinitions.json file. The locale attribute interacts only with the browser locale. The only supported locale values are 
en
 (English) and 
ja
 (Japanese).
Guidelines for the locale section:
  • There can be only one locale section in the file
  • Under the locale section you can have multiple subsections, one for each language. For example, under locale you can list an "en" subsection and a "ja" subsection.
  • For each field label that you want in a specific language, add a corresponding string in the relevant language subsection.
  • If you have a label that you cannot localize, such as a proper name, do not include a string in the locale section.
The following table explains how the browser locale and the locale section work together to render UI pages:
Browser Locale
Specified Locale Section in the uiDefinitions.json File
Language Displayed in the
PAM
UI
English
en
English. All other locale sections in the file are ignored.
If the
label
for a field does not have a corresponding string in the
en
section, the UI uses the literal value of the label. This value can be any language.
Japanese
ja
Japanese. All other locale sections in the file are ignored.
If the
label
for a field does not have a corresponding string in the ja section, the UI uses the literal value of the
label
. This value can be any language.
Note:
If there is no locale section, the UI displays the literal value of the
label
for a control. For example, if a label is in Japanese, the field name displays in Japanese even if the browser is set to English.
You can enter strings in the locale section in two formats. You can mix both formats in the same locale section. The format options are:
  • Regular string values.
    JSON example:
     "AccountTabLabel" : "Account Tab"
  • Unicode hexadecimal character. This format begins with a backslash and the letter u (\u), followed by a four-value hexadecimal constant. This format is required for multi-byte languages, such as Japanese.
    JSON Example:
     "AccountTabLabel" : "\u30a8\u30b3\u30fc\u30a2\u30ab\u30a6\u30f3\u30c8"
    The browser locale determines whether "Account Tab" is rendered in English or rendered in Kanji characters.
The following example is an abbreviated sample JSON file with a locale attribute. The example shows a section for English and Japanese and the regular string and Unicode hexadecimal formats that you can use. The locale section renders four UI panels—an Account Tab in English and Japanese and an Application Tab in English and Japanese. For illustration purposes, the two Account Tab panels are shown.
locale_example_small.png
The following screens show the Account Tab in English and Japanese:
account_english.jpg
account_japanese.jpg
Localization for the
PAM
Server
The language for request and error messages from
PAM
and the Custom Connector server is determined by the
PAM
server. Messages include log and error messages about the TCF and the custom connector, and UI validation errors. If the appliance locale is English, then all error messages that the TCF returns to
PAM
are in English. If the appliance locale is Japanese, then all the error messages that the TCF returns are in Japanese.
When you update a target connector configuration, the validation request goes to the TCF server. If there are errors, the language that the error messages are displayed is based on the locale of the
PAM
server.
Continue by reading about the required web services endpoints.