ルールでメタデータを管理する

ルールを使用して、アプリのメタデータ、ユーザーメタデータ、client metadata を管理する方法を学びます。

ルールと Hooks の提供終了 (EOL) 日は 2026年11月18日 です。また、2023年10月16日 以降に作成された新しいテナントでは、これらはすでに利用できません。アクティブな Hooks を使用している既存のテナントは、提供終了まで Hooks へのアクセスを維持できます。

Auth0 を拡張するには、Actions の使用を強くおすすめします。Actions では、豊富な型情報、インラインドキュメント、公開 npm package を利用できるほか、外部連携に接続して拡張機能をさらに充実させることができます。Actions の機能について詳しくは、Understand How Auth0 Actions Work をご覧ください。

移行を支援するために、ルールから Actions への移行 と フックから Actions への移行 のガイドを用意しています。さらに、機能比較、Actions のデモ、および移行に役立つその他のリソースを紹介する専用の Move to Actions ページもあります。

ルールと Hooks の非推奨化について詳しくは、ブログ記事「Preparing for Rules and Hooks End of Life」をお読みください。

Auth0 Rules を使用すると、メタデータの読み取り、更新、削除を行えます。以降のセクションでは、次の JSON スニペットで表されるユーザーとその情報の例を参照します。

{
  "user_id": "jdoe",
  "email": "[e-mail]",
  "app_metadata": {
    "roles": [ "writer" ]
  },
  "user_metadata": {
    "preferences": {
      "color": "blue"
    }
  }
}

​

メタデータを読み取る

Management API とルールを使用して、メタデータを読み取ることができます。また、user_metadata で次のようなプロファイル関連情報を検索することもできます。

• name
• nickname
• given_name
• family_name

デフォルトでは、Auth0 以外のアイデンティティプロバイダー (Google、Facebook、X など) から提供されるユーザープロファイル属性は、ユーザーがログインするたびにアイデンティティプロバイダーから更新されるため、直接編集できません。アイデンティティプロバイダー由来の属性の詳細については、ユーザープロファイル更新のための Identity Provider Connection の設定を参照してください。

正規化されたユーザープロファイル上の name、nickname、given_name、family_name、または picture のルート属性を編集できるようにするには、接続の同期を Auth0 で設定し、ユーザー属性がアイデンティティプロバイダーから更新されるのはユーザープロファイルの作成時のみになるようにする必要があります。そうすると、これらのルート属性を個別に、または一括インポートで編集できるようになります。

例として、メールアドレス [e-mail] のユーザーに次のメタデータが保存されているとします。

{
    "email": "[e-mail]",
    "user_metadata": {
        "hobby": "surfing"
    },
    "app_metadata": {
        "plan": "full"
    }
}

上記のメタデータ例を使うと、Auth0 ルール や Management API の呼び出しで、データセット内の特定の項目を次のように参照できます。

console.log(user.email); // "[e-mail]"
console.log(user.user_metadata.hobby); // "surfing"
console.log(user.app_metadata.plan); // "full"

有効なJSONスニペットであれば、どれでもメタデータとして使用できますが、user.app_metadata はデフォルトで Undefined である点に注意してください。

利用可能なメタデータを読み取るには、適切なユーザープロパティにアクセスする必要があります。

​

アプリのメタデータを読み取る

ユーザーのロールに基づいて判定できます。

function(user, context, callback){
  user.app_metadata = user.app_metadata || {};
  if (user.app_metadata.roles.indexOf('writer')){
    // 実行するコード
  }
  ...
}

​

ユーザーメタデータを読み取る

色の好みなど、特定の設定に基づいて判断できます。

function(user, context, callback){
  user.user_metadata = user.user_metadata || {};
  if (user.user_metadata.preferences.color === 'black'){
    // 実行するコード
  }
  ...
}

​

アプリケーションのメタデータ (clientMetadata) を読み取る

アプリケーションのメタデータ (clientMetadata) は、context オブジェクトの最上位にある省略可能なプロパティです。既存のアプリケーションでは、このプロパティには値が設定されていません。

function(user, context, callback){
  context.clientMetadata = context.clientMetadata || {};
  if (context.clientMetadata.usersuppliedkey1 === 'black'){
    // このコードはユーザーに対して実行されない
  }
  ...
}

​

メタデータを更新する

ルールを使用して、Auth0 が IdP から受け取る SAML 属性を user_metadata または app_metadata にマッピングします。

​

アプリのメタデータを更新

ユーザーに管理者ロールを追加するには:

function(user, context, callback){
  user.app_metadata = user.app_metadata || {};
  // レスポンスに含まれるapp_metadataを更新する
  user.app_metadata.roles = user.app_metadata.roles || [];
  user.app_metadata.roles.push('administrator');

  // app_metadataの更新を永続化する
  auth0.users.updateAppMetadata(user.user_id, user.app_metadata)
    .then(function(){
      callback(null, user, context);
    })
    .catch(function(err){
      callback(err);
    });
}

その結果、ユーザープロファイルの詳細は次のような JSON 表現になります。

{
  "user_id": "jdoe",
  "email": "[e-mail]",
  "app_metadata": {
    "roles": [ "writer", "administrator" ]
  },
  "user_metadata": {
    "preferences": {
      "color": "blue"
    }
  }
}

​

ユーザーメタデータを更新する

ユーザープロファイルにユーザーの fontSize 設定を追加するには:

function(user, context, callback){
  user.user_metadata = user.user_metadata || {};
  // レスポンスに含まれるuser_metadataを更新する
  user.user_metadata.preferences = user.user_metadata.preferences || {};
  user.user_metadata.preferences.fontSize = 12;

  // user_metadataの更新を永続化する
  auth0.users.updateUserMetadata(user.user_id, user.user_metadata)
    .then(function(){
      callback(null, user, context);
    })
    .catch(function(err){
      callback(err);
    });
}

これにより、ユーザープロファイルの詳細は次のようなJSON形式で表されます。

{
  "user_id": "jdoe",
  "email": "[e-mail]",
  "app_metadata": {
    "roles": [ "writer" ]
  },
  "user_metadata": {
    "preferences": {
      "color": "blue",
      "fontSize": 12
    }
  }
}

​

アプリとユーザーのメタデータを同時に更新する

ルールの処理時間を短縮するため、同じルール内で app_metadata と user_metadata の両方を更新できます。

function(user, context, callback){

  var q = require('q');

  user.app_metadata = user.app_metadata || {};
  user.user_metadata = user.user_metadata || {};
  // レスポンスに含まれるuser_metadataを更新する
  user.user_metadata.preferences = user.user_metadata.preferences || {};
  user.user_metadata.preferences.fontSize = 12;

  // レスポンスに含まれるapp_metadataを更新する
  user.app_metadata.roles = user.app_metadata.roles || [];
  user.app_metadata.roles.push('admin');

  // app_metadataの更新を永続化する
  var appMetadataPromise  = auth0.users.updateAppMetadata(user.user_id, user.app_metadata);

  // user_metadataの更新を永続化する
  var userMetadataPromise = auth0.users.updateUserMetadata(user.user_id, user.user_metadata);

  // qライブラリを使用してすべてのPromiseが完了するまで待機する
  q.all([userMetadataPromise, appMetadataPromise])
    .then(function(){
      callback(null, user, context);
    })
    .catch(function(err){
      callback(err);
    });
}

その結果、ユーザープロファイルの詳細は次のようなJSON形式で表されます。

{
  "user_id": "jdoe",
  "email": "[e-mail]",
  "app_metadata": {
    "roles": [ "writer", "admin" ]
  },
  "user_metadata": {
    "preferences": {
      "color": "blue",
      "fontSize": 12
    }
  }
}

​

メタデータの削除

​

アプリのメタデータのプロパティと値を削除する

プロパティを削除するには、その値を null に設定します。

​

ユーザーのロールを削除する例

ユーザーのロールを削除するには、以下のサンプルルールを使用します。

function(user, context, callback){
  user.app_metadata = user.app_metadata || {};
  // レスポンスに含まれるapp_metadataを更新する
  user.app_metadata.roles = null;

  // app_metadataの更新を永続化する
  auth0.users.updateAppMetadata(user.user_id, user.app_metadata)
    .then(function(){
      callback(null, user, context);
    })
    .catch(function(err){
      callback(err);
    });
}

これにより、ユーザープロファイルは以下のJSON形式で表されます。

{
  "user_id": "jdoe",
  "email": "[e-mail]",
  "app_metadata": { },
  "user_metadata": {
    "preferences": {
      "color": "blue"
    }
  }
}

​

単一のプロパティ値を削除する例

プロパティの値を1つだけ削除するには、その値を削除します。たとえば、ユーザープロファイルから writer ロールを削除するには、次のようにします。

function(user, context, callback){
  user.app_metadata = user.app_metadata || {};
  user.app_metadata.roles = user.app_metadata.roles || [];

  var index = user.app_metadata.roles.indexOf('writer');

  if (index !== -1){
    // レスポンスに含まれるapp_metadataを更新する
    user.app_metadata.roles.splice(index, 1);
  }

  // app_metadataの更新を保存する
  auth0.users.updateAppMetadata(user.user_id, user.app_metadata)
    .then(function(){
      callback(null, user, context);
    })
    .catch(function(err){
      callback(err);
    });
}

これにより、ユーザープロファイルは次のJSONのように表されます。

{
  "user_id": "google-oauth2|1234",
  "email": "[e-mail]",
  "app_metadata": {
    "roles": [ ]
  },
  "user_metadata": {
    "preferences": {
      "color": "blue"
    }
  }
}

roles プロパティは引き続き存在しますが、値は含まれていない点に注意してください。

​

ユーザーのメタデータのプロパティと値を削除する

ユーザーの色の設定を削除するには:

function(user, context, callback){
  user.user_metadata = user.user_metadata || {};
  // レスポンスに含まれるuser_metadataを更新する
  user.user_metadata.preferences = user.user_metadata.preferences || {};
  delete user.user_metadata.preferences.color;

  // user_metadataの更新を永続化する
  auth0.users.updateUserMetadata(user.user_id, user.user_metadata)
    .then(function(){
      callback(null, user, context);
    })
    .catch(function(err){
      callback(err);
  });
}

その結果、ユーザープロファイルの詳細は次のようなJSON形式で表されます。

{
  "user_id": "jdoe",
  "email": "[e-mail]",
  "app_metadata": {
    "roles": [ "writer" ]
  },
  "user_metadata": {
    "preferences": { }
  }
}

​

詳細情報

• ルール内から Management API を使用する
• ルールにおけるコンテキストオブジェクトのプロパティ
• Auth0 ルール