コネクタを設定するための UI フィールドおよびコントロール

PAM
UI は、ターゲット アプリケーションおよびアカウント用のタブと入力コントロールをレンダリングできる必要があります。UI フィールドおよびコントロールは、uiDefinitions.json という名前の JSON ファイルで定義されます。管理者がカスタム コネクタを選択すると、アプライアンスは TCF に接続します。次に、TCF はアプライアンスと UI に JSON ペイロードを返します。UI には、JSON ファイルで定義されているタブおよび設定が表示されます。
capam33
PAM
UI は、ターゲット アプリケーションおよびアカウント用のタブと入力コントロールをレンダリングできる必要があります。UI フィールドおよびコントロールは、
uiDefinitions.json
という名前の JSON ファイルで定義されます。管理者がカスタム コネクタを選択すると、アプライアンスは TCF に接続します。次に、TCF はアプライアンスと UI に JSON ペイロードを返します。UI には、JSON ファイルで定義されているタブおよび設定が表示されます。
このトピックでは、uiDefinitions.json ファイルについて説明する参照情報を提供します。このファイルの内容により、カスタム ターゲット コネクタ用の UI パネルおよびコントロールの表示方法が決定されます。カスタム ターゲット コネクタを構築する準備ができたら、uiDefinitions.json ファイルを変更し、UI 検証ユーティリティを使用して変更を検証します。これらのタスクについては、「カスタム コネクタの構築」で説明します。

uiDefinitions.json ファイルの構造

uiDefinitions.json ファイルは、以下の 3 つの主要セクションで構成されています。
  • account
    アプライアンスでのターゲット アカウントを指定します。
    1 つの子「uiDefinition」属性を含む単一の「account」属性の定義が必要です。
  • application
    -
    アプライアンスでのターゲット アプリケーションを指定します。1 つの子「uiDefinition」属性を含む単一の「application」属性の定義が必要です。
  • locale
    UI コントロールが異なる言語で示される場合、フィールド ラベルの言語を指定します。このトピックで後述する「UI フィールド ラベルのロケールの定義」を参照してください。
account および application セクション
account および application セクションには、1 つまたは複数のタブ付きパネルを含めることができます。各パネルには、関連するターゲット アプリケーションまたはターゲット アカウントの属性のグループを含めることができます。たとえば、サンプル ターゲット コネクタ用の uiDefinitions.json ファイルには、「application」セクションが含まれます。このセクションでは、
[Example - Application]
タブおよび UI コントロールを定義する一連のフィールドを持つパネルを定義します。コントロールは、コネクタに関する詳細を識別します。JSON ファイルには、
[Example - Account]
タブ、説明フィールド、およびターゲット アカウント ドロップダウン リストが含まれる「account」セクションもあります。
JSON ファイルには、「account」および「application」セクションを含める必要があります。
以下の 2 つのパネルは、その後に示す uiDefinitions.json ファイルによってレンダリングされます。
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"
}]
}]
}
}
}

Web サービス Java コードが UI 定義を使用する方法

uiDefinitions.json ファイルの「account」および「application」セクションには、単一の「tabs」属性を持つ「uiDefinitions」属性があります。tabs 属性を使用すると、関連するフィールドをグループ化する高レベルのタブを定義できます。各タブには、すべてのコネクタ関連データのすべての設定可能な設定およびコントロールを定義する「fields」セクションが含まれています。「fields」セクションの下には、個々のコネクタ固有属性があります。その 1 つが「field」です。
「field」属性は、以下の方法で使用されます。
  • 各フィールドは、TCF がデータ値にアクセスできるようにするための一意の識別子として機能します。
  • uiDefinitions.json ファイル内のすべての field 属性に対して、定義ファイルに基づいてフィールド値の検証が自動的に実行されます。相互に依存するフィールドのクロス フィールド検証などのカスタム検証を実行するには、
    Validations.java
    ファイルに検証ロジックを追加する必要があります。検証ロジックを追加する手順については、「カスタム コネクタの構築」の「Web サービス エンドポイントの編集」を参照してください。
  • uiDefinitions.json ファイルからフィールドを削除する場合は、フィールドを参照しないように Java コードを編集します。この手順は、Credentials.java ファイルおよび Validations.java ファイルに適用されます。
  • すべてのフィールド値は、JSON ペイロードで文字列として定義されます。Java コードで何らかのデータ タイプ変換の実行が必要になる場合があります。
このトピックの残りの部分では、各フィールド タイプのさまざまな属性と制約について説明します。

ターゲット アプリケーションおよびアカウント用の UI タブおよびコントロール

以下の表では、
PAM
UI に表示されるカスタム ターゲット コネクタ固有の設定の UI タブおよびコントロールの特性について説明します。各タイプの詳細については、このトピックの後半で説明します。
属性
説明
type
(必須)フィールドの種類およびデータ値エントリのタイプを識別し、検証オプションが許可されます。
オプション:
  • TEXT - ユーザ名などのフィールドのプレーン テキスト エントリ
  • TEXTAREA – 証明書などのテキストのブロックが表示されます
  • NUMBER - ポート番号などの整数データ用
  • PASSWORD - UI でマスクされたプレーン テキストで入力されるパスワード用。
  • CHECKBOX - バイナリ値の true または false を選択するための、各オプションの隣にある選択可能なボックスを提供します。
  • COMBOBOX – 相互に排他的なオプションの事前定義済みセットから 1 つのみを選択するためのドロップダウン リストを提供します
  • RADIO – 相互に排他的なオプションの事前定義済みセットから 1 つのみを選択するためのラジオ ボタンを提供します
  • TARGETACCOUNT – アカウントを選択するための設定済みターゲット アカウントのドロップダウン リストを提供します。
フィールド
(必須)フィールドを参照し、データ値にアクセスするための一意の識別子。識別子は、定義済みのターゲット アプリケーションまたはアカウントに対して一意である必要があります。すべての識別子は文字またはアンダースコアで始まり、その後に 1 つ以上の文字、アンダースコア、または数字が続く必要があります。最初のアンダースコアの後に別のアンダースコアを使用できます。この属性の有効なエントリでは、大文字と小文字が区別されます。フィールド値には、埋め込みのスペースを含めることができません。
label
(必須)フィールド名、ラジオ ボタン ラベル、またはチェックボックス ラベルなど、コントロールのラベルを指定します。ラベルの値がファイルの「locale」セクションの識別子の場合、言語固有の文字列が使用されます。ロケール識別子が指定されていない場合は、リテラル文字列値が使用されます。詳細については、「UI フィールド ラベルのロケールの定義」を参照してください。
value
(オプション)新しいレコードの初期デフォルト値を指定します。
の値
(必須)ラベルと値が含まれるオブジェクトの配列。この属性は、RADIO および COMBOBOX 属性タイプによって使用されます。
特定のフィールド タイプに対する制約
属性タイプの多くに対して、フィールド値に関する特定の制約を指定できます。パターン制約では、ユーザが入力できる値を要求および制限できます。指定された値が制約を満たしていない場合、UI には有効なエントリ条件が含まれるメッセージが表示されます。
以下の表では、uiDefinitions.json ファイルで許可されている制約を示します。
制約
説明
使用対象フィールド タイプ
required
(オプション)フィールド値を入力する必要があるかどうかを指定します。フィールド ラベルの隣に、必須フィールドであることを示す赤いアスタリスクが表示されます。
有効なエントリ
  • false (デフォルト値)。フィールド値は必須ではありません
  • true。基本フィールド検証のためにフィールド値が必須です。
TEXT、TEXTAREA、PASSWORD、NUMBER、TARGETACCOUNT
maxLength
(オプション)フィールド値の最大長
TEXT、TEXTAREA、PASSWORD
minLength
(オプション)フィールド値の最小長
TEXT、TEXTAREA、PASSWORD
minValue
(オプション)許容される最小フィールド値
NUMBER
maxValue
(オプション)許容される最大フィールド値
NUMBER
patternConstraint
(オプション)検証中にコネクタがフィールド値に対してテストする正規表現を指定します。テストが失敗した場合、ユーザが無効なエントリを入力または保存するときに UI によってフィールドが無効としてマークされます。
TEXT、TEXTAREA、PASSWORD
patternConstraintMessage
(オプション) patternConstraint が使用され、検証テストが失敗したときにコネクタが表示するエラー メッセージが含まれます。デフォルトでは、この属性は次の文字列に設定されています: 「
このフィールドの値は無効です
TEXT、TEXTAREA、PASSWORD
パターン制約の例
"patternConstraint": "^(today|tomorrow|yesterday)$"
"patternConstraintMessage": "today、tomorrow、または yesterday を入力してください"
"patternConstraint": "^(?:(25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])(\.(?!$)|$)){4}$"
"patternConstraintMessage": "有効な IPV4 アドレス 12.22.111.132 を入力してください" 
"patternConstraint" = "^\\(?([0-9]{3})\\)?[-. ]?([0-9]{3})[-. ]?([0-9]{4})$";
"patternConstraintMessage" = "有効な電話番号 555-555-5555 または (555)555-5555 を入力してください";
"patternConstraint": "^(5[0-9]{3,4}|[1-4]\d{3,4}|[6-9]\d{3})?$"
"patternConstraintMessage": - "範囲を整数で入力してください [5000..59999]"
JSON ファイル内のパターン制約の例を確認するには、「TEXT、TEXTAREA、および PASSWORD 属性の作成」に移動します。

サンプル JSON ファイルを使用した UI 定義の確認

UI 定義によって UI パネルがレンダリングされる方法を示すために、サンプル ターゲット コネクタ用の JSON ファイルを確認します。このファイルには、1 つの「application」セクションおよび 1 つの「account」セクションがあります。
各属性タイプについて説明するために、このトピックでは
[Example - Application]
パネルを使用します。ただし、すべての UI 定義ガイドラインがファイルの「account」および「application」セクションに適用されます。
[アプリケーション]タブには、
[アプリケーション タイプ]
フィールドがあります。アプリケーション タイプとしてサンプル ターゲット コネクタを選択すると、
[Example - Application]
タブを使用できるようになります。
以下の画面イメージは、
[Example - Application]
タブを示しています。
example_target_app.png
以下のトピックでは、タブおよびフィールドを定義する方法について説明します。
必須の uiDefinition および Tabs 属性の定義
各 account および application セクションには、「uiDefinitions」属性と、その直後に単一の「tabs」属性が必要です。これらの属性は、以下の情報を指定します。
  • uiDefinition - 各 account および application セクションで、この属性は「tabs」定義の親です。
  • tabs - このセクションには、タブ ID、ラベル、および各タブに表示される対応する「フィールド」が含まれるタブ オブジェクトの配列を列挙します。この属性では、関連するフィールドをグループ化する高レベルのタブを定義できます。
以下のコード例に、これらの 2 つのセクションを示します。
"application": {
"uiDefinition": {
"tabs": [{
"id": "ExampleAppDetail",
"label": "Example - Application",
"fields": [{...}]
カスタム コネクタ タブの定義
タブには、ターゲット コネクタ用のすべてのターゲット アプリケーションまたはターゲット アカウント属性が含まれています。関連する属性をグループ化するには、必要に応じて 1 つ以上のタブを作成します。
以下の図に、[Example - Application]タブを示します。
two_custom_tabs.png
各タブには、以下の属性があります。
属性
説明
id
タブの一意の識別子。この識別子は、タブがレンダリングされる UI パネル上で一意である必要があります。すべての識別子は文字またはアンダースコアで始まり、その後に 1 つ以上の文字、アンダースコア、または数字が続く必要があります。最初のアンダースコアの後に別のアンダースコアを使用できます。有効な識別子では、大文字と小文字が区別されます。タブ識別子には、埋め込みのスペースを含めることはできません。
label
前の図に示した[Example - Application]などのタブ自体のテキスト。ラベルの値がファイルの「locale」セクションの識別子の場合、言語固有の文字列が使用されます。ロケール識別子が指定されていない場合は、リテラル文字列値が使用されます。詳細については、「UI フィールド ラベルのロケールの定義」を参照してください。
フィールド
タブ パネル上に表示するフィールド オブジェクトの配列を指定します。
[Example - Application]というラベルのターゲット アプリケーション タブを追加するには、以下の JSON 構文を使用します。
"application": {
"uiDefinition": {
"tabs": [{
"id": "ExampleAppDetail",
"label": "Example - Application",
"fields": [{...}]
[Example - Application]
および
[User Information]
という 2 つのタブを追加するには、以下の JSON 構文を使用します。
"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
}]
}]
}
}
数値フィールドの作成
ポートやタイムアウトなどの数値エントリを必要とするフィールドを表示するには、
NUMBER
フィールド タイプを追加します。最小(「minValue」)または最大(「maxValue」)制約を指定することで、NUMBER フィールドに制約を設定できます。
以下の JSON 構文では、[Example - Application]パネルに[Connect Timeout]、[Read Timeout]、および[SSH Port]フィールドが作成されます。JSON に基づいて、このパネルには各フィールドの初期デフォルト値が含まれています。この例では、指定された値に対して最小値および最大値の制約を指定する方法を示します。また、この例では、「required」属性が true に設定されています。これは、値の指定が必須であることを示しています。この属性は空白にできません。
"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
}]
TEXT、TEXTAREA、および PASSWORD 属性の作成
以下の抜粋は、以下のフィールド タイプ定義を示しています。
  • TEXT: テキストを必要とするフィールド。
  • TEXTAREA: 大量のテキストを格納できるフィールド。
  • PASSWORD: ユーザ パスワード用のフィールド。
TEXT タイプでは、パターン制約が使用されています。TEXT タイプでは、
required
属性が true に設定されています。これは、フィールドを空白のままにできないことを示しています。TEXTAREA には、パターン制約はありません。
{
"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"
}
ラジオ ボタン付きフィールドの表示
RADIO
属性タイプは、事前定義済みかつ相互に排他的なオプションのセットから 1 つのオプションのみを選択するためのコントロールを表示します。
RADIO
タイプは、オプションが数個のみの構成設定に対して使用することをお勧めします。
RADIO
タイプには、コントロールの「
values
」属性と、その直後に 2 つ以上の一意の「
label
」および「
value
」オプションが必要です。
以下の JSON 構文では、3 つのオプション(TLS 1.0、1.2、および 1.3)が含まれるコネクタ プロトコル設定が作成されます。ターゲット アプリケーションまたはアカウントを作成する場合は、TLS 1.2 オプションがデフォルトで設定されています。初期値が指定されていない場合は、最初のオプション(この例では TLS 1.0)がデフォルトで選択されています。
{
"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"
}]
}
チェックボックスを使用したオプションの選択
true または false を選択するためのチェックボックス付きのフィールドを表示するには、CHECKBOX パラメータ タイプを使用します。
以下の JSON 構文では、[Example - Application]パネルに[Use Certificate]フィールドが作成されます。デフォルトでは、このパネルにはデフォルトで true (オン)に設定されているオプションがあります。初期値が指定されていない場合、コントロールは false (オフ)です。
{
"type": "CHECKBOX",
"field": "certificate",
"label": "Use Certificate",
"value": true
}
値のドロップダウン リスト付きフィールドの作成
ドロップダウン リストから選択可能な値を含むフィールドを表示するには、COMBOBOX パラメータ タイプを追加します。
以下の JSON 構文では、[Example - Application]パネルに[Additional Encryption]フィールドが作成されます。ターゲット アプリケーションまたはアカウントを作成する場合、この例ではデフォルト値として設定された AES が示されます。初期値が指定されていない場合は、最初の項目(この例では Triple DES)がデフォルトで選択されています。
{
"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"
}]
}
ターゲット アカウント選択フィールドの作成
ユーザがターゲット アカウントを選択できるフィールドを作成するには、TARGETACCOUNT フィールド タイプを使用します。このフィールドには、アカウントを選択するためのドロップダウン リスト付きのフィールドが表示されます。また、このフィールドでは、ターゲット アカウントを検索および選択できます。以下の例では、[Example - Application]パネルに[Description]と[Master Account]というラベルの 2 つのフィールドがあります。
"fields": [{
"type": "TEXT",
"field": "description",
"label": "Description",
"maxLength": 60
},{
"type": "TARGETACCOUNT",
"field":"anotherAccount",
"label": "Master Account"
}]

UI フィールド ラベルのロケールの定義

Web ブラウザでのフィールド ラベルの表示をローカライズするには、uiDefinitions.json ファイルに
locale
セクションを追加します。locale 属性は、ブラウザのロケールのみと互いに影響します。サポートされているロケール値は、
en
(英語)および
ja
(日本語)のみです。
locale セクションに関するガイドライン
  • ファイル内には locale セクションを 1 つだけ配置できます。
  • locale セクションの下に、言語ごとに複数のサブセクションを配置できます。たとえば、locale の下に「en」サブセクションと「ja」サブセクションを列挙できます。
  • 特定の言語で必要なフィールド ラベルごとに、対応する文字列を関連する言語で追加します。
  • 固有名詞などのローカライズできないラベルがある場合は、locale セクションに文字列を含めないでください。
以下の表では、ブラウザのロケールと locale セクションがどのように連携して UI ページをレンダリングするかについて説明します。
ブラウザのロケール
uiDefinitions.json ファイルで指定された locale セクション
PAM
UI に表示される言語
英語
en
英語。ファイル内の他のすべての locale セクションは無視されます。
フィールドの
label
に対応する文字列が
en
セクションに存在しない場合、UI は
label
のリテラル値を使用します。この値は、任意の言語で指定できます。
日本語
ja
日本語。ファイル内の他のすべての locale セクションは無視されます。
フィールドの
label
に対応する文字列が ja セクションに存在しない場合、UI は
label
のリテラル値を使用します。この値は、任意の言語で指定できます。
注:
locale セクションがない場合、UI はコントロールの
label
のリテラル値を表示します。たとえば、ラベルが日本語の場合、ブラウザが英語に設定されている場合でもフィールド名が日本語で表示されます。
locale セクションには、2 つの形式で文字列を入力することができます。同じ locale セクションで両方のフォーマットを混在させることができます。形式オプションは以下のとおりです。
  • 正規文字列値。
    JSON の例:
    "AccountTabLabel" : "Account Tab"
  • Unicode 16 進文字。この形式は円記号と文字 u (\u)で開始され、その後に 4 つの値の 16 進定数が続きます。この形式は、日本語などのマルチバイト言語に必要です。
    JSON の例:
    "AccountTabLabel" : "\u30a8\u30b3\u30fc\u30a2\u30ab\u30a6\u30f3\u30c8"
    ブラウザのロケールは、「アカウント タブ」が英語または漢字のどちらでレンダリングされるかを決定します。
以下の例は、locale 属性が含まれているサンプル JSON ファイルの抜粋です。この例では、英語と日本語のセクションと、使用できる正規文字列および Unicode 16 進形式を示します。locale セクションにより、4 つの UI パネル(英語と日本語の「アカウント タブ」および英語と日本語の「アプリケーション タブ」)がレンダリングされます。例として、2 つの「アカウント タブ」を示します。
locale_example_small.png
以下の画面は、英語と日本語の「アカウント タブ」を示しています。
account_english.jpg
account_japanese.jpg
サーバのローカライゼーション
PAM
およびカスタム コネクタ サーバからのリクエストおよびエラーのメッセージの言語は、
PAM
サーバによって決定されます。メッセージには、TCF およびカスタム コネクタに関するログとエラー メッセージ、および UI 検証エラーが含まれます。アプライアンスのロケールが英語の場合、TCF が
PAM
に返すすべてのエラー メッセージは英語です。アプライアンスのロケールが日本語の場合、TCF が返すすべてのエラー メッセージは日本語です。
ターゲット コネクタ設定を更新すると、検証リクエストが TCF サーバに送信されます。エラーがある場合、エラー メッセージの表示言語は
PAM
サーバのロケールに基づきます。
続いて、必要な Web サービス エンドポイントについて参照してください。