Delegated Administration: Settings Query Hook

Delegated Administration 拡張機能で Settings Query Hook を使用する方法を説明します。

Settings Query Hook を使用すると、Delegated Administration 拡張機能の外観や使い勝手をカスタマイズできます。

​

Hook contract

• ctx: コンテキスト オブジェクト。

  • request.user: 現在ログインしているユーザー。
  • locale: ロケール (URL から推測) — https://{yourTenant}.us.webtask.io/auth0-delegated-admin/en/users の場合、locale は en に設定されます。

• callback(error, settings): エラーと settings オブジェクトを返せるコールバック。

​

使用例

function(ctx, callback) {
  var department = ctx.request.user.app_metadata && ctx.request.user.app_metadata.department;

  return callback(null, {
    // 接続ピッカーにはこれらの接続のみが表示されます。接続が1つしかない場合、接続ピッカーはUIに表示されません。
    connections: [ 'Username-Password-Authentication', 'My-Custom-DB' ],
    // dictionaryを使用すると、Dashboardのタイトルおよびユーザー作成ダイアログの「Memberships」ラベルを上書きできます。
    dict: {
      title: department ? department + ' User Management' : 'User Management Dashboard',
      memberships: 'Departments',
      menuName: ctx.request.user.name
    },
    // CSSオプションを使用すると、現在のユーザーのコンテキストに応じてカスタムCSSファイルを挿入できます（例：顧客ごとに異なるCSSを適用するなど）。
    css: (department && department !== 'IT') && 'https://cdn.jsdelivr.net/gh/auth0-extensions/auth0-delegated-administration-extension/docs/theme/fabrikam.css',
    // このオプションを使用すると、新規ユーザーの作成を制限できます。
    canCreateUser: (department === 'IT')
  });
}

​

プロパティ

• connections: この管理者がその中でユーザーを作成・編集できる接続の一覧。

• dict: Dashboard のタイトルと、[ユーザー作成] ダイアログ内の Memberships ラベルを上書きできるディクショナリ。

  • dict.title: UI 上部に表示するタイトル。
  • dict.memberships: memberships フィールドに設定するラベル。
  • dict.menuName: 右上のドロップダウンメニューに設定する名前。
  • dict.logoutUrl: ログアウトメニュー項目用の代替 URL。

• userFields: ユーザーフィールドの配列 (下記の「カスタムフィールド」を参照) 。

• css: CSS を読み込むための String URL。

• altcss: 2 つ目の CSS セットを読み込むための String URL。これは、大きなフォント向けのアクセシビリティ CSS などを指定するのに使用できます。ユーザーには、この CSS セットのオン/オフを切り替えられるメニュー項目が表示されます。

• languageDictionary: String URL または Dictionary オブジェクト (「Localization」を参照) 。

• suppressRawData: 生の JSON を表示するページをスキップするには、true に設定します

• errorTranslator: ローカライズに基づいてエラーメッセージを変換する関数。例: (function (error, languageDictionary) { return languageDictionary.customErrors[error] || error; }).toString()

• canCreateUser: Boolean フラグ。false に設定すると、ユーザー作成 ボタンが削除され、新しいユーザーを作成できなくなります。デフォルトは true です。

​

カスタムフィールド

Delegated Admin Extension のバージョン 3.0 以降では、カスタムフィールドを定義し、その値を指定できます。カスタムフィールドは、ユーザーの作成または更新時にアクセス可能な ユーザーメタデータ フィールドおよび アプリメタデータ フィールドに保存できます。

また、メールアドレス、username、名前、接続など、Auth0 で定義されている既存のフィールドをカスタマイズすることもできます。

カスタムフィールドを使用するには、次の作業が必要です。

• userFields のリストを Settings Query Hook に追加する
• Write Hook を実装する。カスタムフィールドで user_metadata と app_metadata を正しく更新するには、Write Hook の使用が必要です。Hook に渡されるコンテキスト (ctx オブジェクト) 内の user_metadata と app_metadata を使って、callback 関数に渡される user オブジェクトを更新する必要があります。

Write Hook の詳細については、Delegated Administration: Write Hook を参照してください。

userFields のスキーマ例:

userFields: [
    {
        "property": string, // 必須
        "label": string,
        "sortProperty": string,
        "display": true || function.toString(),
        "search": false || {
            "display": true || function.toString()
            "listOrder": 1,
            "listSize": string(###%), // 例: 15%
            "filter": boolean,
            "sort": boolean
        },
        "edit": false || {
            "display": true || function.toString()
            "type": "text || select || password || hidden",
            "component": "InputText || Input Combo || InputMultiCombo || InputSelectCombo",
            "options": Array(string) || Array ({ "value": string, "label": string }),
            "disabled": true || false,
            "validationFunction": function.toString()
        },
        "create": false || {
            "display": true || function.toString()
            "type": "text || select || password || hidden",
            "component": "InputText || Input Combo || InputMultiCombo || InputSelectCombo",
            "options": Array(string) || Array ({ "value": string, "label": string }),
            "disabled": true || false,
            "validationFunction": function.toString()
        }
    },
    ...
]

• property (必須) : Write Hook の ctx.payload オブジェクト内のプロパティ名。Write Hook では、"property": "app_metadata.dbId" を指定すると、ctx.payload.app_metadata.dbId が設定されます。

• label: ユーザー情報ページ、作成ページ、プロファイル編集ページ、または検索ページで、フィールドにラベルを追加する際に使用するラベル。

• sortProperty: 検索テーブルでこの項目とは異なるフィールドを並べ替えに使用する場合は、このフィールドを指定します。ドット記法を使用できます。

• display: true || false || stringified => これは既定の表示値です。search、edit、または create で上書きしない場合は、この値が使用されます。

  • true の場合、user.<property> をそのまま返します。
  • デフォルト: false の場合、この値はどのページにも表示されません (search、edit、create でオーバーライドされる場合を除く) 。
  • 関数を文字列化した値の場合: 表示する値を取得するために関数を実行します。例: (function display(user, value, languageDictionary) { return moment(value).fromNow(); }).toString()

• search: false || object => このフィールドが検索ページ上でどのように扱われるかを示します。

  • デフォルト: false の場合、検索テーブルには表示されません。
  • search.display: デフォルトの表示値を上書きします。
  • search.listOrder: 検索表示テーブルでの列の順序を指定します。
  • search.listSize: 列のデフォルトの幅を指定します。
  • search.filter: 検索ドロップダウンでこのフィールドを検索対象にするかどうかを指定します。デフォルトは false です。
  • search.sort: この列をソート可能にするかどうかを指定します。property 以外のフィールドでソートする場合は、sortProperty を使用します。デフォルトは false です。

• edit: false || object => このフィールドを編集ダイアログに表示するかどうかを示します。デフォルトフィールドではなく、かつ object に設定されている場合は、ユーザーページの User Actions ドロップダウンにある Change Profile ページに表示されます。

  • デフォルト: false の場合、どの編集/更新ページにも表示されません。

  • edit.display: デフォルトの表示設定を上書きします。

  • edit.required: 値がない場合にエラーになるようにするには、true に設定します。デフォルトは false です。

  • edit.type required: text || select || password

  • edit.component: InputText || Input Combo || InputMultiCombo || InputSelectCombo

    • InputText (デフォルト): シンプルなテキストボックス。
    • InputCombo: 検索可能なドロップダウン。指定できる値は 1 つだけです。
    • InputMultiCombo: 検索可能なドロップダウン。複数の値を指定できます。
    • InputSelectCombo: オプションを選択するドロップダウン。

  • edit.options: component が InputCombo、InputMultiCombo、InputSelectCombo のいずれかである場合は、オプション値を指定する必要があります。

    • Array(string): 値の配列 (label フィールドと value フィールドには同じ値が設定されます) 。
    • Array({ “value”: string, “label”: string }): value と label にそれぞれ別の値を設定できます。この場合、Write Hook 内の値は同じ値になりますが、Write Hook では value のみを使うように簡略化することもできます。
    • サーバー側の検証により、このフィールドに指定した値が options 配列内に含まれていることが保証されます。

  • edit.disabled: コンポーネントを読み取り専用にする場合は true です。デフォルトは false です。

  • edit.validateFunction: 検証用の文字列化された関数です。この検証関数はサーバー側とクライアント側の両方で実行される点に注意してください。例: (function validate(value, values, context, languageDictionary) { if (value...) return 'something went wrong'; return false; }).toString().

• create: false || object => フィールドが作成ダイアログに表示されるかどうかを示します。

  • デフォルト: false の場合、作成ページには表示されません。

  • create.placeholder: 入力が空のときに表示するプレースホルダーテキストを指定します。

  • create.required: 値がない場合に失敗させるには true に設定します。デフォルトは false です。

  • create.type required: text || select || password

  • create.component: InputText || Input Combo || InputMultiCombo || InputSelectCombo

    • InputText (デフォルト): テキストボックス。type が text と password の場合のデフォルトです。
    • InputCombo: 検索可能なドロップダウンで、指定できる値は 1 つだけです。
    • InputMultiCombo: 複数の値を指定できる検索可能なドロップダウンです。
    • InputSelectCombo: オプションを選択するドロップダウンです。

  • create.options: component が InputCombo、InputMultiCombo、InputSelectCombo のいずれかである場合は、オプション値を指定する必要があります。

    • Array(string): シンプルな値の配列です。label と value には同じ値が設定されます。
    • Array({ “value”: string, “label”: string }): value と label にそれぞれ別の値を設定できます。これにより、Write Hook 内の値は同じになりますが、Write Hook 内では value のみに簡略化できます。
    • サーバー側の検証により、このフィールドに指定された値が options 配列に含まれていることが保証されます。

  • create.disabled: component を読み取り専用にする場合は true に設定します。デフォルトは false です。

  • create.validateFunction: 検証を行うための文字列化された関数です。

    • 例: (function validate(value, values, context, languageDictionary) { if (value...) return 'something went wrong'; return false; }).toString()
    • この検証関数は、サーバー側とクライアント側の両方で実行されます。

​

定義済みフィールド

デフォルトの動作に使用される、あらかじめ定義された検索可能なフィールドがいくつかあります。

デフォルトの動作は、フィールドを userField として追加し、変更したい動作を上書きすることで変更できます。多くの場合、これは display を false に設定してフィールドを非表示にするために行います。

​

検索フィールド

• name: 他のフィールドから生成されるフィールド: 既定の表示関数: (function(user, value) { return (value || user.nickname || user.email || user.user_id); }).toString()
• email: メールアドレスまたは該当なし
• last_login_relative: 最終ログイン日時
• logins_count: ログイン回数
• connection: データベース接続

​

ユーザー情報フィールド

• user_id: ユーザー ID
• name: ユーザーの名前
• username: ユーザー名
• email: ユーザーのメールアドレス
• identity.connection: 接続値
• isBlocked: ユーザーがブロックされているかどうか
• blocked_for: ユーザーがアタックプロテクションによってブロックされているかどうか
• last_ip: ユーザーが最後にログインした際の IP
• logins_count: ユーザーのログイン回数
• currentMemberships: このユーザーのメンバーシップ一覧
• created_at: ユーザーが作成された日時
• updated_at: ユーザーが更新された日時
• last_login: ユーザーが最後にログインした日時

​

ユーザーフィールドの作成と編集

• connection: ユーザーのデータベース接続
• password: 新しいパスワード
• repeatPassword: パスワードの再入力
• email: ユーザーのメールアドレス
• username: ユーザー名

​

使用例

function(ctx, callback) {
  var department = ctx.request.user.app_metadata && ctx.request.user.app_metadata.department;

  return callback(null, {
    // 接続ピッカーには、これらの接続のみが表示されます。
    // 接続が1つしかない場合、接続ピッカーはUIに表示されません。
    connections: [ 'Username-Password-Authentication', 'My-Custom-DB' ],
    // dictionaryを使用すると、Dashboardのタイトルおよびユーザー作成ダイアログの「Memberships」ラベルを上書きできます。
    dict: {
      title: department ? department + ' User Management' : 'User Management Dashboard',
      memberships: 'Departments'
    },
    // User Fieldsは、作成・編集画面に表示できるカスタムフィールドです。検索にも使用でき、ユーザー詳細ページのカスタマイズにも利用できます。
    userFields: [
        {
            "label": "Conexión",
            "property": "connection",
        },
        {
            "label": "Correo Electrónico",
            "property": "email",
        },
        ...
    ],
    // CSSオプションを使用すると、現在のユーザーのコンテキストに応じてカスタムCSSファイルを挿入できます（例：顧客ごとに異なるCSSを適用）
    css: (department && department !== 'IT') && 'https://cdn.jsdelivr.net/gh/auth0-extensions/auth0-delegated-administration-extension/docs/theme/fabrikam.css',
    languageDictionary: 'https://your-cdn.com/locale/es.json'
  });
}

​

Localization

Delegated Admin Extension バージョン 3.0 以降では、ローカライズに使用する言語辞書を指定できます。言語辞書が使用されるのは静的なページコンテンツのみです。フィールドレベルのコンテンツには、userFields のラベルを使用する必要があります。

ローカライズは、ユーザー管理における非管理者向け機能を利用する場合を対象としています。現在、Auth0 はどの Configuration ページでもローカライズをサポートしていません。

ロケールを指定するには、パスを使用できます。たとえば、https://{yourTenant}.us.webtask.io/auth0-delegated-admin/en/users を指定すると、設定クエリ内の context.locale は en に設定されます。

languageDictionary は設定クエリの一部として設定され、次のことが可能です。

• languageDictionary を明示的に定義する
• languageDictionary パラメーターの内容を取得する URL を指定する

詳細については、Delegated Administration Extension の言語辞書ファイルを参照してください。

​

例: 言語辞書ファイルへのリンクを指定する

function(ctx, callback) {
  var department = ctx.request.user.app_metadata && ctx.request.user.app_metadata.department;

  return callback(null, {
    // 接続ピッカーには、これらの接続のみが表示されます。
    // 接続が1つしかない場合、UIに接続ピッカーは表示されません。
    connections: [ 'Username-Password-Authentication', 'My-Custom-DB' ],
    // dictionaryを使用すると、Dashboardのタイトルとユーザー作成ダイアログの「Memberships」ラベルを上書きできます。
    dict: {
      title: department ? department + ' User Management' : 'User Management Dashboard',
      memberships: 'Departments'
    },
    // User Fieldsは、作成・編集画面に表示できるカスタムフィールドです。検索にも使用でき、ユーザー詳細ページのカスタマイズにも利用できます。
    userFields: [
        {
            "label": "Conexión",
            "property": "connection",
        },
        {
            "label": "Correo Electrónico",
            "property": "email",
        },
        ...
    ],
    // CSSオプションを使用すると、現在のユーザーのコンテキストに応じてカスタムCSSファイルを挿入できます（例：顧客ごとに異なるCSSを適用）
    css: (department && department !== 'IT') && 'https://cdn.jsdelivr.net/gh/auth0-extensions/auth0-delegated-administration-extension/docs/theme/fabrikam.css',
    languageDictionary: 'https://your-cdn.com/locale/es.json'
  });
}

​

例: 言語辞書オブジェクトを指定する

function(ctx, callback) {
  var department = ctx.request.user.app_metadata && ctx.request.user.app_metadata.department;

  return callback(null, {
    // 接続ピッカーには、これらの接続のみが表示されます。
    // 接続が1つしかない場合、接続ピッカーはUIに表示されません。
    connections: [ 'Username-Password-Authentication', 'My-Custom-DB' ],
    // dictionaryを使用すると、Dashboardのタイトルと「ユーザー作成」ダイアログの「Memberships」ラベルを上書きできます。
    dict: {
      title: department ? department + ' User Management' : 'User Management Dashboard',
      memberships: 'Departments'
    },
    // User Fieldsは、作成・編集画面に表示できるカスタムフィールドです。検索にも使用でき、ユーザー詳細ページのカスタマイズにも利用できます。
    userFields: [
        {
            "label": "Conexión",
            "property": "connection",
        },
        {
            "label": "Correo Electrónico",
            "property": "email",
        },
        ...
    ],
    // CSSオプションを使用すると、現在のユーザーのコンテキストに応じてカスタムCSSファイルを挿入できます（例：顧客ごとに異なるCSSを適用）
    css: (department && department !== 'IT') && 'https://cdn.jsdelivr.net/gh/auth0-extensions/auth0-delegated-administration-extension/docs/theme/fabrikam.css',
    languageDictionary: {
        loginsCountLabel: 'Cantidad de Logins:',
        searchBarPlaceholder: 'Busqueda de usuarios usando la sintaxis de Lucene',
        deviceNameColumnHeader: 'Dispositivo',
        ...
    }
  });
}

​

詳細はこちら

• Delegated Administration: Access Hook
• Delegated Administration: Filter Hook
• Delegated Administration: Write Hook
• Delegated Administration: Memberships Query Hook