Delegated Administration: 設定クエリ Hook

Delegated Administration Extension で設定クエリ Hook を使用する方法を学びます。

設定クエリ Hook を使用すると、Delegated Administration Extension の外観や使い勝手をカスタマイズできます。

​

Hook の仕様

• 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を使用すると、ダッシュボードのタイトルとユーザー作成ダイアログの「メンバーシップ」ラベルを上書きできます。
    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: ダッシュボードのタイトルと、ユーザー作成ダイアログ内の メンバーシップ ラベルを上書きできる辞書。

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

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

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

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

• languageDictionary: String URL または辞書オブジェクト (下記の「ローカライズ」を参照) 。

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

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

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

​

カスタムフィールド

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

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

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

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

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

userFields の schema の例:

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 || 文字列化した値 => これはデフォルトの表示値です。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 || オブジェクト => このフィールドを編集ダイアログに表示するかどうかを示します。既定のフィールドではなく、オブジェクトに設定されている場合は、ユーザーページの 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: 検索可能なドロップダウン。単一の値のみ指定できます。
    • 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ページには表示されません。

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

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

  • create.type 必須: text || select || password

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

    • InputText (デフォルト): テキストボックス。type が text または password の場合のデフォルトです。
    • InputCombo: 検索可能なドロップダウン。単一の値のみ指定できます。
    • 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: メールアドレスまたは N/A
• 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を使用すると、ダッシュボードのタイトルとユーザー作成ダイアログの「メンバーシップ」ラベルを上書きできます。
    dict: {
      title: department ? department + ' User Management' : 'User Management Dashboard',
      memberships: 'Departments'
    },
    // ユーザーフィールドは、作成・編集時に表示できるカスタムフィールドです。検索にも使用でき、ユーザー表示ページのカスタマイズにも利用できます。
    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'
  });
}

​

ローカライズ

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 Language Dictionary file を参照してください。

​

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

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を使用すると、ダッシュボードのタイトルおよびユーザー作成ダイアログの「メンバーシップ」ラベルを上書きできます。
    dict: {
      title: department ? department + ' User Management' : 'User Management Dashboard',
      memberships: 'Departments'
    },
    // ユーザーフィールドは、作成・編集画面に表示できるカスタムフィールドです。検索にも使用でき、ユーザー詳細ページのカスタマイズにも利用できます。
    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'
  });
}

​

例: Language Dictionary オブジェクトを指定する

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を使用すると、ダッシュボードのタイトルおよびユーザー作成ダイアログの「メンバーシップ」ラベルを上書きできます。
    dict: {
      title: department ? department + ' User Management' : 'User Management Dashboard',
      memberships: 'Departments'
    },
    // ユーザーフィールドは、作成・編集画面に表示できるカスタムフィールドです。検索にも利用でき、ユーザー詳細ページのカスタマイズにも使用できます。
    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: メンバーシップ クエリ Hook