マッピング設定

ここでは、UCIDM に連携されてきたデータから外部連携先モジュールに渡すデータにマッピングするための設定について記載します。

OpenLDAP, Microsoft Entra ID, Google への細かいマッピングの注意事項については、各外部連携の説明ページをご参照ください。

マッピング設定画面

ID 連携管理画面の外部連携設定画面にて、各外部連携先に向けたマッピングの設定ができます。

マッピングの設定項目は、1 属性ごとに以下を設定することができます。

原則として UCIDM では連携されるエントリにおける属性名の大文字小文字を区別しません (case-insensitive) 。例えば、連携元の属性名が givenName であっても givenname, GIVENNAME, givenNAME のいずれでも一致します。

但し、カスタムスクリプトのスクリプト内部で属性名を参照するときはすべて小文字の属性名 (givenname) として参照するようにスクリプトを書いてください。カスタムスクリプトのデバッグ機能があるので意図したマッピング結果になることを確認してください。

  • 連携先の属性名
    • 外部連携先の属性名を指定します
  • 連携元の属性名
    • UCIDM に連携されてきたデータに対応する属性名を指定します
  • ビルトイン関数名
    • 連携元の属性名に対応する属性値について、事前定義済みのビルトイン関数を適用してマッピング結果とすることができます
    • 事前定義済みのビルトイン関数については、本ページ下部の 事前定義済みのビルトイン関数 の項を参照してください
  • テンプレート文字列
    • UCIDM に連携されてきたデータに対応する属性値を組み合わせて、文字列を生成できます
    • UCIDM に連携されてきたデータに対応する属性名を %{xxx} の形で %{} で囲むことで、属性値を文字列に入れ込むことが出来ます
    • 例えば、%{cn}-%{sn} とすると UCIDM に連携されてきたデータの cn と sn の値を - でつないだ文字列がマッピング結果として使用されます
  • 固定値
    • 固定値をマッピングしたい場合に使用します。マルチバリューについても指定することができます。
  • カスタムスクリプトを利用
    • カスタムのスクリプト（後述）を使用してマッピングをしたい場合に on （true）にします。
  • 関数名
    • 上記で「カスタムスクリプトを利用」が true の場合に使われます
    • 使用したいスクリプトの関数名を指定します
  • 引数
    • 上記で「カスタムスクリプトを利用」が true の場合に使われます
    • 使用したいスクリプトに渡す引数を指定します

カスタムスクリプト

UCIDM のマッピング処理においては、カスタムスクリプトを用いて、任意の関数の処理を実行した結果をマッピング結果に設定することができます。

カスタムスクリプトは javascript で記述します。

以下はカスタムスクリプトスクリプトの一例です。

function addPrefix(prefix) {
    return [prefix + cn];
}

上記で prefix には、任意の引数の値を渡すことができます。（上記マッピング設定の、「引数」で指定します。）

cn の部分は環境値となり、マッピング元のデータの cn の値が参照されます。

カスタムスクリプトはユーザ、グループにおいてそれぞれ定義することができます。また、複数の関数を定義することができます。（マッピングで使用したい関数を、上記マッピング設定の「関数名」で指定する必要があります。）

関数呼び出し確認では、関数の引数を「引数値リスト」、cn のような環境値を「環境値リスト」に設定し、「関数呼び出し確認」ボタンをクリックすることで、呼び出し結果が表示されます。

このカスタムスクリプトにて undefined または null を返すと、連携先の属性名で指定した属性に対するマッピングは無視されます。

カスタムスクリプトには以下の環境値で情報が渡されます。

UCIDM_OPERATION_TYPE

以下の操作種別が渡されます。

  • create
    • ユーザー追加・グループ追加の時にこの値が設定されます。
  • update
    • ユーザー更新・グループ更新の時にこの値が設定されます。
  • password
    • ユーザーパスワード更新の時にこの値が設定されます。
  • none
    • 上記以外の操作種別の際のこの値が設定されます。

マッピングの動き

全体として以下の順に処理が行われます。外部連携先に連携したい属性は、必ずここで定義を入れる必要があります。マッピング定義がない属性はマッピング結果に反映されません。

  • 連携元の属性名
  • テンプレート文字列
  • 固定値
  • カスタムスクリプト

以下で上記マッピング処理の詳細な動きについて説明します。

  • 連携元の属性名
    • 連携元の属性名 の値がある場合
      • ビルトイン関数名 の値がある場合
        • 連携元の属性名に対応する属性値をビルトイン関数に引数として渡し、その結果をマッピングの結果とします
      • ビルトイン関数名 の値がない場合
        • 連携元の属性名に対応する属性値を取得して、マッピング結果とします
    • 連携元の属性名 の値がない、連携元の属性名 の属性値が取得できない場合は、後続の処理に進みます
  • テンプレート文字列
    • テンプレート文字列 の値がある場合は、属性値をつかって、テンプレート文字列 の文字列を置換して、マッピング結果とします
    • 属性名に対応する属性値がマルチバリューの場合は、その部分にはマルチバリューの 0 番目の要素がセットされます
    • 属性名に対応する属性値がない場合は、その部分には空文字（“”）がセットされます
    • テンプレート文字列 の値がない場合は、後続の処理に進みます
  • 固定値
    • 固定値 の値がある場合は、その値をマッピング結果とします
    • 固定値 の値がない場合は、後続の処理に進みます
  • カスタムスクリプト
    • useScript が true の場合はカスタムスクリプトによる関数実行を行い、その実行結果の返り値をマッピング結果とします
      • カスタムスクリプトは実行時エラーが発生する可能性があるため、ここでエラーが返る可能性があります
    • useScript が false の場合は、後続の処理に進みます
  • ここまで値がセットされない場合は、空配列をマッピング結果とします

事前定義済みのビルトイン関数

invertBooleanValue

  • 引数として受け取った boolean の値を、その真偽値を反転させてマッピング結果とします
    • true として読み込める値は以下となります
      • true（大文字/小文字を区別しない）, t（大文字/小文字を区別しない）, 1
    • false として読み込める値は以下となります
      • false（大文字/小文字を区別しない）, f（大文字/小文字を区別しない）, 0
  • 引数の値が存在しない場合、boolean でない場合はマッピングエラーとなります
  • 引数の値が複数存在する場合は、その 1 つめの要素について真偽値の反転処理をおこないます

マッピング設定のインポート・エクスポート

ID 連携管理画面では、マッピング設定のインポートおよびエクスポートをすることができます。

マッピング設定のインポート

  • 外部連携設定詳細のマッピング設定欄の「インポート」ボタンを押すことで、UTF-8 形式の json ファイルをインポートすることができます。
  • 「参照」ボタンでインポートしたい json ファイルを指定してから、「インポート」を押下しください。
  • インポート後、画面上のマッピング設定の内容が json ファイルの内容で上書きされます。内容が正しいことを確認してから外部連携設定の更新を行ってください。

マッピング設定のエクスポート

  • 外部連携設定詳細のマッピング設定欄の「エクスポート」ボタンを押すことで、UTF-8 形式の json ファイルがダウンロードできます。